ifupdown_interfaces_file
ifupdown_interfaces_file manages one file of ifupdown on a node, the Linux
server MMX manages. ifupdown is the Debian package that configures network
interfaces from /etc/network/interfaces at boot, through
networking.service. The module writes either /etc/network/interfaces
itself or one file directly in /etc/network/interfaces.d.
ifupdown_interfaces_file then takes the interfaces that the change touches
down with ifdown and brings them up with ifup.
Three other modules do the same for the other network tools:
netplan_file for Netplan,
networkmanager_connection_file for
NetworkManager, and systemd_networkd_file for
systemd-networkd.
Choose the module for the node's tool
says which tool the measured test images use. The inputs work as
Inputs shared by all four modules
describes, with one difference: this module takes path, not name. The
other three modules take a file name in one fixed directory. Debian's
installer and the installers of some server providers put the main
interface's settings in /etc/network/interfaces itself, so this module
must reach that file. path is either /etc/network/interfaces or
/etc/network/interfaces.d/<name>, where <name> has only letters,
digits, underscores (_), and hyphens (-).
The module takes the whole file in ifupdown's own format, as
interfaces(5) describes it. Addresses, routes, VLANs, and bridges stay in
ifupdown's configuration format. MMX does not give addresses, routes, VLANs,
or bridges a second set of fields.
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 brings its interfaces up
again by itself. It does this even if the controller machine disconnects,
the node job worker process dies, or the node restarts. The node job worker
process is the program that carries out the node's tasks. The
execution design
owns this mechanism, reachability confirmation and owed restore.
Inputs
path(string; required): /etc/network/interfaces, or/etc/network/interfaces.d/<name>where the name has only letters, digits, underscores, and hyphens. The file belongs to root:root.permissions_mode(string; optional): Quoted octal, such as "0600". Omit to keep an existing file's mode; a new file gets 0644. Ignored with state: absent.content(string; optional): The complete file text in ifupdown's format; 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 takes the file's interfaces down, with the virtual devices they created, and removes the file. /etc/network/interfaces cannot be removed.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 checks the proposed file with ifquery and ifup --no-act, which read it from standard input, without writing or activating anything. Lists the interfaces it would take down and bring up. 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 card in its own file
The complete playbook below gives a second card an address. Replace
enp6s0 with the second card's name on your node. The playbook leaves the
main card's settings alone.
fleet_stages:
- id: network
nodes: web01
node_tasks:
- ifupdown_interfaces_file:
path: /etc/network/interfaces.d/60-second
content: |
auto enp6s0
iface enp6s0 inet static
address 10.0.0.5/24
restore_unless_controller_confirms_within: 2m
On node web01, MMX first checks that /etc/network/interfaces reads the
file: Debian's main file has the line source /etc/network/interfaces.d/*.
MMX checks the proposed file with ifupdown's own programs, writes
/etc/network/interfaces.d/60-second, and runs ifup enp6s0. MMX then
waits for the reachability confirmations.
Run mmx dryrun <playbook> first, then mmx run <playbook>. The dryrun
says which interfaces the change would take down and bring up. After each
file change, the node job worker process waits for every required
confirmation before starting the next node task. An unchanged
file causes no ifdown, no ifup, and no confirmation wait.
To change the address later, write the whole file again with the new
address. MMX takes enp6s0 down with the previous file, which removes the
old address, and brings it up with the new file.
A route on the main interface, in the main file
Debian's installer, and the installers of some server providers, give the
main interface a stanza in /etc/network/interfaces. A stanza is an
iface line followed by the interface's option lines, such as address
and gateway below. To add a route to the main interface, manage the whole
/etc/network/interfaces file. Start from the node's current file, which
cat /etc/network/interfaces shows, and change only what you mean to
change:
- ifupdown_interfaces_file:
path: /etc/network/interfaces
content: |
source /etc/network/interfaces.d/*
auto lo
iface lo inet loopback
auto enp5s0
iface enp5s0 inet static
address 203.0.113.10/24
gateway 203.0.113.1
up ip route add 198.51.100.0/24 via 203.0.113.1 dev enp5s0
Keep the source line exactly as the node's file has it: MMX refuses a
change that alters it; see Why it works this way.
Keep the address that the controller machine uses. On the node, MMX runs
ifdown for enp5s0 with a saved copy of the previous file, then
ifup enp5s0. In the measurements, a ping every 0.1 seconds lost no
answer during this change. An SSH connection that was open stayed open, and
new connections worked at once. If the new file cuts the node off, the node
puts the previous file back and brings enp5s0 up with it.
A VLAN on the second card
- ifupdown_interfaces_file:
path: /etc/network/interfaces.d/61-vlan
content: |
auto enp6s0.100
iface enp6s0.100 inet static
address 10.0.100.5/24
ifupdown reads the name enp6s0.100 as VLAN 100 on the card enp6s0, and
ifup creates the VLAN device itself. The dotted VLAN name enp6s0.100
needs no other package.
The form vlan100 with a vlan-raw-device line needs the vlan package,
and a bridge with bridge_ports needs bridge-utils. Install vlan for
vlan-raw-device, or bridge-utils for bridge_ports, in an earlier node
task with apt_package.
Remove a file
- ifupdown_interfaces_file:
path: /etc/network/interfaces.d/61-vlan
state: absent
On the node, this takes enp6s0.100 down with the file, which removes its
address and the VLAN device, and then removes the file. The removal has the
same confirmations and restore as a change.
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 sections below describe the steps specific to ifupdown_interfaces_file.
The file and its metadata
The file is owned by root:root. Optional permissions_mode sets the mode
of the file named by path, such as "0600" for root-only access.
Without permissions_mode, an existing file keeps its mode and a new file
gets 0644, readable by every account on the node.
A key or password can also live in a root-only file that a stanza command reads. MMX creates a missing
/etc/network/interfaces.d as root:root, mode 0755, and leaves an
existing directory alone. Files get the SELinux label of their path; Debian
has no SELinux policy by default. 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.
state: absent removes a file in /etc/network/interfaces.d. It is refused
for /etc/network/interfaces when the project loads: ifupdown and
networking.service need that file. 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.
Checks before installation
When the file would change, MMX checks the node before it changes anything:
ifup,ifdown,ifquery, andsystemctlare installed.systemctl is-enabled networking.serviceprintsenabled. Otherwise ifupdown would not apply the file at the next boot.- The first line of
ifup --versionstarts withifup version, as ifupdown 0.8 prints it. Another program namedifup, such as ifupdown2, is refused. - ifupdown reads the proposed file:
ifquery -i /dev/stdin --list, with the proposed file on standard input, finds syntax errors such as a misplaced option. - MMX's own reading of the existing and the proposed file refuses a
mappingstanza and a change of thesource,source-directory, orrenamelines. - For a file in
/etc/network/interfaces.d, thesourceorsource-directorylines of/etc/network/interfacesmust read it.source /etc/network/interfaces.d/*is Debian's line. A relative pattern is relative to/etc/network. MMX does not followsourcelines inside sourced files. - When the change brings interfaces up,
ifup --no-act --force -i /dev/stdin <interface>..., with the proposed file on standard input, finds missing settings. For example, a misspelledadressline givesifup: missing required variable: address.
Steps 4 and 7 need no file on disk, so a dryrun runs them too. In their
messages MMX writes the destination path in place of /dev/stdin. It
discards what ifup --no-act prints on standard output: that is the list
of commands with their values. A missing program or a service that is not
enabled gives not_checked in a dryrun, because an earlier node task may
provide it, and fails a run. The other checks fail a dryrun and a run alike.
Which interfaces a change touches
MMX reads the file only far enough to know which interfaces change. MMX joins
a line that ends in \ with the next one and skips blank lines and
comments. It reads the iface stanzas, the auto and allow- lines, and
the no-auto-down and no-scripts lines. For each interface it compares the
existing file with the proposed file: the interface's stanzas with their
option lines, the stanzas they inherit from in the same file, its auto or
allow- classes, and its flags. Spaces within a line and comments do not
count. An interface changes when any of these differs. A new file has no
interfaces before the change; a removed file has none after it.
lo is never taken down, as networking.service never takes it down.
MMX activates only interfaces with an iface stanza in the file named by
path. MMX brings up an interface only when the file named by path lists
the interface in auto or allow-hotplug, as Debian's installer writes
the configuration. Keep each interface's auto line and iface stanza
together in the file named by path. MMX refuses a change that would take
down an interface that is up when the file named by path does not list
the interface in auto or allow-hotplug: the restore could not bring the
interface up again, and a node whose main card stays down is cut off.
A change that touches no interface, such as a new comment, still installs the file and waits for the confirmations. Nothing is taken down or brought up.
Activation and its check
After installation, MMX activates the change in this order:
- For each changed interface that the previous file declares and that
ifupdown lists as up (
ifquery --state <interface>), in reverse order of the file:ifdown <vlan>for each VLAN on the interface that ifupdown lists as up, thenifdown -i <saved copy of the previous file> <interface>. - For each changed interface that the new file declares, in the order of
the file:
ifup <interface>for one inauto, andifup --allow=hotplug <interface>for one inallow-hotplug. The second form skips an interface whose device does not exist, as at boot. ifup <vlan>for each VLAN that step 1 took down.
The VLAN steps exist because taking an interface down takes its VLANs down
too, and bringing it up brings them back without the routes that their
stanzas add: in the guest suite, a VLAN kept its address but lost the route
of its up ip route add line. MMX finds the VLANs on an interface from the
kernel (/sys/class/net/<interface>/upper_<vlan>), so a VLAN declared in
another file counts too; ifdown and ifup read its unchanged stanza from
the files in place. A changed VLAN declared in the file named by path is
taken down and brought up like any changed interface.
The node saved both copies, of the previous and of the proposed file, in
root-private storage under /var/lib/mmx/owed_restores/<owed-restore-id>/
before installation. MMX runs one command per interface. A command that
exits with a status other than 0 fails the task with what the tool wrote on
standard error.
Then MMX checks the result. Each interface brought up from auto must be
listed as up. An interface from allow-hotplug must be listed as up when
its device exists. Each VLAN that MMX took down must be listed as up again. A virtual device that MMX took down and did not bring up
again, and that no file ifupdown reads declares any more (ifquery <interface> fails), must be gone. A failed command or check starts the
restore at once.
What removal does
state: absent takes down each interface of the file that ifupdown lists as
up, with the file itself, and then removes the file. ifdown removes the
interface's addresses. For a virtual device that the file declared, such as
the VLAN enp6s0.100 or a bridge, ifdown also removes the device; MMX
checks that it is gone. MMX never deletes a physical card.
What a restore puts back
A failed activation or check starts the restore at once. A missing reachability confirmation starts it 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;
- runs
ifdown --force -i <saved copy of the proposed file> <interface>for each changed interface of the proposed file whose device exists or that ifupdown lists as up, afterifdown <vlan>for each VLAN on it that ifupdown lists as up; - runs
ifupfor each changed interface that the previous file lists inautoorallow-hotplug, and thenifup <vlan>for each VLAN that step 2 took down.
After a node restart, the restore service starts after network.target.
networking.service runs before network.target, so the restore follows
boot's ifup -a, which brought up the proposed file. The restore puts back
configuration, not a snapshot of every dynamic address. In the measurements,
an interface back on DHCP got a different address from the DHCP server.
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 ifupdown:
| The reason holds | What the reason means, and what to do |
|---|---|
The path must be /etc/network/interfaces or /etc/network/interfaces.d/<name>, where the name has only letters, digits, underscores, and hyphens, because source-directory reads only such names. |
The project does not load. Choose a name such as 60-second, without a dot. |
ifupdown_interfaces_file cannot remove /etc/network/interfaces: ... |
The project does not load. To remove an interface from the main file, write the main file without its stanza. |
Cannot change <path>: ifup is not installed. |
A program is missing. ifdown, ifquery, and systemctl give the same text. Install ifupdown in an earlier node task. A dryrun reports it not checked. |
Cannot change <path>: networking.service is not enabled, so ifupdown would not apply the network configuration file at boot; enable networking.service. |
Enable networking.service in an earlier node task. A dryrun reports it not checked. |
ifupdown_interfaces_file needs ifupdown, the Debian package; this node's ifup reports "<line>". |
The node's ifup belongs to another program, such as ifupdown2, which activates files in another way. This module does not support it. |
ifupdown does not accept the proposed <path>: <diagnostic>. |
ifquery or ifup --no-act refused the proposed file, for example <path>:2: misplaced option or missing required variable: address. Correct the file. Nothing was changed. |
Cannot change <path>: the existing or proposed file uses a mapping stanza; ... |
Replace the mapping stanza with plain iface stanzas for the device names. |
Cannot change <path>: the proposed file changes source, source-directory, or rename lines; ... |
Copy the source, source-directory, and rename lines unchanged from the node's file into the proposed configuration. |
Cannot change <path>: the main ifupdown file /etc/network/interfaces does not include the proposed file; add an include line such as `source /etc/network/interfaces.d/*` to the main ifupdown file. |
See the main file reads no other file. |
Cannot change <path>: interface name "<name>" cannot be taken down and brought up by MMX; ... |
Interface names have at most 15 bytes, without spaces, a slash, or an equals sign, and do not start with a hyphen. A long name of a stanza that others inherit from counts too. |
Cannot change <path>: interface <interface> is up, but the file has no auto or allow-hotplug line for the interface, so a restore could not bring the interface up again; ... |
The interface's auto line is in another file, or it has none and was brought up by hand. Move its auto or allow-hotplug line into this file, next to its stanza. Nothing was changed. |
ifupdown did not accept <path>: <diagnostic>. |
ifdown or ifup failed during activation, or an interface from auto or a VLAN that MMX took down is not up afterwards. The node restores the previous file at once. |
Cannot check whether ifupdown accepted <path>: <diagnostic>. |
MMX could not run its check after activation. The node restores. |
ifdown left the virtual device <name> that <path> declared. |
The device still exists after ifdown. The node restores. |
Cannot change <path>: the file changed while MMX read which interfaces the change takes down. |
Another program changed the file during the task. Run the playbook again. |
The main file reads no other file
When /etc/network/interfaces has no source line for
/etc/network/interfaces.d, ifupdown never reads a file there, so MMX
refuses to write one. This module also refuses to add the line to the main
file, because the line changes which files ifupdown reads only at the next
boot. Add it with a line node task first:
- line:
path: /etc/network/interfaces
line: source /etc/network/interfaces.d/*
insert_at_start_of_file: true
Do this while /etc/network/interfaces.d holds no file, as ls /etc/network/interfaces.d on the node shows: then the new line changes
nothing until this module adds a file, with its confirmations and restore.
Tested on
Distributions: Debian 12 and 13.
The suite tests/integration/ifupdown_interfaces_files.py runs on Debian 12
and Debian 13 test guests that its setup switches to ifupdown, as Debian's
installer and some server providers set nodes up:
| Distribution | ifupdown |
|---|---|
| Debian 12 | 0.8.41 |
| Debian 13 | 0.8.44+deb13u1 |
The validation record gives the latest results.
Measured by hand, not by the suite: a bridge with bridge_ports, which
ifdown with its file deleted; a change of the main interface from a static
address to DHCP and back; and stanzas for IPv4 and IPv6 of one interface.
Why it works this way
path, notname. The other three modules own a file in one fixed directory. Debian's installer and the installers of some server providers put the main interface's settings in/etc/network/interfacesitself, so the module must reach that file as well as files in/etc/network/interfaces.d.- Names of letters, digits,
_, and-.source /etc/network/interfaces.d/*reads every name but dot files, whilesource-directoryreads only names made from letters, digits,_, and-. A name containing only letters, digits,_, and-works withsource /etc/network/interfaces.d/*and withsource-directory. ifdownwith the previous file. ifdown takes an interface down only with the stanza that brought it up. With the stanza gone from the files,ifdown enp6s0printedignoring unknown interface, exited 0, and left the address and a bridge in place. With a saved copy of the old file,ifdown -i <copy>removed the address and bridge device.ifdown --forcewith the proposed file in a restore. A failedifupleaves the address configured but does not list the interface as up. Plainifdownthen left the address;ifdown --forceremoved it, and it exits 0 for a device that does not exist.source,source-directory, andrenamelines stay as they are. MMX activates only the interfaces declared in the file named bypath. Removingsource /etc/network/interfaces.d/*would prevent ifupdown from reading the files in/etc/network/interfaces.dat the next boot. At boot, ifupdown would not start interfaces declared only in/etc/network/interfaces.d, outside any confirmation and restore.- No
mappingstanzas. The interface that a mapping chooses is known only when its script runs, so MMX cannot know which interface to take down and up. Mappings are old and rare. lois left alone. Likeifupdown_interfaces_file,networking.servicenever takeslodown. The service stops withifdown -a --exclude=lo.- Permissions are optional. Keeping an existing mode avoids exposing a
previously private file. New files default to
0644, matching Debian's installer and the ifupdown package; writepermissions_mode: "0600"when the file must be private. - Checks through standard input.
ifqueryandifup --no-actread the proposed file as/dev/stdin, so no candidate file appears where ifupdown could read it, and a dryrun can check too.ifup --no-actchanged nothing in the measurements: ifupdown's state and the addresses stayed as they were.--forceis needed becauseifupof an interface that is up stops withalready configured. - ifupdown2 is not covered. It installs programs with the same names, as on some virtualization systems, but activates a changed file in another way.
This page is docs/reference/modules/ifupdown_interfaces_file.md in the MMX repository.