nmcli: Common Tasks Without the GUI

Introduction¶

On current RHEL, Fedora, and Ubuntu Server, NetworkManager manages network interfaces. Hand-editing /etc/sysconfig/network-scripts/ifcfg-* or /etc/network/interfaces either doesn't work or gets overwritten. nmcli is the scriptable way to drive it.

The model: connections vs devices¶

• A device is a physical or virtual interface (eth0, ens3, bond0).
• A connection ("connection profile") is a named configuration that can be applied to a device — IP settings, DNS, routes, VLAN tags. Stored under /etc/NetworkManager/system-connections/.

One device can have several connection profiles (home, office); only one is active at a time. This indirection is why nmcli feels different from ip.

nmcli device status            # devices and which connection is active
nmcli connection show          # all profiles
nmcli connection show --active
nmcli -f ip4,dns device show eth0

Static IP¶

nmcli connection modify "Wired connection 1" \
  ipv4.method manual \
  ipv4.addresses 192.168.1.50/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "1.1.1.1 9.9.9.9" \
  ipv4.dns-search example.com

nmcli connection up "Wired connection 1"      # apply

Back to DHCP:

nmcli connection modify "Wired connection 1" ipv4.method auto \
  ipv4.gateway "" ipv4.addresses "" ipv4.dns ""
nmcli connection up "Wired connection 1"

Add a second IP without replacing the first: nmcli con mod NAME +ipv4.addresses 10.0.0.9/24. The +/- prefixes add/remove list items.

Add a static route¶

nmcli connection modify "Wired connection 1" \
  +ipv4.routes "10.20.0.0/16 192.168.1.254"
nmcli connection up "Wired connection 1"
ip route            # verify

DNS only (keep DHCP for addressing)¶

nmcli con mod "Wired connection 1" ipv4.ignore-auto-dns yes ipv4.dns "1.1.1.1"
nmcli con up "Wired connection 1"

VLAN¶

nmcli connection add type vlan con-name vlan100 dev eth0 id 100 \
  ipv4.method manual ipv4.addresses 10.100.0.5/24 ipv4.gateway 10.100.0.1

Bond (active-backup)¶

nmcli con add type bond con-name bond0 ifname bond0 \
  bond.options "mode=active-backup,miimon=100"
nmcli con add type ethernet con-name bond0-p1 ifname eth1 master bond0
nmcli con add type ethernet con-name bond0-p2 ifname eth2 master bond0
nmcli con mod bond0 ipv4.method manual ipv4.addresses 10.0.0.10/24 ipv4.gateway 10.0.0.1
nmcli con up bond0
cat /proc/net/bonding/bond0        # which slave is active, link status

For LACP use mode=802.3ad and configure the switch side to match.

Bridge (for VMs / containers)¶

nmcli con add type bridge con-name br0 ifname br0 \
  ipv4.method manual ipv4.addresses 192.168.1.50/24 ipv4.gateway 192.168.1.1 \
  bridge.stp no
nmcli con add type ethernet con-name br0-port ifname eth0 master br0
nmcli con up br0

Note: attaching eth0 to the bridge moves the IP to br0; do this on the console or via a script with a rollback timer, not over the SSH session you'd lose.

Wi-Fi¶

nmcli device wifi list
nmcli device wifi connect "SSID-Name" password "secret"
nmcli connection modify "SSID-Name" connection.autoconnect yes

Verification and troubleshooting¶

nmcli connection show "Wired connection 1" | grep -Ei 'ipv4|ipv6|route'
nmcli device show eth0
journalctl -u NetworkManager -f          # watch what NM does on `con up`
nmcli general logging level DEBUG domains ALL   # crank up logging temporarily

• Edited ifcfg-eth0 / netplan yaml and nothing changed — NetworkManager owns it. Use nmcli, or nmcli connection reload after editing the keyfile under /etc/NetworkManager/system-connections/ directly.
• nmcli con up fails "Connection activation failed: IP configuration could not be reserved" — DHCP got no answer, or the static config conflicts (duplicate IP, wrong subnet). journalctl -u NetworkManager has the reason.
• Changes revert after reboot — you used ip addr add (runtime only) or nmcli device modify (not persisted) instead of nmcli connection modify.
• Device shows "unmanaged" — it's excluded in /etc/NetworkManager/NetworkManager.conf or a .nmconnection doesn't exist for it. nmcli device set eth0 managed yes.
• DNS not what you set — systemd-resolved is in the path; check resolvectl status. NM feeds resolved unless dns=none/dns=default is configured otherwise.
• Lost SSH after a bridge/bond change — always wrap risky changes: nmcli con up NAME & sleep 60 && nmcli con up OLD_PROFILE as a dead-man switch, or use nmcli from console/IPMI.

Related tools and reading¶

• On-site: Subnet Calculator, IP address lookup, DNS lookup.
• Related posts: ss and conntrack for connection debugging, Linux permissions and ACLs.