nixos/doc/manual/configuration/renaming-interfaces.section.md

   1 # Renaming network interfaces {#sec-rename-ifs}
   2
   3 NixOS uses the udev [predictable naming
   4 scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) to assign names
   5 to network interfaces. This means that by default cards are not given
   6 the traditional names like `eth0` or `eth1`, whose order can change
   7 unpredictably across reboots. Instead, relying on physical locations and
   8 firmware information, the scheme produces names like `ens1`, `enp2s0`,
   9 etc.
  10
  11 These names are predictable but less memorable and not necessarily
  12 stable: for example installing new hardware or changing firmware
  13 settings can result in a [name
  14 change](https://github.com/systemd/systemd/issues/3715#issue-165347602).
  15 If this is undesirable, for example if you have a single ethernet card,
  16 you can revert to the traditional scheme by setting
  17 [](#opt-networking.usePredictableInterfaceNames)
  18 to `false`.
  19
  20 ## Assigning custom names {#sec-custom-ifnames}
  21
  22 In case there are multiple interfaces of the same type, it's better to
  23 assign custom names based on the device hardware address. For example,
  24 we assign the name `wan` to the interface with MAC address
  25 `52:54:00:12:01:01` using a netword link unit:
  26
  27 ```nix
  28 {
  29   systemd.network.links."10-wan" = {
  30     matchConfig.PermanentMACAddress = "52:54:00:12:01:01";
  31     linkConfig.Name = "wan";
  32   };
  33 }
  34 ```
  35
  36 Note that links are directly read by udev, *not networkd*, and will work
  37 even if networkd is disabled.
  38
  39 Alternatively, we can use a plain old udev rule:
  40
  41 ```nix
  42 {
  43   boot.initrd.services.udev.rules = ''
  44     SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
  45     ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
  46   '';
  47 }
  48 ```
  49
  50 ::: {.warning}
  51 The rule must be installed in the initrd using
  52 `boot.initrd.services.udev.rules`, not the usual `services.udev.extraRules`
  53 option. This is to avoid race conditions with other programs controlling
  54 the interface.
  55 :::