nixos: nixos/doc/manual/configuration/renaming-interfaces.xml to CommonMark

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.&quot;10-wan&quot; = {
+  matchConfig.MACAddress = &quot;52:54:00:12:01:01&quot;;
+  linkConfig.Name = &quot;wan&quot;;
+};
+</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==&quot;net&quot;, ACTION==&quot;add&quot;, DRIVERS==&quot;?*&quot;, \
+  ATTR{address}==&quot;52:54:00:12:01:01&quot;, KERNEL==&quot;eth*&quot;, NAME=&quot;wan&quot;
+'';
+</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>