1NMCLI-EXAMPLES(7)                  Examples                  NMCLI-EXAMPLES(7)
2
3
4

NAME

6       nmcli-examples - usage examples of nmcli
7

SYNOPSIS

9       nmcli [OPTIONS...]
10

DESCRIPTION

12       nmcli is a command-line client for NetworkManager. It allows
13       controlling NetworkManager and reporting its status. For more
14       information please refer to nmcli(1) manual page.
15
16       The purpose of this manual page is to provide you with various examples
17       and usage scenarios of nmcli.
18

EXAMPLES

20       Example 1. Listing available Wi-Fi APs
21
22           $ nmcli device wifi list
23           *  SSID               MODE    CHAN  RATE       SIGNAL  BARS  SECURITY
24              netdatacomm_local  Infra   6     54 Mbit/s  37      ▂▄__  WEP
25           *  F1                 Infra   11    54 Mbit/s  98      ▂▄▆█  WPA1
26              LoremCorp          Infra   1     54 Mbit/s  62      ▂▄▆_  WPA2 802.1X
27              Internet           Infra   6     54 Mbit/s  29      ▂___  WPA1
28              HPB110a.F2672A     Ad-Hoc  6     54 Mbit/s  22      ▂___  --
29              Jozinet            Infra   1     54 Mbit/s  19      ▂___  WEP
30              VOIP               Infra   1     54 Mbit/s  20      ▂___  WEP
31              MARTINA            Infra   4     54 Mbit/s  32      ▂▄__  WPA2
32              N24PU1             Infra   7     11 Mbit/s  22      ▂___  --
33              alfa               Infra   1     54 Mbit/s  67      ▂▄▆_  WPA2
34              bertnet            Infra   5     54 Mbit/s  20      ▂___  WPA1 WPA2
35
36       This command shows how to list available Wi-Fi networks (APs). You can
37       also use --fields option for displaying different columns.  nmcli -f
38       all dev wifi list will show all of them.
39
40       Example 2. Showing general information and properties for a Wi-Fi
41       interface
42
43           $ nmcli -p -f general,wifi-properties device show wlan0
44           ===========================================================================
45                                   Device details (wlan0)
46           ===========================================================================
47           GENERAL.DEVICE:           wlan0
48           GENERAL.TYPE:             wifi
49           GENERAL.VENDOR:           Intel Corporation
50           GENERAL.PRODUCT:          PRO/Wireless 5100 AGN [Shiloh] Network Connection
51           GENERAL.DRIVER:           iwlwifi
52           GENERAL.DRIVER-VERSION:   3.8.13-100.fc17.x86_64
53           GENERAL.FIRMWARE-VERSION: 8.83.5.1 build 33692
54           GENERAL.HWADDR:           00:1E:65:37:A1:D3
55           GENERAL.MTU:              1500
56           GENERAL.STATE:            100 (connected)
57           GENERAL.REASON:           0 (No reason given)
58           GENERAL.UDI:              /sys/devices/pci0000:00/0000:00:1c.1/net/wlan0
59           GENERAL.IP-IFACE:         wlan0
60           GENERAL.IS-SOFTWARE:      no
61           GENERAL.NM-MANAGED:       yes
62           GENERAL.AUTOCONNECT:      yes
63           GENERAL.FIRMWARE-MISSING: no
64           GENERAL.CONNECTION:       My Alfa WiFi
65           GENERAL.CON-UUID:         85194f4c-d496-4eec-bae0-d880b4cbcf26
66           GENERAL.CON-PATH:         /org/freedesktop/NetworkManager/ActiveConnection/
67           10
68           ---------------------------------------------------------------------------
69           WIFI-PROPERTIES.WEP:      yes
70           WIFI-PROPERTIES.WPA:      yes
71           WIFI-PROPERTIES.WPA2:     yes
72           WIFI-PROPERTIES.TKIP:     yes
73           WIFI-PROPERTIES.CCMP:     yes
74           WIFI-PROPERTIES.AP:       no
75           WIFI-PROPERTIES.ADHOC:    yes
76           ---------------------------------------------------------------------------
77
78       This command shows information about a Wi-Fi device.
79
80       Example 3. Listing NetworkManager polkit permissions
81
82           $ nmcli general permissions
83           PERMISSION                                                VALUE
84           org.freedesktop.NetworkManager.enable-disable-network     yes
85           org.freedesktop.NetworkManager.enable-disable-wifi        yes
86           org.freedesktop.NetworkManager.enable-disable-wwan        yes
87           org.freedesktop.NetworkManager.enable-disable-wimax       yes
88           org.freedesktop.NetworkManager.sleep-wake                 no
89           org.freedesktop.NetworkManager.network-control            yes
90           org.freedesktop.NetworkManager.wifi.share.protected       yes
91           org.freedesktop.NetworkManager.wifi.share.open            yes
92           org.freedesktop.NetworkManager.settings.modify.system     yes
93           org.freedesktop.NetworkManager.settings.modify.own        yes
94           org.freedesktop.NetworkManager.settings.modify.hostname   auth
95           org.freedesktop.NetworkManager.settings.modify.global-dns auth
96           org.freedesktop.NetworkManager.reload                     auth
97
98       This command shows configured polkit permissions for various
99       NetworkManager operations. These permissions or actions (using polkit
100       language) are configured by a system administrator and are not meant to
101       be changed by users. The usual place for the polkit configuration is
102       /usr/share/polkit-1/actions/org.freedesktop.NetworkManager.policy.
103       pkaction command can display description for polkit actions.
104
105             pkaction --action-id org.freedesktop.NetworkManager.network-control --verbose
106
107
108       More information about polkit can be found at
109       http://www.freedesktop.org/wiki/Software/polkit.
110
111       Example 4. Listing NetworkManager log level and domains
112
113           $ nmcli general logging
114           LEVEL  DOMAINS
115           INFO   PLATFORM,RFKILL,ETHER,WIFI,BT,MB,DHCP4,DHCP6,PPP,WIFI_SCAN,IP4,IP6,A
116           UTOIP4,DNS,VPN,SHARING,SUPPLICANT,AGENTS,SETTINGS,SUSPEND,CORE,DEVICE,OLPC,
117           WIMAX,INFINIBAND,FIREWALL,ADSL,BOND,VLAN,BRIDGE,DBUS_PROPS,TEAM,CONCHECK,DC
118           B,DISPATCH
119
120       This command shows current NetworkManager logging status.
121
122       Example 5. Changing NetworkManager logging
123
124           $ nmcli g log level DEBUG domains CORE,ETHER,IP
125           $ nmcli g log level INFO domains DEFAULT
126
127       The first command makes NetworkManager log in DEBUG level, and only for
128       CORE, ETHER and IP domains. The second command restores the default
129       logging state. Please refer to the NetworkManager.conf(5) manual page
130       for available logging levels and domains.
131
132       Example 6. Activating a VPN connection profile requiring interactive
133       password input
134
135           $ nmcli --ask con up my-vpn-con
136
137       This command activates a VPN connection profile enabling nmcli to
138       interact with the user ('--ask'): this will allow nmcli to prompt for
139       the VPN password on the command line when the password-flags are set to
140       '0x02' ('always ask', see nm-settings(5) ). This is particularly useful
141       for OTP based VPNs, as the user needs to be prompted for the password
142       each time the connection is activated.
143
144       Example 7. Adding a bonding master and two slave connection profiles
145
146           $ nmcli con add type bond ifname mybond0 mode active-backup
147           $ nmcli con add type ethernet ifname eth1 master mybond0
148           $ nmcli con add type ethernet ifname eth2 master mybond0
149
150       This example demonstrates adding a bond master connection and two
151       slaves. The first command adds a master bond connection, naming the
152       bonding interface mybond0 and using active-backup mode. The next two
153       commands add slaves connections, both enslaved to mybond0. The first
154       slave will be bound to eth1 interface, the second to eth2.
155
156       Example 8. Adding a team master and two slave connection profiles
157
158           $ nmcli con add type team con-name Team1 ifname Team1 config team1-master-json.conf
159           $ nmcli con add type ethernet con-name Team1-slave1 ifname em1 master Team1
160           $ nmcli con add type ethernet con-name Team1-slave2 ifname em2 master Team1
161
162       This example demonstrates adding a team master connection profile and
163       two slaves. It is very similar to the bonding example. The first
164       command adds a master team profile, naming the team interface and the
165       profile Team1. The team configuration for the master is read from
166       team1-master-json.conf file. Later, you can change the configuration
167       with modify command (nmcli con modify Team1 team.config
168       team1-master-another-json.conf). The last two commands add slaves
169       profiles, both enslaved to Team1. The first slave will be bound to em1
170       interface, the second to em2. The slaves don't specify config and thus
171       teamd will use its default configuration. You will activate the whole
172       setup by activating both slaves:
173
174             $ nmcli con up Team1-slave1
175             $ nmcli con up Team1-slave2
176
177       By default, the created profiles are marked for auto-activation. But if
178       another connection has been activated on the device, the new profile
179       won't activate automatically and you need to activate it manually.
180
181       Example 9. Adding a bridge and two slave profiles
182
183           $ nmcli con add type bridge con-name TowerBridge ifname TowerBridge
184           $ nmcli con add type ethernet con-name br-slave-1 ifname ens3 master TowerBridge
185           $ nmcli con add type ethernet con-name br-slave-2 ifname ens4 master TowerBridge
186           $ nmcli con modify TowerBridge bridge.stp no
187
188       This example demonstrates adding a bridge master connection and two
189       slaves. The first command adds a master bridge connection, naming the
190       bridge interface and the profile as TowerBridge. The next two commands
191       add slaves profiles, both will be enslaved to TowerBridge. The first
192       slave will be tied to ens3 interface, the second to ens4. The last
193       command will disable 802.1D STP for the TowerBridge profile.
194
195       Example 10. Adding an ethernet connection profile with manual IP
196       configuration
197
198           $ nmcli con add con-name my-con-em1 ifname em1 type ethernet \
199             ip4 192.168.100.100/24 gw4 192.168.100.1 ip4 1.2.3.4 ip6 abbe::cafe
200           $ nmcli con mod my-con-em1 ipv4.dns "8.8.8.8 8.8.4.4"
201           $ nmcli con mod my-con-em1 +ipv4.dns 1.2.3.4
202           $ nmcli con mod my-con-em1 ipv6.dns "2001:4860:4860::8888 2001:4860:4860::8844"
203           $ nmcli -p con show my-con-em1
204
205       The first command adds an Ethernet connection profile named my-con-em1
206       that is bound to interface name em1. The profile is configured with
207       static IP addresses. Three addresses are added, two IPv4 addresses and
208       one IPv6. The first IP 192.168.100.100 has a prefix of 24 (netmask
209       equivalent of 255.255.255.0). Gateway entry will become the default
210       route if this profile is activated on em1 interface (and there is no
211       connection with higher priority). The next two addresses do not specify
212       a prefix, so a default prefix will be used, i.e. 32 for IPv4 and 128
213       for IPv6. The second, third and fourth commands modify DNS parameters
214       of the new connection profile. The last con show command displays the
215       profile so that all parameters can be reviewed.
216
217       Example 11. Convenient field values retrieval for scripting
218
219           $ nmcli -g ip4.address connection show my-con-eth0
220           192.168.1.12/24
221
222           $ nmcli -g ip4.address,ip4.dns connection show my-con-eth0
223           192.168.1.12/24
224           192.168.1.1
225
226           $ nmcli -g ip4 connection show my-con-eth0
227           IP4:192.168.1.12/24:192.168.1.1::192.168.1.1::
228
229       This example shows retrieval of ip4 connection field values via the
230       --get-values option. Multiple comma separated fields can be provided:
231       they will be printed one per line. If a whole section is provided
232       instead of a single field, the name of the section will be printed
233       followed by all the related field values on the same line. See also
234       --terse, --mode, --fields and --escape options in nmcli(1) manual page
235       for more customized output.
236
237       Example 12. Adding an Ethernet connection and configuring SR-IOV VFs
238
239           $ nmcli con add type ethernet con-name EthernetPF ifname em1
240           $ nmcli con modify EthernetPF sriov.total-vfs 3 sriov.autoprobe-drivers false
241           $ nmcli con modify EthernetPF sriov.vfs '0 mac=00:11:22:33:44:55 vlans=10, 1 trust=true spoof-check=false'
242           $ nmcli con modify EthernetPF +sriov.vfs '2 max-tx-rate=20'
243
244       This example demonstrates adding an Ethernet connection for physical
245       function (PF) ens4 and configuring 3 SR-IOV virtual functions (VFs) on
246       it. The first VF is configured with MAC address 00:11:22:33:44:55 and
247       VLAN 10, the second one has the trust and spoof-check features
248       respectively enabled and disabled. VF number 2 has a maximux
249       transmission rate of 20Mbps. The kernel is instructed to not
250       automatically instantiate a network interface for the VFs.
251
252       Example 13. Escaping colon characters in tabular mode
253
254           $ nmcli -t -f general -e yes -m tab dev show eth0
255           GENERAL:eth0:ethernet:Intel Corporation:82567LM Gigabit Network Connection:
256           e1000e:2.1.4-k:1.8-3:00\:22\:68\:15\:29\:21:1500:100 (connected):0 (No reas
257           on given):/sys/devices/pci0000\:00/0000\:00\:19.0/net/eth0:eth0:yes:yes:no:
258           ethernet-13:89cbcbc6-dc85-456c-9c8b-bd828fee3917:/org/freedesktop/NetworkMa
259           nager/ActiveConnection/9
260
261       This example shows escaping colon characters in tabular mode. It may be
262       useful for script processing, because ':' is used as a field separator.
263
264       Example 14. nmcli usage in a NetworkManager dispatcher script to make
265       Ethernet and Wi-Fi mutually exclusive
266
267           #!/bin/bash
268           export LC_ALL=C
269
270           enable_disable_wifi ()
271           {
272               result=$(nmcli dev | grep "ethernet" | grep -w "connected")
273               if [ -n "$result" ]; then
274                   nmcli radio wifi off
275               else
276                   nmcli radio wifi on
277               fi
278           }
279
280           if [ "$2" = "up" ]; then
281               enable_disable_wifi
282           fi
283
284           if [ "$2" = "down" ]; then
285               enable_disable_wifi
286           fi
287
288
289       This dispatcher script makes Wi-Fi mutually exclusive with wired
290       networking. When a wired interface is connected, Wi-Fi will be set to
291       airplane mode (rfkilled). When the wired interface is disconnected,
292       Wi-Fi will be turned back on. Name this script e.g.
293       70-wifi-wired-exclusive.sh and put it into
294       /etc/NetworkManager/dispatcher.d/ directory. See NetworkManager(8)
295       manual page for more information about NetworkManager dispatcher
296       scripts.
297
298       Example sessions of interactive connection editor
299
300       Example 15. Adding an ethernet connection profile in interactive editor
301       (a)
302
303           $ nmcli connection edit type ethernet
304
305           ===| nmcli interactive connection editor |===
306
307           Adding a new '802-3-ethernet' connection
308
309           Type 'help' or '?' for available commands.
310           Type 'describe [<setting>.<prop>]' for detailed property description.
311
312           You may edit the following settings: connection, 802-3-ethernet (ethernet),
313           802-1x, ipv4, ipv6, dcb
314           nmcli> print
315           ===========================================================================
316                                     Connection details
317           ===========================================================================
318           connection.id:                      ethernet-4
319           connection.uuid:                    de89cdeb-a3e1-4d53-8fa0-c22546c775f4
320           connection.interface-name:          --
321           connection.type:                    802-3-ethernet
322           connection.autoconnect:             yes
323           connection.autoconnect-priority:    0
324           connection.timestamp:               0
325           connection.read-only:               no
326           connection.permissions:
327           connection.zone:                    --
328           connection.master:                  --
329           connection.slave-type:              --
330           connection.secondaries:
331           connection.gateway-ping-timeout:    0
332           ---------------------------------------------------------------------------
333           802-3-ethernet.port:                --
334           802-3-ethernet.speed:               0
335           802-3-ethernet.duplex:              --
336           802-3-ethernet.auto-negotiate:      yes
337           802-3-ethernet.mac-address:         --
338           802-3-ethernet.cloned-mac-address:  --
339           802-3-ethernet.mac-address-blacklist:
340           802-3-ethernet.mtu:                 auto
341           802-3-ethernet.s390-subchannels:
342           802-3-ethernet.s390-nettype:        --
343           802-3-ethernet.s390-options:
344           ---------------------------------------------------------------------------
345           ipv4.method:                        auto
346           ipv4.dns:
347           ipv4.dns-search:
348           ipv4.addresses:
349           ipv4.gateway:                       --
350           ipv4.routes:
351           ipv4.route-metric:                  -1
352           ipv4.ignore-auto-routes:            no
353           ipv4.ignore-auto-dns:               no
354           ipv4.dhcp-client-id:                --
355           ipv4.dhcp-send-hostname:            yes
356           ipv4.dhcp-hostname:                 --
357           ipv4.never-default:                 no
358           ipv4.may-fail:                      yes
359           ---------------------------------------------------------------------------
360           ipv6.method:                        auto
361           ipv6.dns:
362           ipv6.dns-search:
363           ipv6.addresses:
364           ipv6.gateway:                       --
365           ipv6.routes:
366           ipv6.route-metric:                  -1
367           ipv6.ignore-auto-routes:            no
368           ipv6.ignore-auto-dns:               no
369           ipv6.never-default:                 no
370           ipv6.may-fail:                      yes
371           ipv6.ip6-privacy:                   -1 (unknown)
372           ipv6.dhcp-hostname:                 --
373           ---------------------------------------------------------------------------
374           nmcli> goto ethernet
375           You may edit the following properties: port, speed, duplex, auto-negotiate,
376            mac-address, cloned-mac-address, mac-address-blacklist, mtu, s390-subchann
377           els, s390-nettype, s390-options
378           nmcli 802-3-ethernet> set mtu 1492
379           nmcli 802-3-ethernet> b
380           nmcli> goto ipv4.addresses
381           nmcli ipv4.addresses> desc
382
383           === [addresses] ===
384           [NM property description]
385           Array of IP addresses.
386
387           [nmcli specific description]
388           Enter a list of IPv4 addresses formatted as:
389             ip[/prefix], ip[/prefix],...
390           Missing prefix is regarded as prefix of 32.
391
392           Example: 192.168.1.5/24, 10.0.0.11/24
393
394           nmcli ipv4.addresses> set 192.168.1.100/24
395           Do you also want to set 'ipv4.method' to 'manual'? [yes]: yes
396           nmcli ipv4.addresses>
397           nmcli ipv4.addresses> print
398           addresses: 192.168.1.100/24
399           nmcli ipv4.addresses> back
400           nmcli ipv4> b
401           nmcli> set ipv4.gateway 192.168.1.1
402           nmcli> verify
403           Verify connection: OK
404           nmcli> print
405           ===========================================================================
406                                     Connection details
407           ===========================================================================
408           connection.id:                      ethernet-4
409           connection.uuid:                    de89cdeb-a3e1-4d53-8fa0-c22546c775f4
410           connection.interface-name:          --
411           connection.type:                    802-3-ethernet
412           connection.autoconnect:             yes
413           connection.autoconnect-priority:    0
414           connection.timestamp:               0
415           connection.read-only:               no
416           connection.permissions:
417           connection.zone:                    --
418           connection.master:                  --
419           connection.slave-type:              --
420           connection.secondaries:
421           connection.gateway-ping-timeout:    0
422           ---------------------------------------------------------------------------
423           802-3-ethernet.port:                --
424           802-3-ethernet.speed:               0
425           802-3-ethernet.duplex:              --
426           802-3-ethernet.auto-negotiate:      yes
427           802-3-ethernet.mac-address:         --
428           802-3-ethernet.cloned-mac-address:  --
429           802-3-ethernet.mac-address-blacklist:
430           802-3-ethernet.mtu:                 1492
431           802-3-ethernet.s390-subchannels:
432           802-3-ethernet.s390-nettype:        --
433           802-3-ethernet.s390-options:
434           ---------------------------------------------------------------------------
435           ipv4.method:                        manual
436           ipv4.dns:
437           ipv4.dns-search:
438           ipv4.addresses:                     192.168.1.100/24
439           ipv4.gateway:                       192.168.1.1
440           ipv4.routes:
441           ipv4.route-metric:                  -1
442           ipv4.ignore-auto-routes:            no
443           ipv4.ignore-auto-dns:               no
444           ipv4.dhcp-client-id:                --
445           ipv4.dhcp-send-hostname:            yes
446           ipv4.dhcp-hostname:                 --
447           ipv4.never-default:                 no
448           ipv4.may-fail:                      yes
449           ---------------------------------------------------------------------------
450           ipv6.method:                        auto
451           ipv6.dns:
452           ipv6.dns-search:
453           ipv6.addresses:
454           ipv6.routes:
455           ipv6.route-metric:                  -1
456           ipv6.ignore-auto-routes:            no
457           ipv6.ignore-auto-dns:               no
458           ipv6.never-default:                 no
459           ipv6.may-fail:                      yes
460           ipv6.ip6-privacy:                   -1 (unknown)
461           ipv6.dhcp-hostname:                 --
462           ---------------------------------------------------------------------------
463           nmcli> set ipv4.dns 8.8.8.8 8.8.4.4
464           nmcli> print
465           ===========================================================================
466                                     Connection details
467           ===========================================================================
468           connection.id:                      ethernet-4
469           connection.uuid:                    de89cdeb-a3e1-4d53-8fa0-c22546c775f4
470           connection.interface-name:          --
471           connection.type:                    802-3-ethernet
472           connection.autoconnect:             yes
473           connection.autoconnect-priority:    0
474           connection.timestamp:               0
475           connection.read-only:               no
476           connection.permissions:
477           connection.zone:                    --
478           connection.master:                  --
479           connection.slave-type:              --
480           connection.secondaries:
481           connection.gateway-ping-timeout:    0
482           ---------------------------------------------------------------------------
483           802-3-ethernet.port:                --
484           802-3-ethernet.speed:               0
485           802-3-ethernet.duplex:              --
486           802-3-ethernet.auto-negotiate:      yes
487           802-3-ethernet.mac-address:         --
488           802-3-ethernet.cloned-mac-address:  --
489           802-3-ethernet.mac-address-blacklist:
490           802-3-ethernet.mtu:                 1492
491           802-3-ethernet.s390-subchannels:
492           802-3-ethernet.s390-nettype:        --
493           802-3-ethernet.s390-options:
494           ---------------------------------------------------------------------------
495           ipv4.method:                        manual
496           ipv4.dns:                           8.8.8.8,8.8.4.4
497           ipv4.dns-search:
498           ipv4.addresses:                     192.168.1.100/24
499           ipv4.gateway:                       192.168.1.1
500           ipv4.routes:
501           ipv4.route-metric:                  -1
502           ipv4.ignore-auto-routes:            no
503           ipv4.ignore-auto-dns:               no
504           ipv4.dhcp-client-id:                --
505           ipv4.dhcp-send-hostname:            yes
506           ipv4.dhcp-hostname:                 --
507           ipv4.never-default:                 no
508           ipv4.may-fail:                      yes
509           ---------------------------------------------------------------------------
510           ipv6.method:                        auto
511           ipv6.dns:
512           ipv6.dns-search:
513           ipv6.addresses:
514           ipv6.gateway:                       --
515           ipv6.routes:
516           ipv6.route-metric:                  -1
517           ipv6.ignore-auto-routes:            no
518           ipv6.ignore-auto-dns:               no
519           ipv6.never-default:                 no
520           ipv6.may-fail:                      yes
521           ipv6.ip6-privacy:                   -1 (unknown)
522           ipv6.dhcp-hostname:                 --
523           ---------------------------------------------------------------------------
524           nmcli> verify
525           Verify connection: OK
526           nmcli> save
527           Connection 'ethernet-4' (de89cdeb-a3e1-4d53-8fa0-c22546c775f4) successfully
528            saved.
529           nmcli> quit
530
531       Example session in the nmcli interactive connection editor. The
532       scenario creates an Ethernet connection profile with static addressing
533       (IPs and DNS).
534

SEE ALSO

536       nmcli(1), NetworkManager(8), NetworkManager.conf(5), nm-settings(5),
537       nm-online(1), nm-applet(1), nm-connection-editor(1)
538
539
540
541NetworkManager 1.16.2                                        NMCLI-EXAMPLES(7)
Impressum