2.3. Using the NetworkManager Command Line Tool, nmcli

The command‐line tool nmcli can be used by both users and scripts for controlling NetworkManager. The basic format of a command is as follows:
nmcli OPTIONS OBJECT { COMMAND | help }
where OBJECT can be one of general, networking, radio, connection, or device. The most used options are: -t, --terse for use in scripts, the -p, --pretty option for users, and the -h, --help option. Command completion has been implemented for nmcli, so remember to press Tab whenever you are unsure of the command options available. See the nmcli(1) man page for a complete list of the options and commands. To list a quick overview of configuration on the known network devices, use the nmcli device command without arguments.
The nmcli tool has some built-in context-sensitive help. For example, issue the following two commands and notice the difference:
~]$ nmcli help
Usage: nmcli [OPTIONS] OBJECT { COMMAND | help }

OPTIONS
  -t[erse]                                   terse output
  -p[retty]                                  pretty output
  -m[ode] tabular|multiline                  output mode
  -f[ields] <field1,field2,...>|all|common   specify fields to output
  -e[scape] yes|no                           escape columns separators in values
  -n[ocheck]                                 don't check nmcli and NetworkManager versions
  -a[sk]                                     ask for missing parameters
  -w[ait] <seconds>                          set timeout waiting for finishing operations
  -v[ersion]                                 show program version
  -h[elp]                                    print this help

OBJECT
  g[eneral]       NetworkManager's general status and operations
  n[etworking]    overall networking control
  r[adio]         NetworkManager radio switches
  c[onnection]    NetworkManager's connections
  d[evice]        devices managed by NetworkManager
  a[gent]         NetworkManager secret agent or polkit agent
  m[onitor]       monitor NetworkManager changes
~]$ nmcli general help
Usage: nmcli general { COMMAND | help }

  COMMAND := { status | hostname | permissions | logging }

  status

  hostname [<hostname>]

  permissions

  logging [level <log level>] [domains <log domains>]
In the second example above the help is related to the object general.
The nmcli-examples(5) man page has many useful examples. A brief selection is shown here:
To show the overall status of NetworkManager:
nmcli general status
To control NetworkManager logging:
nmcli general logging
To show all connections:
nmcli connection show
To show only currently active connections, add the -a, --active option as follows:
nmcli connection show --active
To show devices recognized by NetworkManager and their state:
nmcli device status
Commands can be shortened and some options omitted. For example the command:
nmcli connection modify id 'MyCafe' 802-11-wireless.mtu 1350
Can be reduced to the following command:
nmcli con mod MyCafe 802-11-wireless.mtu 1350
The id option can be omitted because the connection ID (name) is unambiguous for nmcli in this case. As you become familiar with the commands, further abbreviations can be made. For example:
nmcli connection add type ethernet
can be reduced to:
nmcli c a type eth

Note

Remember to use tab completion when in doubt.

Starting and Stopping an Interface Using nmcli

The nmcli tool can be used to start and stop any network interface, including masters. For example:
nmcli con up id bond0
nmcli con up id port0
nmcli dev disconnect bond0
nmcli dev disconnect ens3

Note

It is recommended to use nmcli dev disconnect iface-name rather than nmcli con down id id-string because disconnection places the interface into a manual mode, in which no automatic connection will be started until the user tells NetworkManager to start a connection or until an external event like a carrier change, hibernate, or sleep, occurs.

The nmcli Interactive Connection Editor

The nmcli tool has an interactive connection editor. To use it, enter the following command:
~]$ nmcli con edit
You will be prompted to enter a valid connection type from the list displayed. After entering a connection type you will be placed at the nmcli prompt. If you are familiar with the connection types you can add a valid connection type option to the nmcli con edit command and be taken straight to the nmcli prompt. The format is as follows for editing an existing connection profile:
nmcli con edit [id | uuid | path] ID
For adding and editing a new connection profile, the following format applies:
nmcli con edit [type new-connection-type] [con-name new-connection-name]
Type help at the nmcli prompt to see a list of valid commands. Use the describe command to get a description of settings and their properties. The format is as follows:
describe setting.property
For example:
nmcli> describe team.config

2.3.1. Understanding the nmcli Options

Many of the nmcli commands are self-explanatory, however a few command options are worth a moments study:
type — The 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. Press Tab to see a list of them or see the TYPE_SPECIFIC_OPTIONS list in the nmcli(1) man page. The type option is applicable after the following: nmcli connection add and nmcli connection edit.
con-name — The name assigned to a connection profile.
If you do not specify a connection name, one will be generated as follows:
 type-ifname[-number]
The connection name is the name of a connection profile and should not be confused with the interface name that denotes a device (wlan0, ens3, em1, and so on). Users can however 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.
id — An identification string assigned by the user to a connection profile.
The ID can be used in nmcli connection commands to identify a connection. The NAME field in the output always denotes the connection ID (name). 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.

2.3.2. Connecting to a Network Using nmcli

To list the currently available network connections, issue a command as follows:
~]$ nmcli con show
NAME              UUID                                  TYPE            DEVICE
Auto Ethernet     9b7f2511-5432-40ae-b091-af2457dfd988  802-3-ethernet  --
ens3              fb157a65-ad32-47ed-858c-102a48e064a2  802-3-ethernet  ens3
MyWiFi            91451385-4eb8-4080-8b82-720aab8328dd  802-11-wireless wlan0
Note that the NAME field in the output always denotes the connection ID (name). It is not the interface name even though it might look the same. In the second connection shown above, ens3 in the NAME field is the connection ID given by the user to the profile applied to the interface ens3. In the last connection shown, the user has assigned the connection ID MyWiFi to the interface wlan0.
Adding an Ethernet connection means creating a configuration profile which is then assigned to a device. Before creating a new profile, review the available devices as follows:
~]$ nmcli dev status
DEVICE  TYPE      STATE         CONNECTION
ens3    ethernet  disconnected  --
ens9    ethernet  disconnected  --
lo      loopback  unmanaged     --

Adding a Dynamic Ethernet Connection

To add an Ethernet configuration profile with dynamic IP configuration, allowing DHCP to assign the network configuration, a command in the following format can be used:
nmcli connection add type ethernet con-name connection-name ifname interface-name
For example, to create a dynamic connection profile named my-office, issue a command as follows:
~]$ nmcli con add type ethernet con-name my-office ifname ens3
Connection 'my-office' (fb157a65-ad32-47ed-858c-102a48e064a2) successfully added.
NetworkManager will set its internal parameter connection.autoconnect to yes. NetworkManager will also write out settings to /etc/sysconfig/network-scripts/ifcfg-my-office where the ONBOOT directive will be set to yes.
Note that manual changes to the ifcfg file will not be noticed by NetworkManager until the interface is next brought up. See Section 1.9, “Network Configuration Using sysconfig Files” for more information on using configuration files.
To bring up the Ethernet connection, issue a command as follows:
~]$ nmcli con up my-office
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/5)
Review the status of the devices and connections:
~]$ nmcli device status
DEVICE  TYPE      STATE         CONNECTION
ens3    ethernet  connected     my-office
ens9    ethernet  disconnected  --
lo      loopback  unmanaged     --
To change the host name sent by a host to a DHCP server, modify the dhcp-hostname property as follows:
~]$ nmcli con modify my-office my-office ipv4.dhcp-hostname host-name ipv6.dhcp-hostname host-name
To change the IPv4 client ID sent by a host to a DHCP server, modify the dhcp-client-id property as follows:
~]$ nmcli con modify my-office my-office ipv4.dhcp-client-id client-ID-string
There is no dhcp-client-id property for IPv6, dhclient creates an identifier for IPv6. See the dhclient(8) man page for details.
To ignore the DNS servers sent to a host by a DHCP server, modify the ignore-auto-dns property as follows:
~]$ nmcli con modify my-office my-office ipv4.ignore-auto-dns yes ipv6.ignore-auto-dns yes
See the nm-settings(5) man page for more information on properties and their settings.

Example 2.1. Configuring a Dynamic Ethernet Connection Using the Interactive Editor

To configure a dynamic Ethernet connection using the interactive editor, issue commands as follows:
~]$ nmcli con edit type ethernet con-name ens3

===| nmcli interactive connection editor |===

Adding a new '802-3-ethernet' connection

Type 'help' or '?' for available commands.
Type 'describe [<setting>.<prop>]' for detailed property description.

You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb
nmcli> describe ipv4.method

=== [method] ===
[NM property description]
IPv4 configuration method.  If 'auto' is specified then the appropriate automatic method (DHCP, PPP, etc) is used for the interface and most other properties can be left unset.  If 'link-local' is specified, then a link-local address in the 169.254/16 range will be assigned to the interface.  If 'manual' is specified, static IP addressing is used and at least one IP address must be given in the 'addresses' property.  If 'shared' is specified (indicating that this connection will provide network access to other computers) then the interface is assigned an address in the 10.42.x.1/24 range and a DHCP and forwarding DNS server are started, and the interface is NAT-ed to the current default network connection.  'disabled' means IPv4 will not be used on this connection.  This property must be set.

nmcli> set ipv4.method auto
nmcli> save
Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection.
Do you still want to save? [yes] yes
Connection 'ens3' (090b61f7-540f-4dd6-bf1f-a905831fc287) successfully saved.
nmcli> quit
~]$
The default action is to save the connection profile as persistent. If required, the profile can be held in memory only, until the next restart, by means of the save temporary command.

Adding a Static Ethernet Connection

To add an Ethernet connection with static IPv4 configuration, a command in the following format can be used:
nmcli connection add type ethernet con-name connection-name ifname interface-name ip4 address gw4 address
IPv6 address and gateway information can be added using the ip6 and gw6 options.
For example, a command to create a static Ethernet connection with only IPv4 address and gateway is as follows:
~]$ nmcli con add type ethernet con-name test-lab ifname ens9 ip4 10.10.10.10/24 \
gw4 10.10.10.254
Optionally, at the same time specify IPv6 address and gateway for the device as follows:
~]$ nmcli con add type ethernet con-name test-lab ifname ens9 ip4 10.10.10.10/24 \
gw4 10.10.10.254 ip6 abbe::cafe gw6 2001:db8::1
Connection 'test-lab' (05abfd5e-324e-4461-844e-8501ba704773) successfully added.
NetworkManager will set its internal parameter ipv4.method to manual and connection.autoconnect to yes. NetworkManager will also write out settings to /etc/sysconfig/network-scripts/ifcfg-my-office where the corresponding BOOTPROTO will be set to none and ONBOOT will be set to yes.
Note that manual changes to the ifcfg file will not be noticed by NetworkManager until the interface is next brought up. See Section 1.9, “Network Configuration Using sysconfig Files” for more information on using configuration files.
To set two IPv4 DNS server addresses:
~]$ nmcli con mod test-lab ipv4.dns "8.8.8.8 8.8.4.4"
Note that this will replace any previously set DNS servers. To set two IPv6 DNS server addresses:
~]$ nmcli con mod test-lab ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844"
Note that this will replace any previously set DNS servers. Alternatively, to add additional DNS servers to any previously set, use the + prefix as follows:
~]$ nmcli con mod test-lab +ipv4.dns "8.8.8.8 8.8.4.4"
~]$ nmcli con mod test-lab +ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844"
To bring up the new Ethernet connection, issue a command as follows:
~]$ nmcli con up test-lab ifname ens9
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/6)
Review the status of the devices and connections:
~]$ nmcli device status
DEVICE  TYPE      STATE      CONNECTION
ens3    ethernet  connected  my-office
ens9    ethernet  connected  test-lab
lo      loopback  unmanaged  --
To view detailed information about the newly configured connection, issue a command as follows:
~]$ nmcli -p con show test-lab
===============================================================================
                     Connection profile details (test-lab)
===============================================================================
connection.id:                          test-lab
connection.uuid:                        05abfd5e-324e-4461-844e-8501ba704773
connection.interface-name:              ens9
connection.type:                        802-3-ethernet
connection.autoconnect:                 yes
connection.timestamp:                   1410428968
connection.read-only:                   no
connection.permissions:                 
connection.zone:                        --
connection.master:                      --
connection.slave-type:                  --
connection.secondaries:                 
connection.gateway-ping-timeout:        0
[output truncated]
The use of the -p, --pretty option adds a title banner and section breaks to the output.

Example 2.2. Configuring a Static Ethernet Connection Using the Interactive Editor

To configure a static Ethernet connection using the interactive editor, issue commands as follows:
~]$ nmcli con edit type ethernet con-name ens3

===| nmcli interactive connection editor |===

Adding a new '802-3-ethernet' connection

Type 'help' or '?' for available commands.
Type 'describe [>setting<.>prop<]' for detailed property description.

You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb
nmcli> set ipv4.addresses 192.168.122.88/24
Do you also want to set 'ipv4.method' to 'manual'? [yes]: yes
nmcli>
nmcli> save temporary
Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection.
Do you still want to save? [yes] no
nmcli> save
Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection.
Do you still want to save? [yes] yes
Connection 'ens3' (704a5666-8cbd-4d89-b5f9-fa65a3dbc916) successfully saved.
nmcli> quit
~]$
The default action is to save the connection profile as persistent. If required, the profile can be held in memory only, until the next restart, by means of the save temporary command.

Locking a Profile to a Specific Device

To lock a profile to a specific interface device, the commands used in the examples above include the interface name. For example:
nmcli connection add type ethernet con-name connection-name ifname interface-name
To make a profile usable for all compatible Ethernet interfaces, issue a command as follows:
nmcli connection add type ethernet con-name connection-name ifname "*"
Note that you have to use the ifname argument even if you do not want to set a specific interface. Use the wildcard character * to specify that the profile can be used with any compatible device.
To lock a profile to a specific MAC address, use a command in the following format:
nmcli connection add type ethernet con-name "connection-name" ifname "*" mac 00:00:5E:00:53:00

Adding a Wi-Fi Connection

To view the available Wi-Fi access points, issue a command as follows:
~]$ nmcli dev wifi list
  SSID            MODE  CHAN  RATE     SIGNAL  BARS  SECURITY
  FedoraTest     Infra  11    54 MB/s  98      ▂▄▆█  WPA1
  Red Hat Guest  Infra  6     54 MB/s  97      ▂▄▆█  WPA2
  Red Hat        Infra  6     54 MB/s  77      ▂▄▆_  WPA2 802.1X
* Red Hat        Infra  40    54 MB/s  66      ▂▄▆_  WPA2 802.1X
  VoIP           Infra  1     54 MB/s  32      ▂▄__  WEP
  MyCafe         Infra  11    54 MB/s  39      ▂▄__  WPA2
To create a Wi-Fi connection profile with static IP configuration, but allowing automatic DNS address assignment, issue a command as follows:
~]$ nmcli con add con-name MyCafe ifname wlan0 type wifi ssid MyCafe \
ip4 192.168.100.101/24 gw4 192.168.100.1
To set a WPA2 password, for example caffeine, issue commands as follows:
~]$ nmcli con modify MyCafe wifi-sec.key-mgmt wpa-psk
~]$ nmcli con modify MyCafe wifi-sec.psk caffeine
See the Red Hat Enterprise Linux 7 Security Guide for information on password security.
To change Wi-Fi state, issue a command in the following format:
~]$ nmcli radio wifi [on | off ]

Changing a Specific Property

To check a specific property, for example mtu, issue a command as follows:
~]$ nmcli connection show id 'MyCafe' | grep mtu
802-11-wireless.mtu:                     auto
To change the property of a setting, issue a command as follows:
~]$ nmcli connection modify id 'MyCafe' 802-11-wireless.mtu 1350
To verify the change, issue a command as follows:
~]$ nmcli connection show id 'MyCafe' | grep mtu
802-11-wireless.mtu:                     1350
Note that NetworkManager refers to parameters such as 802-3-ethernet and 802-11-wireless as the setting, and mtu as a property of the setting. See the nm-settings(5) man page for more information on properties and their settings.

2.3.3. Configuring Static Routes Using nmcli

To configure static routes using the nmcli tool, the command line or the interactive editor mode can be used.

Example 2.3. Configuring Static Routes Using nmcli

To configure a static route for an existing Ethernet connection using the command line, enter a command as follows:
~]# nmcli connection modify eth0 +ipv4.routes "192.168.122.0/24 10.10.10.1"
This will direct traffic for the 192.168.122.0/24 subnet to the gateway at 10.10.10.1

Example 2.4. Configuring Static Routes Using nmcli Editor

To configure a static route for an Ethernet connection using the interactive editor, issue commands as follows:
~]$ nmcli con edit type ethernet con-name ens3

===| nmcli interactive connection editor |===

Adding a new '802-3-ethernet' connection

Type 'help' or '?' for available commands.
Type 'describe [>setting<.>prop<]' for detailed property description.

You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6, dcb
nmcli> set ipv4.routes 192.168.122.0/24 10.10.10.1
nmcli>
nmcli> save persistent
Saving the connection with 'autoconnect=yes'. That might result in an immediate activation of the connection.
Do you still want to save? [yes] yes
Connection 'ens3' (704a5666-8cbd-4d89-b5f9-fa65a3dbc916) successfully saved.
nmcli> quit
~]$