The nmcli Command

The nmcli command isn’t new, it was released in 2010. Together with the ip command, it replaces the venerable—but deprecated— ifconfig. Old habits die hard, and many sysadmins still use ifconfig. They already know how to use it, there’s no learning curve, and they just need to get the job done. So why learn yet another tool?

Well, eventually, ifconfig will be dropped by the distributions so it’s a change that is coming, like it or not. But nmcli has some neat tricks all of its own that make it worthwhile finding out what it can offer.

The ncmli Concepts and Syntax

Like all CLI commands, nmcli accepts command line parameters. The parameters are grouped into three categories.

Options: These modify nmcli‘s behavior Sections: These tell nmcli which set of actions you are invoking. Think of sections as collections of commands. Actions: These tell nmcli what you want it to do. Think of them as commands.

The general syntax format is:

Actually, status is the default action for general, so we could have left that word off the command. But we’ve verified that nmcli —and therefore NetworkManager—is installed and operational. Let’s find out a bit more about this computer.

We can list all of the in-memory and on-disk network connection profiles using the show action from the connection section:

The output is wider than the terminal window. Our results were:

The test machine used for this article is running a pre-launch version of Ubuntu 21.10. It has three network adaptors installed in it, named enp0s3, enp0s8, and enp0s9.

Understanding the Plumbing

A network connection allows your computer to communicate over a network to another device. Internally, nmcli holds all the information regarding a network connection in a data object it calls a connection.

An nmcli connection encapsulates all of the information related to that connection, including data link layer and IP addressing information. You can think of nmcli‘s connections as the configuration details for real-world network connections.

To reach the outside world a connection must use a networking interface device, such as a network card. A connection is bound to a device. When a device is active and able to receive or transmit data, the connection is said to be active or up. The corresponding inactive state is called, unsurprisingly, inactive or down.

Adding Network Connections

With nmcli you can create a network connection and set some of its configuration options with a single command. On this test computer, there is no connection on enp0s8 , the name for our wired connection (ethernet) number 2. We’ll add a connection to enp0s8. Because we’re making system changes, you’ll need to use sudo:

This command uses the add action from the connection section. We used the type option to request an ethernet connection, and the ifname (interface name) option to specify the network interface device we want this connection to use.

Let’s check what’s happened:

Our new connection, ethernet-enp0s8-1 , has been created. Its universally unique identifier (UUID) has been assigned, and the connection type is ethernet. We can now make it active with the up command. The up command must be followed by the connection name or its UUID:

Let’s check our active connections once more:

Our new connection, ethernet-enp0s8-1, is now active and bound to the enp0s8 network interface device.

Adjusting Connections

Of course, ncmli lets you change the parameters of existing connections too. Suppose we want to switch a network interface from Dynamic Host Configuration Protocol (DHCP) to using a static IP address. To match our network, we need a fixed IP address of 192.168.1.40 for our new connection.

To achieve that, you need to issue two commands. One to set the IP address, and one to set the connection’s method of obtaining an IP address to manual:

The “/24” we’re providing with the IP address is the subnet mask in Classless Inter-Domain Routing (CIDR). In this context “/24” means “255.255.255.0.”

The changes won’t take effect until the connection is “bounced.” That is, disabled and brought back online. The first command takes the connection down and the second brings it back up.

If you want to reverse the change and move from a static IP address to a DHCP IP Address, use the auto option instead of manual.

Device Management

The nmcli device section contains actions (commands) that let you manage the network interfaces installed on your computer. To see the status of all the network interfaces on your computer use:

Showing Device Details

To examine the details of a network interface, we use the show action from the device section. If you do not provide a device name, the details of all devices are retrieved and displayed. You can scroll and page up and down to review them.

Let’s take a look at enp0s8, the device our new connection is using. We can verify that the IP address in use is the address that we previously requested.

A screenful of information is returned by nmcli . Some of the commonly useful items are:

DEVICE: The name of the device we’re examining. TYPE: The type of connection using this device. HWADDR: The MAC address of the interface card. STATE: Whether this device has a live connection on it. IP4. ADDRESS[1]: The IP address and subnet mask for this device. CONNECTION: The name of the connection using this device.

The nmcli Interactive Editor

Although nmcli is a command-line tool it does have an elementary interactive editor. The edit action in the connection section opens the interactive editor on the connection you pass on the command line:

Some help text is printed to the screen, and you’re presented with the “nmcli>” command prompt.

if you type print and hit “Enter”, nmcli lists all the properties associated with the connection. There are lots of them. You can scroll through them to review them.

Let’s change our connection back to using DHCP. We’ll use the “ipv4” settings. To do that, we need to “go” to the IPv4 settings.

The property we want to change is method. We want to set it to automatic.

You’ll see the following prompt:

If you don’t clear the IP address, the next time you set this connection to use a static IP address it’ll use the one that was previously set. If you do clear it, you’ll need to set a new IP address if you ever change this connection back to using a static IP address. Type “yes” or just hit “Enter” to clear it. Type “no” and hit “Enter” to keep it.

We need to save our changes:

Type “quit” to exit the interactive editor. If you don’t want to quit, type “back” to go back to the main level, and carry on using the editor.

There’s Much More in man

The nmcli command can do much more. It has a great many command-line parameters and options. So many in fact, that its man page runs to over 1200 lines. Review them to see what else nmcli can do for you.

And of course, if you’re remotely administering network connections, don’t disable the connection you’ve connected in on. That’s never fun.