Set a Stable Network Interface Name with systemd.link

You will create a .link file that matches one network device by its MAC address and gives it a predictable name such as lan0. You will also inspect the rule without taking the interface down, then cover the controlled way to apply it. Allow about fifteen minutes. You need root access to write under /etc/systemd/network, and you should have console access if the interface carries your current connection.

The examples describe the systemd 255 interface installed here, from package version 255.4-1ubuntu8.17. Replace AA:BB:CC:DD:EE:FF with the real address of the target device and lan0 with a name that is unique on your host.

1. Identify the device and its current address

Start with read-only commands. This avoids matching an interface by a kernel name that may change after a reboot:

$ ip -br link
$ ip link show enp0s31f6

Use the interface name from your own output. The link/ether value is the current MAC address. If another configuration deliberately changes that address, use the matching strategy that describes the device reliably, such as PermanentMACAddress=, Path=, or Driver=. OriginalName= matches the udev interface name, but the manpage warns that kernel-assigned names are not stable between reboots.

Checkpoint: record the target MAC address and check that the proposed name is not already in use:

$ ip link show lan0
Device "lan0" does not exist.

Your diagnostic wording may differ. If lan0 already exists, choose another name rather than relying on a race between two interfaces.

2. Create an early matching rule

Local link files belong in /etc/systemd/network. The first matching file in alphanumeric order wins, and the shipped 99-default.link would otherwise be considered first. Create a file with a numeric prefix below 70:

$ sudo install -d -m 0755 /etc/systemd/network
$ sudoedit /etc/systemd/network/10-lan.link

Enter this configuration, replacing the placeholder MAC address:

[Match]
MACAddress=AA:BB:CC:DD:EE:FF

[Link]
Name=lan0

The two sections have different jobs. [Match] selects the device; every match setting in that section must succeed. [Link] describes the change. Because this file does not set NamePolicy=, its explicit Name=lan0 can take effect. Interface names must be 1 to 15 characters, cannot be fully numeric, and must not contain :, /, or %. Avoid names such as eth0, which can collide with a kernel-assigned name.

This is a persistent configuration change, although it is not applied merely by saving the file. Keep a second session or local console available before changing a live network interface.

3. Check what udev would apply

Test the installed net_setup_link builtin against the interface's current sysfs path. This is a read-only diagnostic and does not rename the device:

$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/INTERFACE
...

Replace INTERFACE with the current name, for example enp0s31f6. In the output, look for lines like these:

Config file /etc/systemd/network/10-lan.link is applied
ID_NET_LINK_FILE=/etc/systemd/network/10-lan.link
ID_NET_NAME=lan0

The debug text contains more hardware and naming details than this excerpt, and wording can change. The useful checkpoint is the path to your file and the proposed ID_NET_NAME. If the shipped /usr/lib/systemd/network/99-default.link is still shown as the applied file, your rule did not match or was ordered too late. Check the MAC spelling, the current interface path, and the numeric filename prefix.

4. Apply the rule during a maintenance window

Saving a .link file does not retroactively change an existing device. First reload udev's rules:

$ sudo udevadm control --reload

Applying a link rule can rename the interface, interrupt traffic, and confuse the service managing its addresses. Stop or pause that service if your host requires it. Then, only when you have console access or an out-of-band session, use the documented reapplication sequence:

$ sudo ip link set INTERFACE down
$ sudo udevadm trigger --verbose --settle --action add /sys/class/net/INTERFACE

Replace INTERFACE in both commands with the old name. Do not run this blindly over SSH on the only reachable interface. If NetworkManager or systemd-networkd manages the device, restart or resume it according to that service's normal procedure after the rename.

Verify the result with ordinary, unprivileged commands:

$ ip -br link
lan0             UP             ...
$ udevadm info --query=property --path=/sys/class/net/lan0 | grep '^ID_NET_LINK_FILE='
ID_NET_LINK_FILE=/etc/systemd/network/10-lan.link

Exact columns and additional properties vary. Confirm that the new name exists, the link has the expected state, and your network service has restored its configuration.

5. Undo a mistaken rule

If the rule matches the wrong device or the new name breaks service configuration, remove or rename the file and repeat the controlled application process. Removing a file under /etc is destructive, so preserve a copy first if you may need to inspect it:

$ sudo cp --preserve=all /etc/systemd/network/10-lan.link /tmp/10-lan.link.backup
$ sudo rm /etc/systemd/network/10-lan.link
$ sudo udevadm control --reload

Do not delete the backup until the old naming and service configuration have been tested. If the interface is currently called lan0, reapplication may require using that current name in the sysfs path and restoring the network service afterwards. A reboot is a possible recovery route, but it is not a substitute for checking the service configuration and it can leave a remote host unreachable.

6. Avoid the common matching traps

• A link file with no valid [Match] settings matches every interface and causes a udev warning. If you really intend that, use OriginalName=* to state it explicitly.
• Matching files are collectively sorted across /usr/lib, /run, and /etc. An earlier matching file wins, so a later local file cannot override it simply because /etc has higher directory priority.
• MACAddress= in [Link] only takes effect when MACAddressPolicy= is unset, empty, or none. Do not combine a fixed MAC address with a conflicting policy.
• NamePolicy= has higher precedence than Name=. If a policy succeeds, the explicit name may not be used.
• Drop-ins use a directory named after the file, such as 10-lan.link.d/, and only files ending in .conf are merged. A drop-in can change a setting without editing the main file, but it still participates in the same configuration and ordering rules.