533 lines
16 KiB
Groff
533 lines
16 KiB
Groff
.\" 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 (C) 2010 - 2012 Red Hat, Inc.
|
|
.\"
|
|
.TH NMCLI "1" "26 July 2012"
|
|
|
|
.SH NAME
|
|
nmcli \(en command\(hyline tool for controlling NetworkManager
|
|
.SH SYNOPSIS
|
|
.ad l
|
|
.B nmcli
|
|
.RI " [ " OPTIONS " ] " OBJECT " { " COMMAND " | "
|
|
.BR help " } "
|
|
.sp
|
|
|
|
.IR OBJECT " := { "
|
|
.BR nm " | " con " | " dev " } "
|
|
.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\-f\fR[\fIields\fR] <field1,field2,...> | all | common
|
|
.br
|
|
\fB\-e\fR[\fIscape\fR] yes | no
|
|
.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 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
|
|
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
|
|
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 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
|
|
.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. Currenly, they are:
|
|
.br
|
|
.nf
|
|
'nmcli con list id|uuid <name>'
|
|
'nmcli dev list'
|
|
.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 \-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 \-v, \-\-version
|
|
Show \fInmcli\fP version.
|
|
.TP
|
|
.B \-h, \-\-help
|
|
Print help information.
|
|
.SS \fIOBJECT\fP
|
|
.TP
|
|
.B nm
|
|
NetworkManager
|
|
.br
|
|
Use this object to inquire and change state of NetworkManager.
|
|
.TP
|
|
.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
|
|
command is provided to \fInm\fP object.
|
|
.br
|
|
.nf
|
|
\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\(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\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager
|
|
method: Enable
|
|
arguments: TRUE or FALSE
|
|
.fi
|
|
.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\(hyBus
|
|
\fISleep\fP method is designed to put NetworkManager to sleep or awake for
|
|
suspending/resuming the computer.
|
|
.br
|
|
.nf
|
|
\fBReference to D\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager
|
|
method: Sleep
|
|
arguments: TRUE or FALSE
|
|
.fi
|
|
.TP
|
|
.B wifi [on|off]
|
|
.br
|
|
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\(hyBus:\fP
|
|
No simple reference.
|
|
.fi
|
|
.TP
|
|
.B wwan [on|off]
|
|
.br
|
|
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\(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
|
|
|
|
.TP
|
|
.B con
|
|
Connections
|
|
.br
|
|
Get information about NetworkManager's connections.
|
|
.TP
|
|
.SS \fICOMMAND\fP := { list | status | up | down | delete }
|
|
.sp
|
|
.RS
|
|
.TP
|
|
.B list [id <id> | uuid <id>]
|
|
.br
|
|
List configured connections. Without a parameter, all connections
|
|
are listed. In order to get connection details, \fIid\fP with connection's
|
|
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\(hyBus:\fP
|
|
No simple reference.
|
|
.fi
|
|
.TP
|
|
.B status
|
|
.br
|
|
Print status of active connections.
|
|
.br
|
|
.nf
|
|
\fBReference to D\(hyBus:\fP
|
|
No simple reference.
|
|
.fi
|
|
.TP
|
|
.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. 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\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager
|
|
method: ActivateConnection
|
|
arguments: according to arguments
|
|
.fi
|
|
.RE
|
|
|
|
.TP
|
|
.B down id <id> | uuid <id>
|
|
.br
|
|
Deactivate a connection.
|
|
The connection is identified by its name using \fIid\fP
|
|
or UUID using \fIuuid\fP.
|
|
.br
|
|
.nf
|
|
\fBReference to D\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager
|
|
method: DeactivateConnection
|
|
arguments: according to arguments
|
|
.fi
|
|
.TP
|
|
.B delete id <id> | uuid <id>
|
|
.br
|
|
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\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager.Settings.Connection
|
|
method: Delete
|
|
arguments: none
|
|
.fi
|
|
.RE
|
|
|
|
.TP
|
|
.B dev
|
|
Devices
|
|
.br
|
|
Get information about devices.
|
|
.TP
|
|
.SS \fICOMMAND\fP := { status | list | disconnect | wifi }
|
|
.sp
|
|
.RS
|
|
.TP
|
|
.B status
|
|
.br
|
|
Print status of devices. This is the default action, when no command
|
|
is specified to \fIdev\fP object.
|
|
.br
|
|
.nf
|
|
\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, the \fIiface\fP argument
|
|
with the interface name should be provided.
|
|
.br
|
|
.nf
|
|
\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.
|
|
.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\(hyBus:\fP
|
|
interface: org.freedesktop.NetworkManager.Device
|
|
method: Disconnect
|
|
arguments: none
|
|
.fi
|
|
.RE
|
|
.TP
|
|
.B wifi [list [iface <iface>] [bssid <BSSID>]]
|
|
.br
|
|
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\(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\(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's 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 commands with \fI\-\-timeout\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
|
|
|
|
.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 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),
|
|
.BR nm\-online (1),
|
|
.BR NetworkManager(8).
|