1NMCLI-EXAMPLES(7) Examples NMCLI-EXAMPLES(7)
2
6 nmcli-examples - usage examples of nmcli
7
9 nmcli [OPTIONS...]
10
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 The purpose of this manual page is to provide you with various examples
17 and usage scenarios of nmcli.
18
20 Example 1. Listing available Wi-Fi APs
21 $ 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 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 Example 2. Showing general information and properties for a Wi-Fi
41 interface
42 $ 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 This command shows information about a Wi-Fi device.
79 Example 3. Listing NetworkManager polkit permissions
81 $ 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 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 pkaction --action-id org.freedesktop.NetworkManager.network-control --verbose
106 More information about polkit can be found at
109 http://www.freedesktop.org/wiki/Software/polkit.
110 Example 4. Listing NetworkManager log level and domains
112 $ 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 This command shows current NetworkManager logging status.
121 Example 5. Changing NetworkManager logging
123 $ nmcli g log level DEBUG domains CORE,ETHER,IP
125 $ nmcli g log level INFO domains DEFAULT
126 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 Example 6. Activating a VPN connection profile requiring interactive
133 password input
134 $ nmcli --ask con up my-vpn-con
136 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 Example 7. Adding a bonding master and two slave connection profiles
145 $ 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 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 Example 8. Adding a team master and two slave connection profiles
157 $ 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 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 $ nmcli con up Team1-slave1
175 $ nmcli con up Team1-slave2
176 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 Example 9. Adding a bridge and two slave profiles
182 $ 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 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 Example 10. Adding an ethernet connection profile with manual IP
196 configuration
197 $ 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 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 Example 11. Convenient field values retrieval for scripting
218 $ nmcli -g ip4.address connection show my-con-eth0
220 192.168.1.12/24
221 $ nmcli -g ip4.address,ip4.dns connection show my-con-eth0
223 192.168.1.12/24
224 192.168.1.1
225 $ nmcli -g ip4 connection show my-con-eth0
227 IP4:192.168.1.12/24:192.168.1.1::192.168.1.1::
228 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 Example 12. Adding an Ethernet connection and configuring SR-IOV VFs
238 $ 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 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 Example 13. Escaping colon characters in tabular mode
253 $ 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 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 Example 14. nmcli usage in a NetworkManager dispatcher script to make
265 Ethernet and Wi-Fi mutually exclusive
266 #!/bin/bash
268 export LC_ALL=C
269 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 if [ "$2" = "up" ]; then
281 enable_disable_wifi
282 fi
283 if [ "$2" = "down" ]; then
285 enable_disable_wifi
286 fi
287 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 Example sessions of interactive connection editor
299 Example 15. Adding an ethernet connection profile in interactive editor
301 (a)
302 $ nmcli connection edit type ethernet
304 ===| nmcli interactive connection editor |===
306 Adding a new '802-3-ethernet' connection
308 Type 'help' or '?' for available commands.
310 Type 'describe [<setting>.<prop>]' for detailed property description.
311 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 === [addresses] ===
384 [NM property description]
385 Array of IP addresses.
386 [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 Example: 192.168.1.5/24, 10.0.0.11/24
393 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 Example session in the nmcli interactive connection editor. The
532 scenario creates an Ethernet connection profile with static addressing
533 (IPs and DNS).
534
536 nmcli(1), NetworkManager(8), NetworkManager.conf(5), nm-settings(5),
537 nm-online(1), nm-applet(1), nm-connection-editor(1)
538NetworkManager 1.20.8 NMCLI-EXAMPLES(7)