diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile.in | 11 | ||||
| -rw-r--r-- | man/nmcli.1 | 285 | ||||
| -rw-r--r-- | man/nmcli.1.in | 285 |
3 files changed, 442 insertions, 139 deletions
diff --git a/man/Makefile.in b/man/Makefile.in index 89bb3c89..bf3f5217 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -50,7 +50,7 @@ am__aclocal_m4_deps = $(top_srcdir)/m4/compiler_warnings.m4 \ $(top_srcdir)/m4/ltsugar.m4 $(top_srcdir)/m4/ltversion.m4 \ $(top_srcdir)/m4/lt~obsolete.m4 $(top_srcdir)/m4/nls.m4 \ $(top_srcdir)/m4/po.m4 $(top_srcdir)/m4/progtest.m4 \ - $(top_srcdir)/configure.ac + $(top_srcdir)/m4/vapigen.m4 $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) mkinstalldirs = $(install_sh) -d @@ -167,6 +167,10 @@ INTLTOOL_EXTRACT = @INTLTOOL_EXTRACT@ INTLTOOL_MERGE = @INTLTOOL_MERGE@ INTLTOOL_PERL = @INTLTOOL_PERL@ INTLTOOL_UPDATE = @INTLTOOL_UPDATE@ +INTLTOOL_V_MERGE = @INTLTOOL_V_MERGE@ +INTLTOOL_V_MERGE_OPTIONS = @INTLTOOL_V_MERGE_OPTIONS@ +INTLTOOL__v_MERGE_ = @INTLTOOL__v_MERGE_@ +INTLTOOL__v_MERGE_0 = @INTLTOOL__v_MERGE_0@ INTL_MACOSX_LIBS = @INTL_MACOSX_LIBS@ INTROSPECTION_CFLAGS = @INTROSPECTION_CFLAGS@ INTROSPECTION_COMPILER = @INTROSPECTION_COMPILER@ @@ -262,6 +266,9 @@ UDEV_BASE_DIR = @UDEV_BASE_DIR@ USE_NLS = @USE_NLS@ UUID_CFLAGS = @UUID_CFLAGS@ UUID_LIBS = @UUID_LIBS@ +VAPIGEN = @VAPIGEN@ +VAPIGEN_MAKEFILE = @VAPIGEN_MAKEFILE@ +VAPIGEN_VAPIDIR = @VAPIGEN_VAPIDIR@ VERSION = @VERSION@ XGETTEXT = @XGETTEXT@ XGETTEXT_015 = @XGETTEXT_015@ @@ -300,6 +307,8 @@ htmldir = @htmldir@ includedir = @includedir@ infodir = @infodir@ install_sh = @install_sh@ +intltool__v_merge_options_ = @intltool__v_merge_options_@ +intltool__v_merge_options_0 = @intltool__v_merge_options_0@ libdir = @libdir@ libexecdir = @libexecdir@ localedir = @localedir@ diff --git a/man/nmcli.1 b/man/nmcli.1 index 03ed664c..bd84edb7 100644 --- a/man/nmcli.1 +++ b/man/nmcli.1 @@ -20,12 +20,12 @@ .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. .\" -.\" Copyright (C) 2010 - 2011 Red Hat, Inc. +.\" Copyright (C) 2010 - 2012 Red Hat, Inc. .\" -.TH NMCLI "1" "6 September 2011" +.TH NMCLI "1" "29 May 2012" .SH NAME -nmcli \- command-line tool for controlling NetworkManager +nmcli \(en command\(hyline tool for controlling NetworkManager .SH SYNOPSIS .ad l .B nmcli @@ -57,26 +57,26 @@ nmcli \- command-line tool for controlling NetworkManager .SH DESCRIPTION .B nmcli -is a command-line tool for controlling NetworkManager and getting its status. -It is not meant as a replacement of \fInm-applet\fP or other similar clients. -Rather it's a complementary utility to these programs. -The main \fInmcli\fP's usage is on servers, headless machines or just for -power users who prefer the command line. +is a command\(hyline tool for controlling NetworkManager and reporting on its status. +It is not meant as a full replacement for \fInm\(hyapplet\fP or other similar clients +but as a complementary utility to those programs. +The main usage for \fInmcli\fP is on servers, headless machines or for power users +who prefer the command line. .P -The use cases comprise: +Typical applications include: .IP \(em 4 Initscripts: ifup/ifdown can utilize NetworkManager via \fInmcli\fP instead of having to manage connections itself and possibly interfere with NetworkManager. .IP \(em 4 Servers, headless machines: No GUI is available; then \fInmcli\fP can be used to activate/deactivate connections. However, if a connection requires a secret -to activate and if that secret is not stored at the system level, \fInmcli\fP -will not be able to activate it; it is currently unable to supply the needed -secrets to NetworkManager. +in order to activate and if that secret is not stored at the system level, +\fInmcli\fP will not be able to activate it; it is currently unable to supply +the secrets to NetworkManager. .IP \(em 4 -User sessions: \fInmcli\fP can be used activate/deactivate connections from the -command line, but a full NetworkManager client (like \fInm-applet\fP) is used -for supplying secrets not stored at the system level. Keyring dialogs and +User sessions: \fInmcli\fP can be used to activate/deactivate connections from +the command line, but a client with a secret agent (like \fInm\(hyapplet\fP) is needed +for supplying secrets not stored at the system level. Keyring dialogs and password prompts may appear if this happens. .SS \fIOPTIONS\fP .TP @@ -85,12 +85,12 @@ 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 easy readable outputs +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 +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. Currenly, they are: .br @@ -98,21 +98,21 @@ line, default is \fImultiline\fP. Currenly, they are: 'nmcli con list id|uuid <name>' 'nmcli dev list' .fi -\fItabular\fP - Output is a table where each line describes a single entry. +\fItabular\fP \(en Output is a table where each line describes a single entry. Columns define particular properties of the entry. .br -\fImultiline\fP - Each entry comprises more lines, each property on its own line. -The values are prefixed with the property name. +\fImultiline\fP \(en Each entry comprises multiple lines, each property on its own +line. The values are prefixed with the property name. .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. +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 +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 @@ -133,28 +133,41 @@ NetworkManager .br Use this object to inquire and change state of NetworkManager. .TP -.SS \fICOMMAND\fP := { status | enable | sleep | wifi | wwan } +.SS \fICOMMAND\fP := { status | permissions | enable | sleep | wifi | wwan | wimax } .sp .RS .TP .B status .br -Show overall status of NetworkManager. This is the default action, when no +Show overall status of NetworkManager. This is the default action, when no command is provided to \fInm\fP object. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP +.B permissions +.br +Show the permissions a caller has for various authenticated operations that +NetworkManager provides, like enable/disable networking, changing Wi\(hyFi, WWAN, +and WiMAX state, modifying connections, etc. +.br +.nf +\fBReference to D\(hyBus:\fP +interface: org.freedesktop.NetworkManager +method: GetPermissions +arguments: none +.fi +.TP .B enable [true|false] .br -Get networking-enabled status or enable/disable networking by NetworkManager. +Get networking\(hyenabled status or enable/disable networking by NetworkManager. All interfaces managed by NetworkManager are deactivated when networking has been disabled. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: Enable arguments: TRUE or FALSE @@ -162,13 +175,14 @@ arguments: TRUE or FALSE .TP .B sleep [true|false] .br -Get sleep status or put to sleep/awake NetworkManager. All interfaces managed by NetworkManager -are deactivated when it falls asleep. This command is not meant for user to enable/disable -networking, use \fIenable\fP for that. D-Bus \fISleep\fP method is designed -to put NetworkManager to sleep or awake for suspending/resuming computer. +Get sleep status or put to sleep/awake NetworkManager. All interfaces managed +by NetworkManager are deactivated when it falls asleep. This command is not +meant for user to enable/disable networking, use \fIenable\fP for that. D\(hyBus +\fISleep\fP method is designed to put NetworkManager to sleep or awake for +suspending/resuming the computer. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: Sleep arguments: TRUE or FALSE @@ -176,21 +190,33 @@ arguments: TRUE or FALSE .TP .B wifi [on|off] .br -Inquire or set status of WiFi in NetworkManager. Without any further argument, -WiFi status is printed; \fIon\fP enables WiFi; \fIoff\fP disables WiFi. +Inquire 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. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B wwan [on|off] .br -Inquire or set status of WWAN in NetworkManager. Without any further argument, +Inquire or set status of WWAN in NetworkManager. If no arguments are supplied, WWAN status is printed; \fIon\fP enables WWAN; \fIoff\fP disables WWAN. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP +No simple reference. +.fi +.TP +.B wimax [on|off] +.br +Inquire or set status of WiMAX in NetworkManager. If no arguments are supplied, +WiMAX status is printed; \fIon\fP enables WiMAX; \fIoff\fP disables WiMAX. +.br +Note: WiMAX support is a compile\(hytime decision, so it may be unavailable on some +installations. +.nf +\fBReference to D\(hyBus:\fP No simple reference. .fi .RE @@ -213,7 +239,7 @@ name or \fIuuid\fP with connection's UUID shall be specified. When no command is given to the \fIcon\fP object, the default action is 'nmcli con list'. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP @@ -222,26 +248,41 @@ No simple reference. Print status of active connections. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP -.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [\-\-nowait] [\-\-timeout <timeout>] +.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [nsp <name>] [\-\-nowait] [\-\-timeout <timeout>] .br Activate a connection. The connection is identified by its name using \fIid\fP -or UUID using \fIuuid\fP. For requiring particular device to activate -the connection on, \fIiface\fP option with interface name should be given. -\fIap\fP option can further concretize what AP should be used in case of WiFi -connection. \fI\-\-nowait\fP option causes \fInmcli\fP to exit immediately and -not to wait for command completion. \fI\-\-timeout\fP option provides a means -to specify how long to wait for operation completion. +or UUID using \fIuuid\fP. When requiring a particular device to activate the +connection on, the \fIiface\fP option with interface name should be given. In +case of a VPN connection, the \fIiface\fP option specify the device of the base +connection. The \fIap\fP option specify what particular AP should be used in case +of a Wi\(hyFi connection. +.RS +.PP +Available options are: +.IP \fIiface\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 \fInsp\fP 13 +\(en NSP (Network Service Provider) which the command should connect to (for WiMAX connections) +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 90 s) +.PP .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: ActivateConnection arguments: according to arguments .fi +.RE + .TP .B down id <id> | uuid <id> .br @@ -250,7 +291,7 @@ The connection is identified by its name using \fIid\fP or UUID using \fIuuid\fP. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: DeactivateConnection arguments: according to arguments @@ -258,11 +299,11 @@ arguments: according to arguments .TP .B delete id <id> | uuid <id> .br -Delete a configured connection. The connection to delete is specified with +Delete a configured connection. The connection to delete is specified with \fIid\fP (connection name) or \fIuuid\fP (connection UUID). .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager.Settings.Connection method: Delete arguments: none @@ -285,64 +326,108 @@ Print status of devices. This is the default action, when no command is specified to \fIdev\fP object. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B list [iface <iface>] .br Get detailed information about devices. Without an argument, all devices are -examined. To get information for a specific device, \fIiface\fP argument +examined. To get information for a specific device, the \fIiface\fP argument with the interface name should be provided. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B disconnect iface <iface> [\-\-nowait] [\-\-timeout <timeout>] .br Disconnect a device and prevent the device from automatically activating further -connections without user/manual intervention. \fI\-\-nowait\fP option causes -\fInmcli\fP to exit immediately and not to wait for command completion. -\fI\-\-timeout\fP option provides a means to specify how long to wait for -operation completion. +connections without user/manual intervention. +.RS +.PP +Available options are: +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 10 s) +.PP .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager.Device method: Disconnect arguments: none .fi +.RE .TP .B wifi [list [iface <iface>] [bssid <BSSID>]] .br -List available WiFi access points. \fIiface\fP and \fIbssid\fP options -can be used to get just APs for particular interface or specific AP, +List available Wi\(hyFi access points. The \fIiface\fP and \fIbssid\fP options +can be used to list APs for a particular interface or with a specific BSSID, respectively. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi +.TP +.B wifi connect <(B)SSID> [password <password>] [wep\-key\-type key|phrase] [iface <iface>] [bssid <BSSID>] [name <name>] [\-\-private] [\-\-nowait] [\-\-timeout <timeout>] +.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's better to connect through it using +\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. +.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 \fIiface\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 \fI\-\-private\fP 13 +\(en the connection will only be visible to the user who created it (else the connection is system\(hywide) +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 90 s) +.PP +.br +.nf +\fBReference to D\(hyBus:\fP +interface: org.freedesktop.NetworkManager +method: AddAndActivateConnection +arguments: according to arguments +.fi .RE .SH ENVIRONMENT VARIABLES \fInmcli\fP's behavior is affected by the following environment variables. .IP "LC_ALL" 13 -If set to a non-empty string value, override the values of all the other +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 internationalised messages. +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 -Notes about localization: +Internationalization notes: .br Be aware that \fInmcli\fP is localized and that's why the output depends on -your environment. It's important to realize that especially when you parse the +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 @@ -354,9 +439,10 @@ 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 errors occur. +\fInmcli\fP exits with status 0 if it succeeds, a value greater than 0 is +returned if an error occurs. .IP "0" 4 -Success - indicates the operation succeeded +Success \(en indicates the operation succeeded .IP "1" 4 Unknown or unspecified error .IP "2" 4 @@ -370,9 +456,70 @@ Connection deactivation failed .IP "6" 4 Disconnecting device failed +.SH EXAMPLES +.IP "\fB\f(CWnmcli \-t \-f RUNNING nm\fP\fP" +.IP +tells you whether NetworkManager is running or not. + +.IP "\fB\f(CWnmcli \-t \-f STATE nm\fP\fP" +.IP +shows the overall status of NetworkManager. + +.IP "\fB\f(CWnmcli nm wifi off\fP\fP" +.IP +switches Wi\(hyFi off. + +.IP "\fB\f(CWnmcli \-p con list\fP\fP" +.IP +lists all connections NetworkManager has. + +.IP "\fB\f(CWnmcli \-f name,autoconnect con list\fP\fP" +.IP +lists all connections' names and their autoconnect settings. + +.IP "\fB\f(CWnmcli con list id \(dq\&My wired connection\(dq\&\fP\fP" +.IP +lists all details of the connection with "My wired connection" name. + +.IP "\fB\f(CWnmcli \-p con up id \(dq\&My wired connection\(dq\& iface eth0\fP\fP" +.IP +activates the connection with name "My wired connection" on interface eth0. +The \-p option makes nmcli show progress of the activation. + +.IP "\fB\f(CWnmcli con up uuid 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 dev status\fP\fP" +.IP +shows the status for all devices. + +.IP "\fB\f(CWnmcli dev disconnect iface em2\fP\fP" +.IP +disconnects a connection on interface em2 and marks the device as unavailable for +auto\(hyconnecting. That's why no connection will automatically be activated on the +device until the device's "autoconnect" is set to TRUE or user manually activates +a connection. + +.IP "\fB\f(CWnmcli \-f GENERAL,WIFI\-PROPERTIES dev list iface wlan0\fP\fP" +.IP +lists details for wlan0 interface; only GENERAL and WIFI\-PROPERTIES sections will be shown. + +.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 "caffeine" password. 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. + .SH BUGS -There are probably some. If you find a bug, please report to -https://bugzilla.gnome.org/ \- product \fINetworkManager\fP. +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 nm\-tool (1), diff --git a/man/nmcli.1.in b/man/nmcli.1.in index 03ed664c..bd84edb7 100644 --- a/man/nmcli.1.in +++ b/man/nmcli.1.in @@ -20,12 +20,12 @@ .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, .\" USA. .\" -.\" Copyright (C) 2010 - 2011 Red Hat, Inc. +.\" Copyright (C) 2010 - 2012 Red Hat, Inc. .\" -.TH NMCLI "1" "6 September 2011" +.TH NMCLI "1" "29 May 2012" .SH NAME -nmcli \- command-line tool for controlling NetworkManager +nmcli \(en command\(hyline tool for controlling NetworkManager .SH SYNOPSIS .ad l .B nmcli @@ -57,26 +57,26 @@ nmcli \- command-line tool for controlling NetworkManager .SH DESCRIPTION .B nmcli -is a command-line tool for controlling NetworkManager and getting its status. -It is not meant as a replacement of \fInm-applet\fP or other similar clients. -Rather it's a complementary utility to these programs. -The main \fInmcli\fP's usage is on servers, headless machines or just for -power users who prefer the command line. +is a command\(hyline tool for controlling NetworkManager and reporting on its status. +It is not meant as a full replacement for \fInm\(hyapplet\fP or other similar clients +but as a complementary utility to those programs. +The main usage for \fInmcli\fP is on servers, headless machines or for power users +who prefer the command line. .P -The use cases comprise: +Typical applications include: .IP \(em 4 Initscripts: ifup/ifdown can utilize NetworkManager via \fInmcli\fP instead of having to manage connections itself and possibly interfere with NetworkManager. .IP \(em 4 Servers, headless machines: No GUI is available; then \fInmcli\fP can be used to activate/deactivate connections. However, if a connection requires a secret -to activate and if that secret is not stored at the system level, \fInmcli\fP -will not be able to activate it; it is currently unable to supply the needed -secrets to NetworkManager. +in order to activate and if that secret is not stored at the system level, +\fInmcli\fP will not be able to activate it; it is currently unable to supply +the secrets to NetworkManager. .IP \(em 4 -User sessions: \fInmcli\fP can be used activate/deactivate connections from the -command line, but a full NetworkManager client (like \fInm-applet\fP) is used -for supplying secrets not stored at the system level. Keyring dialogs and +User sessions: \fInmcli\fP can be used to activate/deactivate connections from +the command line, but a client with a secret agent (like \fInm\(hyapplet\fP) is needed +for supplying secrets not stored at the system level. Keyring dialogs and password prompts may appear if this happens. .SS \fIOPTIONS\fP .TP @@ -85,12 +85,12 @@ 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 easy readable outputs +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 +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. Currenly, they are: .br @@ -98,21 +98,21 @@ line, default is \fImultiline\fP. Currenly, they are: 'nmcli con list id|uuid <name>' 'nmcli dev list' .fi -\fItabular\fP - Output is a table where each line describes a single entry. +\fItabular\fP \(en Output is a table where each line describes a single entry. Columns define particular properties of the entry. .br -\fImultiline\fP - Each entry comprises more lines, each property on its own line. -The values are prefixed with the property name. +\fImultiline\fP \(en Each entry comprises multiple lines, each property on its own +line. The values are prefixed with the property name. .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. +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 +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 @@ -133,28 +133,41 @@ NetworkManager .br Use this object to inquire and change state of NetworkManager. .TP -.SS \fICOMMAND\fP := { status | enable | sleep | wifi | wwan } +.SS \fICOMMAND\fP := { status | permissions | enable | sleep | wifi | wwan | wimax } .sp .RS .TP .B status .br -Show overall status of NetworkManager. This is the default action, when no +Show overall status of NetworkManager. This is the default action, when no command is provided to \fInm\fP object. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP +.B permissions +.br +Show the permissions a caller has for various authenticated operations that +NetworkManager provides, like enable/disable networking, changing Wi\(hyFi, WWAN, +and WiMAX state, modifying connections, etc. +.br +.nf +\fBReference to D\(hyBus:\fP +interface: org.freedesktop.NetworkManager +method: GetPermissions +arguments: none +.fi +.TP .B enable [true|false] .br -Get networking-enabled status or enable/disable networking by NetworkManager. +Get networking\(hyenabled status or enable/disable networking by NetworkManager. All interfaces managed by NetworkManager are deactivated when networking has been disabled. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: Enable arguments: TRUE or FALSE @@ -162,13 +175,14 @@ arguments: TRUE or FALSE .TP .B sleep [true|false] .br -Get sleep status or put to sleep/awake NetworkManager. All interfaces managed by NetworkManager -are deactivated when it falls asleep. This command is not meant for user to enable/disable -networking, use \fIenable\fP for that. D-Bus \fISleep\fP method is designed -to put NetworkManager to sleep or awake for suspending/resuming computer. +Get sleep status or put to sleep/awake NetworkManager. All interfaces managed +by NetworkManager are deactivated when it falls asleep. This command is not +meant for user to enable/disable networking, use \fIenable\fP for that. D\(hyBus +\fISleep\fP method is designed to put NetworkManager to sleep or awake for +suspending/resuming the computer. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: Sleep arguments: TRUE or FALSE @@ -176,21 +190,33 @@ arguments: TRUE or FALSE .TP .B wifi [on|off] .br -Inquire or set status of WiFi in NetworkManager. Without any further argument, -WiFi status is printed; \fIon\fP enables WiFi; \fIoff\fP disables WiFi. +Inquire 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. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B wwan [on|off] .br -Inquire or set status of WWAN in NetworkManager. Without any further argument, +Inquire or set status of WWAN in NetworkManager. If no arguments are supplied, WWAN status is printed; \fIon\fP enables WWAN; \fIoff\fP disables WWAN. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP +No simple reference. +.fi +.TP +.B wimax [on|off] +.br +Inquire or set status of WiMAX in NetworkManager. If no arguments are supplied, +WiMAX status is printed; \fIon\fP enables WiMAX; \fIoff\fP disables WiMAX. +.br +Note: WiMAX support is a compile\(hytime decision, so it may be unavailable on some +installations. +.nf +\fBReference to D\(hyBus:\fP No simple reference. .fi .RE @@ -213,7 +239,7 @@ name or \fIuuid\fP with connection's UUID shall be specified. When no command is given to the \fIcon\fP object, the default action is 'nmcli con list'. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP @@ -222,26 +248,41 @@ No simple reference. Print status of active connections. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP -.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [\-\-nowait] [\-\-timeout <timeout>] +.B up id <id> | uuid <id> [iface <iface>] [ap <BSSID>] [nsp <name>] [\-\-nowait] [\-\-timeout <timeout>] .br Activate a connection. The connection is identified by its name using \fIid\fP -or UUID using \fIuuid\fP. For requiring particular device to activate -the connection on, \fIiface\fP option with interface name should be given. -\fIap\fP option can further concretize what AP should be used in case of WiFi -connection. \fI\-\-nowait\fP option causes \fInmcli\fP to exit immediately and -not to wait for command completion. \fI\-\-timeout\fP option provides a means -to specify how long to wait for operation completion. +or UUID using \fIuuid\fP. When requiring a particular device to activate the +connection on, the \fIiface\fP option with interface name should be given. In +case of a VPN connection, the \fIiface\fP option specify the device of the base +connection. The \fIap\fP option specify what particular AP should be used in case +of a Wi\(hyFi connection. +.RS +.PP +Available options are: +.IP \fIiface\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 \fInsp\fP 13 +\(en NSP (Network Service Provider) which the command should connect to (for WiMAX connections) +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 90 s) +.PP .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: ActivateConnection arguments: according to arguments .fi +.RE + .TP .B down id <id> | uuid <id> .br @@ -250,7 +291,7 @@ The connection is identified by its name using \fIid\fP or UUID using \fIuuid\fP. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager method: DeactivateConnection arguments: according to arguments @@ -258,11 +299,11 @@ arguments: according to arguments .TP .B delete id <id> | uuid <id> .br -Delete a configured connection. The connection to delete is specified with +Delete a configured connection. The connection to delete is specified with \fIid\fP (connection name) or \fIuuid\fP (connection UUID). .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager.Settings.Connection method: Delete arguments: none @@ -285,64 +326,108 @@ Print status of devices. This is the default action, when no command is specified to \fIdev\fP object. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B list [iface <iface>] .br Get detailed information about devices. Without an argument, all devices are -examined. To get information for a specific device, \fIiface\fP argument +examined. To get information for a specific device, the \fIiface\fP argument with the interface name should be provided. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi .TP .B disconnect iface <iface> [\-\-nowait] [\-\-timeout <timeout>] .br Disconnect a device and prevent the device from automatically activating further -connections without user/manual intervention. \fI\-\-nowait\fP option causes -\fInmcli\fP to exit immediately and not to wait for command completion. -\fI\-\-timeout\fP option provides a means to specify how long to wait for -operation completion. +connections without user/manual intervention. +.RS +.PP +Available options are: +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 10 s) +.PP .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP interface: org.freedesktop.NetworkManager.Device method: Disconnect arguments: none .fi +.RE .TP .B wifi [list [iface <iface>] [bssid <BSSID>]] .br -List available WiFi access points. \fIiface\fP and \fIbssid\fP options -can be used to get just APs for particular interface or specific AP, +List available Wi\(hyFi access points. The \fIiface\fP and \fIbssid\fP options +can be used to list APs for a particular interface or with a specific BSSID, respectively. .br .nf -\fBReference to D-Bus:\fP +\fBReference to D\(hyBus:\fP No simple reference. .fi +.TP +.B wifi connect <(B)SSID> [password <password>] [wep\-key\-type key|phrase] [iface <iface>] [bssid <BSSID>] [name <name>] [\-\-private] [\-\-nowait] [\-\-timeout <timeout>] +.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's better to connect through it using +\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. +.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 \fIiface\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 \fI\-\-private\fP 13 +\(en the connection will only be visible to the user who created it (else the connection is system\(hywide) +.IP \fI\-\-nowait\fP 13 +\(en exit immediately without waiting for command completion +.IP \fI\-\-timeout\fP 13 +\(en how long to wait for command completion (default is 90 s) +.PP +.br +.nf +\fBReference to D\(hyBus:\fP +interface: org.freedesktop.NetworkManager +method: AddAndActivateConnection +arguments: according to arguments +.fi .RE .SH ENVIRONMENT VARIABLES \fInmcli\fP's behavior is affected by the following environment variables. .IP "LC_ALL" 13 -If set to a non-empty string value, override the values of all the other +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 internationalised messages. +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 -Notes about localization: +Internationalization notes: .br Be aware that \fInmcli\fP is localized and that's why the output depends on -your environment. It's important to realize that especially when you parse the +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 @@ -354,9 +439,10 @@ 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 errors occur. +\fInmcli\fP exits with status 0 if it succeeds, a value greater than 0 is +returned if an error occurs. .IP "0" 4 -Success - indicates the operation succeeded +Success \(en indicates the operation succeeded .IP "1" 4 Unknown or unspecified error .IP "2" 4 @@ -370,9 +456,70 @@ Connection deactivation failed .IP "6" 4 Disconnecting device failed +.SH EXAMPLES +.IP "\fB\f(CWnmcli \-t \-f RUNNING nm\fP\fP" +.IP +tells you whether NetworkManager is running or not. + +.IP "\fB\f(CWnmcli \-t \-f STATE nm\fP\fP" +.IP +shows the overall status of NetworkManager. + +.IP "\fB\f(CWnmcli nm wifi off\fP\fP" +.IP +switches Wi\(hyFi off. + +.IP "\fB\f(CWnmcli \-p con list\fP\fP" +.IP +lists all connections NetworkManager has. + +.IP "\fB\f(CWnmcli \-f name,autoconnect con list\fP\fP" +.IP +lists all connections' names and their autoconnect settings. + +.IP "\fB\f(CWnmcli con list id \(dq\&My wired connection\(dq\&\fP\fP" +.IP +lists all details of the connection with "My wired connection" name. + +.IP "\fB\f(CWnmcli \-p con up id \(dq\&My wired connection\(dq\& iface eth0\fP\fP" +.IP +activates the connection with name "My wired connection" on interface eth0. +The \-p option makes nmcli show progress of the activation. + +.IP "\fB\f(CWnmcli con up uuid 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 dev status\fP\fP" +.IP +shows the status for all devices. + +.IP "\fB\f(CWnmcli dev disconnect iface em2\fP\fP" +.IP +disconnects a connection on interface em2 and marks the device as unavailable for +auto\(hyconnecting. That's why no connection will automatically be activated on the +device until the device's "autoconnect" is set to TRUE or user manually activates +a connection. + +.IP "\fB\f(CWnmcli \-f GENERAL,WIFI\-PROPERTIES dev list iface wlan0\fP\fP" +.IP +lists details for wlan0 interface; only GENERAL and WIFI\-PROPERTIES sections will be shown. + +.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 "caffeine" password. 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. + .SH BUGS -There are probably some. If you find a bug, please report to -https://bugzilla.gnome.org/ \- product \fINetworkManager\fP. +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 nm\-tool (1), |