Product SiteDocumentation Site

2.4.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 
eth0  96a5deb0-5eb0-41e1-a7ed-38fea413f9c8  802-3-ethernet  eth0
MyWiFi             91451385-4eb8-4080-8b82  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 example above eth0 is the connection ID given by the user to the profile applied to the interface eth0. In the second line 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
wlan0     wifi          connected     my-ssid
eth0      ethernet  	unavailable   --
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 eth0
Connection 'my-office' (0a053110-5361-412c-a4fb-6ff20877e9e4) 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.7, “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/1)
Review the status of the devices and connections:
~]$ nmcli device status
DEVICE  TYPE      STATE         CONNECTION
eth0    ethernet  connected     my-office
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 eth0

===| 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 'eth0' (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 eth1 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 eth1 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.7, “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 eth1
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/2
Review the status of the devices and connections:
~]$ nmcli device status
DEVICE  TYPE      STATE      CONNECTION
eth0    ethernet  connected  my-office
eth1    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:              eth1
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.

Modifying a Static Ethernet Connection

To replace existing IP addresses, enter a command as follows:
~]$ nmcli con mod test-lab ipv4.addresses "192.168.112.112"
To add additional IP addresses, use the + prefix as follows:
~]$ nmcli con mod test-lab +ipv4.addresses "192.168.114.114"
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 eth0

===| 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 'eth0' (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
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.