2.4. 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.

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

~]$ 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 been 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 iface bond0
nmcli dev disconnect iface eth0

Note

It is recommended to use nmcli dev disconnect iface 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.4.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, generic, gsm, infiniband, olpc-mesh, pppoe, team, team-slave, vlan, vpn, 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, eth0, 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.