Generate and Inspect Early-Boot NetworkManager Profiles

You will finish with a safe way to turn initrd kernel command-line arguments into NetworkManager connection profiles, inspect the generated result, and recognise when a persistent profile changes the outcome. The examples use NetworkManager 1.46.0 from the installed network-manager package. Allow about fifteen minutes. You need a shell and an initrd that uses NetworkManager; the command itself does not need elevated privileges when you only generate output in a test directory or use --stdout.

1. Confirm the installed tool and its role

nm-initrd-generator runs before the normal system instance of NetworkManager. It scans kernel command-line arguments and writes profiles and supporting configuration for the NetworkManager instance in the initial ramdisk. It is a generator, not a long-running network service and not a replacement for nmcli on the booted system.

On this installation the executable is under /usr/libexec, while the package also provides 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

The help output shows the command shape: options come first, then --, then the kernel-style arguments. Keep that separator. Without it, an argument intended for the simulated kernel command line can be consumed as a generator option.

2. Preview a DHCP configuration

Start with --stdout. This sends generated connection data to the terminal for debugging and avoids asking the generator to write 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 output includes a generated UUID and may contain additional sections. Those values are not stable identifiers to copy into a boot loader. The useful checks are that a connection was generated and that IPv4 uses DHCP. The command exits with status 0 for a successful run:

$ /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, replace the placeholder values with addresses valid for the boot network. The ip value below supplies address, gateway, netmask, hostname, interface and autoconfiguration mode in the dracut command-line format. The nameserver argument adds DNS information 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'

On NetworkManager 1.46.0 this produces 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. It also writes hostname data in the initrd-data directory when the command is run with its normal output locations.

Do not paste these documentation addresses into a real boot configuration. The ranges in this example are reserved for documentation. Use the actual address, gateway, mask, hostname and interface for your environment, and quote the complete ip= argument so the shell does not reinterpret it.

4. Understand where files go

Without --stdout, the generator uses 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.

The exact defaults are implementation details of this installed build, so check --help after upgrading. If you are testing outside an actual initrd, give the generator temporary directories explicitly rather than allowing a test to write into the host's /run or /etc.

5. Test with isolated output directories

Use a temporary directory for a write-mode test. This is an ordinary command, but it creates files under the directory you choose:

$ 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

The final command is the verification point: it should list files under the directories you supplied. The generator does not need sudo for this isolated test. Remove the temporary directory when you have finished inspecting it:

$ rm -rf -- "$test_dir"

This removal is safe only because test_dir was assigned by mktemp -d and is still visible in your shell. Never substitute a broad path such as /run, /etc or an unset variable in a recursive removal command.

6. Account for rd.neednet and existing profiles

rd.neednet expresses that networking is needed in the initrd. When it appears without another usable network description, the generator can create a default connection. The persistent-connections directory changes that rule: if the directory exists, rd.neednet does not by itself cause a default connection to be generated when no other relevant options are present.

This is a common distraction during troubleshooting. A missing default profile does not automatically mean that DHCP is broken. Check whether the initrd contains persistent profiles, then inspect the complete kernel command line for ip, bootdev, rd.bootif and related arguments. Also remember that unrecognised options are ignored, while malformed options produce an error message. Treat a non-zero status or an error on standard error as a generation failure.

7. Know the NetworkManager differences

This generator produces a set of connections for NetworkManager. It does not reproduce every behaviour of dracut's network-legacy module. In particular, NetworkManager does not wait for a static gateway to answer ARP before proceeding. If a boot process depended on that wait as a reachability test, design a separate readiness check rather than assuming the generator provides one.

NetworkManager also gives command-line hostnames precedence over DHCP hostnames, and when several hostnames occur on the command line, the last one wins. Avoid putting contradictory hostname arguments in 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. Use those only after checking the matching dracut.cmdline(7) value format.