sodcalculator

10 Tech How-To

Configure Network with nmcli: Step-by-Step Guide

Guide 10-47755 · Updated · Step by step

This guide shows you how to configure network interfaces, connections, and settings on Linux using the nmcli command-line tool. You’ll learn to view, add, modify, activate, and delete network connections entirely from the terminal—useful for servers, headless systems, or when you prefer the command line over GUI tools. Before starting, ensure you have NetworkManager installed and running, and that you have root or sudo privileges for most configuration changes.

What You’ll Need

  • A Linux system with NetworkManager installed (most major distributions include it by default)
  • Root or sudo access to modify network settings
  • Basic familiarity with the terminal
  • Network interface names (check with ip link or nmcli device status)

Step-by-Step

  1. Check NetworkManager status – Run systemctl status NetworkManager or nmcli general status. If it’s not running, start it with sudo systemctl start NetworkManager and enable it with sudo systemctl enable NetworkManager.
  2. List all network devices – Use nmcli device status to see interfaces like eth0, wlan0, or enp3s0. Note the device name and its connection state (connected or disconnected).
  3. View existing connections – Run nmcli connection show to list saved connections. Each connection has a name (e.g., “Wired connection 1”) and a UUID. Use nmcli connection show to see detailed settings.
  4. Check current IP configuration – Use nmcli device show to see IP addresses, gateway, DNS, and other active settings for a specific interface.
  5. Create a new Ethernet connection with DHCP – Run sudo nmcli connection add type ethernet con-name "my-eth" ifname eth0. This creates a connection named “my-eth” bound to device eth0 that uses DHCP by default. Replace eth0 with your actual interface name.
  6. Create a connection with a static IP – Use sudo nmcli connection add type ethernet con-name "static-eth" ifname eth0 ipv4.method manual ipv4.addresses 192.168.1.100/24 ipv4.gateway 192.168.1.1 ipv4.dns "8.8.8.8,8.8.4.4". Adjust the IP, subnet (CIDR notation), gateway, and DNS servers to match your network.
  7. Activate a connection – Bring up a connection with sudo nmcli connection up . For example, sudo nmcli connection up "my-eth". The device will disconnect from any current connection and use this one.
  8. Modify an existing connection – Change settings with sudo nmcli connection modify ipv4.addresses 192.168.1.50/24. You can modify multiple properties in one command, e.g., sudo nmcli connection modify "static-eth" ipv4.gateway 192.168.1.254 ipv4.dns "1.1.1.1".
  9. Switch to DHCP on an existing connection – Run sudo nmcli connection modify ipv4.method auto ipv4.addresses "" ipv4.gateway "" to clear static settings and use DHCP.
  10. Set the hostname – Change the system hostname with sudo nmcli general hostname . This updates both the current session and the persistent configuration.
  11. Manage Wi-Fi connections – Scan for networks with nmcli device wifi list. Connect to one with sudo nmcli device wifi connect password . To create a saved connection, add name to the command.
  12. Delete a connection – Remove an unused connection with sudo nmcli connection delete . This does not affect the device itself, only the saved profile.
  13. Enable or disable a device – Turn off a network interface with sudo nmcli device disconnect (deactivates but keeps the connection saved). Re-enable with sudo nmcli device connect .
  14. Reload configuration files – After manually editing files in /etc/NetworkManager/system-connections/, run sudo nmcli connection reload to load changes without restarting NetworkManager.

Common Mistakes

  • Wrong interface name – Using eth0 when your system uses enp3s0 or similar. Always check with nmcli device status first.
  • Forgetting CIDR notation – Static IPs must include the subnet prefix (e.g., /24 for a typical home network). Just 192.168.1.100 without /24 will fail.
  • Not using sudo – Most nmcli commands that change settings require root privileges. Without sudo, you’ll get a permission error.
  • Conflicting connections – Having multiple connections for the same device can cause confusion. NetworkManager picks one automatically; use connection up to force a specific one.
  • Clearing static IP incorrectly – To revert to DHCP, you must set ipv4.method auto and clear addresses/gateway. Leaving old addresses can cause unexpected behavior.

Tips

  • Use tab completion – Type nmcli connection show and press Tab to auto-complete connection names.
  • Check changes with nmcli connection show – After modifying, verify the values are correct before activating.
  • Test connectivity – After bringing up a connection, run ping -c 4 8.8.8.8 to confirm internet access, then ping -c 4 google.com to verify DNS.
  • Use nmcli -p for pretty output – The -p flag makes tables more readable, especially on smaller terminals.
  • Backup connection profiles – Copy files from /etc/NetworkManager/system-connections/ before major changes. They’re plain text and easy to restore.
  • Set automatic connection – By default, new connections autoconnect. To disable, add autoconnect no when creating or modifying.

Troubleshooting

  • Connection won’t activate – Check journalctl -u NetworkManager -f for errors. Common issues: wrong interface name, invalid IP settings, or the device being physically down. Try nmcli device status to see if the device is available.
  • No internet after static IP – Verify the gateway and DNS are correct. Test with ip route to see the default route, and cat /etc/resolv.conf to check DNS. If DNS is missing, add it with nmcli connection modify ipv4.dns "8.8.8.8".
  • Wi-Fi not showing networks – Ensure the Wi-Fi device is enabled: nmcli radio wifi on. If still nothing, check if the driver is loaded with lspci -k or lsusb.
  • Changes don’t persist after reboot – Make sure you’re modifying the connection profile, not just the active device. Use nmcli connection modify, not nmcli device modify (the latter is temporary).
  • Permission denied – Run commands with sudo. If you’re already root, check if NetworkManager is running and that you’re not in a container with restricted access.
  • Duplicate connections – If you see multiple connections for the same device, remove the unwanted ones with nmcli connection delete. Then activate the correct one.

Frequently Asked Questions

Q: What’s the difference between a device and a connection in nmcli?
A: A device is physical hardware (like eth0 or wlan0). A connection is a saved configuration profile that can be applied to a device. Multiple connections can exist for one device, but only one can be active at a time.

Q: How do I set a DNS server temporarily without changing the connection?
A: Use sudo nmcli device modify ipv4.dns "8.8.8.8". This applies immediately but resets when the connection restarts. For permanent changes, modify the connection profile instead.

Q: Can I use nmcli to set up a bridge or VLAN?
A: Yes. For a bridge, use nmcli connection add type bridge con-name br0 ifname br0 then add slave interfaces. For VLANs, use type vlan with vlan.id and vlan.parent parameters.

Q: How do I prevent a connection from auto-connecting at boot?
A: Run sudo nmcli connection modify autoconnect no. You can still manually activate it with nmcli connection up when needed.

Q: What does nmcli general status show?
A: It displays overall NetworkManager state, including whether it’s running, the current hostname, and the connectivity status (full, limited, none). It’s a quick health check.

Q: Is nmcli available on all Linux distributions?
A: It’s part of NetworkManager, which is default on most major distros (Ubuntu, Fedora, Debian, RHEL, Arch). On minimal systems, install with your package manager, e.g., sudo apt install network-manager on Debian/Ubuntu.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →