nixos/docs: add section on renaming interfaces

2 files changed, 68 insertions, 0 deletions

diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml
index 02cf811e0bd3d..8369e9c9c852b 100644
--- a/nixos/doc/manual/configuration/networking.xml
+++ b/nixos/doc/manual/configuration/networking.xml
@@ -15,5 +15,6 @@
  <xi:include href="firewall.xml" />
  <xi:include href="wireless.xml" />
  <xi:include href="ad-hoc-network-config.xml" />
+ <xi:include href="renaming-interfaces.xml" />
 <!-- TODO: OpenVPN, NAT -->
 </chapter>
diff --git a/nixos/doc/manual/configuration/renaming-interfaces.xml b/nixos/doc/manual/configuration/renaming-interfaces.xml
new file mode 100644
index 0000000000000..d760bb3a4dace
--- /dev/null
+++ b/nixos/doc/manual/configuration/renaming-interfaces.xml
@@ -0,0 +1,67 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="sec-rename-ifs">
+ <title>Renaming network interfaces</title>
+
+ <para>
+  NixOS uses the udev
+  <link xlink:href="https://systemd.io/PREDICTABLE_INTERFACE_NAMES/">predictable naming scheme</link>
+  to assign names to network interfaces. This means that by default
+  cards are not given the traditional names like
+  <literal>eth0</literal> or <literal>eth1</literal>, whose order can
+  change unpredictably across reboots. Instead, relying on physical
+  locations and firmware information, the scheme produces names like
+  <literal>ens1</literal>, <literal>enp2s0</literal>, etc.
+ </para>
+
+ <para>
+  These names are predictable but less memorable and not necessarily
+  stable: for example installing new hardware or changing firmware
+  settings can result in a
+  <link xlink:href="https://github.com/systemd/systemd/issues/3715#issue-165347602">name change</link>.
+  If this is undesirable, for example if you have a single ethernet
+  card, you can revert to the traditional scheme by setting
+  <xref linkend="opt-networking.usePredictableInterfaceNames"/> to
+  <literal>false</literal>.
+ </para>
+
+ <section xml:id="sec-custom-ifnames">
+  <title>Assigning custom names</title>
+  <para>
+   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 <literal>wan</literal> to the interface
+   with MAC address <literal>52:54:00:12:01:01</literal> using a
+   netword link unit:
+  </para>
+  <programlisting>
+ <link linkend="opt-systemd.network.links">systemd.network.links."10-wan"</link> = {
+   matchConfig.MACAddress = "52:54:00:12:01:01";
+   linkConfig.Name = "wan";
+ };
+  </programlisting>
+  <para>
+   Note that links are directly read by udev, <emphasis>not networkd</emphasis>,
+   and will work even if networkd is disabled.
+  </para>
+  <para>
+   Alternatively, we can use a plain old udev rule:
+  </para>
+  <programlisting>
+ <link linkend="opt-services.udev.initrdRules">services.udev.initrdRules</link> = ''
+  SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
+  ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
+ '';
+  </programlisting>
+
+  <warning><para>
+   The rule must be installed in the initrd using
+   <literal>services.udev.initrdRules</literal>, not the usual
+   <literal>services.udev.extraRules</literal> option. This is to avoid race
+   conditions with other programs controlling the interface.
+  </para></warning>
+ </section>
+
+</section>