diff options
Diffstat (limited to 'nixos')
4 files changed, 114 insertions, 68 deletions
diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml index d48536bd48c..5dd0278569b 100644 --- a/nixos/doc/manual/configuration/networking.xml +++ b/nixos/doc/manual/configuration/networking.xml @@ -15,6 +15,6 @@ <xi:include href="../from_md/configuration/firewall.section.xml" /> <xi:include href="../from_md/configuration/wireless.section.xml" /> <xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" /> - <xi:include href="renaming-interfaces.xml" /> + <xi:include href="../from_md/configuration/renaming-interfaces.section.xml" /> <!-- TODO: OpenVPN, NAT --> </chapter> diff --git a/nixos/doc/manual/configuration/renaming-interfaces.section.md b/nixos/doc/manual/configuration/renaming-interfaces.section.md new file mode 100644 index 00000000000..affa1e0147d --- /dev/null +++ b/nixos/doc/manual/configuration/renaming-interfaces.section.md @@ -0,0 +1,51 @@ +# Renaming network interfaces {#sec-rename-ifs} + +NixOS uses the udev [predictable naming +scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) 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](https://github.com/systemd/systemd/issues/3715#issue-165347602). +If this is undesirable, for example if you have a single ethernet card, +you can revert to the traditional scheme by setting +[`networking.usePredictableInterfaceNames`](options.html#opt-networking.usePredictableInterfaceNames) +to `false`. + +## Assigning custom names {#sec-custom-ifnames} + +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: + +```nix +systemd.network.links."10-wan" = { + matchConfig.MACAddress = "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: + +```nix +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. +::: diff --git a/nixos/doc/manual/configuration/renaming-interfaces.xml b/nixos/doc/manual/configuration/renaming-interfaces.xml deleted file mode 100644 index d760bb3a4da..00000000000 --- a/nixos/doc/manual/configuration/renaming-interfaces.xml +++ /dev/null @@ -1,67 +0,0 @@ -<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> diff --git a/nixos/doc/manual/from_md/configuration/renaming-interfaces.section.xml b/nixos/doc/manual/from_md/configuration/renaming-interfaces.section.xml new file mode 100644 index 00000000000..80c162ca85e --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/renaming-interfaces.section.xml @@ -0,0 +1,62 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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 + <link xlink:href="options.html#opt-networking.usePredictableInterfaceNames"><literal>networking.usePredictableInterfaceNames</literal></link> + 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 language="bash"> +systemd.network.links."10-wan" = { + 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 language="bash"> +services.udev.initrdRules = '' + 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> |