nixpkgs/nixos/doc/manual/configuration/renaming-interfaces.section.md
Andrew Kvalheim 12bab91d3b nixos/doc: improve example of renaming network interfaces
For reliably identifying network interfaces, `PermanentMACAddress` is
likely to be preferable to `MACAddress`. NetworkManager in particular
commonly changes the MAC address of wireless interfaces.

Reference:

  - https://www.freedesktop.org/software/systemd/man/systemd.link.html#PermanentMACAddress=
2021-11-21 20:12:31 -08:00

1.8 KiB

Renaming network interfaces

NixOS uses the udev predictable naming scheme to assign names to network interfaces. This means that by default cards are not given the traditional names like eth0 or eth1, whose order can change unpredictably across reboots. Instead, relying on physical locations and firmware information, the scheme produces names like ens1, enp2s0, etc.

These names are predictable but less memorable and not necessarily stable: for example installing new hardware or changing firmware settings can result in a name change. If this is undesirable, for example if you have a single ethernet card, you can revert to the traditional scheme by setting to false.

Assigning custom names

In case there are multiple interfaces of the same type, it's better to assign custom names based on the device hardware address. For example, we assign the name wan to the interface with MAC address 52:54:00:12:01:01 using a netword link unit:

systemd.network.links."10-wan" = {
  matchConfig.PermanentMACAddress = "52:54:00:12:01:01";
  linkConfig.Name = "wan";
};

Note that links are directly read by udev, not networkd, and will work even if networkd is disabled.

Alternatively, we can use a plain old udev rule:

services.udev.initrdRules = ''
  SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
  ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
'';

::: {.warning} The rule must be installed in the initrd using services.udev.initrdRules, not the usual services.udev.extraRules option. This is to avoid race conditions with other programs controlling the interface. :::