Test Kernel Network Settings with systemd-network-generator

You will finish with a safe way to see how systemd-network-generator turns kernel command-line settings into temporary systemd-networkd configuration. You will test DHCP, link-local addressing and a VLAN in an alternate root, then know where to inspect the files used during a real boot.

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 recognise 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. It is not a systemd.generator despite its name. Check the local package before relying on an example:

$ 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.

Checkpoint: the binary exists and its help shows the --root=PATH test option. The option matters because it lets you generate files under a temporary directory rather than writing the host's /run.

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. The directory is under /tmp, so the real /run/systemd/network/ is not touched:

$ 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]

The output confirms the important boundary: the generator wrote a .network file in the runtime network directory. The generated file is consumed by systemd-networkd.service; the generator does not itself bring 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 can make later boot parameters and persistent network files difficult to reason about.

3. Check the link-local exception

The manpage records a special value, ip=link-local. It 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]

Checkpoint: DHCP and Router Advertisements are explicitly off in this result. Link-local addressing is useful for a deliberately isolated or self-configuring link, but it is not a substitute for a route to a normal LAN or the internet.

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:

$ 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 file names and affect ordering. The example creates the VLAN definition and attaches it to the named parent, but it does not provide an address by itself. A separate network policy, or another kernel command-line setting such as an appropriate ip= value, must determine how the VLAN is configured.

5. Inspect a real boot without regenerating it

On a running machine, generated files are placed 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. The status output should show a completed service when generation succeeded. Reading the unit and runtime files is normally unprivileged, although a host's permissions may require sudo for some diagnostics.

For service logs, use 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. First save the error, check the kernel command line and confirm that the interface names and parameter syntax are valid.

6. Apply a boot parameter only with a recovery path

Changing the bootloader's kernel command line is a service-disrupting operation. It may remove your only remote route, create a VLAN with the wrong parent, or select an address that conflicts 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 parameters comes from dracut.cmdline(7) and the related systemd documentation; do not invent a value from the option name alone.

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