3.3. Configuring IP Networking with nmcli
- 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.
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.
- -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.
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 --
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 |
3.3.2. Starting and Stopping a Network Interface Using nmcli
nmcli con up id bond0 nmcli con up id port0 nmcli dev disconnect bond0 nmcli dev disconnect ens3
Note
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
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.
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
~]$ 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]
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
nmcli c add {ARGUMENTS}
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"
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"
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
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
nmcli c modify
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
property names
. The aliases
are used only for compatibility reasons.
nmcli c modify "My favorite connection" ethernet.mtu 1600
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
~]$ 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.
~]$ 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
IP
configuration, allowing DHCP
to assign the network configuration: nmcli connection add type ethernet con-name connection-name ifname interface-name
~]$ nmcli con add type ethernet con-name my-office ifname ens3
Connection 'my-office' (fb157a65-ad32-47ed-858c-102a48e064a2) successfully added.
~]$ 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
DHCP
server, modify the dhcp-hostname
property:
~]$ nmcli con modify my-office my-office ipv4.dhcp-hostname host-name ipv6.dhcp-hostname host-name
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.
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
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
~]$ 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
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.
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.
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"
~]$ 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 --
~]$ 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
~]$ 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.
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
.
3.3.9. Locking a Profile to a Specific Device Using nmcli
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.
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
~]$ 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
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
~]$ nmcli radio wifi [on | off ]
Changing a Specific Property Using nmcli
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
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
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
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.
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
3.3.11.2. Temporarily Configuring a Device as Unmanaged in NetworkManager
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.
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.