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 (present or absent; default present): 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; default 2m): 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.

  • status
  • change
  • reason

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:

  1. the named file;
  2. the running configuration that the file gave the node, such as an address or a route;
  3. 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 .network configuration to interrupt connectivity, then restore the previous configuration.

Why it works this way

  • networkctl reload alone, never networkctl reconfigure. On the five measured guests, reload applied new, changed, removed, and restored .network files. 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, and systemd-analyze verify does 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-cursor omission 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 UP and Gained carrier left it permanently configuring, making wait-online fail and the node degraded. The wait avoids that startup window.
  • A .netdev whose 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 .netdev node task's confirmation and restore.
  • No .link files. .link files take effect when the kernel announces the device, rather than on a service reload. MMX therefore could not activate .link files and restore the previous .link configuration'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 .network file refers to the device keeps each individual file's restore workable.
  • Creation order is enforced too. On systemd 252, a link's loaded .network does 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 delete removes them. The module's existing-device and reference refusals cover the measured version differences when restoring stacked devices.
  • A .netdev file is 0640 root:systemd-network. Systemd-networkd reads a .netdev with mode 0640 and owner root:systemd-network on every measured guest. Systemd-networkd cannot read a .netdev with mode 0600 and owner root: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 /tmp keeps initrc_tmp_t and 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.