Merge ~morphis/snappy-hwe-snaps/+git/network-manager:feature/add-wowlan-documentation into ~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager:master

[Simon Fels]

Add documentation for Wake-on-WLAN support

This introduces in repository documentation of the snap. This can be easily consumed by a larger documentation site based on the documentation builder (see http://github.com/CanonicalLtd/documentation-builder) to build a common Ubuntu Core snap stacks documentation platform.

This also adds support for all available configuration values NetworkManager provides via the snap wifi.wake-on-wlan option.

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

FAILED: Continuous integration, rev:2d81063bdfe2bea3c8160cb69323726806a144ac
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/661/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/379/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/569/console

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

review: Needs Fixing (continuous-integration)

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

FAILED: Continuous integration, rev:2d81063bdfe2bea3c8160cb69323726806a144ac
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/663/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/381/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/571/console

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

review: Needs Fixing (continuous-integration)

[Jim Hodapp (jhodapp)]

Looking very nice Simon, some of your best English documentation I've seen you write yet. See the following changes inline below.

Also, what do you think about adding a section in the documentation that covers some simple examples on how to test the WoWLAN functionality from a client side? This could provide our future customers some great value.

review: Needs Fixing

[Jim Hodapp (jhodapp)]

A couple more issues found.

[Simon Fels (morphis)]

Fixed all found issues. Also added a note about how a user can verify WoWLAN is correctly applied on the hardware/driver level.

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

FAILED: Continuous integration, rev:b3d9e462461751f9269d8c8531357b2921f655f1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/664/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/382/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/572/console

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

review: Needs Fixing (continuous-integration)

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

FAILED: Continuous integration, rev:b3d9e462461751f9269d8c8531357b2921f655f1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/665/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/383/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/573/console

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

review: Needs Fixing (continuous-integration)

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

PASSED: Continuous integration, rev:9e61cbb21e5fee1e74b8c3c8fb6635ef7c8520b1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/667/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/385
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/575/console

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

review: Approve (continuous-integration)

[Jim Hodapp (jhodapp)]

Weird, I'm running 16.04 and only have snapd version 2.20:

jhodapp@smith:~/Projects/build-scripts$ snap --version
snap 2.20.1ubuntu1
snapd 2.20.1ubuntu1
series 16
ubuntu 16.04

Why would our versions differ? Doesn't snapd still come from a debian
package?

On Wed, Jan 18, 2017 at 5:40 AM, Simon Fels <email address hidden>
wrote:

>
>
> Diff comments:
>
> > diff --git a/README.md b/README.md
> > index 8b92863..968a93c 100644
> > --- a/README.md
> > +++ b/README.md
> > @@ -112,3 +101,32 @@ management service in the system.
> >
> > Depending on the nature of a test case the right test suite should be
> > picked.
> > +
> > +## Documentation
> > +
> > +All documentation is available in the docs/ subdirectory. It uses
> markdown
> > +and the documentation-builder (<https://github.com/
> CanonicalLtd/documentation-builder>)
> > +to generate HTML based documentation.
> > +
> > +To generate the HTML pages install the documentation build snap first
> > +
> > +```
> > + $ snap install documentation-build
> > + $ snap connect documentation-build:home core
>
> Works fine here on 16.04 and snapd 2.21
>
> $ sudo snap install documentation-builder
> documentation-builder 1.1.0 from 'nottrobin' installed
> $ sudo snap list | grep documentation-builder
> documentation-builder 1.1.0 23
> nottrobin -
> $ sudo snap interfaces | grep documentation-builder
> - documentation-builder:home
> $ sudo snap connect documentation-builder:home core
> $ snap --version
> snap 2.21
> snapd 2.21
> series 16
> ubuntu 16.04
>
> > +```
> > +
> > +then enter the docs/ subdirectory and run the builder
> > +
> > +```
> > + $ cd docs
> > + $ documentation-builder
> > +```
> > +
> > +It will generate all documentation as HTML in the a build/
> subdirectory. Open
> > +it via
> > +
> > +```
> > + $ google-chrome build/index.html
> > +```
> > +
> > +for example.
>
>
> --
> https://code.launchpad.net/~morphis/snappy-hwe-snaps/+git/
> network-manager/+merge/314913
> You are reviewing the proposed merge of ~morphis/snappy-hwe-snaps/+
> git/network-manager:feature/add-wowlan-documentation into
> ~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager:master.
>

[Jim Hodapp (jhodapp)]

One additional issue found.

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

FAILED: Continuous integration, rev:9e61cbb21e5fee1e74b8c3c8fb6635ef7c8520b1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/668/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/386/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/576/console

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

review: Needs Fixing (continuous-integration)

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

PASSED: Continuous integration, rev:9e61cbb21e5fee1e74b8c3c8fb6635ef7c8520b1
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/669/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/387
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/577/console

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

review: Approve (continuous-integration)

[Simon Fels (morphis)]

Normally snapd comes from a debian package but if you have SNAP_REEXEC set in your environment then will execute itself from the current core snap. But that doesn't seem to be the case here. Maybe remove the documentation-builder snap and installing it again helps. Otherwise try installing it with --devmode first.

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

PASSED: Continuous integration, rev:3e8311fdc4cd32c20785fbe7e98a2599c3145fc5
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/676/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/392
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/584/console

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

review: Approve (continuous-integration)

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

PASSED: Continuous integration, rev:3e8311fdc4cd32c20785fbe7e98a2599c3145fc5
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/677/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/393
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/585/console

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

review: Approve (continuous-integration)

[Jim Hodapp (jhodapp)]

LGTM

review: Approve

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

There are a couple of minor issues in the docs.

review: Needs Fixing

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

LGTM

review: Approve

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

FAILED: Continuous integration, rev:64ea63d4cabe13200932d0339a3a55c33f4f9b49
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/680/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/generic-run-snap-spread-tests/396/console
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/588/console

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

review: Needs Fixing (continuous-integration)

diff --git a/README.md b/README.md
index 8b92863..5eac800 100644
--- a/README.md
+++ b/README.md
@@ -6,17 +6,6 @@ This is the snap to package the NetworkManager management service.
 
 All implemented hooks are stored inside the hooks directory.
 
-As snapcraft has no support as of today (09/12/2016) to include
-hooks in a snap this always needs to be done manually. For this
-
-$ snapcraft
-$ cp -r hooks prime/meta/
-$ snapcraft snap prime
-
-does the job. Please note that none of the snaps available from the
-store will have these hooks included until snapcraft receives
-support for hooks.
-
 ## Running tests
 
 We have a set of spread (https://github.com/snapcore/spread) tests which
@@ -112,3 +101,32 @@ management service in the system.
 
 Depending on the nature of a test case the right test suite should be
 picked.
+
+## Documentation
+
+All documentation is available in the docs/ subdirectory. It uses markdown
+and the documentation-builder (<https://github.com/CanonicalLtd/documentation-builder>)
+to generate HTML-based documentation.
+
+To generate the HTML pages install the documentation-builder snap first
+
+```
+ $ snap install documentation-builder
+ $ snap connect documentation-builder:home core
+```
+
+then enter the docs/ subdirectory and run the builder
+
+```
+ $ cd docs
+ $ documentation-builder
+```
+
+It will generate all documentation as HTML in the build/ subdirectory. Open
+it via
+
+```
+ $ google-chrome build/index.html
+```
+
+for example.
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..4d539c6
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,17 @@
+---
+title: "NetworkManager"
+table_of_contents: True
+---
+
+# About NetworkManager
+
+NetworkManager is a system network service that manages your network
+devices and connections, attempts to keep network connectivity active
+when available. It manages ethernet, WiFi, mobile broadband (WWAN) and
+PPPoE devices while also providing VPN integration with a variety of
+different VPN serivces.
+
+## Upstream documentation
+
+Existing documentation from the upstream project can be found
+[here](https://wiki.gnome.org/Projects/NetworkManager).
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
new file mode 100644
index 0000000..d04aaac
--- /dev/null
+++ b/docs/metadata.yaml
@@ -0,0 +1,11 @@
+navigation:
+  - title: Introduction
+    children:
+      - title: About NetworkManager
+        location: index.md
+  - title: Reference
+    children:
+      - title: Configuration
+        children:
+          - title: Wake on WLAN
+            location: reference/configuration/wowlan.md
diff --git a/docs/reference/configuration/wowlan.md b/docs/reference/configuration/wowlan.md
new file mode 100644
index 0000000..29be8fc
--- /dev/null
+++ b/docs/reference/configuration/wowlan.md
@@ -0,0 +1,123 @@
+---
+title: Wake on WLAN
+table_of_contents: true
+---
+
+# Wake on WLAN
+
+Wake on WLAN (called WoWLAN in the following) is a feature which allows a device
+to be woken up from standby power states to faciliate device management. It is based
+on the well established standard for Wake on LAN. The functionality is not entirely
+equivalent to Wake on LAN and there are some limitations.
+
+The NetworkManager snap allows its users to configure one or more triggers to allow
+the device it operates on to be woken up remotely.
+
+An important precondition for WoWLAN to work is that your kernel WiFi driver has
+support for it.
+
+You can read more about the kernel side implementation on the following sites:
+
+ * <https://wireless.wiki.kernel.org/en/users/documentation/wowlan>
+
+## Enable Wake on WLAN Globally
+
+To allow users to enable or disable WoWLAN, the snap provides two configuration
+options:
+
+ * **wifi.wake-on-wlan**
+ * **wifi.wake-on-wlan-password**
+
+Both options can be set via the configuration API snap provide. See
+<https://docs.ubuntu.com/core/en/guides/build-device/config-hooks> for more
+details.
+
+Both configuration options will affect all wireless network devices. If you
+want to change it just for a single wireless connection please have a look at
+the chapter [Per Connection Configuration](#per-connection-configuration) below.
+
+
+### wifi.wake-on-wlan
+
+This configuration option accepts the following values
+
+ * **disabled (default):** Wake on WLAN is disabled for all wireless network devices.
+ * **any:** Wake on WLAN is enabled and any possible trigger will cause the system to wake up.
+ * **disconnect:** If a connection to a station gets disconnected the device will be woken up.
+ * **magic:** Wake on WLAN is enabled and only a received magic packet will cause the 
+ system to wake up. The magic packet has the same structure as the one
+ used for Wake on LAN. For more details see <https://en.wikipedia.org/wiki/Wake-on-LAN#Magic_packet>
+ The content of the magic packet can be extended with the
+ wifi.wake-on-wlan-password option to require the client to send a
+ specific byte sequence functioning as a password so that not anyone
+ unpriviledged can wake up the system.
+ * **gtk-rekey-failure:** A failure of a GTK rekey operation will cause the device to wake up.
+ * **4way-handshake:** Reiteration of the 4way handshake will cause the device to wake up.
+ * **rfkill-release:** Release of a rfkill will cause the device to wake up.
+ * **tcp:** Any incoming TCP packet will cause the device to wake up.
+
+Example:
+
+```
+ $ snap set network-manager wifi.wake-on-wlan=magic
+```
+
+### wifi.wake-on-wlan-password
+
+This configuration option accepts a textual value. If specified, the value will
+be used in addition to the wireless device MAC address to function as a password
+that disallows unpriviledged actors to wake up the device.
+
+Example:
+
+```
+ $ snap set network-manager wifi.wake-on-wlan-password=MyPassword
+```
+
+## Per Connection Configuration
+
+To configure WoWLAN per connection you have to use the *nmcli* utility which comes
+with the NetworkManager snap. It allows you to configure the same two options
+as the snap accepts. However, the *wifi.wake-on-wlan* option takes a numeric value
+instead of a textual one.
+
+The *wifi.wake-on-wlan* option accepts the following values (see above for a detailed
+description of each value)
+
+ * **0:** disabled
+ * **1:** Use global default configuration
+ * **2:** any
+ * **4:** disconnect
+ * **8:** magic
+ * **16:** gtk-rekey-failure
+ * **32:** 4way-handshake
+ * **128:** rfkill-release
+ * **256:** tcp
+
+The *wifi.wake-on-wlan-password* option accepts the same values as the snap
+configuration option.
+
+Example:
+
+```
+ $ nmcli c modify my-connection wifi.wake-on-wlan 2
+ $ nmcli c modify my-connection wifi.wake-on-wlan-password Test1234
+```
+
+## Verify WoWLAN Configuration
+
+NetworkManager will use the kernel to configure WoWLAN on the hardware level.
+The *iw* utility provides a simple way to verify the right option is configured.
+
+If you don't have the *iw* utility on your system you can install it with the
+*wireless-tools* snap.
+
+```
+ $ snap install --devmode wireless-tools
+ $ sudo wireless-tools.iw phy phy0 wowlan show
+ WoWLAN is enabled:
+ * wake up on magic packet
+```
+
+See the help output of the *iw* command for more documentation and available
+options.
diff --git a/hooks/configure b/hooks/configure
index 60b33d2..711ff60 100755
--- a/hooks/configure
+++ b/hooks/configure
@@ -34,17 +34,29 @@ switch_wifi_wake_on_wlan() {
     disabled)
       value=0
       ;;
-    global)
-      value=1
-      ;;
     any)
       value=2
       ;;
+    disconnect)
+      value=4
+      ;;
     magic)
       value=8
       ;;
-    all)
-      value=510
+    gtk-rekey-failure)
+      value=16
+      ;;
+    eap-identity-request)
+      value=32
+      ;;
+    4way-handshake)
+      value=64
+      ;;
+    rfkill-release)
+      value=128
+      ;;
+    tcp)
+      value=256
       ;;
     *)
       echo "ERROR: Invalid value provided for wifi.wake-on-wlan"
diff --git a/tests/main/wifi-wowlan-config-option/task.yaml b/tests/main/wifi-wowlan-config-option/task.yaml
index f5b59ce..bb34a01 100644
--- a/tests/main/wifi-wowlan-config-option/task.yaml
+++ b/tests/main/wifi-wowlan-config-option/task.yaml
@@ -30,14 +30,22 @@ execute: |
     # Test all other possible keys for the wifi.wake-on-wlan option
     snap set network-manager wifi.wake-on-wlan=disabled
     grep "^wifi.wake-on-wlan=0$" $WIFI_WOWL_CONF_PATH
-    snap set network-manager wifi.wake-on-wlan=global
-    grep "^wifi.wake-on-wlan=1$" $WIFI_WOWL_CONF_PATH
     snap set network-manager wifi.wake-on-wlan=any
     grep "^wifi.wake-on-wlan=2$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=disconnect
+    grep "^wifi.wake-on-wlan=4$" $WIFI_WOWL_CONF_PATH
     snap set network-manager wifi.wake-on-wlan=magic
     grep "^wifi.wake-on-wlan=8$" $WIFI_WOWL_CONF_PATH
-    snap set network-manager wifi.wake-on-wlan=all
-    grep "^wifi.wake-on-wlan=510$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=gtk-rekey-failure
+    grep "^wifi.wake-on-wlan=16$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=eap-identity-request
+    grep "^wifi.wake-on-wlan=32$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=4way-handshake
+    grep "^wifi.wake-on-wlan=64$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=rfkill-release
+    grep "^wifi.wake-on-wlan=128$" $WIFI_WOWL_CONF_PATH
+    snap set network-manager wifi.wake-on-wlan=tcp
+    grep "^wifi.wake-on-wlan=256$" $WIFI_WOWL_CONF_PATH
 
     # Not setting any concrete value should remove the configuration
     snap set network-manager wifi.wake-on-wlan-password=