Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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

~]$ 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.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
Copy link

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:
Expand
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.
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
Copy link

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 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
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
The connection.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. 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.
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] ID
For 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.property
For example: 
nmcli> describe team.config
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 the nm-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
Copy link

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

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.

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: 
~]$ 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: 
~]$ 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.
To lock a profile to a specific interface device: 
nmcli connection add type ethernet con-name connection-name ifname interface-name
To 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
Copy link

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: 
~]$ nmcli con add con-name MyCafe ifname wlp61s0 type wifi ssid MyCafe \
ip4 192.168.100.101/24 gw4 192.168.100.1
To set a WPA2 password, for example “caffeine”: 
~]$ 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: 
~]$ 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.
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.
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

  1. 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  --
...
  2. 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 the unmanaged-devices parameter with semicolon: 
    [keyfile]
unmanaged-devices=interface-name:interface_1;interface-name:interface_2;...
  3. Reload the NetworkManager service: 
    # systemctl reload NetworkManager

Verification Steps

  • Display the list of devices: 
    # nmcli device status
DEVICE  TYPE      STATE      CONNECTION
enp1s0  ethernet  unmanaged  --
...
    The unmanaged state next to the enp1s0 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.
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

  1. 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  --
...
  2. Set the enp1s0 device to the unmanaged state: 
    # nmcli device set enp1s0 managed no

Verification Steps

  • Display the list of devices: 
    # nmcli device status
DEVICE  TYPE      STATE      CONNECTION
enp1s0  ethernet  unmanaged  --
...
    The unmanaged state next to the enp1s0 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.
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top