networking: Document how to customize NIC names

modules/ROOT/nav.adoc

@@ -22,6 +22,7 @@
 *** xref:sysctl.adoc[Kernel Tuning]
 *** xref:running-containers.adoc[Running Containers]
 *** xref:authentication.adoc[Configuring Authentication]
+*** xref:customize-nic[How to Customize a NIC Name]
 ** OS updates
 *** xref:update-streams.adoc[Update Streams]
 *** xref:auto-updates.adoc[Auto-Updates]

modules/ROOT/pages/customize-nic.adoc

@@ -0,0 +1,48 @@
+:experimental:
+= How to Customize a NIC Name
+
+== Using a `systemd` Link File
+You can create a `systemd` xref:https://www.freedesktop.org/software/systemd/man/systemd.link.html[link file] with `ignition` configs.
+
+For example, to name NIC with the MAC address `12:34:56:78:9a:bc` to "infra", place a `systemd` link file at `/etc/systemd/network/25-infra.link` using the xref:fcct-config.adoc[FCCT] configuration snippet shown below:
+
+.Example: Customize NIC via systemd Link File
+[source,yaml]
+----
+storage:
+  files:
+    - path: /etc/systemd/network/25-infra.link
+      mode: 0644
+      contents:
+        inline: |
+          [Match]
+          MACAddress=12:34:56:78:9a:bc
+          [Link]
+          Name=infra
+----
+
+== Using Udev Rules
+Similarly, also through `ignition` configs, to name NIC with the MAC address `12:34:56:78:9a:bc` to "infra", create a xref:https://linux.die.net/man/8/udev[udev rule] at `/etc/udev/rules.d/80-ifname.rules` using the xref:fcct-config.adoc[FCCT] configuration snippet shown below:
+
+.Example: Customize NIC via Udev Rules
+[source,yaml]
+----
+storage:
+  files:
+    - path: /etc/udev/rules.d/80-ifname.rules
+      mode: 0644
+      contents:
+        inline: |
+          SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="12:34:56:78:9a:bc", ATTR{type}=="1", NAME="infra"'
+----
+
+== Networking in the `initramfs` via Kernel Arguments
+If networking in the `initramfs` is required, the `dracut` argument `ifname=` dynamically creates a udev rule to change the name of a NIC. This gets applied via `ifname-genrules.sh` from the `40network` dracut module which creates a rule in the `initramfs`.
+
+For example, to name NIC with the MAC `12:34:56:78:9a:bc` to "infra", provide the argument `ifname=infra:12:34:56:78:9a:bc`. A udev rule would be created in the `initramfs` like:
+----
+# cat /etc/udev/rules.d/80-ifname.rules
+SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", ATTR{address}=="12:34:56:78:9a:bc", ATTR{type}=="1", NAME="infra"
+----
+
+Currently, unlike other parts of the networking config from the `initramfs` (e.g. static IPs, hostnames, etc.), these udev rules are not persisted into the real root. For the naming to persist into the real root, either a link file or udev rule must be created, as shown above.