Red Hat Training
A Red Hat training course is available for Red Hat Enterprise Linux
3.3. Configuring IP Networking 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. See Section 2.5, “NetworkManager Tools”. 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 3.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 3.2. Specifying Fields in the output
~]$
or even better for scripting:nmcli -f DEVICE,TYPE device
DEVICE TYPE ens3 ethernet lo loopback~]$
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.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:
nmcli help
- This command lists the available options and object names to be used in subsequent commands.
nmcli object help
- This command displays the list of available actions related to a specified object. For example,
nmcli c help
3.3.1. Brief Selection of nmcli Examples
Example 3.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 3.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 3.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 3.7. Viewing only currently active connections
~]$ nmcli connection show --active
NAME UUID TYPE DEVICE
Profile 1 db1060e9-c164-476f-b2b5-caec62dc1b05 ethernet ens3
Example 3.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 3.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 |
For more examples, see the nmcli-examples(5) man page.
3.3.2. Starting and Stopping a Network Interface Using nmcli
The nmcli tool can be used to start and stop any network interface, including controllers. For example:
nmcli con up id bond0 nmcli con up id port0 nmcli dev disconnect bond0 nmcli dev disconnect ens3
Note
The
nmcli connection down
command, deactivates a connection from a device without preventing the device from further auto-activation. The nmcli device disconnect
command, disconnects a device and prevent the device from automatically activating further connections without manual intervention.
3.3.3. Understanding the nmcli Options
Following are some of the important nmcli property options. See the comprehensive list in the nmcli(1) man page :
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. You can see the
TYPE_SPECIFIC_OPTIONS
list in the nmcli(1) man page. For example:- A
gsm
connection requires the access point name specified in anapn
.nmcli c add connection.type gsm apn access_point_name
- A
wifi
device requires the service set identifier specified in assid
.nmcli c add connection.type wifi ssid My identifier
connection.interface-name
- A device name relevant for the connection.
nmcli con add connection.interface-name enp1s0 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
Theconnection.id
is the name of a connection profile and should not be confused with the interface name which denotes a device (wlp61s0
,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. Theid
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 innmcli connection
commands to identify a connection.
3.3.4. Using the nmcli Interactive Connection Editor
The nmcli tool has an interactive connection editor. To use it:
~]$ 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] IDFor editing a new connection profile:
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: describe setting.propertyFor example:
nmcli> describe team.config
3.3.5. Creating and Modifying a Connection Profile with nmcli
A connection profile contains the connection property information needed to connect to a data source.
To create a new profile for NetworkManager using nmcli:
nmcli c add {ARGUMENTS}
The
nmcli c add
accepts two different types of parameters:
- Property names
- the names which NetworkManager uses to describe the connection internally. The most important are:
- connection.type
nmcli c add connection.type
bond
- connection.interface-name
nmcli c add connection.interface-name
enp1s0
- connection.id
nmcli c add connection.id
"My Connection"
See thenm-settings(5)
man page for more information on properties and their settings.
- Aliases names
- the human-readable names which are translated to properties internally. The most common are:
- type (the connection.type property)
nmcli c add type
bond
- ifname (the connection.interface-name property)
nmcli c add ifname
enp1s0
- con-name (the connection.id property)
nmcli c add con-name
"My Connection"
In previous versions of
nmcli
, to create a connection required using the aliases
. For example, ifname
enp1s0 and con-name
My Connection. A command in the following format could be used: nmcli c add type ethernet ifname enp1s0 con-name "My Connection"
In more recent versions, both the
property names
and the aliases
can be used interchangeably. The following examples are all valid and equivalent: nmcli c add type ethernet ifname enp1s0 con-name "My Connection" ethernet.mtu 1600
nmcli c add connection.type ethernet ifname enp1s0 con-name "My Connection" ethernet.mtu 1600
nmcli c add connection.type ethernet connection.interface-name enps1s0 connection.id "My Connection" ethernet.mtu 1600
The arguments differ according to the connection types. Only the
type
argument is mandatory for all connection types and ifname
is mandatory for all types except bond
, team
, bridge
and vlan
.
- type type_name
- connection type. For example:
nmcli c add type
bond
- ifname interface_name
- interface to bind the connection to. For example:
nmcli c add ifname interface_name type ethernet
To modify one or more properties of a connection profile, use the following command:
nmcli c modify
For example, to change the
connection.id
from My Connection to My favorite connection
and the connection.interface-name
to enp1s0
, issue the command as follows: nmcli c modify "My Connection" connection.id "My favorite connection" connection.interface-name enp1s0
Note
It is preferable to use the
property names
. The aliases
are used only for compatibility reasons.
In addition, to set the ethernet MTU to 1600, modify the size as follows:
nmcli c modify "My favorite connection" ethernet.mtu 1600
To apply changes after a modified connection using nmcli, activate again the connection by entering this command:
nmcli con up con-name
For example:
nmcli con up My-favorite-connection
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/16)
3.3.6. Connecting to a Network Using nmcli
To list the currently available network connections:
~]$ 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 wlp61s0
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 wlp61s0.
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 device status
DEVICE TYPE STATE CONNECTION
ens3 ethernet disconnected --
ens9 ethernet disconnected --
lo loopback unmanaged --
3.3.7. Adding and Configuring a Dynamic Ethernet Connection with nmcli
Adding a Dynamic Ethernet Connection
To add an Ethernet configuration profile with dynamic
IP
configuration, allowing DHCP
to assign the network configuration: nmcli connection add type ethernet con-name connection-name ifname interface-name
For example, to create a dynamic connection profile named my-office:
~]$ nmcli con add type ethernet con-name my-office ifname ens3
Connection 'my-office' (fb157a65-ad32-47ed-858c-102a48e064a2) successfully added.
To open the Ethernet connection:
~]$ 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 --
Configuring a Dynamic Ethernet Connection
To change the host name sent by a host to a
DHCP
server, modify the dhcp-hostname
property:
~]$ 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:
~]$ 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:
~]$ 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 3.9. Configuring a Dynamic Ethernet Connection Using the Interactive Editor
To configure a dynamic Ethernet connection using the interactive editor:
~]$ 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.
3.3.8. Adding and Configuring a Static Ethernet Connection with nmcli
Adding a Static Ethernet Connection
To add an Ethernet connection with static
IPv4
configuration: 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, to create a static Ethernet connection with only
IPv4
address and gateway:
~]$Optionally, at the same time specifynmcli con add type ethernet con-name test-lab ifname ens9 ip4 10.10.10.10/24 \
gw4 10.10.10.254
IPv6
address and gateway for the device:
~]$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.
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:
~]$ 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 open the new Ethernet connection:
~]$ 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 3.10. Configuring a Static Ethernet Connection Using the Interactive Editor
To configure a static Ethernet connection using the interactive editor:
~]$ 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.
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 corresponding BOOTPROTO will be set to none
and ONBOOT 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 2.7, “Using NetworkManager with sysconfig files”, Section 3.5, “Configuring IP Networking with ifcfg Files” for more information on using configuration files.
3.3.9. Locking a Profile to a Specific Device Using nmcli
To lock a profile to a specific interface device:
nmcli connection add type ethernet con-name connection-name ifname interface-nameTo make a profile usable for all compatible Ethernet interfaces:
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:
nmcli connection add type ethernet con-name "connection-name" ifname "*" mac 00:00:5E:00:53:00
3.3.10. Adding a Wi-Fi Connection with nmcli
To view the available Wi-Fi access points:
~]$ 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:
~]$To set a WPA2 password, for example “caffeine”:nmcli con add con-name MyCafe ifname wlp61s0 type wifi ssid MyCafe \
ip4 192.168.100.101/24 gw4 192.168.100.1
~]$See the Red Hat Enterprise Linux 7 Security Guide for information on password security.nmcli con modify MyCafe wifi-sec.key-mgmt wpa-psk
~]$nmcli con modify MyCafe wifi-sec.psk caffeine
To change Wi-Fi state:
~]$ nmcli radio wifi [on | off ]
Changing a Specific Property Using nmcli
To check a specific property, for example
mtu
:
~]$ nmcli connection show id 'MyCafe' | grep mtu
802-11-wireless.mtu: auto
To change the property of a setting:
~]$ nmcli connection modify id 'MyCafe' 802-11-wireless.mtu 1350
To verify the change:
~]$ 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.
3.3.11. Configuring NetworkManager to Ignore Certain Devices
By default, NetworkManager manages all devices except the
lo
(loopback) device. However, you can set certain devices as unmanaged
to configure that NetworkManager ignores these devices. With this setting, you can manually manage these devices, for example, using a script.
3.3.11.1. Permanently Configuring a Device as Unmanaged in NetworkManager
You can configure devices as
unmanaged
based on several criteria, such as the interface name, MAC address, or device type. This procedure describes how to permanently set the enp1s0
interface as unmanaged in NetworkManager.
To temporarily configure network devices as
unmanaged
, see Section 3.3.11.2, “Temporarily Configuring a Device as Unmanaged in NetworkManager”.
Procedure
- Optional: Display the list of devices to identify the device you want to set as
unmanaged
:#
nmcli device status
DEVICE TYPE STATE CONNECTION enp1s0 ethernet disconnected -- ... - Create the
/etc/NetworkManager/conf.d/99-unmanaged-devices.conf
file with the following content:[keyfile] unmanaged-devices=interface-name:enp1s0
To set multiple devices as unmanaged, separate the entries in theunmanaged-devices
parameter with semicolon:[keyfile] unmanaged-devices=interface-name:interface_1;interface-name:interface_2;...
- Reload the
NetworkManager
service:#
systemctl reload NetworkManager
Verification Steps
- Display the list of devices:
#
nmcli device status
DEVICE TYPE STATE CONNECTION enp1s0 ethernet unmanaged -- ...Theunmanaged
state next to theenp1s0
device indicates that NetworkManager does not manage this device.
Additional Resources
For a list of criteria you can use to configure devices as unmanaged and the corresponding syntax, see the Device List Format section in the NetworkManager.conf(5) man page.
3.3.11.2. Temporarily Configuring a Device as Unmanaged in NetworkManager
You can configure devices as
unmanaged
based on several criteria, such as the interface name, MAC address, or device type. This procedure describes how to temporarily set the enp1s0
interface as unmanaged
in NetworkManager.
Use this method, for example, for testing purposes. To permanently configure network devices as
unmanaged
, see Section 3.3.11.1, “Permanently Configuring a Device as Unmanaged in NetworkManager”.
Procedure
- Optional: Display the list of devices to identify the device you want to set as
unmanaged
:#
nmcli device status
DEVICE TYPE STATE CONNECTION enp1s0 ethernet disconnected -- ... - Set the
enp1s0
device to theunmanaged
state:#
nmcli device set enp1s0 managed no
Verification Steps
- Display the list of devices:
#
nmcli device status
DEVICE TYPE STATE CONNECTION enp1s0 ethernet unmanaged -- ...Theunmanaged
state next to theenp1s0
device indicates that NetworkManager does not manage this device.
Additional Resources
For a list of criteria you can use to configure devices as unmanaged and the corresponding syntax, see the Device List Format section in the NetworkManager.conf(5) man page.