systemd_networkd_file
systemd_networkd_file manages one .network or .netdev file on a node,
the Linux server MMX manages. It writes the file in /etc/systemd/network
and activates it with networkctl reload. The service must already be
running; MMX does not install or switch network managers. Use this module
on a node whose network is managed by systemd-networkd. The
Netplan file module supports Netplan, the
NetworkManager file module supports
NetworkManager, and the
ifupdown file module supports ifupdown.
Choose the module for the node's tool
says which tool the measured test images use. The inputs work alike in all
four modules, as
Inputs shared by all four modules
describes.
The module takes the whole file in systemd-networkd's own format.
Addresses, routes, DNS, bridges, and VLANs stay in systemd-networkd's format.
MMX does not give network settings a second set of fields. A .network
file configures a card or another device. A .netdev file declares a
virtual device, such as a bridge, a bond, or a VLAN. .link files are refused.
A wrong network file can cut the node off from your controller machine,
where you run mmx. Before changing the file, MMX saves its previous state
and arms a systemd timer on the node. Your running mmx command must prove
reachability over new connections before and after activation. If the proof
fails, the node restores the previous file and reloads systemd-networkd by
itself. It does this even if the controller machine disconnects, the node
job worker process dies, or the node restarts. The
execution design
defines the requirements for reachability confirmation and owed restore.
Inputs
name(string; required): One .network or .netdev filename in /etc/systemd/network; .link files are refused.content(string; optional): The complete file text; exactly one of content and template is required for a present file.template(string; optional): A Go template on the controller machine, relative to the project or role directory.state(presentorabsent; defaultpresent): Absent removes the file, its running configuration, and its declared virtual devices that no other file declares. Remove references from other .network files first.restore_unless_controller_confirms_within(string; default2m): How long the node waits after the change for the controller process to confirm reachability before restoring the previous file. Activation uses part of this time. The wait before the change has the same limit.
Outputs
The node task's result holds these fields. A later node task reads them as .node_tasks.<id>.<field>, where <id> is the node task's id.
statuschangereason
What a dryrun reports
Compares the file and reports device removals without writing or activating anything. Missing prerequisites are not checked.
Retries and time limits
Runs once; rejects retry, time_limit, and time_limit_per_try, and ignores node_task_defaults; restore_unless_controller_confirms_within bounds the change.
Examples
A second network card
This complete playbook gives a second card an address. Replace enp6s0
with the second card's name on your node. The playbook leaves the main
card's file alone.
fleet_stages:
- id: network
nodes: web01
node_tasks:
- systemd_networkd_file:
name: 20-second.network
content: |
[Match]
Name=enp6s0
[Network]
DHCP=no
Address=10.0.0.5/24
restore_unless_controller_confirms_within: 2m
On node web01, MMX writes /etc/systemd/network/20-second.network and
reloads systemd-networkd with networkctl reload alone. Choose the
filename and match so that systemd-networkd selects 20-second.network for
the second card.
Run mmx dryrun <playbook> first, then mmx run <playbook>. Each changed
file waits for confirmation before the next node task starts. An unchanged
file causes no reload or confirmation wait.
A bridge with a second card as its port
Each file is a separate node task with a separate restore. Keep the main
card's existing connectivity in every intermediate configuration. There is
no transaction across files and no automatic recovery of a whole node task
block. For a bridge with a second physical card as a port, create the
bridge's .netdev first, then its .network file, then attach the card in
the card's own .network file. Use these node tasks in this order under
the playbook's node_tasks:
- systemd_networkd_file:
name: 20-app-bridge.netdev
content: |
[NetDev]
Name=appbr0
Kind=bridge
- systemd_networkd_file:
name: 21-app-bridge.network
content: |
[Match]
Name=appbr0
[Network]
Address=10.0.8.5/24
ConfigureWithoutCarrier=yes
- systemd_networkd_file:
name: 22-second.network
content: |
[Match]
Name=enp6s0
[Network]
Bridge=appbr0
Remove 22-second.network first, then 21-app-bridge.network, then
20-app-bridge.netdev. Each removal is a node task with the removed file's
filename in name and state: absent:
- systemd_networkd_file: {name: 22-second.network, state: absent}
- systemd_networkd_file: {name: 21-app-bridge.network, state: absent}
- systemd_networkd_file: {name: 20-app-bridge.netdev, state: absent}
Removing 20-app-bridge.netdev, which declares appbr0, removes that
file, the bridge's running address, and appbr0 itself. Whatever was
attached to the bridge, such as the network of a container or VM, loses
that bridge. Remove references to the bridge from other .network files
first. The bridge's own .network file, which only matches appbr0 and
assigns its address, can stay: it does not refer to a device it depends on.
A VLAN on the second card
For a VLAN on the second card, first declare the device, then attach it to its parent, then give it an address. Keep the parent card's existing connectivity in every step.
- systemd_networkd_file:
name: 20-app-vlan.netdev
content: |
[NetDev]
Name=appvlan0
Kind=vlan
[VLAN]
Id=71
- systemd_networkd_file:
name: 21-second.network
content: |
[Match]
Name=enp6s0
[Network]
VLAN=appvlan0
- systemd_networkd_file:
name: 22-app-vlan.network
content: |
[Match]
Name=appvlan0
[Network]
Address=10.0.71.5/24
Remove them in reverse order: 22-app-vlan.network, 21-second.network,
then 20-app-vlan.netdev, using state: absent and no content.
A second address on a card
For a second address on a card, put both addresses in its one .network
file. Systemd-networkd uses the first matching .network, not the combined
contents of several matching files. If MMX owns 20-second.network, replace
its complete content with:
- systemd_networkd_file:
name: 20-second.network
content: |
[Match]
Name=enp6s0
[Network]
DHCP=no
Address=10.0.0.5/24
Address=10.0.0.6/24
To remove just the second address, replace the file again with only the
first Address=. To remove all settings from 20-second.network, use
state: absent. Do not leave another earlier file matching enp6s0.
MMX does not remove or rewrite the earlier matching .network file.
Do not remove the node address used by the controller machine to connect
to the node.
How it works
A run follows the steps of
What a run does, which
all four network modules share. Removal follows
What state: absent removes,
and several files follow
Several files run in playbook order.
The rest of "How it works" describes behavior particular to systemd-networkd.
The file and its metadata
A .network file is owned by root:root, mode 0644. A .netdev file is
owned by root:systemd-network, mode 0640. The group must exist:
systemd-networkd runs as its own user and must read the file. A .netdev
can hold a key, so MMX does not make it readable by everyone. MMX creates
a missing destination directory as root:root, mode 0755, and leaves an
existing directory alone. Files get the SELinux label of their destination.
Existing symlinks, directories, and special files at the destination are
refused. Secrets in content or a template hide the task's result text and
file difference.
For absent, omit content and template. The node task runs once;
retry, time_limit, and time_limit_per_try are refused. Project
defaults for these fields do not apply.
Dryrun renders and compares the file, checks the device refusals below,
and lists intended device removals. It writes no candidate, record, or unit
and activates nothing. Missing tools, a missing group, or a stopped service
give not_checked; acceptance and reachability after activation are not
checked.
Activation and its check
There is no native check before installation. After installation, MMX
runs networkctl reload alone. MMX never runs networkctl reconfigure.
Before the reload, MMX takes the journal position with
journalctl --no-pager -n 1 -o cat --show-cursor. After the reload
returns, MMX runs journalctl --sync, then reads once with
journalctl --no-pager --cursor <cursor> -u systemd-networkd.service -n 200 -o json --output-fields=__CURSOR,PRIORITY,MESSAGE,CONFIG_FILE,CONFIG_LINE,SYSLOG_IDENTIFIER,_SYSTEMD_UNIT.
MMX discards only the entry whose __CURSOR equals the saved position. The
position may belong to another service, so the first returned entry is not
discarded merely because it is first. A missing or unreadable entry cursor
fails the check. There is no sleep or link-state poll: the service writes
file diagnostics while it reads files in the reload call.
A warning or an error of the service that names this file fails the task;
these entries have priorities from 0 through 4. MMX uses the entry's
configuration-file field, CONFIG_FILE, when present, otherwise the exact
path in the message with filename boundaries. It accepts the measured
colon, quote, and sentence-ending period forms, and does not match a
drop-in, backup, or longer filename. Ordinary information about configuring
a link, at priority 6, does not fail the task. A failed position,
synchronization, read, or decoding fails the check. Reaching the 200-entry
cap or the command output limit also fails: the earlier entries might be
missing.
This catches what systemd-networkd logs about the file. It does not prove that every setting was understood. With systemd 252.23, an assignment outside a section produced no warning naming the file. The module does not add a second parser that validates native settings. Reachability also does not prove that the requested address, route, or DNS setting works for the user's application. Add the application's own checks.
Devices that a .netdev declares
To identify the devices of one file, MMX reads [NetDev] Name= and a
veth's [Peer] Name= in a .netdev. A veth declaration also owns its
named peer. When inspecting other .netdev files and drop-ins, a
[Peer] Name= protects that name even without a local Kind=veth: a
drop-in can inherit the kind from its main file. The reader removes a UTF-8
byte-order mark, and keeps ordered sections and assignments, including
resets, quotes, and continued lines. This limited reading supports
ownership and removal; it does not turn the file's settings into MMX inputs.
Device names must be literal, without systemd % specifiers. MMX also
refuses a managed .netdev with .conf drop-ins in any of the three
directories /etc/systemd/network, /run/systemd/network, and
/usr/lib/systemd/network: another file must not change the device
identity or settings behind the managed file. Put its complete definition
in the managed file first. These limits let MMX identify exactly which
devices that one file declares and can restore.
A .netdev is a recipe for creating a device. If its device already exists,
MMX permits only the same parsed settings in the same order: the same
sections, keys, and values. Comments, blank lines, and spaces around = do
not count as settings changes. File ownership and permissions can also be
corrected without changing settings. Any other change of a .netdev whose
device exists fails before MMX changes anything; see
the errors.
Order between .netdev and .network files
Before removing a .netdev device or renaming it, MMX scans all .network
files and their drop-ins in /etc/systemd/network, /run/systemd/network,
and /usr/lib/systemd/network. MMX does not restrict the scan to files
selected by systemd-networkd. Any [Network] key whose value, or one of
the key's space-separated values, names the device being removed or renamed
is a reference. MMX checks every
[Network] key, regardless of the key's meaning. A [Match] Name=appbr0
alone is not a reference. MMX refuses removal or renaming while a
reference exists.
The same scan also runs before adding a .netdev or changing its device
name. If a .network file already refers to the new name, MMX refuses.
Both order checks run before any change, including in dryrun.
What removal does
state: absent removes three things:
- the named file;
- the running configuration that the file gave the node, such as an address or a route;
- every virtual device that the file declared and no other file declares, such as a bridge, a bond, or a VLAN device.
Removing a .network file removes its running settings, not the device
of a separate .netdev. MMX never deletes a physical card, another file,
or a device declared by another .netdev. Before a deletion, it checks
that the device's sysfs path resolves below /sys/devices/virtual/net/ and
that no other .netdev in the three directories declares it. Forward
deletion also requires that the previous file declared the device and the
proposed file does not. MMX checks the virtual status and the other
declarations again immediately before each deletion, deletes with
networkctl delete <name>, and checks that the device is gone. Renaming
an unreferenced device in a .netdev removes the old device after reload
and creates the new one.
What a restore puts back
A failed activation or check starts restoration immediately. Missing
reachability confirmation starts restoration when the node's deadline passes.
The restore puts back the previous bytes, owner, group, permissions, and
modification time, or removes the new file if none existed. It reloads
systemd-networkd and deletes each device the proposed file declared that did
not exist before the change. This also applies when the previous file declares
the same name: a device absent before the change is absent after restoration.
These deletions still require a virtual device with no other .netdev
declaration, but they do not refuse because a .network file refers to it.
The creation-order check prevents an earlier reference from creating that
conflict in normal use. Restoration does not reject warnings the previous
file already caused: it skips the journal check. It verifies successful
activation and deletion commands and that devices it had to delete are gone.
Before reloading the previous configuration, the restore gives
systemd-networkd up to ten seconds to finish configuring cards during
startup. It runs systemd-networkd-wait-online --timeout=10, looked up in
/usr/lib/systemd/ and then /lib/systemd/. It skips the wait when the
program is missing and ignores its output and exit code. Forward activation
does not wait. A restore therefore takes up to ten seconds longer while a
card required for "online" cannot finish its configuration.
This restores configuration, not a snapshot of dynamic DHCP leases or every
kernel setting. It does not put back a physical device, undo another file's
changes, or recreate a VM or container attached to a removed bridge.
A restored change remains a failed, changed node task. mmx status <run-id>
shows the current restore outcome, also for an interrupted node job.
A failed restore keeps the saved state and refuses another task for that file.
After correcting its cause, start the service named in the failure message:
systemctl start mmx-owed-restore-<owed-restore-id>.service on the node.
Errors and what they mean
The texts shared by all four network modules, such as an expired confirmation, a restore that is still owed, and a failed restore, are in Results and failure reasons. The texts particular to systemd-networkd:
| The reason holds | What the reason means, and what to do |
|---|---|
systemd_networkd_file refuses 20-eth1.link: .link files cannot be activated and restored by reloading systemd-networkd. |
name ends in .link. Manage such a file another way; see Why it works this way. |
Cannot change network configuration file /etc/systemd/network/20-eth1.network: systemd-networkd.service is not running. |
The service is stopped. Start it in an earlier node task. A missing tool or a missing systemd-network group also fails a run. A dryrun reports each of them not checked, because an earlier node task may provide it. |
systemd-networkd did not accept <path>: <tool diagnostic>. |
The reload failed, or the service logged a warning or an error that names the file. The node restores the previous file at once. |
Cannot check whether systemd-networkd accepted <path>: <diagnostic>. |
MMX could not read the journal completely. The check fails, and the node restores. |
Cannot change <path> while device <name> exists: ... |
The settings of an existing device changed; see below. |
Cannot add <path>: device <name> already exists and was not created by the .netdev file. |
The file declares a device that already exists, and the previous file did not declare it. The refusal covers physical cards and devices another program created. |
Cannot remove device <name> declared in <path>: <other path> still refers to the device (<Key>=<value>). Remove the device reference from the referring file first. |
Another .network file refers to the device; see below. |
Cannot add <path>: <other path> already refers to device <name> (<Key>=<value>). Add the .netdev file before installing the file that refers to the device. |
A .network file refers to the device before its .netdev exists; see below. |
A settings change of an existing device fails before MMX changes anything:
Cannot change /etc/systemd/network/20-app-bridge.netdev while device appbr0 exists: systemd-networkd applies a .netdev file only when systemd-networkd creates the device. Remove the device first with state: absent, then add the new .netdev file.
Remove the device with state: absent first, then add the new file. There
is no automatic device recreation option.
Removal or renaming is refused while any .network file or its drop-in
refers to the device in [Network]. For example:
cannot remove device appbr0 declared in /etc/systemd/network/20-app-bridge.netdev: /etc/systemd/network/22-second.network still refers to the device (Bridge=appbr0). Remove the device reference from the referring file first
Remove or change the referring file first, as the bridge example does.
MMX also checks references before adding a .netdev or renaming the
declared device. MMX refuses when a .network file or drop-in already
refers to the new device name in /etc/systemd/network,
/run/systemd/network, or /usr/lib/systemd/network:
cannot add /etc/systemd/network/20-app-bridge.netdev: /etc/systemd/network/22-second.network already refers to device appbr0 (Bridge=appbr0). Add the .netdev file before installing the file that refers to the device
Remove the referring file, add the .netdev, then add the referring file
again.
Tested on
Distributions: Debian 12 and 13.
The suite tests/integration/systemd_networkd_files.py runs on the two
test guests that use systemd-networkd:
| Distribution | systemd |
|---|---|
| Debian 12 | 252.39 |
| Debian 13 | 257.13 |
The validation record gives the cases and the latest results. Not covered by the suite:
tunnel,vrf, and other device kinds than bridge, bond, VLAN, dummy, and veth.- A node whose only way in is the device that a change removes. The
connectivity-loss tests change the main card's
.networkconfiguration to interrupt connectivity, then restore the previous configuration.
Why it works this way
networkctl reloadalone, nevernetworkctl reconfigure. On the five measured guests, reload applied new, changed, removed, and restored.networkfiles. Explicit reconfiguration of the unchanged main card removed its DHCP address and default route. On Debian 12, reconfiguration also prevented the DHCP address and default route from returning within ten seconds during a restore.- No check before installation. Neither systemd 252 nor 257
advertised
networkctl verify, andsystemd-analyze verifydoes not accept these file kinds. - A check of the logged diagnostics after the reload. Systemd-networkd can return zero after rejecting or ignoring content. The measured unknown-key diagnostic was readable immediately on every guest, and the guest suite requires immediate detection of every measured mistake class that produced an attributable warning on that guest.
- The journal read discards only the entry at the saved position. This
avoids systemd 252's
--after-cursoromission of the first matching entry after another service's position. Journal cursors and JSON fields work on all five tested distributions. - A restore waits up to ten seconds for startup. On measured systemd
252.23, a reload between a card's
Link UPandGained carrierleft it permanentlyconfiguring, making wait-online fail and the node degraded. The wait avoids that startup window. - A
.netdevwhose device exists keeps its settings. No measured systemd version changes an existing VLAN's identifier. Systemd 252 changes no existing device settings; newer versions change some settings. The service does not warn about settings it leaves unapplied. Such settings could take effect at a later node restart, outside the.netdevnode task's confirmation and restore. - No
.linkfiles..linkfiles take effect when the kernel announces the device, rather than on a service reload. MMX therefore could not activate.linkfiles and restore the previous.linkconfiguration's effect. - Removal order is enforced, not only advised. On systemd 252,
restoring a bridge's file recreates the bridge but does not reattach its
port, and a restored VLAN does not return while the parent keeps its old
reference. Refusing removal or renaming while a
.networkfile refers to the device keeps each individual file's restore workable. - Creation order is enforced too. On systemd 252, a link's loaded
.networkdoes not pick up a device declared later. The port or device could appear only after a node restart, outside this change's confirmation and restore. - Removal deletes the file's virtual devices. New bridges, bonds, dummy
devices, and veth pairs are created by reload; a VLAN also needs a parent
reference. File removal leaves devices until
networkctl deleteremoves them. The module's existing-device and reference refusals cover the measured version differences when restoring stacked devices. - A
.netdevfile is0640 root:systemd-network. Systemd-networkd reads a.netdevwith mode0640and ownerroot:systemd-networkon every measured guest. Systemd-networkd cannot read a.netdevwith mode0600and ownerroot:root. - Files get their destination's SELinux label. With SELinux
enforcing, the service reads a file created with its
destination's policy label. A file moved from
/tmpkeepsinitrc_tmp_tand is not usable, so both installation and restoration use the destination label.
This page is docs/reference/modules/systemd_networkd_file.md in the MMX repository.