Nmcli Configure Network Connection: Full Guide

Nmcli is the command-line tool for NetworkManager on Linux, and it lets you configure network connections—Ethernet, Wi-Fi, VPNs, and more—directly from the terminal. You enter a command like nmcli con add or nmcli dev wifi connect, and the tool creates or modifies the connection profile that NetworkManager uses to manage your network interfaces. This guide covers the essential commands, how to use them, and common pitfalls.

What Is Nmcli and Why Use It?

Nmcli is the command-line client for NetworkManager, the default network management service on most modern Linux distributions (Fedora, Ubuntu, Debian, Arch, and others). It provides a text-based interface to control both devices (physical or virtual network interfaces) and connections (saved configurations for those devices).

Using the command line is often faster and more scriptable than clicking through a GUI. It’s especially useful for:

• Headless servers without a desktop environment
• Automating network setup in scripts or provisioning tools
• Managing connections over SSH
• Creating multiple profiles for different networks (home, office, VPN)

Basic Nmcli Commands You Need

Before configuring anything, you should see what’s already there. Here are the most common commands:

• nmcli general status – Shows whether NetworkManager is running and if it’s enabled.
• nmcli device status – Lists all network devices (e.g., eth0, wlan0) and their state.
• nmcli connection show – Lists all saved connection profiles.
• nmcli connection show "" – Shows details of a specific profile.
• nmcli device wifi list – Scans and lists available Wi-Fi networks.

These commands give you a clear picture of your current setup before you make any changes.

How to Create a New Connection with Nmcli

Creating a connection is done with nmcli connection add. The basic syntax is:

nmcli connection add type <type> con-name <name> ifname <interface> [options]

Where <type> can be ethernet, wifi, vpn, bridge, bond, etc. The con-name is a label you choose (e.g., “work”), and ifname is the network interface (e.g., eth0).

For example, to create a static Ethernet connection on interface eth0 with IP 192.168.1.100:

nmcli con add type ethernet con-name work ifname eth0 ip4 192.168.1.100/24 gw4 192.168.1.1

To create a DHCP-based Ethernet connection:

nmcli con add type ethernet con-name home ifname eth0

For Wi-Fi, you can use the simpler command:

nmcli dev wifi connect "MyWiFi" password "mypassword"

This automatically creates and activates a connection profile named after the SSID.

Modifying and Deleting Connections

To change a connection, use nmcli connection modify. For example, to change the IP address of the “work” connection:

nmcli con modify work ipv4.addresses 192.168.1.101/24

To add a DNS server:

nmcli con modify work ipv4.dns 8.8.8.8

To switch from DHCP to static, you need to set the method:

nmcli con modify work ipv4.method manual

To delete a connection:

nmcli con delete work

Remember to activate a modified connection with nmcli con up work for changes to take effect.

Activating and Deactivating Connections

Activating a connection tells NetworkManager to use that profile on the associated device. You can do this with:

nmcli con up work

To deactivate (disconnect) a connection:

nmcli con down work

If you have multiple connections on the same device, NetworkManager will automatically choose one based on its priority (the autoconnect and connection.autoconnect-priority properties). You can manually override this by activating a specific profile.

Common Problems and How to Fix Them

Even with a clear guide, things can go wrong. Here are the most frequent issues:

1. “Error: Connection activation failed”

This usually means the device couldn’t get an IP address or the Wi-Fi password was wrong. Check the system logs with journalctl -u NetworkManager or nmcli dev status to see the device state.

2. Wi-Fi won’t connect to a hidden SSID

Use nmcli con add type wifi con-name hidden ifname wlan0 ssid MyHidden and then set 802-11-wireless.hidden yes.

3. Static IP not taking effect

Make sure you set ipv4.method manual and that the address is in the correct CIDR format (e.g., /24). Also, check for conflicts with other devices.

4. DNS not working

Verify the DNS servers are set correctly and that the ipv4.ignore-auto-dns property is set to yes if you want to override DHCP-provided DNS.

5. Connection drops after reboot

Check that connection.autoconnect is set to yes (which is the default). If not, enable it with nmcli con mod <name> connection.autoconnect yes.

Frequently Asked Questions

How do I see all available Wi-Fi networks?

Run nmcli device wifi list. This scans and shows nearby networks with their SSID, signal strength, and security type. If you don’t see any, make sure your Wi-Fi device is enabled (nmcli radio wifi on).

What is the difference between a device and a connection in nmcli?

A device is the physical or virtual network interface (like wlan0 or eth0). A connection is a saved configuration profile that tells NetworkManager how to set up that device (IP, DNS, security, etc.). One device can have multiple connection profiles, but only one can be active at a time.

Can I use nmcli to set up a VPN?

Yes, but you first need to install the VPN plugin for NetworkManager (e.g., networkmanager-l2tp, networkmanager-openvpn). Then you can import a VPN config file with nmcli connection import type openvpn file /path/to/config.ovpn, or add a VPN connection manually with nmcli con add type vpn.

How do I make a connection auto-connect on boot?

By default, new connections have autoconnect set to yes. If it’s not, use nmcli con mod <name> connection.autoconnect yes. You can also set the priority with connection.autoconnect-priority to choose which connection is used when multiple are available.

What does “nmcli con up” do exactly?

It activates the connection profile, meaning NetworkManager applies the settings (IP, DNS, etc.) to the associated device and brings the interface up. If the device is already up with another profile, it will switch to the one you specify.

Is nmcli safe to use on a production server?

Yes, nmcli is the standard tool for managing NetworkManager on servers. However, always test changes in a maintenance window and have a backup plan (like a console or out-of-band management) in case you lock yourself out. You can also use nmcli con reload to reload configs from disk without disrupting active connections.

Alternatives to Nmcli

While nmcli is powerful, there are other ways to manage network connections on Linux:

• nmtui – A text-based user interface that provides a menu-driven way to manage connections. Good for those who prefer a visual but terminal-based tool.
• GNOME Settings – The graphical network manager for desktop environments; it uses NetworkManager under the hood.
• ip and ethtool – Lower-level tools for direct interface configuration, but they don’t manage profiles or auto-connect features.
• systemd-networkd – A different network management daemon that uses .network files; it’s an alternative to NetworkManager entirely.

For most users, nmcli offers the best balance of flexibility and ease of use, especially in scripts and remote administration.

Related

• Google Messages vs Apple & Samsung: 5 New Features
• Best Games April: Top Picks & Buying Guide
• Sling TV Returns to Roots With 20 Select Bundle