Merge ~kzapalowicz/snappy-hwe-snaps/+git/network-manager:feature/update-documentation into ~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager:master

Proposed by Konrad Zapałowicz
Status: Merged
Approved by: Simon Fels
Approved revision: 7f5338830414ce8dd2c8fb1cb1048c1c98115608
Merged at revision: 5f2abc005bf79be8167bd54f5f8f66331576aecc
Proposed branch: ~kzapalowicz/snappy-hwe-snaps/+git/network-manager:feature/update-documentation
Merge into: ~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager:master
Diff against target: 537 lines (+387/-33)
9 files modified
docs/configure-cellular-connections.md (+4/-4)
docs/configure-wifi-connections.md (+36/-29)
docs/edit-connections.md (+155/-0)
docs/installation.md (+3/-0)
docs/logging-messages.md (+43/-0)
docs/metadata.yaml (+8/-0)
docs/reference/snap-configuration/wifi-powersave.md (+38/-0)
docs/report-bug.md (+4/-0)
docs/routing-tables.md (+96/-0)
Reviewer Review Type Date Requested Status
Simon Fels Approve
Jim Hodapp (community) Approve
System Enablement Bot continuous-integration Approve
Alfonso Sanchez-Beato Approve
Review via email: mp+323381@code.launchpad.net

Description of the change

Update documentation and improve on the scope of what it covers.

Also fix text treated as HTML tags and not visible in browser.

To post a comment you must log in.
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
Alfonso Sanchez-Beato (alfonsosanchezbeato) wrote :

Some comments, but looks very good.

I think that it would be good also to explain how to configure dynamically logging with "nmcli g logging" command. We can add a section for that and also refer to it from the "Report a bug" section.

Revision history for this message
Simon Fels (morphis) :
review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Some comments inline below.

review: Needs Fixing
Revision history for this message
Alfonso Sanchez-Beato (alfonsosanchezbeato) :
Revision history for this message
Jim Hodapp (jhodapp) :
Revision history for this message
Alfonso Sanchez-Beato (alfonsosanchezbeato) wrote :

Thanks for the changes. I still have some comments, see below.

Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Needs Fixing (continuous-integration)
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Looking good, some changes still to make.

review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) wrote :

One more fix needed.

review: Needs Fixing
Revision history for this message
Jim Hodapp (jhodapp) wrote :

Found one more typo.

review: Needs Fixing
Revision history for this message
Alfonso Sanchez-Beato (alfonsosanchezbeato) wrote :

LGTM

review: Approve
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
Jim Hodapp (jhodapp) wrote :

LGTM!

review: Approve
Revision history for this message
Simon Fels (morphis) wrote :

LGTM, thanks for the rework!

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
diff --git a/docs/configure-cellular-connections.md b/docs/configure-cellular-connections.md
index 5f9dd3d..215f2dc 100644
--- a/docs/configure-cellular-connections.md
+++ b/docs/configure-cellular-connections.md
@@ -86,10 +86,10 @@ $ nmcli c add type gsm ifname <interface> con-name <name> apn <operator_apn>
86$ nmcli r wwan on86$ nmcli r wwan on
87```87```
8888
89where <interface> is the string listed as “primary port” in the output from 'sudo mmcli -m <N>'89where &lt;interface&gt; is the string listed as “primary port” in the output from 'sudo mmcli -m &lt;N&gt;'
90(as previously described),90(as previously described),
91<name> is an arbitrary name used to identify the connection, and <operator_apn> is91&lt;name&gt; is an arbitrary name used to identify the connection, and &lt;operator_apn&gt; is
92the APN name for your cellular data plan. Note that <interface> is usually a serial92the APN name for your cellular data plan. Note that &lt;interface&gt; is usually a serial
93port with pattern /dev/tty*, not a networking interface. The reason for ModemManager93port with pattern /dev/tty*, not a networking interface. The reason for ModemManager
94to use that instead of the networking interface is that this last one can appear/disappear94to use that instead of the networking interface is that this last one can appear/disappear
95dynamically while the ports do not if the hardware configuration remains unchanged.95dynamically while the ports do not if the hardware configuration remains unchanged.
@@ -99,7 +99,7 @@ different each time it is possible to have other ppp connections with, say, VPNs
99After executing these commands, NetworkManager will automatically try to bring up99After executing these commands, NetworkManager will automatically try to bring up
100the cellular connection whenever ModemManager reports that the modem has100the cellular connection whenever ModemManager reports that the modem has
101registered (the state of the modem can be checked with the previously introduced101registered (the state of the modem can be checked with the previously introduced
102command “sudo modem-manager.mmcli -m <N>”). When done successfully, NetworkManager102command “sudo modem-manager.mmcli -m &lt;N&gt;”). When done successfully, NetworkManager
103will create routes for the new network interface, with less priority than103will create routes for the new network interface, with less priority than
104Ethernet or WiFi interfaces. To disable the connection, we can do:104Ethernet or WiFi interfaces. To disable the connection, we can do:
105105
diff --git a/docs/configure-wifi-connections.md b/docs/configure-wifi-connections.md
index fc3a72d..1d5a7fa 100644
--- a/docs/configure-wifi-connections.md
+++ b/docs/configure-wifi-connections.md
@@ -1,10 +1,20 @@
1---1---
2title: "Configure WiFi Connections"2title: "Configure WiFi Connections"
3table_of_contents: False3table_of_contents: True
4---4---
55
6# Configure WiFi Connections6# Configure WiFi Connections
77
8This section explains how to establish a WiFi connection. It covers creating and
9modyfying connections as well as directly connecting.
10
11## Establish a Wireless Connection
12
13This section will show how to establish a wifi connection to the wireles
14network. Note that directly connecting will implicitly create a connection (that
15can be seen with "nmcli c"). The naming of such will follow "SSID N" pattern,
16where N is a number.
17
8First, determine the name of the WiFi interface:18First, determine the name of the WiFi interface:
919
10```20```
@@ -24,51 +34,48 @@ Then, list the available WiFi networks:
2434
25```35```
26$ nmcli d wifi list36$ nmcli d wifi list
27* SSID MODE CHAN RATE SIGNAL BARS SECURITY 37* SSID MODE CHAN RATE SIGNAL BARS SECURITY
28 ...38 ...
29 my_wifi Infra 5 54 Mbit/s 89 ▂▄▆█ WPA2 39 my_wifi Infra 5 54 Mbit/s 89 ▂▄▆█ WPA2
30```40```
3141
32As an example, to connect to the access point ‘my_wifi’, you would use the42As an example, to connect to the access point 'my_wifi', you would use the
33following commands:43following command:
3444
35```45```
36$ nmcli c add con-name <name> ifname wlan0 type wifi ssid my_wifi46$ nmcli d wifi connect my_wifi password <password>
37$ nmcli c modify <name> wifi-sec.key-mgmt wpa-psk wifi-sec.psk <password>
38```47```
3948
40<name> is an arbitrary name given to the connection, and <password> is the49&lt;password&gt; is the password for the connection which needs to have 8-63
41password for the connection (this last command can be used to change the50characters or 64 hexadecimal characters to specify a full 256-bit key.
42password too). The password needs to have 8-63 characters or 64 hexadecimal characters to specify a full 256-bit key. New connections have DHCP enabled51
43for both IPv4 and IPv6 by default.52## Connect to a Hidden Network
4453
45Once a connection has been created, NetworkManager will consider it for54A hidden network is a normal wireless network that simply does not broadcast
46a given connection whenever the device’s WiFi is disconnected and NetworkManager55it's SSID unless solicited. This means that its name cannot be searched and
47detects the access point is available via recent scan results.56must be known from some other source.
4857
49The autoconnect behaviour of a connection is enabled by default and can be changed58Issue the following command to create a connection associated with a hidden
50by modifying the connection’s autoconnect property:59network &lt;ssid&gt;:
5160
52```61```
53$ nmcli c modify <name> connection.autoconnect [yes|no]62$ nmcli c add type wifi con-name <name> ifname wlan0 ssid <ssid>
63$ nmcli c modify <name> wifi-sec.key-mgmt wpa-psk wifi-sec.psk <password>
54```64```
5565
56Some other interesting commands follow.66Now you can establish a connection by typing:
57
58To show the details of a connection:
5967
60```68```
61$ nmcli c show <name>69$ nmcli c up <name>
62```70```
6371
64To trigger a manual WiFi scan:72&lt;name&gt; is an arbitrary name given to the connection and &lt;password&gt;
73is the password to the network. It needs to have between 8-63 characters or 64
74hexadecimal characters in order to specify a full 256-bit key.
6575
66```76## Further Information
67$ nmcli d wifi rescan
68```
6977
70To delete a connection:78You will find further information and more detailed examples on following pages:
7179
72```80* <https://developer.gnome.org/NetworkManager/unstable/nmcli.html>
73$ nmcli c delete <name>81* <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/sec-Using_the_NetworkManager_Command_Line_Tool_nmcli.html>
74```
diff --git a/docs/edit-connections.md b/docs/edit-connections.md
75new file mode 10064482new file mode 100644
index 0000000..0c9d087
--- /dev/null
+++ b/docs/edit-connections.md
@@ -0,0 +1,155 @@
1---
2title: "Edit Connections"
3table_of_contents: True
4---
5
6# Edit Connections
7
8This part will show you how to use a network-manager built-in editor to modify
9the connections as well as provide a reference for setting some of the
10settings.
11
12## Using nmcli Console
13
14Aside from offering the possibility to manage and modify the network connections
15using the command-line, network-manager offers a built-in, interactive
16console to achieve the same. In order to use it type:
17
18```
19$ nmcli connection edit
20```
21
22It will bring up an interactive console. In the first step you will be prompted
23to enter the connection type. The list of valid connection types will be
24displayed on the screen. Once you select one you will be taken to the nmcli
25console where you have the possibility to modify its parameters.
26
27Alternatively, if you know the valid connection types, you could jump straight
28to the nmcli console by providing the type as a parameter:
29
30```
31$ nmcli connection edit type <type>
32```
33
34where &lt;type&gt; must be a valid connection type such as 'wifi'.
35
36An attempt to edit the wifi connection type would look like:
37
38```
39$ nmcli c edit
40
41Valid connection types: generic, 802-3-ethernet (ethernet), pppoe,
42802-11-wireless (wifi), wimax, gsm, cdma, infiniband, adsl, bluetooth, vpn,
43802-11-olpc-mesh (olpc-mesh), vlan, bond, team, bridge, bond-slave, team-slave,
44bridge-slave, no-slave, tun, ip-tunnel, macvlan, vxlan
45Enter connection type: wifi
46
47===| nmcli interactive connection editor |===
48
49Adding a new '802-11-wireless' connection
50
51Type 'help' or '?' for available commands.
52Type 'describe [<setting>.<prop>]' for detailed property description.
53
54You may edit the following settings: connection, 802-11-wireless (wifi),
55802-11-wireless-security (wifi-sec), 802-1x, ipv4, ipv6
56nmcli>
57```
58
59From now on it is possible to edit the wifi connection settings. The list of
60settings is provided as in the example above. The nmcli console offers a set of
61commands that can be used to navigate between settings. To get the list of
62available commands type 'help' or '?'
63
64```
65nmcli> ?
66------------------------------------------------------------------------------
67---[ Main menu ]---
68goto [<setting> | <prop>] :: go to a setting or property
69remove <setting>[.<prop>] | <prop> :: remove setting or reset property value
70set [<setting>.<prop> <value>] :: set property value
71describe [<setting>.<prop>] :: describe property
72print [all | <setting>[.<prop>]] :: print the connection
73verify [all | fix] :: verify the connection
74save [persistent|temporary] :: save the connection
75activate [<ifname>] [/<ap>|<nsp>] :: activate the connection
76back :: go one level up (back)
77help/? [<command>] :: print this help
78nmcli <conf-option> <value> :: nmcli configuration
79quit :: exit nmcli
80------------------------------------------------------------------------------
81nmcli>
82```
83
84## Change Connection Details
85
86This section will show how to change some of the connection details including
87IPv4 and IPv6 settings.
88
89It is important to understand that every option can be modified using either the
90command-line or the editor. The advantage of the editor is that it shows which
91options are availabe for modification in contrast to the command-line which does
92not.
93
94It is possible however to learn about the available settings from the
95command-line by printing the connection details. Type:
96
97```
98$ nmcli c show <name>
99```
100
101where &lt;name&gt; is the connection name.
102
103The above will bring a fairly long list of text on the terminal, therefore it is
104best to either use a pager or grep to make the results manageable.
105
106### IPv4 and IPv6 Options
107
108For example for IPv4 settings one would do:
109
110```
111$ nmcli c show <name> | grep ipv4
112ipv4.method: auto
113ipv4.dns:
114ipv4.dns-search:
115ipv4.dns-options: (default)
116ipv4.addresses:
117ipv4.gateway: --
118ipv4.routes:
119ipv4.route-metric: -1
120ipv4.ignore-auto-routes: no
121ipv4.ignore-auto-dns: no
122ipv4.dhcp-client-id: --
123ipv4.dhcp-timeout: 0
124ipv4.dhcp-send-hostname: yes
125ipv4.dhcp-hostname: --
126ipv4.dhcp-fqdn: --
127ipv4.never-default: no
128ipv4.may-fail: yes
129ipv4.dad-timeout: -1 (default)
130```
131
132For example setting up the DNS server would require typing:
133
134```
135$ nmcli c modify <name> ipv4.dns "8.8.8.8"
136```
137
138The rest of the settings can be modified in the same fashion.
139
140### WiFi Powersave Option
141
142The WiFi powersave option can have one of the following values:
143
144| Value | Meaning |
145|-------|---------------------------------------------------|
146| 0 | Default |
147| 1 | Ignore, do not touch currently configured setting |
148| 2 | Disable |
149| 3 | Enable |
150
151Changing it is as simple as:
152
153```
154$ nmcli c modify <name> 802-11-wireless.powersave 2
155```
diff --git a/docs/installation.md b/docs/installation.md
index 2f6872d..6169238 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -56,3 +56,6 @@ Now you have NetworkManager successfully installed.
56 * [Explore Network Status](explore-network-status.md)56 * [Explore Network Status](explore-network-status.md)
57 * [Configure WiFi Connections](configure-wifi-connections.md)57 * [Configure WiFi Connections](configure-wifi-connections.md)
58 * [Configure Cellular Connections](configure-cellular-connections.md)58 * [Configure Cellular Connections](configure-cellular-connections.md)
59 * [Edit Network Connections](edit-connections.md)
60 * [Routing Tables](routing-tables.md)
61 * [Logging Messages](logging-messages.md)
diff --git a/docs/logging-messages.md b/docs/logging-messages.md
59new file mode 10064462new file mode 100644
index 0000000..d242808
--- /dev/null
+++ b/docs/logging-messages.md
@@ -0,0 +1,43 @@
1---
2title: "Logging Messages"
3table_of_contents: False
4---
5
6# Logging Messages
7
8This section will show how to modify the logging levels by NetworkManager.
9
10NetworkManager supports on the fly changing of the logging levels and allows for
11a fine control over what is logged.
12
13First check what is the current logging setup, type:
14
15```
16$ nmcli general logging
17```
18
19As a result you will be presented with the information about the current
20configuration:
21
22```
23LEVEL DOMAINS
24INFO PLATFORM,RFKILL,ETHER,WIFI,BT,MB,DHCP4,DHCP6,PPP,IP4,IP6,AUTOIP4,DNS,VPN,SHARING,SUPPLICANT,AGENTS,SETTINGS,SUSPEND,CORE,DEVICE,OLPC,INFINIBAND,FIREWALL,ADSL,BOND,VLAN,BRIDGE,TEAM,CONCHECK,DCB,DISPATCH,AUDIT,SYSTEMD
25```
26
27It is possible to change the level either globally or for each domain
28separately. The command to achieve this is:
29
30```
31$ nmcli general logging [level <level> [domain <domain>]]
32```
33
34The &lt;level&gt; is the desired log level. You can choose from the following:
35
36* **ERR:** will log only critical errors
37* **WARN:** will log warnin messages
38* **INFO:** will log various informational messages
39* **DEBUG:** enables verbose logging for debugging purposes
40
41&lt;domain&gt; is the category of messages that shall be logged with given
42severity. **WIFI** will include only WiFi related messages, **IP4** will include
43only IPv4 related messages and so on..
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
index 477b29d..b9c4f41 100644
--- a/docs/metadata.yaml
+++ b/docs/metadata.yaml
@@ -17,12 +17,20 @@ navigation:
17 location: configure-cellular-connections.md17 location: configure-cellular-connections.md
18 - title: Enable Ethernet Support18 - title: Enable Ethernet Support
19 location: enable-ethernet-support.md19 location: enable-ethernet-support.md
20 - title: Edit Connections
21 location: edit-connections.md
22 - title: Routing Tables
23 location: routing-tables.md
24 - title: Logging Messages
25 location: logging-messages.md
20 - title: Reference26 - title: Reference
21 children:27 children:
22 - title: Snap Configuration28 - title: Snap Configuration
23 children:29 children:
24 - title: Wake on WLAN30 - title: Wake on WLAN
25 location: reference/snap-configuration/wowlan.md31 location: reference/snap-configuration/wowlan.md
32 - title: WiFi Powersave
33 location: reference/snap-configuration/wifi-powersave.md
26 - title: Available Commands34 - title: Available Commands
27 location: reference/available-commands.md35 location: reference/available-commands.md
28 - title: DBUS API36 - title: DBUS API
diff --git a/docs/reference/snap-configuration/wifi-powersave.md b/docs/reference/snap-configuration/wifi-powersave.md
29new file mode 10064437new file mode 100644
index 0000000..8b9e68f
--- /dev/null
+++ b/docs/reference/snap-configuration/wifi-powersave.md
@@ -0,0 +1,38 @@
1---
2title: WiFi Powersave
3table_of_contents: True
4---
5
6# WiFi Powersave
7
8WiFi Powersave is a feature that allows a device to suspend its radio activity
9after a fixed period of inactivity. The device remains idle for a fixed time,
10usualy about 100ms, and once it is reached it wakes up to check if the
11infrastructure has any packets queued up for it.
12
13The NetworkManager snap allows to configure this option by either enabling or
14disabling the powersave feature.
15
16You can read more about the WiFi Powersave feature on the following sites:
17
18*
19<https://wireless.wiki.kernel.org/en/developers/documentation/ieee80211/power-savings>
20
21### Enable WiFi Powersave
22
23To allow users to enable or disable WiFi Powersave, the snap provides a single
24configuration option:
25
26* wifi.powersave
27
28Option can be set via the configuration API snaps provide. See
29<https://docs.ubuntu.com/core/en/guides/build-device/config-hooks> for more
30details.
31
32#### wifi.powersave
33
34This configuration option accepts the following values:
35
36* **disabled (default):** WiFi powersaving is disabled
37* **enabled:** WiFi powersaving is enabled
38
diff --git a/docs/report-bug.md b/docs/report-bug.md
index 9ec4b89..faa9853 100644
--- a/docs/report-bug.md
+++ b/docs/report-bug.md
@@ -18,6 +18,10 @@ $ nmcli d
18$ nmcli c18$ nmcli c
19```19```
2020
21It is a good idea to set the log level to DEBUG so that the verbose information
22is provided. To do this for NetworkManager please see the [Logging Messages](logging-messages.md)
23page.
24
21If there is a modem and the modem-manager snap is installed, also add the output25If there is a modem and the modem-manager snap is installed, also add the output
22of26of
2327
diff --git a/docs/routing-tables.md b/docs/routing-tables.md
24new file mode 10064428new file mode 100644
index 0000000..85b4ff8
--- /dev/null
+++ b/docs/routing-tables.md
@@ -0,0 +1,96 @@
1---
2title: "Routing Tables"
3table_of_contents: True
4---
5
6# Routing Tables
7
8This section describes the way to setup routing table as well as it explains the
9logic used to prioritize interfaces.
10
11The routing table is stored in the kernel which merely acts upon it. The route
12itself is set by the user-space tools. There is no preference as any tool
13created for this reason will do. It can be either a DHCP client, ip command or
14route command.
15
16It is important to understand that NetworkManager changes the routing table
17whenever it creates a new connection.
18
19Routing table acts as a junction and is there to show where the different
20network subnets will be routed to. An example of a routing table is shown below.
21
22```
23$ ip route
24default via 10.0.0.1 dev wlp3s0 proto static metric 600
2510.0.0.0/24 dev wlp3s0 proto kernel scope link src 10.0.0.73 metric 600
2610.0.1.0/24 dev lxcbr0 proto kernel scope link src 10.0.1.1
27169.254.0.0/16 dev docker0 scope link metric 1000 linkdown
28172.17.0.0/16 dev docker0 proto kernel scope link src 172.17.0.1 linkdown
29192.168.122.0/24 dev virbr0 proto kernel scope link src 192.168.122.1 linkdown
30```
31
32The first column is the &lt;Destination&gt; subnet with the "default" being a
33wildcard for everything else. The "via" fragment points to the &lt;Gateway&gt;
34however when it is missing it indicates that that network is connected directly
35and instead it describes a source address.
36
37The &lt;Metric&gt; column translates to the number of hops required to reach the
38destination and is used to determine which route shall be preferred when there
39are more than one route available for a specific destination. Since it
40reassembles the concept of distance the lower it's value is the better.
41
42The &lt;Metric&gt; value can be set manually however when NetworkManager creates
43a connection the following defaults are applied:
44
45* Ethernet is preferred over WiFi
46* WiFi is preferred over WWAN
47
48# Editing the Routing Tables
49
50The routing table can be added or modified using the standard *ip* command which
51is available on Ubuntu Core.
52
53You can find more information on it on the following page:
54
55* <https://linux.die.net/man/8/ip?>
56
57Separately it is possible to modify routing information per single connection
58using the nmcli tool. The parameters such as: gateway, routes and metrics can be
59modified.
60
61The following options are responsible:
62
63```
64ipv4.gateway:
65ipv4.routes:
66ipv4.route-metric:
67
68ipv6.gateway:
69ipv6.routes:
70ipv6.route-metric:
71```
72
73These options can be modified in a following way:
74
75```
76$ nmcli connection modify <name> +ipv4.routes <destination> ipv4.gateway <gateway>
77$ nmcli connection modify <name> ipv4.route-metric <metric>
78```
79
80Where &lt;name&gt; is the connection name. You can obtain it by listing
81available connections on the system:
82
83```
84$ nmcli c show
85```
86
87&lt;destination&gt; is the destination network provided as a static IP address,
88subnet or "default". &lt;gateway&gt; is the new gateway information.
89&lt;metric&gt; is the new metric information.
90
91Note that this kind of changes can be made separately for each connection thus
92it is possible to provide a fine grained control over how the packets directed
93to different networks are routed.
94
95It is also important to understand that bringing up and down connections with
96different values set for these options is in fact changing the routing table.

Subscribers

People subscribed via source and target branches