Skip to content

nm_connection

A NetworkManager connection profile, written as a keyfile and brought up.

Use nm_connection to set up a network connection with NetworkManager: a static address, a bond, or a VLAN. Each step is one connection profile, which Conn3x writes as a keyfile and brings up. A change is guarded by default: if Conn3x can’t log in again after it, the host puts the old profile back by itself.

A static address on a second interface:

step "lan" {
nm_connection {
name = "lan"
type = "ethernet"
ifname = "eth1"
ip4 = ["192.0.2.10/24"]
gw4 = "192.0.2.1"
dns4 = ["192.0.2.53"]
}
}

A bond of two ports, with a VLAN on it:

step "bond0" {
nm_connection {
name = "bond0"
type = "bond"
ifname = "bond0"
bond_mode = "802.3ad"
bond_options = { miimon = "100" }
ip4 = ["disabled"]
ip6 = ["disabled"]
}
}
step "bond0_ports" {
for_each = ["eth2", "eth3"]
nm_connection {
name = "bond0-${item.value}"
type = "ethernet"
ifname = item.value
controller = "bond0"
}
}
step "vlan10" {
nm_connection {
name = "vlan10"
type = "vlan"
ifname = "bond0.10"
vlan_parent = "bond0"
vlan_id = 10
ip4 = ["198.51.100.10/24"]
}
}
Name Type Required Description
autoconnect bool No Bring the connection up now and at boot. Defaults to true.
bond_mode string No For a bond: balance-rr (the default), active-backup, balance-xor, broadcast, 802.3ad, balance-tlb or balance-alb.
bond_options map of string No For a bond: other bonding options, such as { miimon = “100” }.
confirm_after string No Before a change, the host keeps the old keyfile and schedules its own revert after this long; after it, Conn3x logs in again over a new connection and cancels the revert. Defaults to “60s”, since changing the connection Conn3x logs in over is the classic lockout. “off” turns it off. Needs systemd.
controller string No For a bond port: the name of the bond connection. A port has no addresses of its own.
dns4 list of string No IPv4 DNS servers.
dns6 list of string No IPv6 DNS servers.
dns_search list of string No DNS search domains.
gw4 string No The IPv4 gateway.
gw6 string No The IPv6 gateway.
ifname string Yes The interface, such as eth1, bond0 or bond0.10.
ip4 list of string No IPv4 addresses with prefixes, such as [“192.0.2.10/24”], or [“auto”] for DHCP (the default) or [“disabled”].
ip6 list of string No IPv6 addresses with prefixes, or [“auto”] (the default) or [“disabled”].
mtu number No The MTU, from 576 to 65535.
name string Yes The connection’s name. Its keyfile is /etc/NetworkManager/system-connections/.nmconnection.
on_remove string No “forget” (default) leaves the connection as it is, “delete” removes the profile, which takes the connection down.
type string Yes “ethernet”, “bond” or “vlan”.
vlan_id number No For a vlan: its ID, from 1 to 4094.
vlan_parent string No For a vlan: the parent interface.

Conn3x sets these; reference them as conn3x_nm_connection.<circuit>__<step>["<host>"].<name>.

Name Type Description
in_sync bool Whether the keyfile is Conn3x’s and, with autoconnect, the connection is up.
revision string Changes each time Conn3x changes this on the host. Handlers watch it.

A step lowers to the conn3x_nm_connection resource, one instance per host, and connects with its circuit’s ssh block.

Reading. On every plan, Conn3x reads the keyfile, /etc/NetworkManager/system-connections/<name>.nmconnection, and asks nmcli which connections are up. in_sync is true when the keyfile is exactly the one Conn3x writes and, with autoconnect, the connection is up. An edit with nmcli connection modify, which rewrites the keyfile, shows as a change.

Applying. Conn3x writes the whole keyfile, owned by root and readable by nobody else, as NetworkManager requires. Then it runs nmcli connection reload and, with autoconnect, nmcli connection up. The host’s other profiles are left alone.

The lockout guard. Changing the connection Conn3x logs in over is the classic way to lose a server. So by default, before the change, the host keeps a copy of the old keyfile and schedules its own revert after confirm_after, 60 seconds unless you say otherwise. After the change, Conn3x logs in again over a new connection and cancels the revert. If that login doesn’t come, the host puts the old keyfile back and reloads, whatever happened to Conn3x, and the apply fails. confirm_after = "off" turns the guard off. It needs systemd.

Addresses. ip4 and ip6 take addresses with their prefixes, or ["auto"] (DHCP for IPv4, autoconfiguration for IPv6, the default for both) or ["disabled"]. A bond port has no addresses of its own: set them on the bond.

Rules. type is ethernet, bond or vlan. ifname is 15 characters or fewer. Only an ethernet connection can be a bond port, through controller. vlan_parent and vlan_id are for a vlan, and bond_mode and bond_options for a bond. mtu is from 576 to 65535.

Changes. Changing any setting rewrites the keyfile and brings the connection up again, behind the guard. Changing name replaces the step, and on_remove decides what happens to the old profile.

When you delete an nm_connection step, on_remove decides what happens on the host. The default, "forget", leaves the profile and the connection as they are. "delete" removes the profile with nmcli connection delete, which takes the connection down. Removal isn’t guarded, so don’t delete the connection Conn3x logs in over.