Skip to content
LinuxHow-To Published Updated 3 min readViews unavailable

How to Configure Persistent Linux Networking with NetworkManager and nmcli

A safe nmcli workflow for connection profiles, static addressing, DNS, routes, staged activation, rollback, and proof that settings survive reboot.

NetworkManager persists network intent in connection profiles and activates a profile on a device. Editing the live address with ip addr can be useful for diagnosis, but it does not update that stored intent. A durable change uses nmcli connection, preserves remote access during activation, and verifies both the active state and the saved profile.

Inventory names before modifying anything

Device names and connection names are not interchangeable. List both, record the currently active profile, gateway, routes, DNS, and management path:

nmcli device status
nmcli connection show --active
nmcli -f NAME,UUID,TYPE,DEVICE connection show
ip -brief address
ip route

On a remote host, keep an out-of-band console or a tested timed rollback. Changing the route that carries the SSH session can disconnect you before a corrective command runs.

Create or clone a profile

For a new Ethernet profile with static IPv4 configuration:

nmcli connection add type ethernet ifname enp1s0 con-name prod-static \
  ipv4.method manual \
  ipv4.addresses 192.0.2.20/24 \
  ipv4.gateway 192.0.2.1 \
  ipv4.dns "192.0.2.53 192.0.2.54" \
  ipv6.method disabled

Those documentation-prefix addresses are examples; substitute the approved network plan. Do not disable IPv6 merely because the example does. Use ipv6.method auto, manual, or the site policy, and understand whether disabling it breaks local services or monitoring.

For an existing production profile, cloning it creates an easy rollback point. Modify the clone, give it lower autoconnect priority until tested, and activate it explicitly. NetworkManager properties are typed; use nm-settings-nmcli(5) to confirm whether a value replaces a list, appends with +, or removes with -.

Add a route and per-route metric deliberately:

nmcli connection modify prod-static \
  +ipv4.routes "198.51.100.0/24 192.0.2.1, 50"
nmcli connection show prod-static

Multiple default routes need explicit metrics and policy. DNS behavior depends on the selected resolver integration; inspect nmcli device show, the active resolver, and split-DNS domains rather than assuming /etc/resolv.conf is a static file.

Activate with a recovery path

Validate the profile first, arrange a timed command or console that can reactivate the old profile, then run:

nmcli connection up prod-static ifname enp1s0

From another session, test the local address, default gateway, required routes, DNS resolution, and application endpoints. ping alone does not prove TCP, DNS, MTU, source-address selection, or firewall behavior. Compare nmcli connection show --active with nmcli device show enp1s0 and ip route get for representative destinations.

If activation fails, reactivate the saved old profile by name or UUID. Avoid deleting it until the new profile has survived a full maintenance cycle.

For Wi-Fi, bonds, bridges, VLANs, WireGuard, or 802.1X, create the correct NetworkManager connection type instead of forcing Ethernet properties onto it. A bridge’s IP configuration belongs on the bridge profile, while its member interfaces normally act as ports; placing the same address on both creates duplicate routes and ARP confusion. For DHCP reservations, verify the profile’s cloned MAC/client identifier policy agrees with the server. nmcli connection show "$profile" should be the reviewed declarative record before activation.

NetworkManager supports checkpoints through its D-Bus API and tooling in appropriate versions, allowing a disruptive change to roll back if not confirmed. Use only the mechanism documented by the installed release and still retain console access: a checkpoint cannot recover from every driver crash, firmware reset, or management-plane failure.

Prove persistence and ownership

Set intentional autoconnect and priority properties, restart NetworkManager during an approved window or reboot, and repeat the acceptance tests. Confirm that no cloud-init, provisioning agent, distribution network generator, or second network manager rewrites the profile. Two systems controlling the same interface create changes that appear to “randomly” revert.

Export non-secret profile properties into configuration management, but protect Wi-Fi keys, private keys, and 802.1X credentials. The completed change has a named source of truth, an activation and rollback sequence, and evidence after restart—not merely an address visible in one shell.

Related:

Sources:

Comments