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.
Example usage
Section titled “Example usage”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"] }}Arguments
Section titled “Arguments”| 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/ |
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. |
Read-only attributes
Section titled “Read-only attributes”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.
How it works
Section titled “How it works”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.
Removal
Section titled “Removal”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.