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

[Konrad Zapałowicz]

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

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

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:fc30fc56c87cb8992def0516ed7b5f6882ac0702
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1506/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/1305
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1414/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1731
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/916/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1506/rebuild

review: Approve (continuous-integration)

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

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.

[Simon Fels (morphis)]

review: Needs Fixing

[Jim Hodapp (jhodapp)]

Some comments inline below.

review: Needs Fixing

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

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

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:c0faa9640d0c69e2898ca30d4abccc9c7317bb8e
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1507/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/1406/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1415/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1825/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/1011

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1507/rebuild

review: Needs Fixing (continuous-integration)

[Jim Hodapp (jhodapp)]

Looking good, some changes still to make.

review: Needs Fixing

[Jim Hodapp (jhodapp)]

One more fix needed.

review: Needs Fixing

[Jim Hodapp (jhodapp)]

Found one more typo.

review: Needs Fixing

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

LGTM

review: Approve

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:e4dafda8fff4d7c3b7be645a2d4c1a234b394c82
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1508/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/1467
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1416/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1883
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/1069

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1508/rebuild

review: Approve (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:7f5338830414ce8dd2c8fb1cb1048c1c98115608
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1509/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/1468
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1417/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1884
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/1070/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1509/rebuild

review: Approve (continuous-integration)

[Jim Hodapp (jhodapp)]

LGTM!

review: Approve

[Simon Fels (morphis)]

LGTM, thanks for the rework!

review: Approve

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>
 $ nmcli r wwan on
 ```
 
-where <interface> is the string listed as “primary port” in the output from 'sudo mmcli -m <N>'
+where &lt;interface&gt; is the string listed as “primary port” in the output from 'sudo mmcli -m &lt;N&gt;'
 (as previously described),
-<name> is an arbitrary name used to identify the connection, and <operator_apn> is
-the APN name for your cellular data plan.  Note that <interface> is usually a serial
+&lt;name&gt; is an arbitrary name used to identify the connection, and &lt;operator_apn&gt; is
+the APN name for your cellular data plan.  Note that &lt;interface&gt; is usually a serial
 port with pattern /dev/tty*, not a networking interface. The reason for ModemManager
 to use that instead of the networking interface is that this last one can appear/disappear
 dynamically 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
 After executing these commands, NetworkManager will automatically try to bring up
 the cellular connection whenever ModemManager reports that the modem has
 registered (the state of the modem can be checked with the previously introduced
-command “sudo modem-manager.mmcli -m <N>”). When done successfully, NetworkManager
+command “sudo modem-manager.mmcli -m &lt;N&gt;”). When done successfully, NetworkManager
 will create routes for the new network interface, with less priority than
 Ethernet or WiFi interfaces. To disable the connection, we can do:
 
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 @@
 ---
 title: "Configure WiFi Connections"
-table_of_contents: False
+table_of_contents: True
 ---
 
 # Configure WiFi Connections
 
+This section explains how to establish a WiFi connection. It covers creating and
+modyfying connections as well as directly connecting.
+
+## Establish a Wireless Connection
+
+This section will show how to establish a wifi connection to the wireles
+network. Note that directly connecting will implicitly create a connection (that
+can be seen with "nmcli c"). The naming of such will follow "SSID N" pattern,
+where N is a number.
+
 First, determine the name of the WiFi interface:
 
 ```
@@ -24,51 +34,48 @@ Then, list the available WiFi networks:
 
 ```
 $ nmcli d wifi list
-*  SSID           MODE   CHAN  RATE       SIGNAL  BARS  SECURITY         
+*  SSID           MODE   CHAN  RATE       SIGNAL  BARS  SECURITY
    ...
-   my_wifi      Infra  5     54 Mbit/s  89      ▂▄▆█  WPA2      
+   my_wifi      Infra  5     54 Mbit/s  89      ▂▄▆█  WPA2
 ```
 
-As an example, to connect to the access point ‘my_wifi’, you would use the
-following commands:
+As an example, to connect to the access point 'my_wifi', you would use the
+following command:
 
 ```
-$ nmcli c add con-name <name> ifname wlan0 type wifi ssid my_wifi
-$ nmcli c modify <name> wifi-sec.key-mgmt wpa-psk wifi-sec.psk <password>
+$ nmcli d wifi connect my_wifi password <password>
 ```
 
-<name> is an arbitrary name given to the connection, and <password> is the
-password for the connection (this last command can be used to change the
-password too). The password needs to have 8-63 characters or 64 hexadecimal characters to specify a full 256-bit key. New connections have DHCP enabled
-for both IPv4 and IPv6 by default.
+&lt;password&gt; is the password for the connection which needs to have 8-63
+characters or 64 hexadecimal characters to specify a full 256-bit key.
+
+## Connect to a Hidden Network
 
-Once a connection has been created, NetworkManager will consider it for
-a given connection whenever the device’s WiFi is disconnected and NetworkManager
-detects the access point is available via recent scan results.
+A hidden network is a normal wireless network that simply does not broadcast
+it's SSID unless solicited. This means that its name cannot be searched and
+must be known from some other source.
 
-The autoconnect behaviour of a connection is enabled by default and can be changed
-by modifying the connection’s autoconnect property:
+Issue the following command to create a connection associated with a hidden
+network &lt;ssid&gt;:
 
 ```
-$ nmcli c modify <name> connection.autoconnect [yes|no]
+$ nmcli c add type wifi con-name <name> ifname wlan0 ssid <ssid>
+$ nmcli c modify <name> wifi-sec.key-mgmt wpa-psk wifi-sec.psk <password>
 ```
 
-Some other interesting commands follow.
-
-To show the details of a connection:
+Now you can establish a connection by typing:
 
 ```
-$ nmcli c show <name>
+$ nmcli c up <name>
 ```
 
-To trigger a manual WiFi scan:
+&lt;name&gt; is an arbitrary name given to the connection and &lt;password&gt;
+is the password to the network. It needs to have between 8-63 characters or 64
+hexadecimal characters in order to specify a full 256-bit key.
 
-```
-$ nmcli d wifi rescan
-```
+## Further Information
 
-To delete a connection:
+You will find further information and more detailed examples on following pages:
 
-```
-$ nmcli c delete <name>
-```
+* <https://developer.gnome.org/NetworkManager/unstable/nmcli.html>
+* <https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/Networking_Guide/sec-Using_the_NetworkManager_Command_Line_Tool_nmcli.html>
diff --git a/docs/edit-connections.md b/docs/edit-connections.md
new file mode 100644
index 0000000..0c9d087
--- /dev/null
+++ b/docs/edit-connections.md
@@ -0,0 +1,155 @@
+---
+title: "Edit Connections"
+table_of_contents: True
+---
+
+# Edit Connections
+
+This part will show you how to use a network-manager built-in editor to modify
+the connections as well as provide a reference for setting some of the
+settings.
+
+## Using nmcli Console
+
+Aside from offering the possibility to manage and modify the network connections
+using the command-line, network-manager offers a built-in, interactive
+console to achieve the same. In order to use it type:
+
+```
+$ nmcli connection edit
+```
+
+It will bring up an interactive console. In the first step you will be prompted
+to enter the connection type. The list of valid connection types will be
+displayed on the screen. Once you select one you will be taken to the nmcli
+console where you have the possibility to modify its parameters.
+
+Alternatively, if you know the valid connection types, you could jump straight
+to the nmcli console by providing the type as a parameter:
+
+```
+$ nmcli connection edit type <type>
+```
+
+where &lt;type&gt;  must be a valid connection type such as 'wifi'.
+
+An attempt to edit the wifi connection type would look like:
+
+```
+$ nmcli c edit
+
+Valid connection types: generic, 802-3-ethernet (ethernet), pppoe,
+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, no-slave, tun, ip-tunnel, macvlan, vxlan
+Enter connection type: wifi
+
+===| nmcli interactive connection editor |===
+
+Adding a new '802-11-wireless' connection
+
+Type 'help' or '?' for available commands.
+Type 'describe [<setting>.<prop>]' for detailed property description.
+
+You may edit the following settings: connection, 802-11-wireless (wifi),
+802-11-wireless-security (wifi-sec), 802-1x, ipv4, ipv6
+nmcli>
+```
+
+From now on it is possible to edit the wifi connection settings. The list of
+settings is provided as in the example above. The nmcli console offers a set of
+commands that can be used to navigate between settings. To get the list of
+available commands type 'help' or '?'
+
+```
+nmcli> ?
+------------------------------------------------------------------------------
+---[ Main menu ]---
+goto     [<setting> | <prop>]        :: go to a setting or property
+remove   <setting>[.<prop>] | <prop> :: remove setting or reset property value
+set      [<setting>.<prop> <value>]  :: set property value
+describe [<setting>.<prop>]          :: describe property
+print    [all | <setting>[.<prop>]]  :: print the connection
+verify   [all | fix]                 :: verify the connection
+save     [persistent|temporary]      :: save the connection
+activate [<ifname>] [/<ap>|<nsp>]    :: activate the connection
+back                                 :: go one level up (back)
+help/?   [<command>]                 :: print this help
+nmcli    <conf-option> <value>       :: nmcli configuration
+quit                                 :: exit nmcli
+------------------------------------------------------------------------------
+nmcli> 
+```
+
+## Change Connection Details
+
+This section will show how to change some of the connection details including
+IPv4 and IPv6 settings.
+
+It is important to understand that every option can be modified using either the
+command-line or the editor. The advantage of the editor is that it shows which
+options are availabe for modification in contrast to the command-line which does
+not.
+
+It is possible however to learn about the available settings from the
+command-line by printing the connection details. Type:
+
+```
+$ nmcli c show <name>
+```
+
+where &lt;name&gt; is the connection name.
+
+The above will bring a fairly long list of text on the terminal, therefore it is
+best to either use a pager or grep to make the results manageable.
+
+### IPv4 and IPv6 Options
+
+For example for IPv4 settings one would do:
+
+```
+$ nmcli c show <name> | grep ipv4
+ipv4.method:                            auto
+ipv4.dns:
+ipv4.dns-search:
+ipv4.dns-options:                       (default)
+ipv4.addresses:
+ipv4.gateway:                           --
+ipv4.routes:
+ipv4.route-metric:                      -1
+ipv4.ignore-auto-routes:                no
+ipv4.ignore-auto-dns:                   no
+ipv4.dhcp-client-id:                    --
+ipv4.dhcp-timeout:                      0
+ipv4.dhcp-send-hostname:                yes
+ipv4.dhcp-hostname:                     --
+ipv4.dhcp-fqdn:                         --
+ipv4.never-default:                     no
+ipv4.may-fail:                          yes
+ipv4.dad-timeout:                       -1 (default)
+```
+
+For example setting up the DNS server would require typing:
+
+```
+$ nmcli c modify <name> ipv4.dns "8.8.8.8"
+```
+
+The rest of the settings can be modified in the same fashion.
+
+### WiFi Powersave Option
+
+The WiFi powersave option can have one of the following values:
+
+| Value | Meaning                                           |
+|-------|---------------------------------------------------|
+| 0     | Default                                           |
+| 1     | Ignore, do not touch currently configured setting |
+| 2     | Disable                                           |
+| 3     | Enable                                            |
+
+Changing it is as simple as:
+
+```
+$ nmcli c modify <name> 802-11-wireless.powersave 2
+```
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.
  * [Explore Network Status](explore-network-status.md)
  * [Configure WiFi Connections](configure-wifi-connections.md)
  * [Configure Cellular Connections](configure-cellular-connections.md)
+ * [Edit Network Connections](edit-connections.md)
+ * [Routing Tables](routing-tables.md)
+ * [Logging Messages](logging-messages.md)
diff --git a/docs/logging-messages.md b/docs/logging-messages.md
new file mode 100644
index 0000000..d242808
--- /dev/null
+++ b/docs/logging-messages.md
@@ -0,0 +1,43 @@
+---
+title: "Logging Messages"
+table_of_contents: False
+---
+
+# Logging Messages
+
+This section will show how to modify the logging levels by NetworkManager.
+
+NetworkManager supports on the fly changing of the logging levels and allows for
+a fine control over what is logged.
+
+First check what is the current logging setup, type:
+
+```
+$ nmcli general logging
+```
+
+As a result you will be presented with the information about the current
+configuration:
+
+```
+LEVEL  DOMAINS                                                                                                                                                                                                                 
+INFO   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 
+```
+
+It is possible to change the level either globally or for each domain
+separately. The command to achieve this is:
+
+```
+$ nmcli general logging [level <level> [domain <domain>]]
+```
+
+The &lt;level&gt; is the desired log level. You can choose from the following:
+
+* **ERR:** will log only critical errors
+* **WARN:** will log warnin messages
+* **INFO:** will log various informational messages
+* **DEBUG:** enables verbose logging for debugging purposes
+
+&lt;domain&gt; is the category of messages that shall be logged with given
+severity. **WIFI** will include only WiFi related messages, **IP4** will include
+only 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:
         location: configure-cellular-connections.md
       - title: Enable Ethernet Support
         location: enable-ethernet-support.md
+      - title: Edit Connections
+        location: edit-connections.md
+      - title: Routing Tables
+        location: routing-tables.md
+      - title: Logging Messages
+        location: logging-messages.md
   - title: Reference
     children:
       - title: Snap Configuration
         children:
           - title: Wake on WLAN
             location: reference/snap-configuration/wowlan.md
+          - title: WiFi Powersave
+            location: reference/snap-configuration/wifi-powersave.md
       - title: Available Commands
         location: reference/available-commands.md
       - title: DBUS API
diff --git a/docs/reference/snap-configuration/wifi-powersave.md b/docs/reference/snap-configuration/wifi-powersave.md
new file mode 100644
index 0000000..8b9e68f
--- /dev/null
+++ b/docs/reference/snap-configuration/wifi-powersave.md
@@ -0,0 +1,38 @@
+---
+title: WiFi Powersave
+table_of_contents: True
+---
+
+# WiFi Powersave
+
+WiFi Powersave is a feature that allows a device to suspend its radio activity
+after a fixed period of inactivity. The device remains idle for a fixed time,
+usualy about 100ms, and once it is reached it wakes up to check if the
+infrastructure has any packets queued up for it.
+
+The NetworkManager snap allows to configure this option by either enabling or
+disabling the powersave feature.
+
+You can read more about the WiFi Powersave feature on the following sites:
+
+*
+<https://wireless.wiki.kernel.org/en/developers/documentation/ieee80211/power-savings>
+
+### Enable WiFi Powersave
+
+To allow users to enable or disable WiFi Powersave, the snap provides a single
+configuration option:
+
+* wifi.powersave
+
+Option can be set via the configuration API snaps provide. See
+<https://docs.ubuntu.com/core/en/guides/build-device/config-hooks> for more
+details.
+
+#### wifi.powersave
+
+This configuration option accepts the following values:
+
+* **disabled (default):** WiFi powersaving is disabled
+* **enabled:** WiFi powersaving is enabled
+
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
 $ nmcli c
 ```
 
+It is a good idea to set the log level to DEBUG so that the verbose information
+is provided. To do this for NetworkManager please see the [Logging Messages](logging-messages.md)
+page.
+
 If there is a modem and the modem-manager snap is installed, also add the output
 of
 
diff --git a/docs/routing-tables.md b/docs/routing-tables.md
new file mode 100644
index 0000000..85b4ff8
--- /dev/null
+++ b/docs/routing-tables.md
@@ -0,0 +1,96 @@
+---
+title: "Routing Tables"
+table_of_contents: True
+---
+
+# Routing Tables
+
+This section describes the way to setup routing table as well as it explains the
+logic used to prioritize interfaces.
+
+The routing table is stored in the kernel which merely acts upon it. The route
+itself is set by the user-space tools. There is no preference as any tool
+created for this reason will do. It can be either a DHCP client, ip command or
+route command.
+
+It is important to understand that NetworkManager changes the routing table
+whenever it creates a new connection.
+
+Routing table acts as a junction and is there to show where the different
+network subnets will be routed to. An example of a routing table is shown below.
+
+```
+$ ip route
+default via 10.0.0.1 dev wlp3s0  proto static  metric 600
+10.0.0.0/24 dev wlp3s0  proto kernel  scope link  src 10.0.0.73  metric 600
+10.0.1.0/24 dev lxcbr0  proto kernel  scope link  src 10.0.1.1
+169.254.0.0/16 dev docker0  scope link  metric 1000 linkdown
+172.17.0.0/16 dev docker0  proto kernel  scope link  src 172.17.0.1 linkdown
+192.168.122.0/24 dev virbr0  proto kernel  scope link  src 192.168.122.1 linkdown
+```
+
+The first column is the &lt;Destination&gt; subnet with the "default" being a
+wildcard for everything else. The "via" fragment points to the &lt;Gateway&gt;
+however when it is missing it indicates that that network is connected directly
+and instead it describes a source address.
+
+The &lt;Metric&gt; column translates to the number of hops required to reach the
+destination and is used to determine which route shall be preferred when there
+are more than one route available for a specific destination. Since it
+reassembles the concept of distance the lower it's value is the better.
+
+The &lt;Metric&gt; value can be set manually however when NetworkManager creates
+a connection the following defaults are applied:
+
+* Ethernet is preferred over WiFi
+* WiFi is preferred over WWAN
+
+# Editing the Routing Tables
+
+The routing table can be added or modified using the standard *ip* command which
+is available on Ubuntu Core.
+
+You can find more information on it on the following page:
+
+* <https://linux.die.net/man/8/ip?>
+
+Separately it is possible to modify routing information per single connection
+using the nmcli tool. The parameters such as: gateway, routes and metrics can be
+modified.
+
+The following options are responsible:
+
+```
+ipv4.gateway:
+ipv4.routes:
+ipv4.route-metric:
+
+ipv6.gateway:
+ipv6.routes:
+ipv6.route-metric:
+```
+
+These options can be modified in a following way:
+
+```
+$ nmcli connection modify <name> +ipv4.routes <destination> ipv4.gateway <gateway>
+$ nmcli connection modify <name> ipv4.route-metric <metric>
+```
+
+Where &lt;name&gt; is the connection name. You can obtain it by listing
+available connections on the system:
+
+```
+$ nmcli c show
+```
+
+&lt;destination&gt; is the destination network provided as a static IP address,
+subnet or "default". &lt;gateway&gt; is the new gateway information.
+&lt;metric&gt; is the new metric information.
+
+Note that this kind of changes can be made separately for each connection thus
+it is possible to provide a fine grained control over how the packets directed
+to different networks are routed.
+
+It is also important to understand that bringing up and down connections with
+different values set for these options is in fact changing the routing table.