From 34465bdb2685ae1d9ec56208e5122e068c07a780 Mon Sep 17 00:00:00 2001 From: Mirek Jahoda Date: Tue, 10 Jul 2018 17:58:38 +0200 Subject: [PATCH] Configuring IP networking with nmcli (igkioka) --- .../configuring-ip-networking-with-nmcli.adoc | 12 + .../con_Getting-started-with-nmcli.adoc | 122 ++++++++++ .../con_Understanding-the-nmcli-options.adoc | 65 ++++++ ...roc_Brief-selection-of-nmcli-examples.adoc | 108 +++++++++ ...ref_Configuring-networking-with-nmcli.adoc | 214 ++++++++++++++++++ 5 files changed, 521 insertions(+) create mode 100644 en-US/configuring-ip-networking-with-nmcli.adoc create mode 100644 en-US/modules/con_Getting-started-with-nmcli.adoc create mode 100644 en-US/modules/con_Understanding-the-nmcli-options.adoc create mode 100644 en-US/modules/proc_Brief-selection-of-nmcli-examples.adoc create mode 100644 en-US/modules/ref_Configuring-networking-with-nmcli.adoc diff --git a/en-US/configuring-ip-networking-with-nmcli.adoc b/en-US/configuring-ip-networking-with-nmcli.adoc new file mode 100644 index 0000000..4738e11 --- /dev/null +++ b/en-US/configuring-ip-networking-with-nmcli.adoc @@ -0,0 +1,12 @@ +[id='Configuring-networking-with-nmcli'] += Configuring networking with nmcli + +How to configure networking using the [application]*nmcli* (NetworkManager Command Line Interface) command-line utility. + +include::modules/con_Getting-started-with-nmcli.adoc[leveloffset=+1] + +include::modules/proc_Brief-selection-of-nmcli-examples.adoc[leveloffset=+1] + +include::modules/con_Understanding-the-nmcli-options.adoc[leveloffset=+1] + +include::modules/proc_Configuring-networking-with-nmcli.adoc[leveloffset=+1] diff --git a/en-US/modules/con_Getting-started-with-nmcli.adoc b/en-US/modules/con_Getting-started-with-nmcli.adoc new file mode 100644 index 0000000..036c92c --- /dev/null +++ b/en-US/modules/con_Getting-started-with-nmcli.adoc @@ -0,0 +1,122 @@ +// Module included in the following assemblies: +// +// assembly_Configuring-networking-with-nmcli.adoc + +[id='Getting-started-with-nmcli'] += Getting started with nmcli + +The [application]*nmcli* (NetworkManager Command Line Interface) command-line utility is used for controlling NetworkManager and reporting network status. It can be utilized as a replacement for [application]*nm-applet* or other graphical clients. [application]*nmcli* is used to create, display, edit, delete, activate, and deactivate network connections, as well as control and display network device status. + +The [application]*nmcli* utility can be used by both users and scripts for controlling [application]*NetworkManager*: + +* For servers, headless machines, and terminals, [application]*nmcli* can be used to control [application]*NetworkManager* directly, without GUI, including creating, editing, starting and stopping network connections and viewing network status. + +* For scripts, [application]*nmcli* supports a terse output format which is better suited for script processing. It is a way to integrate network configuration instead of managing network connections manually. + +The basic format of a [application]*nmcli* command is as follows: + +[literal,subs="+quotes,verbatim"] +.... +nmcli [OPTIONS] OBJECT { COMMAND | help } +.... + +where OBJECT can be one of the following options: `general`, `networking`, `radio`, `connection`, `device`, `agent`, and `monitor`. You can use any prefix of these options in your commands. For example, [command]`nmcli con help`, [command]`nmcli c help`, [command]`nmcli connection help` generate the same output. + +Some of useful optional OPTIONS to get started are: + +-t, terse:: ++ +This mode can be used for computer script processing as you can see a terse output displaying only the values. ++ +[[ex-Viewing_a_terse_output_for_scripts]] +.Viewing a terse output +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli -t device` +ens3:ethernet:connected:Profile 1 +lo:loopback:unmanaged: + +.... + +==== + +-f, field:: ++ +This option specifies what fields can be displayed in output. For example, NAME,UUID,TYPE,AUTOCONNECT,ACTIVE,DEVICE,STATE. You can use one or more fields. If you want to use more, do not use space after comma to separate the fields. ++ +[[ex-Specifying_Fields_in_the_output]] +.Specifying Fields in the output +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli -f DEVICE,TYPE device` +DEVICE TYPE +ens3 ethernet +lo loopback +.... + +or even better for scripting: + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli -t -f DEVICE,TYPE device` +ens3:ethernet +lo:loopback + +.... + +==== + +-p, pretty:: ++ +This option causes [application]*nmcli* to produce human-readable output. For example, values are aligned and headers are printed. ++ +[[ex-Viewing_an_output_in_pretty_Mode]] +.Viewing an output in pretty mode +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli -p device` +===================== + Status of devices +===================== +DEVICE TYPE STATE CONNECTION +-------------------------------------------------------------- +ens3 ethernet connected Profile 1 +lo loopback unmanaged -- + +.... + +==== + +-h, help:: ++ +Prints help information. + +The [application]*nmcli* tool has some built-in context-sensitive help. To list the available options and object names: +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ [command]`nmcli help` +.... + +To list available actions related to a specified object: +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ [command]`nmcli _object_ help` +.... + +For example, +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ [command]`nmcli c help` +.... + +[discrete] +== Additional resources +* link:++https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/networking_guide/sec-introduction_to_networkmanager++[Introduction to NetworkManager] + +* link:++https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/networking_guide/sec-installing_networkmanager#sec-Interacting_with_NetworkManager[Interacting with NetworkManager] diff --git a/en-US/modules/con_Understanding-the-nmcli-options.adoc b/en-US/modules/con_Understanding-the-nmcli-options.adoc new file mode 100644 index 0000000..0fbd953 --- /dev/null +++ b/en-US/modules/con_Understanding-the-nmcli-options.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// assembly_Configuring-networking-with-nmcli.adoc + +[id='Understanding-the-nmcli-options'] += The nmcli options + +Following are some of the important [application]*nmcli* property options: + + +[option]`connection.type`:: ++ +A connection type. Allowed values are: adsl, bond, bond-slave, bridge, bridge-slave, bluetooth, cdma, ethernet, gsm, infiniband, olpc-mesh, team, team-slave, vlan, wifi, wimax. Each connection type has type-specific command options. For example: ++ +** A `gsm` connection requires the access point name specified in an [option]`apn`. ++ +[literal,subs="+quotes,verbatim,macros"] +.... +nmcli c add connection.type gsm apn pass:quotes[_access_point_name_] +.... ++ +** A `wifi` device requires the service set identifier specified in a [option]`ssid`. ++ +[literal,subs="+quotes,verbatim,macros"] +.... +nmcli c add connection.type wifi ssid +_My identifier_ +.... + +You can see the `TYPE_SPECIFIC_OPTIONS` list in the [citetitle]_pass:attributes[{blank}]*nmcli*(1)_ man page. + +[option]`connection.interface-name`:: ++ +A device name relevant for the connection. ++ +[literal,subs="+quotes,verbatim,macros"] +.... +nmcli con add connection.interface-name _eth0_ type _ethernet_ +.... + +[option]`connection.id`:: ++ +A name used for the connection profile. If you do not specify a connection name, one will be generated as follows: ++ +[literal,subs="+quotes,verbatim,macros"] +.... +_connection.type -connection.interface-name_ +.... ++ +The [option]`connection.id` is the name of a _connection profile_ and should not be confused with the interface name which denotes a device (`wlan0`, `ens3`, `em1`). However, users can name the connections after interfaces, but they are not the same thing. There can be multiple connection profiles available for a device. This is particularly useful for mobile devices or when switching a network cable back and forth between different devices. Rather than edit the configuration, create different profiles and apply them to the interface as needed. The [option]`id` option also refers to the connection profile name. + +The most important options for [application]*nmcli* commands such as `show`, `up`, `down` are: + +[option]`id`:: ++ +An identification string assigned by the user to a connection profile. Id can be used in nmcli connection commands to identify a connection. The NAME field in the command output always denotes the connection id. It refers to the same connection profile name that the con-name does. + +[option]`uuid`:: ++ +A unique identification string assigned by the system to a connection profile. The `uuid` can be used in [command]`nmcli connection` commands to identify a connection. + +[discrete] +== Additional resources + +* See the comprehensive list in the [citetitle]_pass:attributes[{blank}]*nmcli*(1)_ man page. diff --git a/en-US/modules/proc_Brief-selection-of-nmcli-examples.adoc b/en-US/modules/proc_Brief-selection-of-nmcli-examples.adoc new file mode 100644 index 0000000..1136d22 --- /dev/null +++ b/en-US/modules/proc_Brief-selection-of-nmcli-examples.adoc @@ -0,0 +1,108 @@ +// Module included in the following assemblies: +// +// assembly_Configuring-networking-with-nmcli.adoc + +[id='Brief-selection-of-nmcli-examples'] += Brief Selection of nmcli Examples + +This section provides a brief selection of [application]*nmcli* examples. + +[discrete] +== Prerequisites +<> + + +.Checking the overall status of NetworkManager +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli general status` +STATE CONNECTIVITY WIFI-HW WIFI WWAN-HW WWAN +connected full enabled enabled enabled enabled +.... + +In terse mode: + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli -t -f STATE general` +connected +.... + +==== + +.Viewing NetworkManager logging status +==== + +[literal,subs="+quotes,verbatim"] +.... +~]$ [command]`nmcli general logging` + LEVEL DOMAINS + INFO PLATFORM,RFKILL,ETHER,WIFI,BT,MB,DHCP4,DHCP6,PPP,WIFI_SCAN,IP4,IP6,A +UTOIP4,DNS,VPN,SHARING,SUPPLICANT,AGENTS,SETTINGS,SUSPEND,CORE,DEVICE,OLPC, +WIMAX,INFINIBAND,FIREWALL,ADSL,BOND,VLAN,BRIDGE,DBUS_PROPS,TEAM,CONCHECK,DC +B,DISPATCH +.... + +==== + +.Viewing all connections +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli connection show` + NAME UUID TYPE DEVICE +Profile 1 db1060e9-c164-476f-b2b5-caec62dc1b05 ethernet ens3 +ens3 aaf6eb56-73e5-4746-9037-eed42caa8a65 ethernet -- +.... + +==== + +.Viewing only currently active connections +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli connection show --active` + NAME UUID TYPE DEVICE +Profile 1 db1060e9-c164-476f-b2b5-caec62dc1b05 ethernet ens3 +.... + +==== + +.Viewing only devices recognized by [application]*NetworkManager* and their state +==== + +[literal,subs="+quotes,verbatim,macros"] +.... +~]$ pass:attributes[{blank}][command]`nmcli device status` +DEVICE TYPE STATE CONNECTION +ens3 ethernet connected Profile 1 +lo loopback unmanaged -- +.... + +==== + +You can also use the following abbreviations of the [application]*nmcli* commands: + +[[tabl-nmcli_examples]] +.Abbreviations of some nmcli commands + +[options="header"] +|=== +|nmcli command|abbreviation +|nmcli general status|nmcli g +|nmcli general logging|nmcli g log +|nmcli connection show|nmcli con show +|nmcli connection show --active|nmcli con show -a +|nmcli device status|nmcli dev +|=== + +[discrete] +== Additional resources + +* For more examples, see the +[citetitle]_pass:attributes[{blank}]*nmcli-examples*(5)_ +man page. diff --git a/en-US/modules/ref_Configuring-networking-with-nmcli.adoc b/en-US/modules/ref_Configuring-networking-with-nmcli.adoc new file mode 100644 index 0000000..0c1a859 --- /dev/null +++ b/en-US/modules/ref_Configuring-networking-with-nmcli.adoc @@ -0,0 +1,214 @@ +[id='Configuring-networking-with-nmcli'] += Configuring networking with nmcli - quick reference + +[[networkmanager-status]] +== NetworkManager status + +Display overall status of NetworkManager: +---- +$ nmcli general status +---- + +Display active connections: +---- +$ nmcli connection show --active +---- + +Display all configured connections: +---- +$ nmcli connection show configured +---- + +[[connectdisconnect-to-an-already-configured-connection]] +== Connect/disconnect to an already configured connection + +Connect to a configured connection by name: +---- +$ nmcli connection up id +---- + +Disconnection by name: +---- +$ nmcli connection down id +---- + +[[wi-fi]] +== Wi-Fi + +Get Wi-Fi status: +---- +$ nmcli radio wifi +---- + +Turn Wi-Fi on or off: +---- +$ nmcli radio wifi _on|off_ +---- + +List available access points (AP) to connect to: +---- +$ nmcli device wifi list +---- + +Refresh the previous list: +---- +$ nmcli device wifi rescan +---- + +Create a new connection to an open AP: +---- +$ nmcli device wifi connect +---- + +Create a new connection to a password protected AP: +---- +$ nmcli device wifi connect password +---- + + +== Network interfaces + +List available devices and their status: +---- +$ nmcli device status +---- + +Disconnect an interface: +---- +$ nmcli device disconnect iface +---- + +[[create-or-modify-a-connection]] +== Create or modify a connection + +To create a new connection using an interactive editor +---- +$ nmcli connection edit con-name +---- + +To edit an already existing connection using an interactive editor: +---- +$ nmcli connection edit +---- + +[[exampletutorial]] +=== Example/Tutorial + +Create a new connection: +---- +$ nmcli connection edit con-name _name of new connection_ +---- + +It asks us to define a connection type: +---- +Valid connection types: 802-3-ethernet (ethernet), 802-11-wireless (wifi), wimax, gsm, cdma, infiniband, adsl, bluetooth, vpn, 802-11-olpc-mesh (olpc-mesh), vlan, bond, team, bridge, bond-slave, team-slave, bridge-slave +Enter connection type: +---- + +In this example, we use ethernet: +---- +Enter connection type: ethernet +---- + +The following message appears, note that `nmcli>` is a prompt and that it lists the main settings available: +---- +===| nmcli interactive connection editor |=== + +Adding a new '802-3-ethernet' connection + +Type 'help' or '?' for available commands. +Type 'describe [.]' for detailed property description. + +You may edit the following settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6 +nmcli> +---- + +Edit the setting `ipv4`: +---- +nmcli> goto ipv4 +---- + +Note that after this our prompt has changed to indicate that we are currently editing the `ipv4` setting: +---- +nmcli ipv4> +---- + +List available properties under the `ipv4` setting and describe the `method` property: +---- +nmcli ipv4> describe + +Available properties: method, dns, dns-search, addresses, routes, ignore-auto-routes, ignore-auto-dns, dhcp-client-id, dhcp-send-hostname, dhcp-hostname, never-default, may-fail +Property name? + +Property name? method +---- + +Set property `method` to `auto`: +---- +nmcli ipv4> set method auto +---- + +The `ipv4` setting is now finished. Go back to the main level. Enter the following command until the prompt looks like `nmcli>`: +---- +nmcli ipv4> back +---- + +To list the main settings again, use the `goto` command without any arguments. After that, press `Enter` and ignore the error. +---- +nmcli> goto + +Available settings: connection, 802-3-ethernet (ethernet), 802-1x, ipv4, ipv6 +Setting name? +---- + +It is possible to set a value for a property directly from the main level: +---- +nmcli> set __setting__.__property__ _value_ +---- + +For example: +---- +nmcli> set connection.autoconnect TRUE + +nmcli> set connection.interface-name _interface name this connection is bound to_ + +nmcli> set ethernet.cloned-mac-address _Spoofed MAC address_ +---- + +Finally, check the connection details, save and exit: +---- +nmcli> print + +nmcli> save + +nmcli> quit +---- + +[[manually-editing]] +=== Manually editing + +To manually edit an `ifcfg` connection configuration, open or create with a text editor the configuration file of the connection located in `/etc/sysconfig/network-scripts/ifcfg-`. + +A description of most common configuration options is available in the link:http://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s1-networkscripts-interfaces.html[RHEL6 Deployment Guide]. + +To modify a connection password, open with a text editor and edit the file `keys-` located in `/etc/sysconfig/network-scripts/`. The password is stored in plain text. For example: +---- +$ cat /etc/sysconfig/network-scripts/keys-__connection name__ +WPA_PSK='password' +---- + +Or, if using keyfile, simply edit the connection file located inside `/etc/NetworkManager/system-connections/` + +Finally, save the files and to apply changes to an already active connection execute. +---- +nmcli connection up id _connection name_ +---- + +[[delete-a-connection-configuration]] +== Delete a connection configuration + +Delete the connection: +---- +nmcli connection delete id +---- +Please note that this also deactivates the connection.