Preview Early-Boot Network Setup with nm-initrd-generator

nm-initrd-generator builds the network profile your machine uses before its root filesystem is even mounted. This guide gets you previewing DHCP and static setups safely, in about fifteen minutes, without touching a real initrd. The examples use NetworkManager 1.46.0 from the installed network-manager package.

You need a shell and an initrd that uses NetworkManager. The command itself needs no elevated privileges when you only generate output to a test directory or use --stdout.

1. Confirm the tool and what it actually does

nm-initrd-generator runs before the normal system instance of NetworkManager. It reads kernel command-line arguments and writes profiles and supporting configuration for the NetworkManager instance living in the initial ramdisk. That is all it does: it is a generator, not a long-running network service, and not a replacement for nmcli once the real system is up.

On this installation the executable sits under /usr/libexec, while the package also ships the manual page:

$ dpkg-query -W -f='${Package} ${Version}\n' network-manager
network-manager 1.46.0-1ubuntu2.8
$ /usr/libexec/nm-initrd-generator --help

• Note the command shape. Options come first, then --, then the kernel-style arguments.
• Keep that separator. Drop it and an argument meant for the simulated kernel command line can get eaten as a generator option instead.

2. Preview a DHCP configuration

Start with --stdout. It sends the generated connection data to your terminal for debugging, and never touches the normal initrd locations:

$ /usr/libexec/nm-initrd-generator --stdout -- rd.neednet ip=dhcp

*** Configuration '15-carrier-timeout.conf' ***

[device-15-carrier-timeout]
match-device=*
carrier-wait-timeout=10000

*** Connection 'default_connection' ***

[connection]
id=Wired Connection
type=ethernet
...

[ipv4]
dhcp-timeout=90
may-fail=false
method=auto

Your own output will carry a generated UUID and possibly extra sections. Do not treat those values as stable identifiers worth copying into a boot loader. The checks that matter: a connection was generated, and IPv4 uses DHCP.

$ /usr/libexec/nm-initrd-generator --stdout -- rd.neednet ip=dhcp
$ printf 'generator status: %s\n' "$?"
generator status: 0

3. Preview a static address and DNS server

For a static example, swap in addresses that are actually valid for the boot network before you use this anywhere real. The ip value carries address, gateway, netmask, hostname, interface and autoconfiguration mode in the dracut command-line format, and nameserver adds DNS to the generated profile:

$ /usr/libexec/nm-initrd-generator --stdout -- \
    'ip=192.0.2.10::192.0.2.1:255.255.255.0:host.example:eth0:none' \
    'nameserver=192.0.2.53'

• Result on NetworkManager 1.46.0. A connection named eth0, with interface-name=eth0, a manual IPv4 method, address 192.0.2.10/24, gateway 192.0.2.1, and the requested DNS server.
• Hostname data too. It also writes hostname information in the initrd-data directory when run with its normal output locations, not --stdout.
• Documentation addresses only. The ranges above are reserved for exactly this purpose; do not paste them into a real boot configuration. Use your actual address, gateway, mask, hostname and interface, and quote the whole ip= argument so the shell does not mangle it.

4. Know where the files go

Without --stdout, the generator falls back to initrd-oriented defaults. The installed help reports these paths:

• --connections-dir, default /run/NetworkManager/system-connections, for generated connection profiles.
• --persistent-connections-dir, default /etc/NetworkManager/system-connections, for persistent profiles already available to the initrd.
• --initrd-data-dir, default /run/NetworkManager/initrd, for initrd data such as the hostname.
• --sysfs-dir, default /sys, for the sysfs mount point.
• --run-config-dir, default /run/NetworkManager/conf.d, for generated configuration files.

Those defaults are implementation details of this installed build, so recheck --help after an upgrade. If you are testing outside an actual initrd, hand the generator temporary directories explicitly rather than letting a test write into the host's /run or /etc.

5. Test with isolated output directories

Use a scratch directory for a write-mode test. This is still an ordinary command, but it does create files, so keep it contained:

$ test_dir=$(mktemp -d)
$ mkdir -p "$test_dir/connections" "$test_dir/persistent" \
    "$test_dir/initrd" "$test_dir/sysfs" "$test_dir/run-config"
$ /usr/libexec/nm-initrd-generator \
    --connections-dir "$test_dir/connections" \
    --persistent-connections-dir "$test_dir/persistent" \
    --initrd-data-dir "$test_dir/initrd" \
    --sysfs-dir "$test_dir/sysfs" \
    --run-config-dir "$test_dir/run-config" -- \
    rd.neednet ip=dhcp
$ find "$test_dir" -maxdepth 3 -type f -print

That last command is the verification point: it should list files under the directories you supplied. No sudo needed for this isolated test. Clean up once you are done inspecting:

$ rm -rf -- "$test_dir"

6. Watch rd.neednet and existing profiles interact

rd.neednet declares that networking is needed in the initrd. On its own, with no other usable network description, it can make the generator create a default connection. A persistent-connections directory changes that: if it exists, rd.neednet alone stops causing a default connection to appear when nothing else relevant is present.

This trips people up during troubleshooting: a missing default profile does not automatically mean DHCP is broken.

• Check for persistent profiles in the initrd first.
• Inspect the full kernel command line for ip, bootdev, rd.bootif and related arguments.
• Remember unrecognised options are ignored, while malformed ones produce an error message. Treat a non-zero status or stderr output as a generation failure.

7. Know where it differs from dracut's network-legacy

This generator builds connections for NetworkManager, and it does not reproduce every behaviour of dracut's network-legacy module. Notably, NetworkManager does not wait for a static gateway to answer ARP before proceeding. If a boot process relied on that wait as a reachability test, you need a separate readiness check rather than assuming the generator provides one.

NetworkManager also gives command-line hostnames precedence over DHCP-supplied ones, and when several hostnames turn up on the command line, the last one wins. Keep contradictory hostname arguments out of a boot loader entry. For specialised hardware, this 1.46.0 manual documents ib.pkey for IPoIB partitions, rd.ethtool for interface autonegotiation and speed, and rd.net.dhcp.dscp for selected DHCP DSCP values; check the matching dracut.cmdline(7) value format before using any of them.