1
diff --git a/README.md b/README.md
2
index 8b92863..5eac800 100644
3
--- a/README.md
4
+++ b/README.md
5
@@ -6,17 +6,6 @@ This is the snap to package the NetworkManager management service.
6
6
6
7
7
All implemented hooks are stored inside the hooks directory.
7
All implemented hooks are stored inside the hooks directory.
8
8
8
9
9
As snapcraft has no support as of today (09/12/2016) to include
10
10
hooks in a snap this always needs to be done manually. For this
11
11
12
12
$ snapcraft
13
13
$ cp -r hooks prime/meta/
14
14
$ snapcraft snap prime
15
15
16
16
does the job. Please note that none of the snaps available from the
17
17
store will have these hooks included until snapcraft receives
18
18
support for hooks.
19
19
20
20
## Running tests
9
## Running tests
21
21
10
22
22
We have a set of spread (https://github.com/snapcore/spread) tests which
11
We have a set of spread (https://github.com/snapcore/spread) tests which
23
@@ -112,3 +101,32 @@ management service in the system.
24
112
101
25
113
Depending on the nature of a test case the right test suite should be
102
Depending on the nature of a test case the right test suite should be
26
114
picked.
103
picked.
27
104
28
105
## Documentation
29
106
30
107
All documentation is available in the docs/ subdirectory. It uses markdown
31
108
and the documentation-builder (<https://github.com/CanonicalLtd/documentation-builder>)
32
109
to generate HTML-based documentation.
33
110
34
111
To generate the HTML pages install the documentation-builder snap first
35
112
36
113
```
37
114
 $ snap install documentation-builder
38
115
 $ snap connect documentation-builder:home core
39
116
```
40
117
41
118
then enter the docs/ subdirectory and run the builder
42
119
43
120
```
44
121
 $ cd docs
45
122
 $ documentation-builder
46
123
```
47
124
48
125
It will generate all documentation as HTML in the build/ subdirectory. Open
49
126
it via
50
127
51
128
```
52
129
 $ google-chrome build/index.html
53
130
```
54
131
55
132
for example.
56
diff --git a/docs/index.md b/docs/index.md
57
115
new file mode 100644
133
new file mode 100644
58
index 0000000..4d539c6
59
--- /dev/null
60
+++ b/docs/index.md
61
@@ -0,0 +1,17 @@
62
1
---
63
2
title: "NetworkManager"
64
3
table_of_contents: True
65
4
---
66
5
67
6
# About NetworkManager
68
7
69
8
NetworkManager is a system network service that manages your network
70
9
devices and connections, attempts to keep network connectivity active
71
10
when available. It manages ethernet, WiFi, mobile broadband (WWAN) and
72
11
PPPoE devices while also providing VPN integration with a variety of
73
12
different VPN serivces.
74
13
75
14
## Upstream documentation
76
15
77
16
Existing documentation from the upstream project can be found
78
17
[here](https://wiki.gnome.org/Projects/NetworkManager).
79
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
80
0
new file mode 100644
18
new file mode 100644
81
index 0000000..d04aaac
82
--- /dev/null
83
+++ b/docs/metadata.yaml
84
@@ -0,0 +1,11 @@
85
1
navigation:
86
2
  - title: Introduction
87
3
    children:
88
4
      - title: About NetworkManager
89
5
        location: index.md
90
6
  - title: Reference
91
7
    children:
92
8
      - title: Configuration
93
9
        children:
94
10
          - title: Wake on WLAN
95
11
            location: reference/configuration/wowlan.md
96
diff --git a/docs/reference/configuration/wowlan.md b/docs/reference/configuration/wowlan.md
97
0
new file mode 100644
12
new file mode 100644
98
index 0000000..29be8fc
99
--- /dev/null
100
+++ b/docs/reference/configuration/wowlan.md
101
@@ -0,0 +1,123 @@
102
1
---
103
2
title: Wake on WLAN
104
3
table_of_contents: true
105
4
---
106
5
107
6
# Wake on WLAN
108
7
109
8
Wake on WLAN (called WoWLAN in the following) is a feature which allows a device
110
9
to be woken up from standby power states to faciliate device management. It is based
111
10
on the well established standard for Wake on LAN. The functionality is not entirely
112
11
equivalent to Wake on LAN and there are some limitations.
113
12
114
13
The NetworkManager snap allows its users to configure one or more triggers to allow
115
14
the device it operates on to be woken up remotely.
116
15
117
16
An important precondition for WoWLAN to work is that your kernel WiFi driver has
118
17
support for it.
119
18
120
19
You can read more about the kernel side implementation on the following sites:
121
20
122
21
 * <https://wireless.wiki.kernel.org/en/users/documentation/wowlan>
123
22
124
23
## Enable Wake on WLAN Globally
125
24
126
25
To allow users to enable or disable WoWLAN, the snap provides two configuration
127
26
options:
128
27
129
28
 * **wifi.wake-on-wlan**
130
29
 * **wifi.wake-on-wlan-password**
131
30
132
31
Both options can be set via the configuration API snap provide. See
133
32
<https://docs.ubuntu.com/core/en/guides/build-device/config-hooks> for more
134
33
details.
135
34
136
35
Both configuration options will affect all wireless network devices. If you
137
36
want to change it just for a single wireless connection please have a look at
138
37
the chapter [Per Connection Configuration](#per-connection-configuration) below.
139
38
140
39
141
40
### wifi.wake-on-wlan
142
41
143
42
This configuration option accepts the following values
144
43
145
44
 * **disabled (default):** Wake on WLAN is disabled for all wireless network devices.
146
45
 * **any:** Wake on WLAN is enabled and any possible trigger will cause the system to wake up.
147
46
 * **disconnect:** If a connection to a station gets disconnected the device will be woken up.
148
47
 * **magic:** Wake on WLAN is enabled and only a received magic packet will cause the 
149
48
 system to wake up. The magic packet has the same structure as the one
150
49
 used for Wake on LAN. For more details see <https://en.wikipedia.org/wiki/Wake-on-LAN#Magic_packet>
151
50
 The content of the magic packet can be extended with the
152
51
 wifi.wake-on-wlan-password option to require the client to send a
153
52
 specific byte sequence functioning as a password so that not anyone
154
53
 unpriviledged can wake up the system.
155
54
 * **gtk-rekey-failure:** A failure of a GTK rekey operation will cause the device to wake up.
156
55
 * **4way-handshake:** Reiteration of the 4way handshake will cause the device to wake up.
157
56
 * **rfkill-release:** Release of a rfkill will cause the device to wake up.
158
57
 * **tcp:** Any incoming TCP packet will cause the device to wake up.
159
58
160
59
Example:
161
60
162
61
```
163
62
 $ snap set network-manager wifi.wake-on-wlan=magic
164
63
```
165
64
166
65
### wifi.wake-on-wlan-password
167
66
168
67
This configuration option accepts a textual value. If specified, the value will
169
68
be used in addition to the wireless device MAC address to function as a password
170
69
that disallows unpriviledged actors to wake up the device.
171
70
172
71
Example:
173
72
174
73
```
175
74
 $ snap set network-manager wifi.wake-on-wlan-password=MyPassword
176
75
```
177
76
178
77
## Per Connection Configuration
179
78
180
79
To configure WoWLAN per connection you have to use the *nmcli* utility which comes
181
80
with the NetworkManager snap. It allows you to configure the same two options
182
81
as the snap accepts. However, the *wifi.wake-on-wlan* option takes a numeric value
183
82
instead of a textual one.
184
83
185
84
The *wifi.wake-on-wlan* option accepts the following values (see above for a detailed
186
85
description of each value)
187
86
188
87
 * **0:** disabled
189
88
 * **1:** Use global default configuration
190
89
 * **2:** any
191
90
 * **4:** disconnect
192
91
 * **8:** magic
193
92
 * **16:** gtk-rekey-failure
194
93
 * **32:** 4way-handshake
195
94
 * **128:** rfkill-release
196
95
 * **256:** tcp
197
96
198
97
The *wifi.wake-on-wlan-password* option accepts the same values as the snap
199
98
configuration option.
200
99
201
100
Example:
202
101
203
102
```
204
103
 $ nmcli c modify my-connection wifi.wake-on-wlan 2
205
104
 $ nmcli c modify my-connection wifi.wake-on-wlan-password Test1234
206
105
```
207
106
208
107
## Verify WoWLAN Configuration
209
108
210
109
NetworkManager will use the kernel to configure WoWLAN on the hardware level.
211
110
The *iw* utility provides a simple way to verify the right option is configured.
212
111
213
112
If you don't have the *iw* utility on your system you can install it with the
214
113
*wireless-tools* snap.
215
114
216
115
```
217
116
 $ snap install --devmode wireless-tools
218
117
 $ sudo wireless-tools.iw phy phy0 wowlan show
219
118
 WoWLAN is enabled:
220
119
 * wake up on magic packet
221
120
```
222
121
223
122
See the help output of the *iw* command for more documentation and available
224
123
options.
225
diff --git a/hooks/configure b/hooks/configure
226
index 60b33d2..711ff60 100755
227
--- a/hooks/configure
228
+++ b/hooks/configure
229
@@ -34,17 +34,29 @@ switch_wifi_wake_on_wlan() {
230
34
    disabled)
34
    disabled)
231
35
      value=0
35
      value=0
232
36
      ;;
36
      ;;
233
37
    global)
234
38
      value=1
235
39
      ;;
236
40
    any)
37
    any)
237
41
      value=2
38
      value=2
238
42
      ;;
39
      ;;
239
40
    disconnect)
240
41
      value=4
241
42
      ;;
242
43
    magic)
43
    magic)
243
44
      value=8
44
      value=8
244
45
      ;;
45
      ;;
247
46
    all)
46
    gtk-rekey-failure)
248
47
      value=510
47
      value=16
249
48
      ;;
250
49
    eap-identity-request)
251
50
      value=32
252
51
      ;;
253
52
    4way-handshake)
254
53
      value=64
255
54
      ;;
256
55
    rfkill-release)
257
56
      value=128
258
57
      ;;
259
58
    tcp)
260
59
      value=256
261
48
      ;;
60
      ;;
262
49
    *)
61
    *)
263
50
      echo "ERROR: Invalid value provided for wifi.wake-on-wlan"
62
      echo "ERROR: Invalid value provided for wifi.wake-on-wlan"
264
diff --git a/tests/main/wifi-wowlan-config-option/task.yaml b/tests/main/wifi-wowlan-config-option/task.yaml
265
index f5b59ce..bb34a01 100644
266
--- a/tests/main/wifi-wowlan-config-option/task.yaml
267
+++ b/tests/main/wifi-wowlan-config-option/task.yaml
268
@@ -30,14 +30,22 @@ execute: |
269
30
    # Test all other possible keys for the wifi.wake-on-wlan option
30
    # Test all other possible keys for the wifi.wake-on-wlan option
270
31
    snap set network-manager wifi.wake-on-wlan=disabled
31
    snap set network-manager wifi.wake-on-wlan=disabled
271
32
    grep "^wifi.wake-on-wlan=0$" $WIFI_WOWL_CONF_PATH
32
    grep "^wifi.wake-on-wlan=0$" $WIFI_WOWL_CONF_PATH
272
33
    snap set network-manager wifi.wake-on-wlan=global
273
34
    grep "^wifi.wake-on-wlan=1$" $WIFI_WOWL_CONF_PATH
274
35
    snap set network-manager wifi.wake-on-wlan=any
33
    snap set network-manager wifi.wake-on-wlan=any
275
36
    grep "^wifi.wake-on-wlan=2$" $WIFI_WOWL_CONF_PATH
34
    grep "^wifi.wake-on-wlan=2$" $WIFI_WOWL_CONF_PATH
276
35
    snap set network-manager wifi.wake-on-wlan=disconnect
277
36
    grep "^wifi.wake-on-wlan=4$" $WIFI_WOWL_CONF_PATH
278
37
    snap set network-manager wifi.wake-on-wlan=magic
37
    snap set network-manager wifi.wake-on-wlan=magic
279
38
    grep "^wifi.wake-on-wlan=8$" $WIFI_WOWL_CONF_PATH
38
    grep "^wifi.wake-on-wlan=8$" $WIFI_WOWL_CONF_PATH
282
39
    snap set network-manager wifi.wake-on-wlan=all
39
    snap set network-manager wifi.wake-on-wlan=gtk-rekey-failure
283
40
    grep "^wifi.wake-on-wlan=510$" $WIFI_WOWL_CONF_PATH
40
    grep "^wifi.wake-on-wlan=16$" $WIFI_WOWL_CONF_PATH
284
41
    snap set network-manager wifi.wake-on-wlan=eap-identity-request
285
42
    grep "^wifi.wake-on-wlan=32$" $WIFI_WOWL_CONF_PATH
286
43
    snap set network-manager wifi.wake-on-wlan=4way-handshake
287
44
    grep "^wifi.wake-on-wlan=64$" $WIFI_WOWL_CONF_PATH
288
45
    snap set network-manager wifi.wake-on-wlan=rfkill-release
289
46
    grep "^wifi.wake-on-wlan=128$" $WIFI_WOWL_CONF_PATH
290
47
    snap set network-manager wifi.wake-on-wlan=tcp
291
48
    grep "^wifi.wake-on-wlan=256$" $WIFI_WOWL_CONF_PATH
292
41
49
293
42
    # Not setting any concrete value should remove the configuration
50
    # Not setting any concrete value should remove the configuration
294
43
    snap set network-manager wifi.wake-on-wlan-password=
51
    snap set network-manager wifi.wake-on-wlan-password=
Status:	Merged
Approved by:	Alfonso Sanchez-Beato on 2017-01-19
Approved revision:	64ea63d4cabe13200932d0339a3a55c33f4f9b49
Merged at revision:	ef41ac61f3c0ff6fe63c877bb10433693ffb5fd2
Proposed branch:	~morphis/snappy-hwe-snaps/+git/network-manager:feature/add-wowlan-documentation
Merge into:	~snappy-hwe-team/snappy-hwe-snaps/+git/network-manager:master
Diff against target:	294 lines (+209/-20) 6 files modified README.md (+29/-11) docs/index.md (+17/-0) docs/metadata.yaml (+11/-0) docs/reference/configuration/wowlan.md (+123/-0) hooks/configure (+17/-5) tests/main/wifi-wowlan-config-option/task.yaml (+12/-4)
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
System Enablement Bot	continuous-integration	2017-01-17	Needs Fixing on 2017-01-19
Alfonso Sanchez-Beato		2017-01-17	Approve on 2017-01-19
Jim Hodapp (community)		2017-01-17	Approve on 2017-01-19
Tony Espy		2017-01-17	Pending
Review via email: mp+314913@code.launchpad.net