Configuring IP networking with nmcli

This page has been converted from the Fedora Project Wiki and cleaned up for publishing here on the Fedora Docs Portal, but it has not yet been reviewed for technical accuracy. This means any information on this page may be outdated or inaccurate. Reviews for technical accuracy are greatly appreciated. If you want to help, see the README file in the source repository for instructions.

How to configure networking using the nmcli (NetworkManager Command Line Interface) command-line utility.

Getting started with nmcli

The nmcli (NetworkManager Command Line Interface) command-line utility is used for controlling NetworkManager and reporting network status. It can be utilized as a replacement for nm-applet or other graphical clients. nmcli is used to create, display, edit, delete, activate, and deactivate network connections, as well as control and display network device status.

The nmcli utility can be used by both users and scripts for controlling NetworkManager:

For servers, headless machines, and terminals, nmcli can be used to control NetworkManager directly, without GUI, including creating, editing, starting and stopping network connections and viewing network status.
For scripts, nmcli supports a terse output format which is better suited for script processing. It is a way to integrate network configuration instead of managing network connections manually.

The basic format of a nmcli command is as follows:

nmcli [OPTIONS] OBJECT { COMMAND | help }

where OBJECT can be one of the following options: general, networking, radio, connection, device, agent, and monitor. You can use any prefix of these options in your commands. For example, nmcli con help, nmcli c help, nmcli connection help generate the same output.

Some of useful optional OPTIONS to get started are:

-t, terse

This mode can be used for computer script processing as you can see a terse output displaying only the values.

Example 1. Viewing a terse output

~]$ nmcli -t device
ens3:ethernet:connected:Profile 1
lo:loopback:unmanaged:

-f, field

This option specifies what fields can be displayed in output. For example, NAME,UUID,TYPE,AUTOCONNECT,ACTIVE,DEVICE,STATE. You can use one or more fields. If you want to use more, do not use space after comma to separate the fields.

Example 2. Specifying Fields in the output

~]$ nmcli -f DEVICE,TYPE device
DEVICE  TYPE
ens3    ethernet
lo      loopback

or even better for scripting:

~]$ nmcli -t -f DEVICE,TYPE device
ens3:ethernet
lo:loopback

-p, pretty

This option causes nmcli to produce human-readable output. For example, values are aligned and headers are printed.

Example 3. Viewing an output in pretty mode

~]$ nmcli -p device
=====================
  Status of devices
=====================
DEVICE  TYPE      STATE      CONNECTION
--------------------------------------------------------------
ens3    ethernet  connected  Profile 1
lo      loopback  unmanaged  --

-h, help

Prints help information.

The nmcli tool has some built-in context-sensitive help. To list the available options and object names:

~]$ nmcli help

To list available actions related to a specified object:

~]$ nmcli object help

For example,

~]$ nmcli c help

Additional resources

Getting Started With NetworkManager

Brief Selection of nmcli Examples

This section provides a brief selection of nmcli examples.

Prerequisites

Getting started with nmcli

Example 4. Checking the overall status of NetworkManager

~]$ nmcli general status
STATE      CONNECTIVITY  WIFI-HW  WIFI     WWAN-HW  WWAN
connected  full          enabled  enabled  enabled  enabled

In terse mode:

~]$ nmcli -t -f STATE general
connected

Example 5. Viewing NetworkManager logging status

~]$ nmcli general logging
  LEVEL  DOMAINS
  INFO   PLATFORM,RFKILL,ETHER,WIFI,BT,MB,DHCP4,DHCP6,PPP,WIFI_SCAN,IP4,IP6,A
UTOIP4,DNS,VPN,SHARING,SUPPLICANT,AGENTS,SETTINGS,SUSPEND,CORE,DEVICE,OLPC,
WIMAX,INFINIBAND,FIREWALL,ADSL,BOND,VLAN,BRIDGE,DBUS_PROPS,TEAM,CONCHECK,DC
B,DISPATCH

Example 6. Viewing all connections

~]$ nmcli connection show
  NAME       UUID                                  TYPE      DEVICE
Profile 1  db1060e9-c164-476f-b2b5-caec62dc1b05  ethernet    ens3
ens3       aaf6eb56-73e5-4746-9037-eed42caa8a65  ethernet    --

Example 7. Viewing only currently active connections

~]$ nmcli connection show --active
  NAME       UUID                                  TYPE      DEVICE
Profile 1  db1060e9-c164-476f-b2b5-caec62dc1b05  ethernet     ens3

Example 8. Viewing only devices recognized by NetworkManager and their state

~]$ nmcli device status
DEVICE  TYPE      STATE      CONNECTION
ens3    ethernet  connected  Profile 1
lo      loopback  unmanaged  --

You can also use the following abbreviations of the nmcli commands:

Table 1. Abbreviations of some nmcli commands
nmcli command	abbreviation
nmcli general status	nmcli g
nmcli general logging	nmcli g log
nmcli connection show	nmcli con show
nmcli connection show --active	nmcli con show -a
nmcli device status	nmcli dev

Additional resources

For more examples, see the nmcli-examples(5) man page.

The nmcli options

Following are some of the important nmcli property options:

connection.type

A connection type. Allowed values are: adsl, bond, bond-slave, bridge, bridge-slave, bluetooth, cdma, ethernet, gsm, infiniband, olpc-mesh, team, team-slave, vlan, wifi, wimax. Each connection type has type-specific command options. For example:

A gsm connection requires the access point name specified in an apn.
```
nmcli c add connection.type gsm apn access_point_name
```
A wifi device requires the service set identifier specified in a ssid.
```
nmcli c add connection.type wifi ssid
My identifier
```

You can see the TYPE_SPECIFIC_OPTIONS list in the nmcli(1) man page.

connection.interface-name

A device name relevant for the connection.

nmcli con add connection.interface-name eth0 type ethernet

connection.id

A name used for the connection profile. If you do not specify a connection name, one will be generated as follows:

connection.type -connection.interface-name

The connection.id is the name of a connection profile and should not be confused with the interface name which denotes a device (wlan0, ens3, em1). However, users can name the connections after interfaces, but they are not the same thing. There can be multiple connection profiles available for a device. This is particularly useful for mobile devices or when switching a network cable back and forth between different devices. Rather than edit the configuration, create different profiles and apply them to the interface as needed. The id option also refers to the connection profile name.

The most important options for nmcli commands such as show, up, down are:

id: An identification string assigned by the user to a connection profile. Id can be used in nmcli connection commands to identify a connection. The NAME field in the command output always denotes the connection id. It refers to the same connection profile name that the con-name does.
uuid: A unique identification string assigned by the system to a connection profile. The uuid can be used in nmcli connection commands to identify a connection.

Additional resources

See the comprehensive list in the nmcli(1) man page.