diff options
| author | Lubomir Rintel <lkundrak@v3.sk> | 2016-03-28 14:32:30 +0200 |
|---|---|---|
| committer | Lubomir Rintel <lkundrak@v3.sk> | 2016-04-05 14:37:50 +0200 |
| commit | b19e4d37b6272834cb98a000cfa7bc247607e2f7 (patch) | |
| tree | 99edc326984fbe803d8a15e612c8dd2b066618df | |
| parent | 05e467ad53adb5fa7d7ba9d787939d8f71444b89 (diff) | |
| download | NetworkManager-b19e4d37b6272834cb98a000cfa7bc247607e2f7.tar.gz | |
man: convert nmcli(1) manual to docbook refentry
| -rw-r--r-- | configure.ac | 2 | ||||
| -rw-r--r-- | docs/api/Makefile.am | 1 | ||||
| -rw-r--r-- | docs/api/network-manager-docs.xml | 1 | ||||
| -rw-r--r-- | man/Makefile.am | 7 | ||||
| -rw-r--r-- | man/nmcli.1.in | 1282 | ||||
| -rw-r--r-- | man/nmcli.xml | 3113 |
6 files changed, 3121 insertions, 1285 deletions
diff --git a/configure.ac b/configure.ac index 131c5d185b..447bb375e3 100644 --- a/configure.ac +++ b/configure.ac @@ -961,6 +961,7 @@ GTK_DOC_CHECK(1.0) # check for pregenerated manpages to be installed install_pregen_manpages=no if test "$enable_gtk_doc" != "yes" \ + -a -f man/nmcli.1 \ -a -f man/NetworkManager.conf.5 \ -a -f man/nm-settings.5 \ -a -f man/nm-settings-keyfile.5 \ @@ -1076,7 +1077,6 @@ introspection/all.xml man/Makefile man/nm-system-settings.conf.5 man/nm-online.1 -man/nmcli.1 man/nmtui.1 po/Makefile.in policy/Makefile diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am index c37ceff172..7174b3a479 100644 --- a/docs/api/Makefile.am +++ b/docs/api/Makefile.am @@ -80,6 +80,7 @@ content_files = \ $(top_builddir)/introspection/nmdbus-settings-org.freedesktop.NetworkManager.Settings.xml \ $(top_builddir)/introspection/nmdbus-device-ethernet-org.freedesktop.NetworkManager.Device.Wired.xml \ $(top_builddir)/introspection/nmdbus-ip4-config-org.freedesktop.NetworkManager.IP4Config.xml \ + $(top_builddir)/man/nmcli.xml \ $(top_builddir)/man/NetworkManager.xml \ $(top_builddir)/man/NetworkManager.conf.xml \ $(top_builddir)/man/nmcli-examples.xml \ diff --git a/docs/api/network-manager-docs.xml b/docs/api/network-manager-docs.xml index a5ccc39f86..584908a26b 100644 --- a/docs/api/network-manager-docs.xml +++ b/docs/api/network-manager-docs.xml @@ -144,6 +144,7 @@ <chapter id="manpages"> <title>UNIX Manual Pages</title> + <xi:include href="../../man/nmcli.xml"/> <xi:include href="../../man/NetworkManager.xml"/> <xi:include href="../../man/NetworkManager.conf.xml"/> <xi:include href="../../man/nmcli-examples.xml"/> diff --git a/man/Makefile.am b/man/Makefile.am index 65d8d007fc..5154a48dca 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -17,12 +17,15 @@ XSLTPROC_MAN_FLAGS = \ if ENABLE_GTK_DOC -%.8: %.xml +%.1: %.xml $(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $< %.5: %.xml $(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $< +%.8: %.xml + $(AM_V_GEN) xsltproc $(XSLTPROC_MAN_FLAGS) $< + endif CLEANFILES += NetworkManager.conf.xml @@ -66,12 +69,12 @@ CLEANFILES += \ endif configure_generated_man_pages = \ - nmcli.1 \ nmtui.1 \ nm-online.1 \ nm-system-settings.conf.5 docbook_generated_man_pages = \ + nmcli.1 \ NetworkManager.8 \ NetworkManager.conf.5 \ nmcli-examples.5 diff --git a/man/nmcli.1.in b/man/nmcli.1.in deleted file mode 100644 index 3c76348f8e..0000000000 --- a/man/nmcli.1.in +++ /dev/null @@ -1,1282 +0,0 @@ -.\" nmcli (1) manual page -.\" -.\" This is free documentation; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License as -.\" published by the Free Software Foundation; either version 2 of -.\" the License, or (at your option) any later version. -.\" -.\" The GNU General Public License's references to "object code" -.\" and "executables" are to be interpreted as the output of any -.\" document formatting or typesetting system, including -.\" intermediate and printed output. -.\" -.\" This manual is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public Licence along -.\" with this manual; if not, write to the Free Software Foundation, Inc., -.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -.\" -.\" Copyright 2010 - 2015 Red Hat, Inc. -.\" -.TH NMCLI "1" "2016-03-09" "NetworkManager 1.2" - -.SH NAME -nmcli \- command\(hyline tool for controlling NetworkManager -.SH SYNOPSIS -.ad l -.B nmcli -.RI " [ " OPTIONS " ] " OBJECT " { " COMMAND " | " -.BR help " } " -.sp - -.IR OBJECT " := { " -.BR general " | " networking " | " radio " | " connection " | " device " | " agent " | " monitor -.RI " }" -.sp - -.IR OPTIONS " := { " -.br -\fB\-t\fR[\fIerse\fR] -.br -\fB\-p\fR[\fIretty\fR] -.br -\fB\-m\fR[\fImode\fR] tabular | multiline -.br -\fB\-c\fR[\fIcolors\fR] auto | yes | no -.br -\fB\-f\fR[\fIields\fR] <field1,field2,...> | all | common -.br -\fB\-e\fR[\fIscape\fR] yes | no -.br -\fB\-n\fR[\fIocheck\fR] -.br -\fB\-a\fR[\fIsk\fR] -.br -\fB\-s\fR[\fIhow-secrets\fR] -.br -\fB\-w\fR[\fIait\fR] <seconds> -.br -\fB\-v\fR[\fIersion\fR] -.br -\fB\-h\fR[\fIelp\fR] -.br -.RI "}" - -.SH DESCRIPTION -.B nmcli -is a command\(hyline tool for controlling NetworkManager and reporting network -status. It can be utilized as a replacement for \fInm\(hyapplet\fP or other -graphical clients. \fInmcli\fP is used to create, display, edit, delete, activate, -and deactivate network connections, as well as control and display network device -status. -.P -Typical uses include: -.IP \(em 4 -Scripts: utilize NetworkManager via \fInmcli\fP instead of managing network -connections manually. \fInmcli\fP supports a terse output format which is better -suited for script processing. Note that NetworkManager can also execute scripts, -called "dispatcher scripts", in response to network events. See -\fBNetworkManager\fP for details about these dispatcher scripts. -.IP \(em 4 -Servers, headless machines, and terminals: \fInmcli\fP can be used to control -NetworkManager without a GUI, including creating, editing, starting and stopping -network connections and viewing network status. -.SS \fIOPTIONS\fP -.TP -.B \-t, \-\-terse -Output is terse. This mode is designed and suitable for computer (script) -processing. -.TP -.B \-p, \-\-pretty -Output is pretty. This causes \fInmcli\fP to produce easily readable outputs -for humans, i.e. values are aligned, headers are printed, etc. -.TP -.B \-m, \-\-mode tabular | multiline -Switch between \fItabular\fP and \fImultiline\fP output. -If omitted, default is \fItabular\fP for most commands. For the commands -producing more structured information, that cannot be displayed on a single -line, default is \fImultiline\fP. Currently, they are: -.br -.nf - 'nmcli connection show <ID>' - 'nmcli device show' -.fi -\fItabular\fP \(en Output is a table where each line describes a single entry. -Columns define particular properties of the entry. -.br -\fImultiline\fP \(en Each entry comprises multiple lines, each property on its own -line. The values are prefixed with the property name. -.TP -.B \-c, \-\-colors auto|yes|no -This option controls color output (using terminal escape sequences). \fIyes\fP -enables colors, \fIno\fP disables them, \fIauto\fP only produces colors when -standard output is directed to a terminal. The default value is \fIauto\fP. -.TP -.B \-f, \-\-fields <field1,field2,...> | all | common -This option is used to specify what fields (column names) should be printed. -Valid field names differ for specific commands. List available fields by -providing an invalid value to the \fI\-\-fields\fP option. -.br -\fIall\fP is used to print all valid field values of the command. -\fIcommon\fP is used to print common field values of the command. -If omitted, default is \fIcommon\fP. -The option is mandatory when \fI\-\-terse\fP is used. In this case, generic -values \fIall\fP and \fIcommon\fP cannot be used. (This is to maintain -compatibility when new fields are added in the future). -.TP -.B \-e, \-\-escape yes | no -Whether to escape ':' and '\\' characters in terse tabular mode. The escape -character is '\\'. -If omitted, default is \fIyes\fP. -.TP -.B \-n, \-\-nocheck -This option can be used to force \fInmcli\fP to skip checking \fInmcli\fP and -\fINetworkManager\fP version compatibility. Use it with care, because using -incompatible versions may produce incorrect results. -.TP -.B \-a, \-\-ask -When using this option \fInmcli\fP will stop and ask for any missing required -arguments, so do not use this option for non-interactive purposes like scripts. -This option controls, for example, whether you will be prompted for a password -if it is required for connecting to a network. -.TP -.B \-s, \-\-show-secrets -When using this option \fInmcli\fP will display passwords and secrets that might -be present in an output of an operation. This option also influences echoing -passwords typed by user as an input. -.TP -.B \-w, \-\-wait <seconds> -This option sets a timeout period for which \fInmcli\fP will wait for \fINetworkManager\fP -to finish operations. It is especially useful for commands that may take a longer time to -complete, e.g. connection activation. -Specifying a value of \fB0\fP instructs \fInmcli\fP not to wait but to exit immediately -with a status of success. The default value depends on the executed command. -.TP -.B \-v, \-\-version -Show \fInmcli\fP version. -.TP -.B \-h, \-\-help -Print help information. -.SS \fIOBJECT\fP -.TP -.B general \- general \fINetworkManager\fP status and operations -.br -Use this object to show NetworkManager status and permissions. You can also get -and change system hostname, as well as NetworkManager logging level and domains. -.TP -.SS \fICOMMAND\fP := { status | hostname | permissions | logging } -.sp -.RS -.TP -.B status -.br -Show overall status of NetworkManager. This is the default action, when no additional -command is provided for \fIgeneral\fP object. -.TP -.B hostname [<hostname>] -.br -Get and change system hostname. With no arguments, this prints currently configured hostname. -When you pass a hostname, it will be handed over to NetworkManager to be set as a new system -hostname. -.br -Note that the term \fBsystem\fP hostname may also be referred to as \fBpersistent\fP or -\fBstatic\fP by other programs or tools. The hostname is stored in /etc/hostname -file in most distributions. For example, systemd-hostnamed service uses the term -\fBstatic\fP hostname and it only reads the /etc/hostname file when it starts. -.TP -.B permissions -.br -Show the permissions a caller has for various authenticated operations that -NetworkManager provides, like enable and disable networking, changing Wi\(hyFi -and WWAN state, modifying connections, etc. -.TP -.B logging [level <log level>] [domains <log domains>] -.br -Get and change \fINetworkManager\fP logging level and domains. Without any argument -current logging level and domains are shown. In order to change logging state, provide -\fIlevel\fP and, or, \fIdomain\fP parameters. See \fBNetworkManager.conf\fP for available -level and domain values. -.RE - -.TP -.B networking \- get or set general networking state of NetworkManager -.br -Use this object to show NetworkManager networking status, or to enable and disable -networking. Disabling networking removes the configuration from all devices and -changes them to the 'unmanaged' state. -.TP -.SS \fICOMMAND\fP := { [ on | off | connectivity ] } -.sp -.RS -.TP -.B [ on | off ] -.br -Get networking\(hyenabled status or enable and disable networking by NetworkManager. -All interfaces managed by NetworkManager are deactivated when networking has -been disabled. -.TP -.B connectivity [check] -.br -Get network connectivity state. -The optional \fIcheck\fP argument tells NetworkManager to re-check the connectivity, -else the most recent known connectivity state is displayed without re-checking. -.br -Possible states are: -.RS -.PP -.IP \fInone\fP 9 -\(en the host is not connected to any network -.IP \fIportal\fP 9 -\(en the host is behind a captive portal and cannot reach the full Internet -.IP \fIlimited\fP 9 -\(en the host is connected to a network, but it has no access to the Internet -.IP \fIfull\fP 9 -\(en the host is connected to a network and has full access to the Internet -.IP \fIunknown\fP 9 -\(en the connectivity status cannot be found out -.RE -.RE - -.TP -.B radio \- get or set radio switch states -.br -Use this object to show radio switches status, or enable and disable -the switches. -.TP -.SS \fICOMMAND\fP := { all | wifi | wwan } -.sp -.RS -.TP -.B wifi [ on | off ] -.br -Show or set status of Wi\(hyFi in NetworkManager. If no arguments are supplied, -Wi\(hyFi status is printed; \fIon\fP enables Wi\(hyFi; \fIoff\fP disables Wi\(hyFi. -.TP -.B wwan [ on | off ] -.br -Show or set status of WWAN (mobile broadband) in NetworkManager. If no arguments -are supplied, mobile broadband status is printed; \fIon\fP enables mobile broadband, -\fIoff\fP disables it. -.TP -.B all [ on | off ] -.br -Show or set all previously mentioned radio switches at the same time. -.RE - -.TP -.B monitor \- monitor NetworkManager -.br -Use this object to observe NetworkManager activity. Watches for changes -in connectivity state, devices or connection profiles. -.br -See also \fImonitor\fP command of \fIconnection\fP or \fIdevice\fP object -to watch for changes in certain objects or object classes. -.RE - -.TP -.B connection \- start, stop, and manage network connections -.sp -NetworkManager stores all network configuration as \fIconnections\fP, which are -collections of data (Layer2 details, IP addressing, etc.) that describe -how to create or connect to a network. A connection is \fIactive\fP when -a device uses that connection's configuration to create or connect to a network. -There may be multiple connections that apply to a device, but only one of them -can be active on that device at any given time. The additional connections can -be used to allow quick switching between different networks and configurations. -.sp -Consider a machine which is usually connected to a DHCP-enabled network, but -sometimes connected to a testing network which uses static IP addressing. Instead -of manually reconfiguring eth0 each time the network is changed, the settings can -be saved as two connections which both apply to eth0, one for DHCP (called -"default") and one with the static addressing details (called "testing"). When -connected to the DHCP-enabled network the user would run "nmcli con up default" -, and when connected to the static network the user would run "nmcli con up testing". -.TP -.SS \fICOMMAND\fP := { show | up | down | add | edit | modify | delete | monitor | reload | load } -.sp -.RS -.TP -.B show [--active] -.br -List in-memory and on-disk connection profiles, some of which may also be -active if a device is using that connection profile. Without a parameter, all -profiles are listed. When --active option is specified, only the active profiles -are shown. -.TP -.B show [--active] [--order <order spec>] [ id | uuid | path | apath ] <ID> ... -.br -Show details for specified connections. By default, both static configuration -and active connection data are displayed. When --active option is specified, -only the active profiles are taken into account. Use global --show-secrets option -to display secrets associated with the profile. -.sp -Ordering: -.br -The --order option can be used to get custom ordering of connections. The -connections can be ordered by active status, name, type or D-Bus path. If -connections are equal according to a sort order category, an additional -category can be specified. -The default sorting order is equivalent to "--order active:name:path". -.sp -<order spec> := category:category:... -.br -category := [+-]active | [+-]name | [+-]type | [+-]path -.br -\fI+\fP or no prefix means sorting in ascending order (alphabetically or in numbers). -.br -\fI-\fP means reverse (descending) order. -.br -The category names can be abbreviated (e.g. --order -a:na) -.sp -\fIid\fP, \fIuuid\fP, \fIpath\fP and \fIapath\fP keywords can be used if -\fI<ID>\fP is ambiguous. -.RS -.PP -Optional <ID>-specifying keywords are: -.IP \fIid\fP 13 -\(en the <ID> denotes a connection name -.IP \fIuuid\fP 13 -\(en the <ID> denotes a connection UUID -.IP \fIpath\fP 13 -\(en the <ID> denotes a D-Bus static connection path -in the format of /org/freedesktop/NetworkManager/Settings/<num> or just <num> -.IP \fIapath\fP 13 -\(en the <ID> denotes a D-Bus active connection path -in the format of /org/freedesktop/NetworkManager/ActiveConnection/<num> or just <num> -.PP -It is possible to filter the output using the global \fI--fields\fP option. Use the following -values: -.RE -.RS -.PP -.IP \fIprofile\fP 13 -\(en only shows static profile configuration -.IP \fIactive\fP 13 -\(en only shows active connection data (when the profile is active) -.PP -You can also specify particular fields. For static configuration, use setting and property names -as described in \fInm-settings\fP(5) manual page. For active data use GENERAL, IP4, DHCP4, IP6, -DHCP6, VPN. -.PP -When no command is given to the \fIconnection\fP object, the default action -is 'nmcli connection show'. -.RE -.TP -.B up [ id | uuid | path ] <ID> [ifname <ifname>] [ap <BSSID>] [passwd-file <file with passwords>] -.RE -.RS -.B up ifname <ifname> [ap <BSSID>] [passwd-file <file with passwords>] -.RS -.br -Activate a connection. The connection is identified by its name, UUID or D-Bus -path. If <ID> is ambiguous, a keyword \fIid\fP, \fIuuid\fP or \fIpath\fP can be -used. When requiring a particular device to activate the connection on, the -\fIifname\fP option with interface name should be given. If the <ID> is not -given an \fIifname\fP is required, and NetworkManager will activate the best -available connection for the given \fIifname\fP. In case of a VPN connection, -the \fIifname\fP option specifies the device of the base connection. The -\fIap\fP option specify what particular AP should be used in case of a Wi\(hyFi -connection. -.br -If '--wait' option is not specified, the default timeout will be 90 seconds. -.br -See \fBconnection show\fP above for the description of the <ID>-specifying keywords. -.RS -.PP -Available options are: -.IP \fIifname\fP 13 -\(en interface that will be used for activation -.IP \fIap\fP 13 -\(en BSSID of the AP which the command should connect to (for Wi\(hyFi connections) -.IP \fIpasswd-file\fP 13 -\(en some networks may require credentials during activation. You can give these -credentials using this option. -Each line of the file should contain one password in the form of -.br -\fBsetting_name.property_name:the password\fP -.br -For example, for WPA Wi-Fi with PSK, the line would be -.br -\fI802-11-wireless-security.psk:secret12345\fP -.br -For 802.1X password, the line would be -.br -\fI802-1x.password:my 1X password\fP -.br -nmcli also accepts "wifi-sec" and "wifi" strings instead of "802-11-wireless-security". -When NetworkManager requires a password and it is not given, nmcli will ask for it -when run with --ask. If --ask was not passed, NetworkManager can ask another secret -agent that may be running (typically a GUI secret agent, such as nm-applet or -gnome-shell). -.RE -.RE -.TP -.B down [ id | uuid | path | apath ] <ID> ... -.br -Deactivate a connection from a device without preventing the device from -further auto-activation. Multiple connections can be passed to the command. -.sp -Be aware that this command deactivates the specified active connection, but the device -on which the connection was active, is still ready to connect and will perform -auto-activation by looking for a suitable connection that has the 'autoconnect' -flag set. This includes the just deactivated connection. So if the connection is set -to auto-connect, it will be automatically started on the disconnected device again. -.br -In most cases you may want to use \fIdevice disconnect\fP command instead. -.sp -The connection is identified by its name, UUID or D-Bus path. -If <ID> is ambiguous, a keyword \fIid\fP, \fIuuid\fP, \fIpath\fP or -\fIapath\fP can be used. -.br -See \fBconnection show\fP above for the description of the <ID>-specifying keywords. -.br -If '--wait' option is not specified, the default timeout will be 10 seconds. -.TP -.B add COMMON_OPTIONS TYPE_SPECIFIC_OPTIONS IP_OPTIONS [-- [+|-]<setting>.<property> <value> ...] -.br -Add a connection for NetworkManager. Arguments differ according to connection types, see below. -.RS -.TP -.B COMMON_OPTIONS: -.IP "\fItype <type>\fP" 42 -\(en connection type; see below \fBTYPE_SPECIFIC_OPTIONS\fP for allowed values; (mandatory) -Note that types \fIbond-slave\fP, \fIteam-slave\fP and \fIbridge-slave\fP create \fIethernet\fP -connection profiles. Their use is discouraged in favor of using a specific type with \fImaster\fP -option. -.IP "\fIifname <ifname> | \(dq\&*\(dq\&\fP" 42 -\(en interface to bind the connection to. The connection will only be applicable to this -interface name. A special value of "\fB*\fP" can be used for interface-independent connections. -The \fIifname\fP argument is mandatory for all connection types except bond, team, bridge and vlan. -Note: use quotes around \fB*\fP to suppress shell expansion. -.IP "\fI[con-name <connection name>]\fP" 42 -\(en connection name (when not provided a default name is generated: <type>[-<ifname>][-<num>]) -.IP "\fI[autoconnect yes|no]\fP" 42 -\(en whether the connection profile can be automatically activated (default: yes) -.IP "\fI[save yes|no]\fP" 42 -\(en whether the connection should be persistent, i.e. NetworkManager should store it on disk (default: yes) -.IP "\fI[master <master (ifname, or connection UUID or name)>]\fP" 42 -\(en master interface name, or connection UUID or ID of master connection profile. -The value can be prefixed with \fBifname/\fP, \fBuuid/\fP or \fBid/\fP to disambiguate it. -.IP "\fI[slave-type <master connection type>]\fP" 42 -\(en type of master connection. Only required when it can not be inferred (i.e. the master connection does -not exist yet). -.RE -.RS -.TP -.B TYPE_SPECIFIC_OPTIONS: -.TP -.B ethernet: -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the device this connection is locked to -.IP "\fI[cloned-mac <cloned MAC address>]\fP" 42 -\(en cloned MAC -.IP "\fI[mtu <MTU>]\fP" 42 -\(en MTU -.RE -.RS -.TP -.B wifi: -.IP "\fIssid <SSID>\fP" 42 -\(en SSID -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the device this connection is locked to -.IP "\fI[cloned-mac <cloned MAC address>]\fP" 42 -\(en cloned MAC -.IP "\fI[mode infrastructure|ap|adhoc]\fP" 42 -\(en Wi-Fi network mode. If blank, \fIinfrastructure\fP is assumed. -.IP "\fI[mtu <MTU>]\fP" 42 -\(en MTU -.RE -.RS -.TP -.B wimax: -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the device this connection is locked to -.IP "\fI[nsp <NSP>]\fP" 42 -\(en Network Service Provider name -.RE -.RS -.TP -.B pppoe: -.IP "\fIusername <PPPoE username>\fP" 42 -\(en PPPoE username -.IP "\fI[password <PPPoE password>]\fP" 42 -\(en Password for the PPPoE username -.IP "\fI[service <PPPoE service name>]\fP" 42 -\(en PPPoE service name (if required by concentrator) -.IP "\fI[mtu <MTU>]\fP" 42 -\(en MTU -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the device this connection is locked to -.RE -.RS -.TP -.B gsm: -.IP "\fIapn <APN>\fP" 42 -\(en APN - GSM Access Point Name -.IP "\fI[user <username>]\fP" 42 -\(en user name -.IP "\fI[password <password>]\fP" 42 -\(en password -.RE -.RS -.TP -.B cdma: -.IP "\fI[user <username>]\fP" 42 -\(en user name -.IP "\fI[password <password>]\fP" 42 -\(en password -.RE -.RS -.TP -.B infiniband: -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the device this connection is locked to (InfiniBand MAC is 20 bytes) -.IP "\fI[mtu <MTU>]\fP" 42 -\(en MTU -.IP "\fI[transport-mode datagram | connected]\fP" 42 -\(en InfiniBand transport mode -.IP "\fI[parent <interface name>]\fP" 42 -\(en the interface name of the parent device (if any) -.IP "\fI[p-key <IPoIB P_Key>]\fP" 42 -\(en the InfiniBand P_Key (16-bit unsigned integer) -.RE -.RS -.TP -.B bluetooth: -.IP "\fI[addr <bluetooth address>]\fP" 42 -\(en Bluetooth device address (MAC) -.IP "\fI[bt-type panu|dun-gsm|dun-cdma]\fP" 42 -\(en Bluetooth connection type -.RE -.RS -.TP -.B vlan: -.IP "\fIdev <parent device (connection UUID, ifname, or MAC)>\fP" 42 -\(en parent device this VLAN is on -.IP "\fIid <VLAN ID>\fP" 42 -\(en VLAN ID in range <0-4095> -.IP "\fI[flags <VLAN flags>]\fP" 42 -\(en flags -.IP "\fI[ingress <ingress priority mapping>]\fP" 42 -\(en VLAN ingress priority mapping -.IP "\fI[egress <egress priority mapping>]\fP" 42 -\(en VLAN egress priority mapping -.IP "\fI[mtu <MTU>]\fP" 42 -\(en MTU -.RE -.RS -.TP -.B bond: -.IP "\fI[mode balance-rr (0) | active-backup (1) | balance-xor (2) | broadcast (3) |\fP" -.IP "\fI 802.3ad (4) | balance-tlb (5) | balance-alb (6)]\fP" 42 -\(en bonding mode (default: balance-rr) -.IP "\fI[primary <ifname>]\fP" 42 -\(en primary interface name (for "active-backup" mode) -.IP "\fI[miimon <num>]\fP" 42 -\(en miimon (default: 100) -.IP "\fI[downdelay <num>]\fP" 42 -\(en downdelay (default: 0) -.IP "\fI[updelay <num>]\fP" 42 -\(en updelay (default: 0) -.IP "\fI[arp-interval <num>]\fP" 42 -\(en ARP interval (default: 0) -.IP "\fI[arp-ip-target <num>]\fP" 42 -\(en ARP IP target -.RE -.RS -.TP -.B bond-slave: -.IP "\fImaster <master (ifname, or connection UUID or name)>\fP" 42 -\(en master bond interface name, or connection UUID or ID of bond master connection profile. -The value can be prefixed with \fBifname/\fP, \fBuuid/\fP or \fBid/\fP to disambiguate it. -.RE -.RS -.TP -.B team: -.IP "\fI[config <file>|<raw JSON data>]\fP" 42 -\(en JSON configuration for team -.RE -.RS -.TP -.B team-slave: -.IP "\fImaster <master (ifname, or connection UUID or name)>\fP" 42 -\(en master team interface name, or connection UUID or ID of team master connection profile. -The value can be prefixed with \fBifname/\fP, \fBuuid/\fP or \fBid/\fP to disambiguate it. -.RE -.RS -.TP -.IP "\fI[config <file>|<raw JSON data>]\fP" 42 -\(en JSON configuration for team -.RE -.RS -.TP -.B bridge: -.IP "\fI[stp yes|no]\fP" 42 -\(en controls whether Spanning Tree Protocol (STP) is enabled for this bridge (default: yes) -.IP "\fI[priority <num>]\fP" 42 -\(en sets STP priority (default: 128) -.IP "\fI[forward-delay <2-30>]\fP" 42 -\(en STP forwarding delay, in seconds (default: 15) -.IP "\fI[hello-time <1-10>]\fP" 42 -\(en STP hello time, in seconds (default: 2) -.IP "\fI[max-age <6-42>]\fP" 42 -\(en STP maximum message age, in seconds (default: 20) -.IP "\fI[ageing-time <0-1000000>]\fP" 42 -\(en the Ethernet MAC address aging time, in seconds (default: 300) -.IP "\fI[multicast-snooping yes|no]\fP" 42 -\(en controls whether IGMP snooping is enabled (default: yes) -.IP "\fI[mac <MAC address>]\fP" 42 -\(en MAC address of the bridge (note: this requires a recent kernel feature, -originally introduced in 3.15 upstream kernel) -.RE -.RS -.TP -.B bridge-slave: -.IP "\fImaster <master (ifname, or connection UUID or name)>\fP" 42 -\(en master bridge interface name, or connection UUID or ID of bridge master connection profile. -The value can be prefixed with \fBifname/\fP, \fBuuid/\fP or \fBid/\fP to disambiguate it. -.RE -.RS -.TP -.IP "\fI[priority <0-63>]\fP" 42 -\(en STP priority of this slave (default: 32) -.IP "\fI[path-cost <1-65535>]\fP" 42 -\(en STP port cost for destinations via this slave (default: 100) -.IP "\fI[hairpin yes|no]\fP" 42 -\(en 'hairpin mode' for the slave, which allows frames -to be sent back out through the slave the frame was received on (default: yes) -.RE -.RS -.TP -.B vpn: -.IP "\fIvpn-type vpnc|openvpn|pptp|openconnect|openswan|libreswan|strongswan|ssh|l2tp|iodine|fortisslvpn|...\fP" 42 -\(en VPN type -.IP "\fI[user <username>]\fP" 42 -\(en VPN username -.RE -.RS -.TP -.B olpc-mesh: -.IP "\fIssid <SSID>\fP" 42 -\(en SSID -.IP "\fI[channel <1-13>]\fP" 42 -\(en channel to use for the network -.IP "\fI[dhcp-anycast <MAC address>]\fP" 42 -\(en anycast DHCP MAC address used when requesting an IP address via DHCP -.RE -.RS -.TP -.B adsl: -.IP "\fIusername <username>\fP" 42 -\(en ADSL user name -.IP "\fIprotocol pppoa|pppoe|ipoatm\fP" 42 -\(en ADSL protocol -.IP "\fI[password <password>]\fP" 42 -\(en ADSL password -.IP "\fI[encapsulation vcmux|llc]\fP" 42 -\(en ADSL encapsulation -.RE -.RS -.TP -.B tun: -.IP "\fImode tun|tap\fP" 42 -\(en Mode for the device -.IP "\fI[owner <UID>]\fP" 42 -\(en UID of the owner -.IP "\fI[group <GID>]\fP" 42 -\(en GID of the group -.IP "\fI[pi yes|no>]\fP" 42 -\(en include packet information (~IFF_NO_PI flag) -.IP "\fI[vnet-hdr yes|no>]\fP" 42 -\(en send and receive large (i.e. GSO) packets and packets with partial checksums (IFF_VNET_HDR flag) -.IP "\fI[multi-queue yes|no>]\fP" 42 -\(en multi-queue support for tun/tap device (IFF_MULTI_QUEUE flag) -.RE -.RS -.TP -.B ip-tunnel: -.IP "\fImode ipip|gre|sit|isatap|vti|ip6ip6|ipip6|ip6gre|vti6\fP" 42 -\(en tunnel mode -.IP "\fIremote <remote endpoint IP>\fP" 42 -\(en IPv4 or IPv6 address of the remote tunnel endpoint -.IP "\fI[local <local endpoint IP>]\fP" 42 -\(en IPv4 or IPv6 address of the local tunnel endpoint -.IP "\fI[dev <parent device (ifname or connection UUID)>]\fP" 42 -\(en device to use for tunnel endpoint communication -.RE -.RS -.TP -.B macvlan: -.IP "\fIdev <parent device (connection UUID, ifname, or MAC)>\fP" 42 -\(en parent device this MACVLAN is on -.IP "\fImode vepa|bridge|private|passthru|source\fP" 42 -\(en MACVLAN mode, which specifies the communication mechanism between multiple MACVLANs on the same lower device -.IP "\fI[tap yes|no]\fP" 42 -\(en controls the device type. If set to 'yes' a MACVTAP will be created (default: no) -.RE -.RS -.TP -.B vxlan: -.IP "\fIid <VXLAN ID>\fP" 42 -\(en VXLAN Network Identifer to use -.IP "\fIremote <IP>\fP" 42 -\(en unicast destination IP address or multicast IP address to join -.IP "\fI[dev <parent device (ifname or connection UUID)>]\fP" 42 -\(en device to use for tunnel endpoint communication -.IP "\fI[local <IP>]\fP" 42 -\(en source IP address -.IP "\fI[source-port-min <0-65535>]\fP" 42 -\(en minimum UDP source port to communicate to the remote VXLAN tunnel endpoint -.IP "\fI[source-port-max <0-65535>]\fP" 42 -\(en maximum UDP source port to communicate to the remote VXLAN tunnel endpoint -.IP "\fI[destination-port <0-65535>]\fP" 42 -\(en UDP destination port to communicate to the remote VXLAN tunnel endpoint -.RE -.RS -.TP -.B IP_OPTIONS: -.IP "\fI[ip4 <IPv4 address>] [gw4 <IPv4 gateway>]\fP" 42 -\(en IPv4 addresses -.IP "\fI[ip6 <IPv6 address>] [gw6 <IPv6 gateway>]\fP" 42 -\(en IPv6 addresses -.RE -.RS -If a \fI--\fP argument is encountered, the rest of command line is interpreted -as property list in the same format as \fIconnection modify\fP command accepts. -This makes it possible to adjust the connection properties before it's added. -.RE -.TP -.B edit [id | uuid | path ] <ID> - edit an existing connection -.RE -.RS -.B edit [type <new connection type>] [con-name <new connection name>] - add a new connection -.RS -Edit an existing connection or add a new one, using an interactive editor. -.br -The existing connection is identified by its name, UUID or D-Bus path. -If <ID> is ambiguous, a keyword \fIid\fP, \fIuuid\fP, or \fIpath\fP can be used. -See \fBconnection show\fP above for the description of the <ID>-specifying keywords. -Not providing an <ID> means that a new connection will be added. -.sp -The interactive editor will guide you through the connection editing and -allow you to change connection parameters according to your needs by means of -a simple menu-driven interface. The editor indicates what settings and -properties can be modified and provides in-line help. -.sp -.PP -Available options: -.IP \fItype\fP 13 -\(en type of the new connection; valid types are the same as for \fIconnection add\fP command -.IP \fIcon-name\fP 13 -\(en name for the new connection. It can be changed later in the editor. -.RE -.RS -.sp -See also \fInm-settings\fP(5) for all NetworkManager settings and property names, and their -descriptions; and \fInmcli-examples\fP(5) for sample editor sessions. -.RE -.TP -.B modify [--temporary] [ id | uuid | path ] <ID> [+|-]<setting>.<property> <value> -.B [+|-]<setting>.<property> <value> ... -.br -Modify one or more properties in the connection profile. -.br -The connection is identified by its name, UUID or D-Bus path. If <ID> is -ambiguous, a keyword \fIid\fP, \fIuuid\fP or \fIpath\fP can be used. See -\fInm-settings\fP(5) for setting and property names, their descriptions and -default values. This command supports abbreviations for \fIsetting name\fP and -\fIproperty name\fP provided they are unique. Empty \fIvalue\fP ("") removes -the property value (sets the property to the default value). The provided -value overwrites the existing property value. -.br -If you want to append an item to the existing value, use \fI+\fP prefix for the -property name. If you want to remove just one item from container-type -property, use \fI-\fP prefix for the property name and specify a value or an -zero-based index of the item to remove (or option name for properties with -named options) as \fIvalue\fP. Of course, \fI+|-\fP only have a real effect for -multi-value (container) properties like ipv4.dns, ipv4.addresses, bond.options, -etc. -.br -The changes to the connection profile will be saved persistently by -NetworkManager, unless \fI--temporary\fP option is provided, in which case the -changes won't persist over NetworkManager restart. -.TP -.B clone [--temporary] [ id | uuid | path ] <ID> <new name> -.br -Clone a connection. The connection to be cloned is identified by its -name, UUID or D-Bus path. If <ID> is ambiguous, a keyword \fIid\fP, -\fIuuid\fP or \fIpath\fP can be used. See \fBconnection show\fP above for -the description of the <ID>-specifying keywords. \fI<new name>\fP is the name -of the new cloned connection. The new connection will be the exact copy except -the connection.id (\fI<new name>\fP) and connection.uuid (generated) -properties. -.br -The new connection profile will be saved as persistent unless \fI--temporary\fP -option is specified, in which case the new profile won't exist after NetworkManager -restart. -.TP -.B delete [ id | uuid | path ] <ID> ... -.br -Delete a configured connection. The connection to be deleted is identified by -its name, UUID or D-Bus path. If <ID> is ambiguous, a keyword \fIid\fP, -\fIuuid\fP or \fIpath\fP can be used. -.br -See \fBconnection show\fP above for the description of the <ID>-specifying keywords. -.br -If '--wait' option is not specified, the default timeout will be 10 seconds. -.TP -.B monitor [ id | uuid | path ] <ID> ... -.br -Monitor connection profile activity. This command prints a line whenever the -specified connection changes. The connection to be monitored is identified by -its name, UUID or D-Bus path. If <ID> is ambiguous, a keyword \fIid\fP, -\fIuuid\fP or \fIpath\fP can be used. -.br -See \fBconnection show\fP above for the description of the <ID>-specifying keywords. -.br -Monitors all connection profiles in case none is specified. The command terminates -when all monitored connections disappear. If you want to monitor connection creation -consider using the global monitor with \fInmcli monitor\fP command. -.TP -.B reload -.br -Reload all connection files from disk. \fINetworkManager\fP does not monitor -changes to connection files by default. So you need to use this command in order -to tell \fINetworkManager\fP to re-read the connection profiles from disk when -a change was made to them. However, the auto-loading feature can be enabled and -then \fINetworkManager\fP will reload connection files any time they change -(monitor-connection-files=true in \fINetworkManager.conf\fP(5)). -.TP -.B load <filename> [<filename>...] -.br -Load/reload one or more connection files from disk. Use this after manually -editing a connection file to ensure that \fBNetworkManager\fP is aware -of its latest state. -.TP -.B import [--temporary] type <type> file <file to import> -.br -Import an external/foreign configuration as a NetworkManager connection profile. -The type of the input file is specified by \fItype\fP option. -.br -Only VPN configurations are supported at the moment. The configuration -is imported by NetworkManager VPN plugins. \fItype\fP values are the same as for -\fIvpn-type\fP option in \fBnmcli connection add\fP. VPN configurations are -imported by VPN plugins. Therefore the proper VPN plugin has to be installed -so that nmcli could import the data. -.br -The imported connection profile will be saved as persistent unless \fI--temporary\fP -option is specified, in which case the new profile won't exist after NetworkManager -restart. -.TP -.B export [ id | uuid | path ] <ID> [<output file>] -.br -Export a connection. -.br -Only VPN connections are supported at the moment. A proper VPN plugin has to be -installed so that nmcli could export a connection. If no \fI<output file>\fP is -provided, the VPN configuration data will be printed to standard output. -.RE - -.TP -.B device - show and manage network interfaces -.br -.TP -.SS \fICOMMAND\fP := { status | show | set | connect | reapply | disconnect | delete | monitor | wifi | lldp } -.sp -.RS -.TP -.B status -.br -Print status of devices. -.br -This is the default action if no command is specified to \fIdevice\fP object. -.TP -.B show [<ifname>] -.br -Show detailed information about devices. Without an argument, all devices are -examined. To get information for a specific device, the interface name has -to be provided. -.TP -.TP -.B set [ifname] <ifname> [autoconnect yes|no] [managed yes|no] -.br -Set device properties. -.TP -.B connect <ifname> -.br -Connect the device. NetworkManager will try to find a suitable connection that -will be activated. It will also consider connections that are not set to auto connect. -.br -If '--wait' option is not specified, the default timeout will be 90 seconds. -.TP -.B reapply <ifname> -.br -Attempt to update device with changes to the currently active connection -made since it was last applied. -.TP -.B disconnect <ifname> ... -.br -Disconnect a device and prevent the device from automatically activating further -connections without user/manual intervention. Note that disconnecting software -devices may mean that the devices will disappear. -.br -If '--wait' option is not specified, the default timeout will be 10 seconds. -.TP -.B delete <ifname> ... -.br -Delete a device. The command removes the interface from the system. Note that -this only works for software devices like bonds, bridges, teams, etc. -Hardware devices (like Ethernet) cannot be deleted by the command. -.br -If '--wait' option is not specified, the default timeout will be 10 seconds. -.TP -.B monitor [<ifname>] ... -.br -Monitor device activity. This command prints a line whenever the specified devices -change state. -.br -Monitors all devices in case no interface is specified. The monitor terminates when -all specified devices disappear. If you want to monitor device addition consider -using the global monitor with \fInmcli monitor\fP command. -.TP -.B wifi [list [ifname <ifname>] [bssid <BSSID>]] -.br -List available Wi\(hyFi access points. The \fIifname\fP and \fIbssid\fP options -can be used to list APs for a particular interface or with a specific BSSID, -respectively. -.TP -.B wifi connect <(B)SSID> [password <password>] [wep\-key\-type key|phrase] [ifname <ifname>] [bssid <BSSID>] [name <name>] -.B [private yes|no] [hidden yes|no] -.br -Connect to a Wi\(hyFi network specified by SSID or BSSID. The command creates a new -connection and then activates it on a device. This is a command\(hyline counterpart -of clicking an SSID in a GUI client. The command always creates a new connection -and thus it is mainly useful for connecting to new Wi\(hyFi networks. If a connection -for the network already exists, it is better to bring up (activate) the existing connection -as follows: \fInmcli con up id <name>\fP. Note that only open, WEP and WPA\(hyPSK networks -are supported at the moment. It is also supposed that IP configuration is obtained via -DHCP. -.br -If '--wait' option is not specified, the default timeout will be 90 seconds. -.RS -.PP -Available options are: -.IP \fIpassword\fP 13 -\(en password for secured networks (WEP or WPA) -.IP \fIwep\-key\-type\fP 13 -\(en type of WEP secret, either \fIkey\fP for ASCII/HEX key or \fIphrase\fP for passphrase -.IP \fIifname\fP 13 -\(en interface that will be used for activation -.IP \fIbssid\fP 13 -\(en if specified, the created connection will be restricted just for the BSSID -.IP \fIname\fP 13 -\(en if specified, the connection will use the name (else NM creates a name itself) -.IP \fIprivate\fP 13 -\(en if set to \fByes\fP, the connection will only be visible to the user who created it. -Otherwise the connection is system\(hywide, which is the default. -.IP \fIhidden\fP 13 -\(en set to \fByes\fP when connecting for the first time to an AP not broadcasting its SSID. -Otherwise the SSID would not be found and the connection attempt would fail. -.RE -.TP -.B wifi hotspot [ifname <ifname>] [con-name <name>] [ssid <SSID>] [band a|bg] [channel <channel>] [password <password>] -.br -Create a Wi-Fi hotspot. The command creates a hotspot connection profile according to -Wi-Fi device capabilities and activates it on the device. The hotspot is secured with WPA -if device/driver supports that, otherwise WEP is used. -Use \fIconnection down\fP or \fIdevice disconnect\fP to stop the hotspot. -.br -.RS -.PP -Parameters of the hotspot can be influenced by the optional parameters: -.IP \fIifname\fP 17 -\(en what Wi-Fi device is used -.IP \fIcon-name\fP 17 -\(en name of the created hotspot connection profile -.IP \fIssid\fP 17 -\(en SSID of the hotspot -.IP \fIband\fP 17 -\(en Wi-Fi band to use -.IP \fIchannel\fP 17 -\(en Wi-Fi channel to use -.IP \fIpassword\fP 17 -\(en password to use for the created hotspot. If not provided, -nmcli will generate a password. The password is either WPA -pre-shared key or WEP key. -.PP -Note that \fI--show-secrets\fP global option can be used to print the hotspot -password. It is useful especially when the password was generated. -.RE -.TP -.B wifi rescan [ifname <ifname>] [[ssid <SSID>] ...] -.br -Request that \fINetworkManager\fP immediately re-scan for available access points. -NetworkManager scans Wi\(hyFi networks periodically, but in some cases it can be -useful to start scanning manually (e.g. after resuming the computer). By using -\fIssid\fP, it is possible to scan for a specific SSID, which is useful for APs -with hidden SSIDs. You can provide multiple \fIssid\fP parameters in order to -scan more SSIDs. -.br -This command does not show the APs, use 'nmcli device wifi list' for that. -.TP -.B lldp [list [ifname <ifname>]] -.br -Display information about neighboring devices learned through the Link -Layer Discovery Protocol (LLDP). The \fIifname\fP option can be used to -list neighbors only for a given interface. The protocol must be -enabled in the connection settings. -.RE - -.TP -.B agent \- run nmcli as a NetworkManager secret agent, or polkit agent -.br -.TP -.SS \fICOMMAND\fP := { secret | polkit | all } -.sp -.RS -.TP -.B secret -.br -Register nmcli as a NetworkManager secret agent and listen for secret requests. -You do usually not need this command, because nmcli can handle secrets when -connecting to networks. However, you may find the command useful when you use -another tool for activating connections and you do not have a secret agent -available (like nm-applet). -.TP -.B polkit -.br -Register nmcli as a polkit agent for the user session and listen for -authorization requests. You do not usually need this command, because nmcli can -handle polkit actions related to NetworkManager operations (when run with ---ask). However, you may find the command useful when you want to run a simple -text based polkit agent and you do not have an agent of a desktop environment. -Note that running this command makes nmcli handle all polkit requests, not only -NetworkManager related ones, because only one polkit agent can run for the -session. -.TP -.B all -.br -Runs nmcli as both NetworkManager secret and a polkit agent. -.RE - -.SH ENVIRONMENT VARIABLES -\fInmcli\fP's behavior is affected by the following environment variables. -.IP "LC_ALL" 13 -If set to a non\(hyempty string value, it overrides the values of all the other -internationalization variables. -.IP "LC_MESSAGES" 13 -Determines the locale to be used for internationalized messages. -.IP "LANG" 13 -Provides a default value for the internationalization variables that are unset -or null. - -.RE -Internationalization notes: -.br -Be aware that \fInmcli\fP is localized and that is why the output depends on -your environment. This is important to realize especially when you parse the -output. -.br -Call \fInmcli\fP as \fBLC_ALL=C nmcli\fP to be sure the locale is -set to "C" while executing in a script. - -\fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP variables specify the LC_MESSAGES -locale category (in that order), which determines the language that \fInmcli\fP -uses for messages. The "C" locale is used if none of these variables are set, -and this locale uses English messages. - -.SH EXIT STATUS -\fInmcli\fP exits with status 0 if it succeeds, a value greater than 0 is -returned if an error occurs. -.IP "0" 4 -Success \(en indicates the operation succeeded -.IP "1" 4 -Unknown or unspecified error -.IP "2" 4 -Invalid user input, wrong \fInmcli\fP invocation -.IP "3" 4 -Timeout expired (see \fI\-\-wait\fP option) -.IP "4" 4 -Connection activation failed -.IP "5" 4 -Connection deactivation failed -.IP "6" 4 -Disconnecting device failed -.IP "7" 4 -Connection deletion failed -.IP "8" 4 -NetworkManager is not running -.IP "9" 4 -\fInmcli\fP and \fINetworkManager\fP versions mismatch -.IP "10" 4 -Connection, device, or access point does not exist. - -.SH EXAMPLES -.PP -This section presents various examples of nmcli usage. If you want even more, -please refer to \fInmcli-examples\fP(5) manual page. -.sp -.IP "\fB\f(CWnmcli \-t \-f RUNNING general\fP\fP" -.IP -tells you whether NetworkManager is running or not. - -.IP "\fB\f(CWnmcli \-t \-f STATE general\fP\fP" -.IP -shows the overall status of NetworkManager. - -.IP "\fB\f(CWnmcli radio wifi off\fP\fP" -.IP -switches Wi\(hyFi off. - -.IP "\fB\f(CWnmcli connection show\fP\fP" -.IP -lists all connections NetworkManager has. - -.IP "\fB\f(CWnmcli \-p \-m multiline \-f all con show\fP\fP" -.IP -shows all configured connections in multi-line mode. - -.IP "\fB\f(CWnmcli connection show --active\fP\fP" -.IP -lists all currently active connections. - -.IP "\fB\f(CWnmcli \-f name,autoconnect c s\fP\fP" -.IP -shows all connection profile names and their auto-connect property. - -.IP "\fB\f(CWnmcli \-p connection show \(dq\&My default em1\(dq\&\fP\fP" -.IP -shows details for "My default em1" connection profile. - -.IP "\fB\f(CWnmcli --show-secrets connection show \(dq\&My Home WiFi\(dq\&\fP\fP" -.IP -shows details for "My Home WiFi" connection profile with all passwords. -Without \fI--show-secrets\fP option, secrets would not be displayed. - -.IP "\fB\f(CWnmcli \-f active connection show \(dq\&My default em1\(dq\&\fP\fP" -.IP -shows details for "My default em1" active connection, like IP, DHCP -information, etc. - -.IP "\fB\f(CWnmcli -f profile con s \(dq\&My wired connection\(dq\&\fP\fP" -.IP -shows static configuration details of the connection profile with "My wired connection" name. - -.IP "\fB\f(CWnmcli \-p con up \(dq\&My wired connection\(dq\& ifname eth0\fP\fP" -.IP -activates the connection profile with name "My wired connection" on interface eth0. -The \-p option makes nmcli show progress of the activation. - -.IP "\fB\f(CWnmcli con up 6b028a27\-6dc9\-4411\-9886\-e9ad1dd43761 ap 00:3A:98:7C:42:D3\fP\fP" -.IP -connects the Wi\(hyFi connection with UUID 6b028a27\-6dc9\-4411\-9886\-e9ad1dd43761 to the AP -with BSSID 00:3A:98:7C:42:D3. - -.IP "\fB\f(CWnmcli device status\fP\fP" -.IP -shows the status for all devices. - -.IP "\fB\f(CWnmcli dev disconnect em2\fP\fP" -.IP -disconnects a connection on interface em2 and marks the device as unavailable for -auto\(hyconnecting. As a result, no connection will automatically be activated on the -device until the device's 'autoconnect' is set to TRUE or the user manually activates -a connection. - -.IP "\fB\f(CWnmcli \-f GENERAL,WIFI\-PROPERTIES dev show wlan0\fP\fP" -.IP -shows details for wlan0 interface; only GENERAL and WIFI\-PROPERTIES sections will be shown. - -.IP "\fB\f(CWnmcli \-f CONNECTIONS device show wlp3s0\fP\fP" -.IP -shows all available connection profiles for your Wi-Fi interface wlp3s0. - -.IP "\fB\f(CWnmcli dev wifi\fP\fP" -.IP -lists available Wi\(hyFi access points known to NetworkManager. - -.IP "\fB\f(CWnmcli dev wifi con \(dq\&Cafe Hotspot 1\(dq\& password caffeine name \(dq\&My cafe\(dq\&\fP\fP" -.IP -creates a new connection named "My cafe" and then connects it to "Cafe Hotspot 1" SSID -using password "caffeine". This is mainly useful when connecting to "Cafe Hotspot 1" for -the first time. Next time, it is better to use 'nmcli con up id "My cafe"' so that the -existing connection profile can be used and no additional is created. - -.IP "\fB\f(CWnmcli -s dev wifi hotspot con-name QuickHotspot\fP\fP" -.IP -creates a hotspot profile and connects it. Prints the hotspot password the user should use -to connect to the hotspot from other devices. - -.IP "\fB\f(CWnmcli connection add type ethernet autoconnect no ifname eth0\fP\fP" -.IP -non-interactively adds an Ethernet connection tied to eth0 interface with automatic IP configuration (DHCP), -and disables the connection's "autoconnect" flag. - -.IP "\fB\f(CWnmcli c a ifname Maxipes\(hyfik type vlan dev eth0 id 55\fP\fP" -.IP -non-interactively adds a VLAN connection with ID 55. The connection will use eth0 and the VLAN interface -will be named Maxipes\(hyfik. - -.IP "\fB\f(CWnmcli c a ifname eth0 type ethernet -- ipv4.method disabled ipv6.method link-local\fP\fP" -.IP -non-interactively adds a connection that will use eth0 Ethernet interface and only have an IPv6 link-local -address configured. - -.IP "\fB\f(CWnmcli connection edit ethernet\-em1\-2\fP\fP" -.IP -edits existing "ethernet\(hyem1\(hy2" connection in the interactive editor. - -.IP "\fB\f(CWnmcli connection edit type ethernet con-name \(dq\&yet another Ethernet connection\(dq\&\fP\fP" -.IP -adds a new Ethernet connection in the interactive editor. - -.IP "\fB\f(CWnmcli con mod ethernet\-2 connection.autoconnect no\fP\fP" -.IP -modifies 'autoconnect' property in the 'connection' setting of 'ethernet\(hy2' connection. - -.IP "\fB\f(CWnmcli con mod \(dq\&Home Wi\-Fi\(dq\& wifi.mtu 1350\fP\fP" -.IP -modifies 'mtu' property in the 'wifi' setting of 'Home Wi\(hyFi' connection. - -.IP "\fB\f(CWnmcli con mod em1-1 ipv4.method manual ipv4.addr \(dq\&192.168.1.23/24 192.168.1.1, 10.10.1.5/8, 10.0.0.11\(dq\&\fP\fP" -.IP -sets manual addressing and the addresses in em1-1 profile. - -.IP "\fB\f(CWnmcli con modify ABC +ipv4.dns 8.8.8.8\fP\fP" -.IP -appends a Google public DNS server to DNS servers in ABC profile. - -.IP "\fB\f(CWnmcli con modify ABC -ipv4.addresses \(dq\&192.168.100.25/24 192.168.1.1\(dq\&\fP\fP" -.IP -removes the specified IP address from (static) profile ABC. - -.IP "\fB\f(CWnmcli con import type openvpn file ~/Downloads/frootvpn.ovpn\fP\fP" -.IP -imports an OpenVPN configuration to NetworkManager. - -.IP "\fB\f(CWnmcli con export corp-vpnc /home/joe/corpvpn.conf\fP\fP" -.IP -exports NetworkManager VPN profile corp-vpnc as standard Cisco (vpnc) configuration. - -.SH NOTES -\fInmcli\fP accepts abbreviations, as long as they are a unique prefix in the set -of possible options. As new options get added, these abbreviations are not guaranteed -to stay unique. For scripting and long term compatibility it is therefore strongly -advised to spell out the full option names. - -.SH BUGS -There are probably some bugs. If you find a bug, please report it to -https://bugzilla.gnome.org/ \(em product \fINetworkManager\fP. - -.SH SEE ALSO -.BR nmcli\-examples (5), -.BR nm\-online (1), -.BR NetworkManager (8), -.BR NetworkManager.conf (5), -.BR nm\-settings (5), -.BR nm\-applet (1), -.BR nm\-connection\-editor (1). diff --git a/man/nmcli.xml b/man/nmcli.xml new file mode 100644 index 0000000000..21faf1af46 --- /dev/null +++ b/man/nmcli.xml @@ -0,0 +1,3113 @@ +<?xml version='1.0'?> +<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + nmcli(1) manual page + + This is free documentation; you can redistribute it and/or + modify it under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + The GNU General Public License's references to "object code" + and "executables" are to be interpreted as the output of any + document formatting or typesetting system, including + intermediate and printed output. + + This manual is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public Licence along + with this manual; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + + Copyright 2010 - 2016 Red Hat, Inc. +--> + +<refentry id='nmcli'> + + <refentryinfo> + <title>nmcli</title> + <author>NetworkManager developers</author> + </refentryinfo> + + <refmeta> + <refentrytitle>nmcli</refentrytitle> + <manvolnum>1</manvolnum> + <refmiscinfo class="source">NetworkManager</refmiscinfo> + <refmiscinfo class="manual">General Commands Manual</refmiscinfo> + <refmiscinfo class="version">1.2</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>nmcli</refname> + <refpurpose>command-line tool for controlling NetworkManager</refpurpose> + </refnamediv> + + <refsynopsisdiv id='synopsis'> + <cmdsynopsis> + <command>nmcli</command> + <arg choice="opt" rep="repeat"><replaceable>OPTIONS</replaceable></arg> + <group choice='req'> + <arg choice='plain'><option>help</option></arg> + <arg choice='plain'><option>general</option></arg> + <arg choice='plain'><option>networking</option></arg> + <arg choice='plain'><option>radio</option></arg> + <arg choice='plain'><option>connection</option></arg> + <arg choice='plain'><option>device</option></arg> + <arg choice='plain'><option>agent</option></arg> + <arg choice='plain'><option>monitor</option></arg> + </group> + <arg><replaceable>COMMAND</replaceable></arg> + <arg rep="repeat"><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1 id='description'><title>Description</title> + <para><command>nmcli</command> is a command-line tool for controlling + NetworkManager and reporting network status. It can be utilized as a + replacement for <command>nm-applet</command> or other graphical clients. + <command>nmcli</command> is used to create, display, edit, delete, activate, + and deactivate network connections, as well as control and display network + device status.</para> + + <para>Typical uses include:</para> + <itemizedlist> + <listitem> + <para>Scripts: Utilize NetworkManager via <command>nmcli</command> instead of + managing network connections manually. <command>nmcli</command> supports a + terse output format which is better suited for script processing. Note that + NetworkManager can also execute scripts, called "dispatcher scripts", in + response to network events. See + <citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about these dispatcher scripts.</para> + </listitem> + + <listitem> + <para>Servers, headless machines, and terminals: <command>nmcli</command> can + be used to control NetworkManager without a GUI, including creating, editing, + starting and stopping network connections and viewing network status.</para> + </listitem> + </itemizedlist> + </refsect1> + + <refsect1 id='options'><title>Options</title> + <variablelist> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-t</option></arg> + <arg choice='plain'><option>--terse</option></arg> + </group></term> + + <listitem> + <para>Output is terse. This mode is designed and suitable for computer (script) + processing.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-p</option></arg> + <arg choice='plain'><option>--pretty</option></arg> + </group></term> + + <listitem> + <para>Output is pretty. This causes <command>nmcli</command> to produce easily + readable outputs for humans, i.e. values are aligned, headers are printed, + etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-m</option></arg> + <arg choice='plain'><option>--mode</option></arg> + <group choice='req'> + <arg choice='plain'>tabular</arg> + <arg choice='plain'>multiline</arg> + </group> + </group></term> + + <listitem> + <para>Switch between tabular and multiline output:</para> + + <variablelist> + <varlistentry> + <term><arg choice='plain'>tabular</arg></term> + <listitem> + <para>Output is a table where each line describes a single entry. + Columns define particular properties of the entry.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><arg choice='plain'>multiline</arg></term> + <listitem> + <para>Each entry comprises multiple lines, each property on its + own line. The values are prefixed with the property name.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>If omitted, default is <literal>tabular</literal> for most commands. + For the commands producing more structured information, that cannot be + displayed on a single line, default is <literal>multiline</literal>. + Currently, they are:</para> + + <itemizedlist> + <listitem> + <para><literal>nmcli connection show <replaceable>ID</replaceable></literal></para> + </listitem> + + <listitem> + <para><literal>nmcli device show</literal></para> + </listitem> + </itemizedlist> + + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-c</option></arg> + <arg choice='plain'><option>--colors</option></arg> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + <arg choice='plain'>auto</arg> + </group> + </group></term> + + <listitem> + <para>This option controls color output (using terminal escape sequences). + <literal>yes</literal> enables colors, <literal>no</literal> disables them, + <literal>auto</literal> only produces colors when standard output is directed + to a terminal. The default value is <literal>auto</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-f</option></arg> + <arg choice='plain'><option>--fields</option></arg> + <group choice='req'> + <arg conice='plain' rep='repeat'><replaceable>field</replaceable></arg> + <arg choice='plain'>all</arg> + <arg choice='plain'>common</arg> + </group> + </group></term> + + <listitem> + <para>This option is used to specify what fields (column names) should be + printed. Valid field names differ for specific commands. List available fields + by providing an invalid value to the <option>--fields</option> option. + <literal>all</literal> is used to print all valid field values of the + command. <literal>common</literal> is used to print common field values of + the command.</para> + + <para>If omitted, default is <literal>common</literal>. The option is + mandatory when <option>--terse</option> is used. In this case, generic values + <literal>all</literal> and <literal>common</literal> cannot be used. This + is to maintain compatibility when new fields are added in the future.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-e</option></arg> + <arg choice='plain'><option>--escape</option></arg> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </group></term> + + <listitem> + <para>Whether to escape <literal>:</literal> and <literal>\</literal> characters in terse tabular mode. The + escape character is <literal>\</literal>.</para> + + <para>If omitted, default is <literal>yes</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-n</option></arg> + <arg choice='plain'><option>--nocheck</option></arg> + </group></term> + + <listitem> + <para>This option can be used to force <command>nmcli</command> to skip + checking <command>nmcli</command> and <command>NetworkManager</command> + version compatibility. Use it with care, because using incompatible versions + may produce incorrect results.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-a</option></arg> + <arg choice='plain'><option>--ask</option></arg> + </group></term> + + <listitem> + <para>When using this option <command>nmcli</command> will stop and ask for any + missing required arguments, so do not use this option for non-interactive + purposes like scripts. This option controls, for example, whether you will be + prompted for a password if it is required for connecting to a network.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-s</option></arg> + <arg choice='plain'><option>--show-secrets</option></arg> + </group></term> + + <listitem> + <para>When using this option <command>nmcli</command> will display passwords + and secrets that might be present in an output of an operation. This option + also influences echoing passwords typed by user as an input.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><arg> + <group choice='plain'> + <arg choice='plain'><option>-w</option></arg> + <arg choice='plain'><option>--wait</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>seconds</replaceable></arg> + </arg></term> + + <listitem> + <para>This option sets a timeout period for which <command>nmcli</command> will + wait for NetworkManager to finish operations. It is + especially useful for commands that may take a longer time to complete, e.g. + connection activation.</para> + + <para>Specifying a value of <literal>0</literal> instructs + <command>nmcli</command> not to wait but to exit immediately with a status of + success. The default value depends on the executed command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-v</option></arg> + <arg choice='plain'><option>--version</option></arg> + </group></term> + + <listitem> + <para>Show <command>nmcli</command> version.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><group choice='plain'> + <arg choice='plain'><option>-h</option></arg> + <arg choice='plain'><option>--help</option></arg> + </group></term> + + <listitem> + <para>Print help information.</para> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1 id='general'><title>General Commands</title> + + <cmdsynopsis> + <command>nmcli general</command> + <group choice='req'> + <arg choice='plain'><command>status</command></arg> + <arg choice='plain'><command>hostname</command></arg> + <arg choice='plain'><command>permissions</command></arg> + <arg choice='plain'><command>logging</command></arg> + </group> + <arg rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + + <para>Use this command to show NetworkManager status and permissions. You can also get + and change system hostname, as well as NetworkManager logging level and domains.</para> + + <variablelist> + + <varlistentry> + <term><command>status</command></term> + + <listitem> + <para>Show overall status of NetworkManager. This is the default action, when + no additional command is provided for <command>nmcli general</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>hostname</command> + <arg><replaceable>hostname</replaceable></arg> + </term> + + <listitem> + <para>Get and change system hostname. With no arguments, this prints currently + configured hostname. When you pass a hostname, it will be handed over to + NetworkManager to be set as a new system hostname.</para> + + <para>Note that the term "system" hostname may also be referred to as + "persistent" or "static" by other programs or tools. The hostname is stored + in <filename>/etc/hostname</filename> file in most distributions. For example, + systemd-hostnamed service uses the term "static" hostname and it only reads + the <filename>/etc/hostname</filename> file when it starts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>permissions</command></term> + + <listitem> + <para>Show the permissions a caller has for various authenticated operations + that NetworkManager provides, like enable and disable networking, changing + Wi-Fi and WWAN state, modifying connections, etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>logging</command> + <arg><option>level</option> <replaceable>level</replaceable></arg> + <arg rep='repeat'><option>domain</option> <replaceable>domains</replaceable></arg> + </term> + + <listitem> + <para>Get and change NetworkManager logging level and + domains. Without any argument current logging level and domains are shown. In + order to change logging state, provide <option>level</option> and, or, + <option>domain</option> parameters. See + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for available level and domain values.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='networking'><title>Networking Control Commands</title> + + <cmdsynopsis> + <command>nmcli networking</command> + <group choice='req'> + <arg choice='plain'><command>on</command></arg> + <arg choice='plain'><command>off</command></arg> + <arg choice='plain'><command>connectivity</command></arg> + </group> + <arg rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + + <para>Query NetworkManager networking status, enable and disable networking. + </para> + + <variablelist> + + <varlistentry> + <term><command>on</command></term> + <term><command>off</command></term> + + <listitem> + <para>Enable enable or disable networking control by NetworkManager. + All interfaces managed by NetworkManager are deactivated when networking + is disabled.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>connectivity</command> + <arg>check</arg> + </term> + + <listitem> + <para>Get network connectivity state. The optional <option>check</option> + argument tells NetworkManager to re-check the connectivity, else the most + recent known connectivity state is displayed without re-checking.</para> + + <para>Possible states are:</para> + + <variablelist> + <varlistentry> + <term><arg choice='plain'>none</arg></term> + <listitem> + <para>the host is not connected to any network.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><arg choice='plain'>portal</arg></term> + <listitem> + <para>the host is behind a captive portal and cannot reach the full Internet.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><arg choice='plain'>limited</arg></term> + <listitem> + <para>the host is connected to a network, but it has no access to the Internet.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><arg choice='plain'>full</arg></term> + <listitem> + <para>the host is connected to a network and has full access to the Internet.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><arg choice='plain'>unknown</arg></term> + <listitem> + <para>the connectivity status cannot be found out.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + </variablelist> + </refsect1> + + <refsect1 id='radio'><title>Radio Transmission Control Commands</title> + + <cmdsynopsis> + <command>nmcli radio</command> + <group choice='req'> + <arg choice='plain'><command>all</command></arg> + <arg choice='plain'><command>wifi</command></arg> + <arg choice='plain'><command>wwan</command></arg> + </group> + <arg rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + + <para>Show radio switches status, or enable and disable the switches.</para> + + <variablelist> + + <varlistentry> + <term> + <command>wifi</command> + <group> + <arg choice='plain'>on</arg> + <arg choice='plain'>off</arg> + </group> + </term> + + <listitem> + <para>Show or set status of Wi-Fi in NetworkManager. If no arguments are + supplied, Wi-Fi status is printed; <option>on</option> enables Wi-Fi; + <option>off</option> disables Wi-Fi.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>wwan</command> + <group> + <arg choice='plain'>on</arg> + <arg choice='plain'>off</arg> + </group> + </term> + + <listitem> + <para>Show or set status of WWAN (mobile broadband) in NetworkManager. If no + arguments are supplied, mobile broadband status is printed; + <option>on</option> enables mobile broadband, <option>off</option> + disables it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>all</command> + <group> + <arg choice='plain'>on</arg> + <arg choice='plain'>off</arg> + </group> + </term> + + <listitem> + <para>Show or set all previously mentioned radio switches at the same time.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='monitor'><title>Activity Monitor</title> + + <cmdsynopsis> + <command>nmcli monitor</command> + </cmdsynopsis> + + <para>Observe NetworkManager activity. Watches for changes + in connectivity state, devices or connection profiles.</para> + + <para>See also <command>nmcli connection monitor</command> + and <command>nmcli device monitor</command> to watch + for changes in certain devices or connections.</para> + </refsect1> + + <refsect1 id='connection'><title>Connection Management Commands</title> + + <cmdsynopsis> + <command>nmcli connection</command> + <group choice='req'> + <arg choice='plain'><command>show</command></arg> + <arg choice='plain'><command>up</command></arg> + <arg choice='plain'><command>down</command></arg> + <arg choice='plain'><command>add</command></arg> + <arg choice='plain'><command>edit</command></arg> + <arg choice='plain'><command>modify</command></arg> + <arg choice='plain'><command>delete</command></arg> + <arg choice='plain'><command>monitor</command></arg> + <arg choice='plain'><command>reload</command></arg> + <arg choice='plain'><command>load</command></arg> + </group> + <arg rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + + <para>NetworkManager stores all network configuration as "connections", + which are collections of data (Layer2 details, IP addressing, etc.) that + describe how to create or connect to a network. A connection is "active" + when a device uses that connection's configuration to create or connect to + a network. There may be multiple connections that apply to a device, but only + one of them can be active on that device at any given time. The additional + connections can be used to allow quick switching between different networks + and configurations.</para> + + <para>Consider a machine which is usually connected to a DHCP-enabled network, + but sometimes connected to a testing network which uses static IP addressing. + Instead of manually reconfiguring eth0 each time the network is changed, the + settings can be saved as two connections which both apply to eth0, one for DHCP + (called <literal>default</literal>) and one with the static addressing details (called + <literal>testing</literal>). When connected to the DHCP-enabled network the user would run + <command>nmcli con up default</command> , and when connected to the static network the user + would run <command>nmcli con up testing</command>.</para> + + <variablelist> + + <varlistentry> + <term> + <command>show</command> + <arg><option>--active</option></arg> + <arg> + <option>--order</option> + <arg choice='plain' rep='repeat'>[+-]<replaceable>category</replaceable>:</arg> + </arg> + </term> + + <listitem> + <para>List in-memory and on-disk connection profiles, some of which may also be + active if a device is using that connection profile. Without a parameter, all + profiles are listed. When <option>--active</option> option is specified, only + the active profiles are shown.</para> + + <para>The <option>--order</option> option can be used to get custom + ordering of connections. The connections can be ordered by active status + (<literal>active</literal>), name (<literal>name</literal>), type + (<literal>type</literal>) or D-Bus path (<literal>path</literal>). If + connections are equal according to a sort order category, an additional + category can be specified. The default sorting order is equivalent to + <literal>--order active:name:path</literal>. <literal>+</literal> or no + prefix means sorting in ascending order (alphabetically or in numbers), + <literal>-</literal> means reverse (descending) order. The category names + can be abbreviated (e.g. <literal>--order -a:na</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>show</command> + <arg><option>--active</option></arg> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + <arg choice='plain'><option>apath</option></arg> + </group> + <arg rep='repeat' choice='plain'><replaceable>ID</replaceable></arg> + </term> + + <listitem> + <para>Show details for specified connections. By default, both static + configuration and active connection data are displayed. When + <option>--active</option> option is specified, only the active profiles are + taken into account. Use global <option>--show-secrets</option> option to + display secrets associated with the profile.</para> + + <para><option>id</option>, <option>uuid</option>, + <option>path</option> and <option>apath</option> keywords can be used + if <replaceable>ID</replaceable> is ambiguous. Optional + <replaceable>ID</replaceable>-specifying keywords are:</para> + + <variablelist> + <varlistentry> + <term><option>id</option></term> + <listitem> + <para>the <replaceable>ID</replaceable> denotes a connection name.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>uuid</option></term> + <listitem> + <para>the <replaceable>ID</replaceable> denotes a connection UUID.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>path</option></term> + <listitem> + <para>the <replaceable>ID</replaceable> denotes a D-Bus + static connection path in the format of + /org/freedesktop/NetworkManager/Settings/<replaceable>num</replaceable> + or just <replaceable>num</replaceable>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>apath</option></term> + <listitem> + <para>the <replaceable>ID</replaceable> denotes a D-Bus active connection path in the format of + /org/freedesktop/NetworkManager/ActiveConnection/<replaceable>num</replaceable> or just + <replaceable>num</replaceable>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>It is possible to filter the output using the global + <option>--fields</option> option. Use the following values:</para> + + <variablelist> + <varlistentry> + <term><option>profile</option></term> + <listitem> + <para>only shows static profile configuration.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>active</option></term> + <listitem> + <para>only shows active connection data (when the profile is active).</para> + </listitem> + </varlistentry> + </variablelist> + + <para>You can also specify particular fields. For static configuration, use + setting and property names as described in + <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> manual page. For active data use GENERAL, IP4, DHCP4, IP6, + DHCP6, VPN.</para> + + <para>When no command is given to the <command>nmcli connection</command>, + the default action is <command>nmcli connection show</command>.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>up</command> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg rep='repeat' choice='plain'><replaceable>ID</replaceable></arg> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg><option>ap</option> <replaceable>BSSID</replaceable></arg> + <arg><option>passwd-file</option> <replaceable>file</replaceable></arg> + </term> + + <listitem> + <para>Activate a connection. The connection is identified by its name, UUID or + D-Bus path. If <replaceable>ID</replaceable> is ambiguous, a keyword <option>id</option>, + <option>uuid</option> or <option>path</option> can be used. When + requiring a particular device to activate the connection on, the + <option>ifname</option> option with interface name should be given. If the + <replaceable>ID</replaceable> is not given an <option>ifname</option> is required, and + NetworkManager will activate the best available connection for the given + <option>ifname</option>. In case of a VPN connection, the + <option>ifname</option> option specifies the device of the base connection. + The <option>ap</option> option specify what particular AP should be used in + case of a Wi-Fi connection.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout will be 90 + seconds.</para> + + <para>See <command>connection show</command> above for the description of the + <replaceable>ID</replaceable>-specifying keywords.</para> + + <para>Available options are:</para> + + <variablelist> + <varlistentry> + <term><option>ifname</option></term> + <listitem> + <para>interface that will be used for activation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>ap</option></term> + <listitem> + <para>BSSID of the AP which the command should connect to (for Wi-Fi connections).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>passwd-file</option></term> + <listitem> + <para>some networks may require credentials during activation. You can give + these credentials using this option. Each line of the file should contain one + password in the form: + + <programlisting>setting_name.property_name:the password</programlisting> + + For example, for WPA Wi-Fi with PSK, the line would be + + <programlisting>802-11-wireless-security.psk:secret12345</programlisting> + + For 802.1X password, the line would be + + <programlisting>802-1x.password:my 1X password</programlisting> + + <command>nmcli</command> also accepts <literal>wifi-sec</literal> and <literal>wifi</literal> strings instead of + <literal>802-11-wireless-security</literal>. When NetworkManager requires a password and it is + not given, <command>nmcli</command> will ask for it when run with <option>--ask</option>. + If <option>--ask</option> was not passed, NetworkManager can ask another secret + agent that may be running (typically a GUI secret agent, such as nm-applet or + gnome-shell).</para> + </listitem> + </varlistentry> + </variablelist> + + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>down</command> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + <arg choice='plain'><option>apath</option></arg> + </group> + <arg rep='repeat' choice='plain'><replaceable>ID</replaceable></arg> + </term> + + <listitem> + <para>Deactivate a connection from a device without preventing the device from + further auto-activation. Multiple connections can be passed to the + command.</para> + + <para>Be aware that this command deactivates the specified active connection, + but the device on which the connection was active, is still ready to connect + and will perform auto-activation by looking for a suitable connection that has + the 'autoconnect' flag set. This includes the just deactivated connection. So + if the connection is set to auto-connect, it will be automatically started on + the disconnected device again.</para> + + <para>In most cases you may want to use <command>device disconnect</command> + command instead.</para> + + <para>The connection is identified by its name, UUID or D-Bus path. If + <replaceable>ID</replaceable> is ambiguous, a keyword <option>id</option>, + <option>uuid</option>, <option>path</option> or + <option>apath</option> can be used.</para> + + <para> See <command>connection show</command> above for the description of + the <replaceable>ID</replaceable>-specifying keywords.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout + will be 10 seconds.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>add</command> + <arg choice='plain'><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg>con-name <replaceable>name</replaceable></arg> + <arg> + <option>autoconnect</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg> + <option>save</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg>master <replaceable>master</replaceable></arg> + <arg>slave-type <replaceable>type</replaceable></arg> + <arg>type <replaceable>type</replaceable></arg> + <arg rep="repeat"><replaceable>ARGUMENTS</replaceable></arg> + <arg>ip4 <replaceable>addr</replaceable></arg> + <arg>gw4 <replaceable>addr</replaceable></arg> + <arg>ip6 <replaceable>addr</replaceable></arg> + <arg>gw6 <replaceable>addr</replaceable></arg> + <arg> + <option>--</option> + <arg choice='plain' rep='repeat'> + [+|-]<replaceable>setting</replaceable>.<replaceable>property</replaceable> + <replaceable>value</replaceable> + </arg> + </arg> + </term> + + <listitem> + <para>Add a connection for NetworkManager. Arguments differ according to connection types, see below.</para> + + <variablelist> + + <varlistentry> + <term><option>ifname</option></term> + <listitem> + <para>interface to bind the connection to. The connection will only be + applicable to this interface name. A special value of <literal>*</literal> + can be used for interface-independent connections. The + <option>ifname</option> argument is mandatory for all connection types + except bond, team, bridge and vlan. Note: use quotes around + <literal>*</literal> to suppress shell expansion.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>con-name</option></term> + <listitem> + <para>connection name (when not provided a default name is generated: + <type>[-<ifname>][-<num>]).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>autoconnect</option></term> + <listitem> + <para>whether the connection profile can be automatically activated (default: + yes).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>save</option></term> + <listitem> + <para>whether the connection should be persistent, i.e. NetworkManager should + store it on disk (default: <literal>yes</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>master</option></term> + <listitem> + <para>master interface name, or connection UUID or ID of master connection + profile. The value can be prefixed with <literal>ifname/</literal>, + <literal>uuid/</literal> or <literal>id/</literal> to disambiguate it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>slave-type</option></term> + <listitem> + <para>type of master connection. Only required when it can not be inferred + (i.e. the master connection does + not exist yet).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>type</option></term> + <listitem> + <para>connection type; see below for allowed values. Note that types + <option>bond-slave</option>, <option>team-slave</option> and + <option>bridge-slave</option> create <option>ethernet</option> connection + profiles. Their use is discouraged in favor of using a specific type with + <option>master</option> option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type ethernet</option> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + <arg><option>cloned-mac</option> <replaceable>addr</replaceable></arg> + <arg><option>mtu</option> <replaceable>mtu</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the device this connection is locked to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>cloned-mac</option></term> + <listitem> + <para>cloned MAC.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mtu</option></term> + <listitem> + <para>MTU.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type wifi</option> + <arg choice='plain'><option>ssid</option> <replaceable>SSID</replaceable></arg> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + <arg><option>cloned-mac</option> <replaceable>addr</replaceable></arg> + <arg> + <option>mode</option> + <group choice='req'> + <arg choice='plain'>infrastructure</arg> + <arg choice='plain'>ap</arg> + <arg choice='plain'>adhoc</arg> + </group> + </arg> + <arg><option>mtu</option> <replaceable>mtu</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>ssid</option></term> + <listitem> + <para>SSID.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the device this connection is locked to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>cloned-mac</option></term> + <listitem> + <para>cloned MAC.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mode</option></term> + <listitem> + <para>Wi-Fi network mode. If blank, <literal>infrastructure</literal> + is assumed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mtu</option></term> + <listitem> + <para>MTU.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type wimax</option> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + <arg><option>nsp</option> <replaceable>nsp</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the device this connection is locked to.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nsp</option></term> + <listitem> + <para>Network Service Provider name.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type pppoe</option> + <arg choice='plain'><option>username</option> <replaceable>user</replaceable></arg> + <arg><option>password</option> <replaceable>passwd</replaceable></arg> + <arg><option>service</option> <replaceable>name</replaceable></arg> + <arg><option>mtu</option> <replaceable>mtu</replaceable></arg> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>username</option></term> + <listitem> + <para>PPPoE username.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>Password for the PPPoE username.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>service</option></term> + <listitem> + <para>PPPoE service name (if required by concentrator).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mtu</option></term> + <listitem> + <para>MTU.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the device this connection is locked to.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type gsm</option> + <arg><option>apn</option> <replaceable>APN</replaceable></arg> + <arg><option>username</option> <replaceable>user</replaceable></arg> + <arg><option>password</option> <replaceable>passwd</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>apn</option></term> + <listitem> + <para>APN - GSM Access Point Name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>user</option></term> + <listitem> + <para>user name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>password.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type cdma</option> + <arg><option>username</option> <replaceable>user</replaceable></arg> + <arg><option>password</option> <replaceable>passwd</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>user</option></term> + <listitem> + <para>user name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>password.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type infiniband</option> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + <arg><option>mtu</option> <replaceable>mtu</replaceable></arg> + <arg> + <option>transport-mode</option> + <group choice='req'> + <arg choice='plain'>datagram</arg> + <arg choice='plain'>connected</arg> + </group> + </arg> + <arg><option>parent</option> <replaceable>device</replaceable></arg> + <arg><option>p-key</option> <replaceable>key</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the device this connection is locked to + (InfiniBand MAC is 20 bytes).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mtu</option></term> + <listitem> + <para>MTU.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>transport-mode</option></term> + <listitem> + <para>InfiniBand transport mode.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>parent</option></term> + <listitem> + <para>the interface name of the parent device (if any).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>p-key</option></term> + <listitem> + <para>the InfiniBand P_Key (16-bit unsigned integer).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type bluetooth</option> + <arg><option>addr</option> <replaceable>addr</replaceable></arg> + <arg> + <option>bt-type</option> + <group choice='req'> + <arg choice='plain'>panu</arg> + <arg choice='plain'>dun-gsm</arg> + <arg choice='plain'>dun-cdma</arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>addr</option></term> + <listitem> + <para>Bluetooth device address (MAC).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>bt-type</option></term> + <listitem> + <para>Bluetooth connection type.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type vlan</option> + <arg choice='plain'><option>dev</option> <replaceable>device</replaceable></arg> + <arg choice='plain'><option>id</option> <replaceable>id</replaceable></arg> + <arg><option>flags</option> <replaceable>flags</replaceable></arg> + <arg><option>ingress</option> <replaceable>mapping</replaceable></arg> + <arg><option>egress</option> <replaceable>mapping</replaceable></arg> + <arg><option>mtu</option> <replaceable>mtu</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>dev</option></term> + <listitem> + <para>parent device this VLAN is on.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>id</option></term> + <listitem> + <para>VLAN ID in range 0-4095.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>flags</option></term> + <listitem> + <para>flags.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ingress</option></term> + <listitem> + <para>VLAN ingress priority mapping.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>egress</option></term> + <listitem> + <para>VLAN egress priority mapping.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mtu</option></term> + <listitem> + <para>MTU.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type bond</option> + <arg> + <option>mode</option> + <group choice='req'> + <arg choice='plain'>active-backup</arg> + <arg choice='plain'>balance-xor</arg> + <arg choice='plain'>broadcast</arg> + <arg choice='plain'>802.3ad</arg> + <arg choice='plain'>balance-tlb</arg> + <arg choice='plain'>balance-alb</arg> + <arg choice='plain'><replaceable>num</replaceable></arg> + </group> + </arg> + <arg><option>primary</option> <replaceable>ifname</replaceable></arg> + <arg><option>miimon</option> <replaceable>num</replaceable></arg> + <arg><option>downdelay</option> <replaceable>num</replaceable></arg> + <arg><option>updelay</option> <replaceable>num</replaceable></arg> + <arg><option>arp-interval</option> <replaceable>num</replaceable></arg> + <arg><option>arp-ip-target</option> <replaceable>num</replaceable></arg> + </term> + <listitem> + <variablelist> + + <varlistentry> + <term><option>mode</option></term> + <listitem> + <para>bonding mode (default: <literal>balance-rr</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>primary</option></term> + <listitem> + <para>primary interface name (for <literal>active-backup</literal> mode).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>miimon</option></term> + <listitem> + <para>miimon (default: <literal>100</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>downdelay</option></term> + <listitem> + <para>downdelay (default: <literal>0</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>updelay</option></term> + <listitem> + <para>updelay (default: <literal>0</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>arp-interval</option></term> + <listitem> + <para>ARP interval (default: <literal>0</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>arp-ip-target</option></term> + <listitem> + <para>ARP IP target.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type bond-slave</option> + <arg><option>master</option> <replaceable>master</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>master</option></term> + <listitem> + <para>master bond interface name, or connection UUID or + ID of bond master connection profile. The value can be + prefixed with <literal>ifname/</literal>, + <literal>uuid/</literal> or <literal>id/</literal> to + disambiguate it.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type team</option> + <arg> + <option>config</option> + <group choice='req'> + <arg choice='plain'>file</arg> + <arg choice='plain'><replaceable>JSON</replaceable></arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + + <varlistentry> + <term><option>config</option></term> + <listitem> + <para>JSON configuration for team.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type team-slave</option> + <arg> + <option>config</option> + <option><replaceable>JSON</replaceable></option> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>master</option></term> + <listitem> + <para>master team interface name, or connection UUID or + ID of team master connection profile. The value can be + prefixed with <literal>ifname/</literal>, + <literal>uuid/</literal> or <literal>id/</literal>to + disambiguate it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>config</option></term> + <listitem> + <para>JSON configuration for team.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type bridge</option> + <arg> + <option>stp</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg><option>priority</option> <replaceable>num</replaceable></arg> + <arg><option>forward-delay</option> <replaceable>2-30</replaceable></arg> + <arg><option>hello-time</option> <replaceable>1-10</replaceable></arg> + <arg><option>max-age</option> <replaceable>6-42</replaceable></arg> + <arg><option>ageing-time</option> <replaceable>0-1000000</replaceable></arg> + <arg> + <option>multicast-snooping</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg><option>mac</option> <replaceable>addr</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>stp</option></term> + <listitem> + <para>controls whether Spanning Tree Protocol (STP) is enabled for this bridge + (default: <literal>yes</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>priority</option></term> + <listitem> + <para>sets STP priority (default: <literal>128</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>forward-delay</option></term> + <listitem> + <para>STP forwarding delay, in seconds (default: <literal>15</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>hello-time</option></term> + <listitem> + <para>STP hello time, in seconds (default: <literal>2</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>max-age</option></term> + <listitem> + <para>STP maximum message age, in seconds (default: <literal>20</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ageing-time</option></term> + <listitem> + <para>the Ethernet MAC address aging time, in seconds (default: <literal>300</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>multicast-snooping</option></term> + <listitem> + <para>controls whether IGMP snooping is enabled (default: <literal>yes</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mac</option></term> + <listitem> + <para>MAC address of the bridge (note: this requires a recent kernel feature, + originally introduced in 3.15 upstream kernel).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type bridge-slave</option> + <arg><option>master</option> <replaceable>master</replaceable></arg> + <arg><option>priority</option> <replaceable>num</replaceable></arg> + <arg><option>path-cost</option> <replaceable>1-65535</replaceable></arg> + <arg> + <option>hairpin</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>master</option></term> + <listitem> + <para>master bridge interface name, or connection UUID + or ID of bridge master connection profile. The value + can be prefixed with <literal>ifname/</literal>, + <literal>uuid/</literal> or <literal>id/</literal> + to disambiguate it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>priority</option></term> + <listitem> + <para>STP priority of this slave (default: <literal>32</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>path-cost</option></term> + <listitem> + <para>STP port cost for destinations via this slave (default: <literal>100</literal>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>hairpin</option></term> + <listitem> + <para>'hairpin mode' for the slave, which allows frames to be sent back out + through the slave the frame was received on (default: <literal>yes</literal>).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type vpn</option> + <arg><option>type</option> <replaceable>type</replaceable></arg> + <arg><option>user</option> <replaceable>username</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>vpn-type</option></term> + <listitem> + <para>VPN type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>user</option></term> + <listitem> + <para>VPN username.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type olpc-mesh</option> + <arg choice='plain'><option>ssid</option> <replaceable>SSID</replaceable></arg> + <arg><option>channel</option> <replaceable>1-13</replaceable></arg> + <arg><option>dhcp-anycast</option> <replaceable>MAC</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>ssid</option></term> + <listitem> + <para>SSID.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>channel</option></term> + <listitem> + <para>channel to use for the network.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>dhcp-anycast</option></term> + <listitem> + <para>anycast DHCP MAC address used when requesting an IP address via DHCP.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type adsl</option> + <arg choice='plain'><option>username</option> <replaceable>username</replaceable></arg> + <arg choice='plain'> + <option>protocol</option> + <group choice='req'> + <arg choice='plain'>pppoa</arg> + <arg choice='plain'>pppoe</arg> + <arg choice='plain'>ipoatm</arg> + </group> + </arg> + <arg><option>password</option> <replaceable>passwd</replaceable></arg> + <arg> + <option>encapsulation</option> + <group choice='req'> + <arg choice='plain'>vcmux</arg> + <arg choice='plain'>llc</arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>username</option></term> + <listitem> + <para>ADSL user name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>protocol</option></term> + <listitem> + <para>ADSL protocol.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>ADSL password.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>encapsulation</option></term> + <listitem> + <para>ADSL encapsulation.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type tun</option> + <arg choice='plain'> + <option>mode</option> + <group choice='req'> + <arg choice='plain'>tun</arg> + <arg choice='plain'>tap</arg> + </group> + </arg> + <arg><option>owner</option> <replaceable>UID</replaceable></arg> + <arg><option>group</option> <replaceable>GID</replaceable></arg> + <arg> + <option>pi</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg> + <option>vnet-hdr</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg> + <option>multi-queue</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>mode</option></term> + <listitem> + <para>Mode for the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>owner</option></term> + <listitem> + <para>UID of the owner.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>group</option></term> + <listitem> + <para>GID of the group.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>pi</option></term> + <listitem> + <para>include packet information (~IFF_NO_PI flag).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>vnet-hdr</option></term> + <listitem> + <para>send and receive large (i.e. GSO) packets and packets with partial + checksums (IFF_VNET_HDR flag).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>multi-queue</option></term> + <listitem> + <para>multi-queue support for tun/tap device (IFF_MULTI_QUEUE flag).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type ip-tunnel</option> + <arg choice='plain'> + <option>mode</option> + <group choice='req'> + <arg choice='plain'>ipip</arg> + <arg choice='plain'>gre</arg> + <arg choice='plain'>sit</arg> + <arg choice='plain'>isatap</arg> + <arg choice='plain'>vti</arg> + <arg choice='plain'>ip6ip6</arg> + <arg choice='plain'>ipip6</arg> + <arg choice='plain'>ip6gre</arg> + <arg choice='plain'>vti6</arg> + <arg choice='plain'>tun</arg> + </group> + </arg> + <arg choice='plain'><option>remote</option> <replaceable>addr</replaceable></arg> + <arg><option>local</option> <replaceable>addr</replaceable></arg> + <arg><option>dev</option> <replaceable>device</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>mode</option></term> + <listitem> + <para>tunnel mode.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>remote</option></term> + <listitem> + <para>IPv4 or IPv6 address of the remote tunnel endpoint.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>local</option></term> + <listitem> + <para>IPv4 or IPv6 address of the local tunnel endpoint.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>dev</option></term> + <listitem> + <para>device to use for tunnel endpoint communication.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type macvlan</option> + <arg choice='plain'><option>dev</option> <replaceable>device</replaceable></arg> + <arg choice='plain'> + <option>mode</option> + <group choice='req'> + <arg choice='plain'>vepa</arg> + <arg choice='plain'>bridge</arg> + <arg choice='plain'>private</arg> + <arg choice='plain'>passthru</arg> + <arg choice='plain'>source</arg> + </group> + </arg> + <arg> + <option>tap</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>dev</option></term> + <listitem> + <para>parent device this MACVLAN is on.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>mode</option></term> + <listitem> + <para>MACVLAN mode, which specifies the communication mechanism between + multiple MACVLANs on the same lower device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>tap</option></term> + <listitem> + <para>controls the device type. If set to 'yes' a MACVTAP will be created + (default: <literal>no</literal>).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <option>type vxlan</option> + <arg choice='plain'><option>id</option> <replaceable>id</replaceable></arg> + <arg choice='plain'><option>remote</option> <replaceable>addr</replaceable></arg> + <arg><option>dev</option> <replaceable>parent device (ifname or connection UUID)</replaceable></arg> + <arg><option>local</option> <replaceable>addr</replaceable></arg> + <arg><option>source-port-min</option> <replaceable>0-65535</replaceable></arg> + <arg><option>source-port-max</option> <replaceable>0-65535</replaceable></arg> + <arg><option>destination-port</option> <replaceable>0-65535</replaceable></arg> + </term> + <listitem> + <variablelist> + <varlistentry> + <term><option>id</option></term> + <listitem> + <para>VXLAN Network Identifer to use.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>remote</option></term> + <listitem> + <para>unicast destination IP address or multicast IP address to join.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>dev</option></term> + <listitem> + <para>device to use for tunnel endpoint communication.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>local</option></term> + <listitem> + <para>source IP address.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>source-port-min</option></term> + <listitem> + <para>minimum UDP source port to communicate to the remote VXLAN tunnel endpoint.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>source-port-max</option></term> + <listitem> + <para>maximum UDP source port to communicate to the remote VXLAN tunnel endpoint.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>destination-port</option></term> + <listitem> + <para>UDP destination port to communicate to the remote VXLAN tunnel endpoint.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ip4</option></term> + <term><option>gw4</option></term> + <listitem> + <para>IPv4 addresses.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>ip6</option></term> + <term><option>gw6</option></term> + <listitem> + <para>IPv6 addresses.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--</option></term> + <listitem> + <para>If a <option>--</option> argument is encountered, the rest of command + line is interpreted as property list in the same format as <command>connection + modify</command> command accepts. This makes it possible to adjust the + connection properties before it's added.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>edit</command> + <group choice='req'> + <arg choice='plain'> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg rep='repeat' choice='plain'><replaceable>ID</replaceable></arg> + </arg> + <arg choice='plain'> + <arg><option>type</option> <replaceable>type</replaceable></arg> + <arg><option>con-name</option> <replaceable>name</replaceable></arg> + </arg> + </group> + </term> + + <listitem> + <para>Edit an existing connection or add a new one, using an interactive editor.</para> + + <para>The existing connection is identified by its name, UUID or D-Bus path. If + <replaceable>ID</replaceable> is ambiguous, a keyword <option>id</option>, + <option>uuid</option>, or <option>path</option> can be used. See + <command>connection show</command> above for the description of the + <replaceable>ID</replaceable>-specifying keywords. Not providing an + <replaceable>ID</replaceable> means that a new connection will be added.</para> + + <para>The interactive editor will guide you through the connection editing and + allow you to change connection parameters according to your needs by means of + a simple menu-driven interface. The editor indicates what settings and + properties can be modified and provides in-line help.</para> + + <para>Available options:</para> + + <variablelist> + <varlistentry> + <term><option>type</option></term> + <listitem> + <para>type of the new connection; valid types are the same as for + <command>connection add</command> command.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>con-name</option></term> + <listitem> + <para>name for the new connection. It can be changed later in the editor.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>See also + <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> for all NetworkManager settings and property names, and their + descriptions; and + <citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for sample editor sessions.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>modify</command> + <arg><option>--temporary</option></arg> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg choice='plain'><replaceable>ID</replaceable></arg> + <arg choice='plain' rep='repeat'> + [+|-]<replaceable>setting</replaceable>.<replaceable>property</replaceable> + <replaceable>value</replaceable> + </arg> + </term> + + <listitem> + <para>Modify one or more properties in the connection profile.</para> + + <para>The connection is identified by its name, UUID or D-Bus path. If + <replaceable>ID</replaceable> is ambiguous, a keyword <option>id</option>, + <option>uuid</option> or <option>path</option> can be used. See + <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum> + </citerefentry> for setting and property names, their descriptions and default + values. This command supports abbreviations for <replaceable>setting</replaceable> + and <replaceable>property</replaceable> provided they are unique. Empty + <replaceable>value</replaceable> ("") removes the property value (sets + the property to the default value). The provided value overwrites the existing + property value.</para> + + <para>If you want to append an item to the existing value, use + <literal>+</literal> prefix for the property name. If you want to remove just + one item from container-type property, use <literal>-</literal> prefix for + the property name and specify a value or an zero-based index of the item to + remove (or option name for properties with named options) as + <replaceable>value</replaceable>. Of course, <literal>+</literal> and + <literal>-</literal> only have a real effect for multi-value (container) + properties like <literal>ipv4.dns</literal>, <literal>ipv4.addresses</literal>, + <literal>bond.options</literal>, etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>clone</command> + <arg><option>--temporary</option></arg> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>ID</replaceable></arg> + <arg choice='plain'><option>new</option> <replaceable>name</replaceable></arg> + </term> + + <listitem> + <para>Clone a connection. The connection to be cloned is identified by its + name, UUID or D-Bus path. If <replaceable>ID</replaceable> is ambiguous, a keyword + <option>id</option>, <option>uuid</option> or <option>path</option> + can be used. See <command>connection show</command> above for the description + of the <replaceable>ID</replaceable>-specifying keywords. <replaceable>name</replaceable> is + the name of the new cloned connection. The new connection will be the exact + copy except the connection.id (<replaceable>name</replaceable>) and + connection.uuid (generated) properties.</para> + + <para>The new connection profile will be saved as persistent unless + <option>--temporary</option> option is specified, in which case the new profile + won't exist after NetworkManager restart.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>delete</command> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>ID</replaceable></arg> + </term> + + <listitem> + <para>Delete a configured connection. The connection to be deleted is + identified by its name, UUID or D-Bus path. If <replaceable>ID</replaceable> is ambiguous, a + keyword <option>id</option>, <option>uuid</option> or <option>path</option> can be used. + See <command>connection show</command> above for the description of + the <replaceable>ID</replaceable>-specifying keywords.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout will be 10 + seconds.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>monitor</command> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg choice='plain' rep='repeat'><replaceable>ID</replaceable></arg> + </term> + + <listitem> + <para>Monitor connection profile activity. This command prints a line whenever + the specified connection changes. The connection to be monitored is identified + by its name, UUID or D-Bus path. If <replaceable>ID</replaceable> is ambiguous, a keyword + <option>id</option>, <option>uuid</option> or <option>path</option> + can be used. See <command>connection show</command> above for the description of the + <replaceable>ID</replaceable>-specifying keywords.</para> + + <para>Monitors all connection profiles in case none is specified. The command + terminates when all monitored connections disappear. If you want to monitor + connection creation consider using the global monitor with <command>nmcli + monitor</command> command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>reload</command> + </term> + + <listitem> + <para>Reload all connection files from disk. + NetworkManager does not monitor changes to connection + files by default. So you need to use this command in order to tell + NetworkManager to re-read the connection profiles from + disk when a change was made to them. However, the auto-loading feature can be + enabled and then NetworkManager will reload connection + files any time they change (monitor-connection-files=true in + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>load</command> + <arg choice='plain' rep='repeat'><replaceable>filename</replaceable></arg> + </term> + + <listitem> + <para>Load/reload one or more connection files from disk. Use this after + manually editing a connection file to ensure that + NetworkManager is aware of its latest state.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>import</command> + <arg><option>--temporary</option></arg> + <arg><option>type</option> <replaceable>type</replaceable></arg> + <arg><option>file</option> <replaceable>file</replaceable></arg> + </term> + + <listitem> + <para>Import an external/foreign configuration as a NetworkManager connection + profile. The type of the input file is specified by <option>type</option> + option.</para> + + <para>Only VPN configurations are supported at the moment. The configuration is + imported by NetworkManager VPN plugins. <option>type</option> values are + the same as for <option>vpn-type</option> option in <command>nmcli + connection add</command>. VPN configurations are imported by VPN plugins. + Therefore the proper VPN plugin has to be installed so that <command>nmcli</command> could import + the data.</para> + + <para>The imported connection profile will be saved as persistent unless + <option>--temporary</option> option is specified, in which case the new profile + won't exist after NetworkManager restart.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>export</command> + <group> + <arg choice='plain'><option>id</option></arg> + <arg choice='plain'><option>uuid</option></arg> + <arg choice='plain'><option>path</option></arg> + </group> + <arg choice='plain'><replaceable>ID</replaceable></arg> + <arg><replaceable>file</replaceable></arg> + </term> + + <listitem> + <para>Export a connection.</para> + + <para>Only VPN connections are supported at the moment. A proper VPN plugin has + to be installed so that <command>nmcli</command> could export a connection. If no + <replaceable>file</replaceable> is provided, the VPN configuration + data will be printed to standard output.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='device'><title>Device Management Commands</title> + + <cmdsynopsis> + <command>nmcli device</command> + <group choice='req'> + <arg choice='plain'><command>status</command></arg> + <arg choice='plain'><command>show</command></arg> + <arg choice='plain'><command>set</command></arg> + <arg choice='plain'><command>connect</command></arg> + <arg choice='plain'><command>reapply</command></arg> + <arg choice='plain'><command>disconnect</command></arg> + <arg choice='plain'><command>delete</command></arg> + <arg choice='plain'><command>monitor</command></arg> + <arg choice='plain'><command>wifi</command></arg> + <arg choice='plain'><command>lldp</command></arg> + </group> + <arg rep='repeat'><replaceable>ARGUMENTS</replaceable></arg> + </cmdsynopsis> + + <para>Show and manage network interfaces.</para> + + <variablelist> + + <varlistentry> + <term><command>status</command></term> + + <listitem> + <para>Print status of devices.</para> + + <para>This is the default action if no command is specified to + <command>nmcli device</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>show</command> + <arg><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Show detailed information about devices. Without an argument, all + devices are examined. To get information for a specific device, the interface + name has to be provided.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>set</command> + <arg>ifname</arg> + <arg choice='plain'><replaceable>ifname</replaceable></arg> + <arg> + <option>autoconnect</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg> + <option>managed</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + </term> + + <listitem> + <para>Set device properties.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>connect</command> + <arg><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Connect the device. NetworkManager will try to find a suitable connection + that will be activated. It will also consider connections that are not set to + auto connect.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout will be 90 + seconds.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>reapply</command> + <arg><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Attempt to update device with changes to the currently active connection + made since it was last applied.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>disconnect</command> + <arg rep='repeat'><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Disconnect a device and prevent the device from automatically activating + further connections without user/manual intervention. Note that disconnecting + software devices may mean that the devices will disappear.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout + will be 10 seconds.</para> + </listitem> + </varlistentry> + + + <varlistentry> + <term> + <command>delete</command> + <arg rep='repeat'><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Delete a device. The command removes the interface from the system. Note + that this only works for software devices like bonds, bridges, teams, etc. + Hardware devices (like Ethernet) cannot be deleted by the command.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout will be 10 + seconds.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>monitor</command> + <arg rep='repeat'><replaceable>ifname</replaceable></arg> + </term> + + <listitem> + <para>Monitor device activity. This command prints a line whenever the + specified devices change state.</para> + + <para>Monitors all devices in case no interface is specified. The monitor + terminates when all specified devices disappear. If you want to monitor device + addition consider using the global monitor with <command>nmcli + monitor</command> command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>wifi</command> + <arg> + <command>list</command> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg><option>bssid</option> <replaceable>BSSID</replaceable></arg> + </arg> + </term> + + <listitem> + <para>List available Wi-Fi access points. The <option>ifname</option> and + <option>bssid</option> options can be used to list APs for a particular + interface or with a specific BSSID, respectively.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>wifi</command> + <command>connect</command> + <arg choice='plain'><replaceable>(B)SSID</replaceable></arg> + <arg><option>password</option> <replaceable>password</replaceable></arg> + <arg> + <option>wep-key-type</option> + <group choice='req'> + <arg choice='plain'>key</arg> + <arg choice='plain'>phrase</arg> + </group> + </arg> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg><option>bssid</option> <replaceable>BSSID</replaceable></arg> + <arg><option>name</option> <replaceable>name</replaceable></arg> + <arg> + <option>private</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + <arg> + <option>hidden</option> + <group choice='req'> + <arg choice='plain'>yes</arg> + <arg choice='plain'>no</arg> + </group> + </arg> + </term> + + <listitem> + <para>Connect to a Wi-Fi network specified by SSID or BSSID. The command + creates a new connection and then activates it on a device. This is a + command-line counterpart of clicking an SSID in a GUI client. The command + always creates a new connection and thus it is mainly useful for connecting to + new Wi-Fi networks. If a connection for the network already exists, it is + better to bring up (activate) the existing connection as follows: + <command>nmcli con up id <replaceable>name</replaceable></command>. Note that + only open, WEP and WPA-PSK networks are supported at the moment. It is also + supposed that IP configuration is obtained via DHCP.</para> + + <para>If <option>--wait</option> option is not specified, the default timeout will be 90 + seconds.</para> + + <para>Available options are:</para> + + <variablelist> + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>password for secured networks (WEP or WPA).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>wep-key-type</option></term> + <listitem> + <para>type of WEP secret, either <option>key</option> for ASCII/HEX key or + <option>phrase</option> for passphrase.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>ifname</option></term> + <listitem> + <para>interface that will be used for activation.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>bssid</option></term> + <listitem> + <para>if specified, the created connection will be restricted just for the + BSSID.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>name</option></term> + <listitem> + <para>if specified, the connection will use the name (else NM creates a name + itself).</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>private</option></term> + <listitem> + <para>if set to <literal>yes</literal>, the connection will only be visible + to the user who created it. Otherwise the connection is system-wide, which is + the default.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>hidden</option></term> + <listitem> + <para>set to <literal>yes</literal> when connecting for the first time to an + AP not broadcasting its SSID. Otherwise the SSID would not be found and the + connection attempt would fail.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>wifi</command> + <command>hotspot</command> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg><option>con-name</option> <replaceable>name</replaceable></arg> + <arg><option>ssid</option> <replaceable>SSID</replaceable></arg> + <arg> + <option>band</option> + <group choice='req'> + <arg choice='plain'>a</arg> + <arg choice='plain'>bg</arg> + </group> + </arg> + <arg><option>channel</option> <replaceable>channel</replaceable></arg> + <arg><option>password</option> <replaceable>password</replaceable></arg> + </term> + + <listitem> + <para>Create a Wi-Fi hotspot. The command creates a hotspot connection profile + according to Wi-Fi device capabilities and activates it on the device. The + hotspot is secured with WPA if device/driver supports that, otherwise WEP is + used. Use <command>connection down</command> or <command>device + disconnect</command> to stop the hotspot.</para> + + <para>Parameters of the hotspot can be influenced by the optional + parameters:</para> + + <variablelist> + <varlistentry> + <term><option>ifname</option></term> + <listitem> + <para>what Wi-Fi device is used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>con-name</option></term> + <listitem> + <para>name of the created hotspot connection profile.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>ssid</option></term> + <listitem> + <para>SSID of the hotspot.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>band</option></term> + <listitem> + <para>Wi-Fi band to use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>channel</option></term> + <listitem> + <para>Wi-Fi channel to use.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>password</option></term> + <listitem> + <para>password to use for the created hotspot. If not provided, <command>nmcli</command> will + generate a password. The password is either WPA pre-shared key or WEP + key.</para> + + <para>Note that <option>--show-secrets</option> global option can be used to + print the hotspot password. It is useful especially when the password was + generated.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>wifi</command> + <command>rescan</command> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + <arg rep='repeat'><option>ssid</option> <replaceable>SSID</replaceable></arg> + </term> + + <listitem> + <para>Request that NetworkManager immediately re-scan for + available access points. NetworkManager scans Wi-Fi networks periodically, but + in some cases it can be useful to start scanning manually (e.g. after resuming + the computer). By using <option>ssid</option>, it is possible to scan for a + specific SSID, which is useful for APs with hidden SSIDs. You can provide + multiple <option>ssid</option> parameters in order to scan more + SSIDs.</para> + + <para>This command does not show the APs, use <command>nmcli device wifi list</command> + for that.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>lldp</command> + <arg> + <command>list</command> + <arg><option>ifname</option> <replaceable>ifname</replaceable></arg> + </arg> + </term> + + <listitem> + <para>Display information about neighboring devices learned through the Link + Layer Discovery Protocol (LLDP). The <option>ifname</option> option can be + used to list neighbors only for a given interface. The protocol must be enabled + in the connection settings.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='agent'><title>Secret Agent</title> + + <cmdsynopsis> + <command>nmcli agent</command> + <group choice='req'> + <arg choice='plain'><command>secret</command></arg> + <arg choice='plain'><command>polkit</command></arg> + <arg choice='plain'><command>all</command></arg> + </group> + </cmdsynopsis> + + <para>Run <command>nmcli</command> as a NetworkManager secret agent, or polkit agent.</para> + + <variablelist> + + <varlistentry> + <term><command>secret</command></term> + + <listitem> + <para>Register <command>nmcli</command> as a NetworkManager secret agent and listen for secret + requests. You do usually not need this command, because <command>nmcli</command> can handle + secrets when connecting to networks. However, you may find the command useful + when you use another tool for activating connections and you do not have a + secret agent available (like nm-applet).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>polkit</command> + </term> + + <listitem> + <para>Register <command>nmcli</command> as a polkit agent for the user session and listen for + authorization requests. You do not usually need this command, because <command>nmcli</command> can + handle polkit actions related to NetworkManager operations (when run with + <option>--ask</option>). However, you may find the command useful when you want + to run a simple text based polkit agent and you do not have an agent of a desktop + environment. Note that running this command makes <command>nmcli</command> handle all polkit requests, + not only NetworkManager related ones, because only one polkit agent can run for the + session.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term> + <command>all</command> + </term> + + <listitem> + <para>Runs <command>nmcli</command> as both NetworkManager secret and a polkit agent.</para> + </listitem> + </varlistentry> + + </variablelist> + + </refsect1> + + <refsect1 id='environment_variables'><title>Environment Variables</title> + + <para><command>nmcli</command>'s behavior is affected by the following + environment variables.</para> + + <variablelist> + <varlistentry> + <term><envar>LC_ALL</envar></term> + <listitem> + <para>If set to a non-empty string value, it overrides the values of all the + other internationalization variables.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>LC_MESSAGES</envar></term> + <listitem> + <para>Determines the locale to be used for internationalized messages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><envar>LANG</envar></term> + <listitem> + <para>Provides a default value for the internationalization variables that are + unset or null.</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1 id='internationalization_notes'><title>Internationalization notes</title> + + <para>Be aware that <command>nmcli</command> is localized and that is why the + output depends on your environment. This is important to realize especially + when you parse the output.</para> + + <para>Call <command>nmcli</command> as <command>LC_ALL=C nmcli</command> to + be sure the locale is set to <literal>C</literal> while executing in a script.</para> + + <para><envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar>, <envar>LANG</envar> + variables specify the <envar>LC_MESSAGES</envar> locale category (in that + order), which determines the language that <command>nmcli</command> uses for + messages. The <literal>C</literal> locale is used if none of these variables are set, and this + locale uses English messages.</para> + + </refsect1> + + <refsect1 id='exit_status'><title>Exit Status</title> + + <para><command>nmcli</command> exits with status 0 if it succeeds, a value + greater than 0 is returned if an error occurs.</para> + + <variablelist spacing='compact' termlength='3'> + <varlistentry> + <term><errorcode>0</errorcode></term> + <listitem> + <para>Success – indicates the operation succeeded.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>1</errorcode></term> + <listitem> + <para>Unknown or unspecified error.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>2</errorcode></term> + <listitem> + <para>Invalid user input, wrong <command>nmcli</command> + invocation.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>3</errorcode></term> + <listitem> + <para>Timeout expired (see <option>--wait</option> option).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>4</errorcode></term> + <listitem> + <para>Connection activation failed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>5</errorcode></term> + <listitem> + <para>Connection deactivation failed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>6</errorcode></term> + <listitem> + <para>Disconnecting device failed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>7</errorcode></term> + <listitem> + <para>Connection deletion failed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>8</errorcode></term> + <listitem> + <para>NetworkManager is not running.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>9</errorcode></term> + <listitem> + <para><command>nmcli</command> and <command>NetworkManager</command> + versions mismatch.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><errorcode>10</errorcode></term> + <listitem> + <para>Connection, device, or access point does not exist.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='examples'><title>Examples</title> + + <para>This section presents various examples of <command>nmcli</command> usage. If you want even + more, please refer to + <citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry> + manual page.</para> + + <variablelist> + <varlistentry> + <term><userinput>nmcli -t -f RUNNING general</userinput></term> + <listitem> + <para>tells you whether NetworkManager is running or not.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -t -f STATE general</userinput></term> + <listitem> + <para>shows the overall status of NetworkManager.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli radio wifi off</userinput></term> + <listitem> + <para>switches Wi-Fi off.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli connection show</userinput></term> + <listitem> + <para>lists all connections NetworkManager has.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -p -m multiline -f all con show</userinput></term> + <listitem> + <para>shows all configured connections in multi-line mode.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli connection show --active</userinput></term> + <listitem> + <para>lists all currently active connections.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -f name,autoconnect c s</userinput></term> + <listitem> + <para>shows all connection profile names and their auto-connect property.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -p connection show "My default em1"</userinput></term> + <listitem> + <para>shows details for "My default em1" connection profile.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli --show-secrets connection show "My Home WiFi"</userinput></term> + <listitem> + <para>shows details for "My Home WiFi" connection profile with all passwords. + Without <option>--show-secrets</option> option, secrets would not be + displayed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -f active connection show "My default em1"</userinput></term> + <listitem> + <para>shows details for "My default em1" active connection, like IP, DHCP + information, etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -f profile con s "My wired connection"</userinput></term> + <listitem> + <para>shows static configuration details of the connection profile with "My + wired connection" name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -p con up "My wired connection" ifname eth0</userinput></term> + <listitem> + <para>activates the connection profile with name "My wired connection" on + interface eth0. The -p option makes <command>nmcli</command> show progress of the + activation.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con up 6b028a27-6dc9-4411-9886-e9ad1dd43761 ap 00:3A:98:7C:42:D3</userinput></term> + <listitem> + <para>connects the Wi-Fi connection with UUID + 6b028a27-6dc9-4411-9886-e9ad1dd43761 to the AP with BSSID + 00:3A:98:7C:42:D3.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli device status</userinput></term> + <listitem> + <para>shows the status for all devices.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli dev disconnect em2</userinput></term> + <listitem> + <para>disconnects a connection on interface em2 and marks the device as + unavailable for auto-connecting. As a result, no connection will automatically + be activated on the device until the device's 'autoconnect' is set to TRUE or + the user manually activates a connection.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -f GENERAL,WIFI-PROPERTIES dev show wlan0</userinput></term> + <listitem> + <para>shows details for wlan0 interface; only GENERAL and WIFI-PROPERTIES + sections will be shown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -f CONNECTIONS device show wlp3s0</userinput></term> + <listitem> + <para>shows all available connection profiles for your Wi-Fi interface + wlp3s0.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli dev wifi</userinput></term> + <listitem> + <para>lists available Wi-Fi access points known to NetworkManager.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli dev wifi con "Cafe Hotspot 1" password caffeine name "My cafe"</userinput></term> + <listitem> + <para>creates a new connection named "My cafe" and then connects it to "Cafe + Hotspot 1" SSID using password "caffeine". This is mainly useful when + connecting to "Cafe Hotspot 1" for the first time. Next time, it is better to + use <command>nmcli con up id "My cafe"</command> so that the + existing connection profile can be used and no additional is created.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli -s dev wifi hotspot con-name QuickHotspot</userinput></term> + <listitem> + <para>creates a hotspot profile and connects it. Prints the hotspot password + the user should use to connect to the hotspot from other devices.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli connection add type ethernet autoconnect no ifname eth0</userinput></term> + <listitem> + <para>non-interactively adds an Ethernet connection tied to eth0 interface with + automatic IP configuration (DHCP), and disables the connection's <literal>autoconnect</literal> + flag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli c a ifname Maxipes-fik type vlan dev eth0 id 55</userinput></term> + <listitem> + <para>non-interactively adds a VLAN connection with ID 55. The connection will + use eth0 and the VLAN interface will be named Maxipes-fik.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli c a ifname eth0 type ethernet -- ipv4.method disabled ipv6.method link-local</userinput></term> + <listitem> + <para>non-interactively adds a connection that will use eth0 Ethernet interface + and only have an IPv6 link-local address configured.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli connection edit ethernet-em1-2</userinput></term> + <listitem> + <para>edits existing "ethernet-em1-2" connection in the interactive + editor.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli connection edit type ethernet con-name "yet another Ethernet connection"</userinput></term> + <listitem> + <para>adds a new Ethernet connection in the interactive editor.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con mod ethernet-2 connection.autoconnect no</userinput></term> + <listitem> + <para>modifies 'autoconnect' property in the 'connection' setting of + 'ethernet-2' connection.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con mod "Home Wi-Fi" wifi.mtu 1350</userinput></term> + <listitem> + <para>modifies 'mtu' property in the 'wifi' setting of 'Home Wi-Fi' + connection.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con mod em1-1 ipv4.method manual ipv4.addr "192.168.1.23/24 192.168.1.1, 10.10.1.5/8, 10.0.0.11"</userinput></term> + <listitem> + <para>sets manual addressing and the addresses in em1-1 profile.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con modify ABC +ipv4.dns 8.8.8.8</userinput></term> + <listitem> + <para>appends a Google public DNS server to DNS servers in ABC profile.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con modify ABC -ipv4.addresses "192.168.100.25/24 192.168.1.1"</userinput></term> + <listitem> + <para>removes the specified IP address from (static) profile ABC.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con import type openvpn file ~/Downloads/frootvpn.ovpn</userinput></term> + <listitem> + <para>imports an OpenVPN configuration to NetworkManager.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><userinput>nmcli con export corp-vpnc /home/joe/corpvpn.conf</userinput></term> + <listitem> + <para>exports NetworkManager VPN profile corp-vpnc as standard Cisco (vpnc) + configuration.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1 id='notes'><title>Notes</title> + <para><command>nmcli</command> accepts abbreviations, as long as they are a unique prefix in the set + of possible options. As new options get added, these abbreviations are not guaranteed + to stay unique. For scripting and long term compatibility it is therefore strongly + advised to spell out the full option names.</para> + </refsect1> + + <refsect1 id='bugs'><title>Bugs</title> + <para>There are probably some bugs. If you find a bug, please report it to + https://bugzilla.gnome.org/ — product <literal>NetworkManager</literal>.</para> + </refsect1> + + <refsect1 id='see_also'><title>See Also</title> + <para><citerefentry><refentrytitle>nmcli-examples</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-online</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>NetworkManager</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>NetworkManager.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-settings</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-applet</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nm-connection-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </refsect1> + +</refentry> |