Test Kernel Network Settings with systemd-network-generator

systemd-network-generator turns kernel command-line settings like ip= into temporary systemd-networkd configuration. You can watch it do that safely in an alternate root, testing DHCP, link-local addressing and a VLAN, before ever touching a real boot parameter.

Allow about fifteen minutes. You need a shell on a system with systemd 255, the installed systemd-network-generator binary, and enough knowledge of the host's network design to spot a wrong interface or VLAN. The examples below do not alter the running host. A real boot-parameter change can affect connectivity and needs a recovery route.

1. Check the installed version and command shape

The installed manpage describes this as a system service that translates ip= and related kernel parameters into systemd.network, systemd.netdev and systemd.link files. Despite the name, it is not itself a systemd.generator. Check the local package before trusting any example, including this one:

$ systemd --version
systemd 255 (255.4-1ubuntu8.17)
$ /usr/lib/systemd/systemd-network-generator --help
systemd-network-generator [OPTIONS...] [-- KERNEL_CMDLINE]
  -h --help                       Show this help
     --version                    Show package version
     --root=PATH                  Operate on an alternate filesystem root

The version string is distribution-specific. This guide was checked against systemd 255.4-1ubuntu8.17; other systemd releases can add or change command-line details.

2. Generate a DHCP configuration in a temporary root

Create a disposable directory and pass one kernel command-line setting after --. This is an ordinary, unprivileged test, and because the directory sits under /tmp, the real /run/systemd/network/ stays untouched:

$ testroot=$(mktemp -d /tmp/systemd-network-generator-guide.XXXXXX)
$ mkdir -p "$testroot/run/systemd/network"
$ /usr/lib/systemd/systemd-network-generator --root="$testroot" -- 'ip=dhcp'
$ find "$testroot/run/systemd/network" -maxdepth 1 -type f -printf '%f\n'
71-default.network
$ sed -n '1,80p' "$testroot/run/systemd/network/71-default.network"
# Automatically generated by systemd-network-generator

[Match]
Kind=!*
Type=!loopback

[Link]

[Network]
DHCP=ipv4

[DHCP]

That output confirms the important boundary: the generator wrote a .network file into the runtime network directory. The generated file is consumed by systemd-networkd.service; the generator itself never brings an interface up.

Do not copy 71-default.network into /etc/systemd/network/ as a permanent configuration. It is generated output, and hand-copying it makes later boot parameters and persistent network files much harder to reason about.

3. Check the link-local exception

The manpage records a special value, ip=link-local, which requests IPv4LL and IPv6LL addressing only, with DHCP and IPv6 Router Advertisements disabled. Test it with a separate temporary root:

$ linkroot=$(mktemp -d /tmp/systemd-network-generator-guide.XXXXXX)
$ mkdir -p "$linkroot/run/systemd/network"
$ /usr/lib/systemd/systemd-network-generator --root="$linkroot" -- 'ip=link-local'
$ sed -n '1,80p' "$linkroot/run/systemd/network/71-default.network"
# Automatically generated by systemd-network-generator

[Match]
Kind=!*
Type=!loopback

[Link]

[Network]
DHCP=no
LinkLocalAddressing=yes
IPv6AcceptRA=no

[DHCP]

4. Preview a VLAN without changing the host

The same generator can translate vlan= into a netdev and a network attachment. In this example the VLAN is named vlan10 and its parent interface is enp1s0. Use names that really exist on the target host when you prepare a boot configuration for real:

$ vlanroot=$(mktemp -d /tmp/systemd-network-generator-guide.XXXXXX)
$ mkdir -p "$vlanroot/run/systemd/network"
$ /usr/lib/systemd/systemd-network-generator --root="$vlanroot" -- 'vlan=vlan10:enp1s0'
$ find "$vlanroot/run/systemd/network" -maxdepth 1 -type f -printf '%f\n'
70-vlan10.netdev
70-enp1s0.network
$ sed -n '1,40p' "$vlanroot/run/systemd/network/70-vlan10.netdev"
# Automatically generated by systemd-network-generator

[NetDev]
Kind=vlan
Name=vlan10
$ sed -n '1,60p' "$vlanroot/run/systemd/network/70-enp1s0.network"
# Automatically generated by systemd-network-generator

[Match]
Name=enp1s0

[Link]

[Network]
VLAN=vlan10

[DHCP]

The numeric prefixes are part of the generated filenames and affect ordering. This example creates the VLAN definition and attaches it to the named parent, but it does not hand out an address by itself. A separate network policy, or another kernel command-line setting such as an appropriate ip= value, has to determine how the VLAN gets configured.

5. Inspect a real boot without regenerating it

On a running machine, generated files land in /run/systemd/network/. Read them before changing anything:

$ find /run/systemd/network -maxdepth 1 -type f -printf '%f\n' -exec sed -n '1,100p' {} \;
$ systemctl cat systemd-network-generator.service
$ systemctl status systemd-network-generator.service --no-pager

The unit is a oneshot service with RemainAfterExit=yes. It runs before the network preparation target and before systemd-udevd.service, and the status output should show a completed service when generation succeeded. Reading the unit and runtime files is normally unprivileged, though a host's permissions may require sudo for some diagnostics.

For service logs, reach for elevated access only if the journal is not readable to your account:

$ sudo journalctl -u systemd-network-generator.service --no-pager

A failure here can leave networkd without the intended generated policy. Do not respond by repeatedly restarting network services on a remote host. Save the error first, check the kernel command line, and confirm the interface names and parameter syntax are actually valid.

6. Apply a boot parameter only with a recovery path

Changing the bootloader's kernel command line is a service-disrupting operation. It can remove your only remote route, create a VLAN with the wrong parent, or select an address that clashes with another machine. Keep console or out-of-band access available, record the previous command line, and schedule the change for a maintenance window.

The generator reads settings such as ip=, nameserver=, rd.route=, rd.peerdns=, ifname=, net.ifname-policy=, vlan=, bond=, bridge= and bootdev=. The detailed syntax for these comes from dracut.cmdline(7) and the related systemd documentation, so do not invent a value purely from the option name.

If the next boot goes wrong, select the previous boot entry or remove the new parameter at the bootloader prompt, then restore the persistent bootloader configuration once the host is reachable again. The generated files live under /run, which is temporary, so correcting the kernel command line and rebooting regenerates them on its own. Do not hand-edit generated files as a lasting fix.