Description

nm-initrd-generator scans the command line for options relevant to network configuration and creates configuration files for an early instance of NetworkManager run from the initial ramdisk during early boot.

Options

Running NetworkManager in the initrd

nm-initrd-generator only writes configuration; it is a separate NetworkManager instance that applies it. NetworkManager ships the systemd units for that instance, so any systemd-based initramfs can use them, not only dracut(8). They are:

The units carry no [Install] section and cannot be enabled with systemctl enable. NetworkManager instead installs a systemd system generator, nm-initrd-generator.sh, which wires them into initrd.target.wants when SYSTEMD_IN_INITRD is 1, additionally linking NetworkManager-wait-online-initrd.service into network-online.target.wants, and masks them on the real root. It masks the host units inside the initrd for the same reason: NetworkManager.service and NetworkManager-initrd.service both claim the org.freedesktop.NetworkManager bus name, so only one of them may be active at a time. An initramfs that includes the generator script therefore does not need to create any .wants symlinks itself. The script is a bash script and uses arrays, so an image that provides only a minimal sh must include bash as well; systemd skips a generator it cannot execute without reporting an error, and the units then never run. Note that some distributions do not ship the generator or the initrd units, and rely on their own equivalents instead.

The generated profiles live in /run/NetworkManager/system-connections, which systemd carries over into the real root at switch-root. The NetworkManager instance on the real root reads the same directory through its keyfile plugin, so a connection configured in the initrd keeps its UUID and stays active. A profile named Wired Connection on a running system normally originates this way.

An initramfs other than dracut's has to supply the environment these units expect. All three assert /etc/initrd-release, so that file has to exist in the image. NetworkManager-initrd.service is Type=dbus and binds to dbus.service: a bus implementation, its configuration and NetworkManager's D-Bus policy file (org.freedesktop.NetworkManager.conf) must be present, and the bus must be reachable at the point the unit runs, and not only once a late target such as sockets.target has been reached. The image also needs the kernel module for the network interface, and, if an ip argument names an interface, whatever udev link configuration the running system uses to arrive at that name. An initramfs that omits it will present the kernel name instead, which such an ip argument then fails to match.

None of these units is ordered against the encryption stage. Where the root device is encrypted and the network exists in order to deliver its passphrase, that ordering has to be added, and an ordering dependency alone is not enough: systemd-cryptsetup@.service is generated with After=cryptsetup-pre.target and nothing pulls that target into the transaction, so a unit that is merely Before=cryptsetup-pre.target is ordered against a target that never runs and has no effect. Declare both Wants=cryptsetup-pre.target and Before=cryptsetup-pre.target, and make sure the target itself is present in the image; a dependency naming a unit the image does not contain is dropped without a diagnostic. Note also that NetworkManager-wait-online-initrd.service runs with NM_ONLINE_TIMEOUT set to 3600. Once it precedes the encryption stage, an interface that never comes up delays the passphrase prompt for that long, so a shorter timeout is usually wanted.

Differences from the network-legacy dracut module

nm-initrd-generator generates a set of connections that are then configured by the NetworkManager instance running in the initrd. There are some differences in behavior compared to the network-legacy dracut module:

Propagation to the real root

The profiles are written to /run/NetworkManager/system-connections and are tagged with the org.freedesktop.NetworkManager.origin user setting, whose value is nm-initrd-generator.

/run is carried over when the initrd switches to the real root, so those profiles are still there when the second NetworkManager instance starts. It reads them and keeps the interfaces configured as the initrd left them. This is deliberate: it is what allows a system whose root filesystem is on the network to switch root without interrupting connectivity.

On a system that boots from local storage the propagation is usually not wanted, because the persistent profiles in /etc/NetworkManager/system-connections are meant to take over. To suppress it, drop a file in /etc/NetworkManager/conf.d containing:

[device]
keep-configuration=no
allowed-connections=except:origin:nm-initrd-generator

keep-configuration=no stops NetworkManager from adopting the existing interface configuration, so it activates the most suitable persistent profile instead; allowed-connections then prevents the initrd profiles from being activated at all. Both keys are described in NetworkManager.conf(5). A [device] section without a match-device key applies to every device; add one only to restrict the setting to particular interfaces.

This stops the initrd profiles from being used, but does not remove them. They stay visible as inactive profiles in nmcli connection show until the next boot, since /run does not survive a reboot. To remove them earlier, delete them with nmcli connection delete.

Exit Status

nm-initrd-generator exits with status 0. It ignores unrecognized options and prints an error message if it encounters a malformed option.

See Also

dracut.cmdline(7), NetworkManager(8), NetworkManager.conf(5), nm-settings-nmcli(5).