/[pkg-wpa]/wpasupplicant/trunk/debian/README.Debian
ViewVC logotype

Contents of /wpasupplicant/trunk/debian/README.Debian

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1441 - (show annotations) (download)
Sat Nov 21 23:01:50 2009 UTC (4 years, 5 months ago) by kelmo-guest
File size: 21409 byte(s)
Remove a few traces of ath/madwifi from debian/NEWS and
debian/README.Debian, thanks again to Stefan Lippers-Hollmann.
1 Modes of Operation in wpasupplicant for Debian
2 ==============================================
3
4 The Debian wpasupplicant package provides two (2) convenient modes of operation
5 that are closely integrated to the core networking infrastructure; ifupdown.
6
7 Table of Contents
8 =================
9
10 1. Specifying the wpa_supplicant driver backend
11 - Table of supported drivers
12 - Choosing driver backend
13
14 2. Mode #1: Managed Mode
15 - Examples
16 - Table of Common Options
17 - Important Notes About Managed Mode
18 - How It Works
19
20 3. Mode #2: Roaming Mode
21 - wpa_supplicant.conf
22 - /etc/network/interfaces
23 - Interacting with wpa_supplicant with wpa_cli and wpa_gui
24 - Controlling the Roaming Daemon with wpa_action
25 - Fine Tuning the Roaming Setup
26 - Using External Mapping Scripts (e.g. guessnet)
27 - /etc/network/interfaces with external mapping
28
29 4. Troubleshooting
30 - Hidden ssids
31
32 5. Security Considerations
33 - Configuration File Permissions
34
35
36 1. Specifying the wpa_supplicant driver backend
37 ===============================================
38
39 The wext driver backend will be used for all interfaces that do not explicitly
40 set 'wpa-driver' to the driver type required for that device. Users of linux
41 2.4 kernels, or 2.6 kernels less than 2.6.14 will be required to specify a
42 wpa-driver type.
43
44 Table of supported drivers
45 ==========================
46
47 A summary of supported drivers follows:
48
49 Driver Description
50 ====== ===========
51 nl80211 Linux 802.11 netlink interface
52 wext Linux wireless extensions (generic)
53 wired wired Ethernet driver
54
55 Choosing driver backend
56 =======================
57
58 Set the driver type in the interfaces(5) stanza for your device with the
59 'wpa-driver' option. For example:
60
61 iface eth0 inet dhcp
62 wpa-driver wext
63 . . . . . more options
64
65 If no wpa-driver configuration is supplied, the wext backend is used.
66
67 2. Mode #1: Managed Mode
68 ========================
69
70 This mode provides the ability to establish a connection via wpa_supplicant to
71 one known network. It is similar to how the wireless-tools package works. Each
72 element required to establish the connection via wpa_supplicant is prefixed
73 with 'wpa-' and followed by the value that will be used for that element.
74
75 Examples
76 ========
77
78 NOTE: the 'wpa-psk' value is only valid if:
79 1) It is a plaintext (ascii) string between 8 and 63 characters in
80 length
81 2) It is a hexadecimal string of 64 characters
82
83 # Connect to access point of ssid 'NETBEER' with an encryption type of
84 # WPA-PSK/WPA2-PSK. It assumes the driver will use the 'wext' driver backend
85 # of wpa_supplicant because no wpa-driver option has been specified.
86 # The passphrase is given as a ASCII (plaintext) string. DHCP is used to
87 # obtain a network address.
88 #
89 iface wlan0 inet dhcp
90 wpa-ssid MyNetWork
91 # plaintext passphrase
92 wpa-psk plaintextsecret
93
94 # Connect to access point of ssid 'homezone' with an encryption type of
95 # WPA-PSK/WPA2-PSK, using the 'wext' driver backend of wpa_supplicant.
96 # The psk is given as an encoded hexadecimal string. DHCP is used to obtain
97 # a network address.
98 #
99 iface wlan0 inet dhcp
100 wpa-driver wext
101 wpa-ssid homezone
102 # hexadecimal psk is encoded from a plaintext passphrase
103 wpa-psk 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
104
105 # Connect to access point of ssid 'HotSpot1' and bssid of '00:1a:2b:3c:4d:5e'
106 # with an encryption type of WPA-PSK/WPA2-PSK, using the the 'nl80211' driver
107 # backend of wpa_supplicant. The passphrase is given as a plaintext string.
108 # A static network address assignment is used.
109 #
110 iface wlan0 inet static
111 wpa-driver nl80211
112 wpa-ssid HotSpot1
113 wpa-bssid 00:1a:2b:3c:4d:5e
114 # plaintext passphrase
115 wpa-psk madhotspot
116 wpa-key-mgmt WPA-PSK
117 wpa-pairwise TKIP CCMP
118 wpa-group TKIP CCMP
119 wpa-proto WPA RSN
120 # static ip settings
121 address 192.168.0.100
122 netmask 255.255.255.0
123 network 192.168.0.0
124 broadcast 192.168.0.255
125 gateway 192.168.0.1
126
127 # User supplied wpa_supplicant.conf is used for eth1. All network information
128 # is contained within the user supplied wpa_supplicant.conf. No wpa-driver type
129 # is specified, so wext is used. DHCP is used to obtain a network address.
130 #
131 iface eth1 inet dhcp
132 wpa-conf /path/to/wpa_supplicant.conf
133
134 Table of Common Options
135 =======================
136
137 A brief summary of common 'wpa-' options that may be used in the
138 /etc/network/interfaces stanza for a wireless device. See the
139 'Important Notes About Managed Mode' section for information about
140 valid and invalid 'wpa-' values.
141
142 NOTE: ALL values are CASE SeNsItVe
143
144 Element Example Value Description
145 ======= ============= ===========
146 wpa-ssid plaintextstring sets the ssid of your network
147
148 wpa-bssid 00:1a:2b:3c:4d:5e the bssid of your AP
149
150 wpa-psk 0123456789...... your preshared wpa key. Use
151 wpa_passphrase(8) to generate your psk
152 from a passphrase and ssid pair
153
154 wpa-key-mgmt NONE, WPA-PSK, WPA-EAP, list of accepted authenticated key
155 IEEE8021X management protocols
156
157 wpa-group CCMP, TKIP, WEP104, list of accepted group ciphers for WPA
158 WEP40
159
160 wpa-pairwise CCMP, TKIP, NONE list of accepted pairwise ciphers for
161 WPA
162
163 wpa-auth-alg OPEN, SHARED, LEAP list of allowed IEEE 802.11
164 authentication algorithms
165
166 wpa-proto WPA, RSN list of accepted protocols
167
168 wpa-identity myplaintextname administrator provided username
169 (EAP authentication)
170
171 wpa-password myplaintextpassword your password (EAP authentication)
172
173 wpa-scan-ssid 0 or 1 toggles scanning of ssid with specific
174 Probe Request frames
175
176 wpa-ap-scan 0 or 1 or 2 adjusts the scanning logic of
177 wpa_supplicant
178
179 The complete functionality of wpa_cli(8) should be implemented. Anything
180 missing is considered a bug and should be reported as such. Patches are always
181 welcome.
182
183 Important Notes About Managed Mode
184 ==================================
185
186 Almost all 'wpa-' options require there is at least a ssid specified. Only a
187 handful of options have a global effect. These are: 'wpa-ap-scan' and
188 'wpa-preauthenticate'.
189
190 Any 'wpa-' option given for a device in the interfaces(5) file is sufficient to
191 trigger the wpa_supplicant daemon into action.
192
193 The wpasupplicant ifupdown script makes assumptions about the 'type' of input
194 that is valid for each option. For example, it assumes that some input is
195 plaintext and wraps quotation marks around the input before passing it on
196 to wpa_cli, which then adds the input to the network block being formed via
197 the wpa_supplicant ctrl_interface socket. Running ifup manually with the
198 '--verbose' option will reveal all of the commands used to form the network
199 block via wpa_cli. If the value you used for any wpa-* option in
200 /etc/network/interfaces is surrounded by double quotes, than it has been
201 assumed to be of "plaintext" or "ascii" type input.
202
203 Some input is assumed to be a hexadecimal string (eg. wpa-wep-key*). The value
204 'type' of the wpa-psk option however, is determined via a simple check for more
205 than one non hexadecimal character.
206
207
208 How It Works
209 ============
210
211 As mentioned earlier, each wpa_supplicant specific element is prefixed with
212 'wpa-'. Each element correlates to a property of wpa_supplicant described in
213 the wpa_supplicant.conf(5), wpa_supplicant(8) and wpa_cli(8) manpages. The
214 supplicant is launched without any pre-configuration whatsoever, and wpa_cli
215 forms a network configuration from the input provided by the 'wpa-*' lines.
216 Initially, wpa_supplicant/wpa_cli does not directly set the properties of the
217 device (like setting an essid with iwconfig, for example), rather it informs
218 the device of what access point is suitable to associate with. Once the device
219 has scanned the area, and found that the suitable access point is available for
220 use, these properties are set.
221
222 The scripts that do all the work are located at:
223
224 /etc/wpa_supplicant/ifupdown.sh
225 /etc/wpa_supplicant/functions.sh
226
227 ifupdown.sh is executed by run-parts, which in turn is invoked by ifupdown
228 during the 'pre-up', 'pre-down' and 'post-down' phases.
229
230 In the 'pre-up' phase, a wpa_supplicant daemon is launched followed by a series
231 of wpa_cli commands that set up a network configuration according to what
232 'wpa-' options were used in /etc/network/interfaces for the physical device.
233
234 If wpa-roam is used, a wpa_cli daemon is launched in the 'post-up' phase.
235
236 In the 'pre-down' phase, the wpa_cli daemon is terminated.
237
238 In the 'post-down' phase, the wpa_supplicant daemon is terminated.
239
240
241 3. Mode #2: Roaming Mode
242 ========================
243
244 A self contained, simplistic roaming mechanism is provided by this package. It
245 is in the form of a wpa_cli action script, /sbin/wpa_action, and it assumes
246 control of ifupdown once activated. The wpa_action(8) manpage describes its
247 technical details in great depth.
248
249 To activate a roaming interface, adapt the following example interfaces(5)
250 stanza:
251
252 iface eth1 inet manual
253 wpa-driver wext
254 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
255
256 Two daemons are spawned from the above example; wpa_supplicant and wpa_cli. It
257 is required to provide a wpa_supplicant.conf containing a minimal amount of
258 global options, and any known network blocks that should be connected to
259 without interaction. A good starting point is provided by an example
260 configuration file:
261
262 # copy the template to /etc/wpa_supplicant/
263 cp /usr/share/doc/wpasupplicant/examples/wpa-roam.conf \
264 /etc/wpa_supplicant/wpa_supplicant.conf
265 # allow only root to read and write to file
266 chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf
267
268 NOTE: it is critical that the used wpa_supplicant.conf defines the location of
269 the 'ctrl_interface' so that a communication socket is created for the
270 wpa_cli (wpa-roam daemon) to attach. The mentioned example configuration,
271 /usr/share/doc/wpasupplicant/examples/wpa-roam.conf, has been set to a
272 sane default.
273
274 It is required to edit this configuration file, and add the network blocks for
275 all known networks. If you do not understand what this means, start reading the
276 wpa_supplicant.conf(5) manpage now.
277
278 For each network, you may specify a special option 'id_str'. It should be set to
279 a simple text string. This text string forms the basis for network profiling; it
280 correlates to a logical interface defined in the interfaces(5) file. When no
281 'id_str' is given for a network, wpa_action assumes it will use the 'default'
282 logical interface as fallback. The fallback interface can be chosen via the
283 'wpa-roam-default-iface' option.
284
285 So what does all this mean? Lets illustrate it with a small example taken from
286 the wpa_action(8) manpage.
287
288 wpa_supplicant.conf
289 ===================
290 network={
291 ssid="foo"
292 key_mgmt=NONE
293 # this id_str will notify /sbin/wpa_action to 'ifup uni'
294 id_str="uni"
295 }
296
297 network={
298 ssid="bar"
299 psk=123456789...
300 # this id_str will notify /sbin/wpa_action to 'ifup home_static'
301 id_str="home_static"
302 }
303
304 network={
305 ssid=""
306 key_mgmt=NONE
307 # no 'id_str' parameter is given, /sbin/wpa_action will 'ifup default'
308 }
309
310 /etc/network/interfaces
311 =======================
312 # the roaming interface MUST use the manual inet method
313 # 'allow-hotplug' or 'auto' ensures the daemon starts automatically
314 allow-hotplug eth1
315 iface eth1 inet manual
316 wpa-driver wext
317 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
318
319 # no id_str, 'default' is used as the fallback mapping target
320 iface default inet dhcp
321
322 # id_str="uni"
323 iface uni inet dhcp
324
325 # id_str="home_static"
326 iface home_static inet static
327 address 192.168.0.20
328 netmask 255.255.255.0
329 network 192.168.0.0
330 broadcast 192.168.0.255
331 gateway 192.168.0.1
332
333 A logical interface is brought up via ifup, and taken down via ifdown, as
334 wpa_supplicant associates and de-associates with the network associated
335 to it by the 'id_str' option used in the wpa_supplicant.conf configuration file.
336
337 /sbin/wpa_action's actions are logged to syslog.
338
339 Interacting with wpa_supplicant with wpa_cli and wpa_gui
340 ========================================================
341
342 The wpa_supplicant process can be interacted with by members of the "netdev"
343 group if the example roaming configuration was used as is (or by whatever
344 group or gid specified by the GROUP= crtl_interface parameter).
345
346 # the default ctrl_interface option used in the example file
347 # /usr/share/doc/wpasupplicant/examples/wpa-roam.conf
348 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
349
350 To interact with the supplicant, the wpa_cli (command line) and wpa_gui (QT)
351 have been provided. With these you may connect, disconnect, add/delete new
352 network blocks, provide required interactive security information and so on.
353
354 Controlling the Roaming Daemon with wpa_action
355 ==============================================
356
357 Once the roaming daemon is started, it assumes control of ifupdown. That is;
358 wpa_cli calls ifup when wpa_supplicant has successfully associated with an
359 access point, and calls ifdown when the connection is lost or terminated.
360 While the roaming daemon is active, ifupdown should not be controlled directly
361 by manually issued commands, rather /sbin/wpa_action is supplied to stop and
362 reload the roaming daemon. For example, to stop the
363 romaing daemon on the device 'eth1':
364
365 wpa_action eth1 stop
366
367 When it is required to update the roaming daemon with a new networks details,
368 it can be done without stopping it. Edit the wpa_supplicant.conf file that is
369 being used by the daemon with the new networks details, add optional network
370 settings to /etc/network/interfaces that are specific to the new network
371 (linked by the 'id_str') and then 'reload' the daemon like so:
372
373 wpa_action eth1 reload
374
375 For the complete technical details of what wpa_action can do, read the
376 wpa_action(8) manpage.
377
378 Fine Tuning the Roaming Setup
379 =============================
380
381 You may face situations where multiple known access points are in close
382 proximity. You can choose which one is preferred manually, with wpa_cli or
383 wpa_gui, or you can give each network its own priority. This is provided by the
384 'priority' option of wpa_supplicant.conf.
385
386 Using External Mapping Scripts (e.g. guessnet)
387 ==============================================
388
389 In addition to the internal mapping of logical interfaces via 'id_str',
390 wpa_action can call external mapping scripts. A mapping script should return
391 the name of the logical interface which should be brought up. Any mapping
392 script that works from ifupdowns mapping mechanism (see man interfaces) should
393 also work when called from wpa_action.
394
395 To call a mapping script add a line 'wpa-mapping-script name-of-the-script' to
396 the interfaces stanza of the physical roaming device. (You may have to specify
397 the absolute path to the mapping script.)
398
399 The contents of lines starting with wpa-map are passed to stdin of the mapping
400 script. Since ifupdown allows only one wpa-map line you can append any number
401 to wpa-map for additional lines. For example:
402
403 iface wlan0 inet manual
404 wpa-driver wext
405 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
406 wpa-mapping-script guessnet-ifupdown
407 wpa-map0 home
408 wpa-map1 work
409 wpa-map2 school
410 # ... additional wpa-mapX lines as required
411
412
413 By default the mapping script will only be used when no 'id_str' is available
414 for the current network. If you want to completely disable 'id_str' matching
415 and use only an external mapping script, use the
416 'wpa-mapping-script-priority 1' option to override default behaviour.
417
418 If the mapping script returns an empty string wpa_action will fallback to using
419 the 'default' interface, unless an alternative is defined by the
420 'wpa-roam-default-iface' option.
421
422 Below is an advanced example, using guessnet-ifupdown as the external mapping
423 script.
424
425 /etc/network/interfaces with external mapping
426 =============================================
427
428 allow-hotplug wlan0
429 iface wlan0 inet manual
430 wpa-driver wext
431 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
432 wpa-roam-default-iface default-wparoam
433 wpa-mapping-script guessnet-ifupdown
434 wpa-map default: default-guessnet
435 wpa-map0 home_static
436 wpa-map1 work_static
437
438 # school can only be chosen via 'id_str' matching
439 iface school inet dhcp
440 # resolvconf
441 dns-nameservers 11.22.33.44 55.66.77.88
442
443 iface home_static inet static
444 address 192.168.0.20
445 netmask 255.255.255.0
446 network 192.168.0.0
447 broadcast 192.168.0.255
448 gateway 192.168.0.1
449 test peer address 192.168.0.1 mac 00:01:02:03:04:05
450
451 iface work_static inet static
452 address 192.168.3.200
453 netmask 255.255.255.0
454 network 192.168.3.0
455 broadcast 192.168.3.255
456 gateway 192.168.3.1
457 test peer address 192.168.3.1 mac 00:01:02:03:04:05
458
459 iface default-guessnet inet dhcp
460
461 iface default-wparoam inet dhcp
462
463 In this example wpa_action will use guessnet for the selection of a suitable
464 logical interface only when no 'id_str' option has been provided for the
465 current network in the provided wpa_supplicant.conf.
466
467 The 'wpa-map' lines provide guessnet with the logical interfaces that are to be
468 tested as well as the default interface to be used when all tests fail. The
469 'test' lines of each logical interface are used by guessnet to determine if
470 we are actually connected to that network. For instance, guessnet will choose
471 the logical interface 'home_static' if there's a device with an IP address of
472 192.168.0.1 and MAC of 00:01:02:03:04:05 on the current network. If all tests
473 fail, the 'default-guessnet' interface will be configured.
474
475 Please, read the guessnet(8) manpage for more information.
476
477
478 4. Troubleshooting
479 ==================
480
481 In order to debug connection, association and authentication problems,
482 increase the verbosity level of wpa_supplicant to log debug output by
483 adding the wpa-debug-level option to /etc/network/interfaces like in
484 the following example:
485
486 iface eth1 inet dhcp
487 wpa-debug-level 3
488 ...
489
490 Debug level number 3 starts the supplicant with the -ddd command line option,
491 level 2 with -dd an level 1 with -d. Values of -1 and -2 will cause
492 wpa_supplicant to be started with -q and -qq options respectively (quiet mode).
493 Any other wpa-debug-level value will cause the supplicant to be started
494 with default debug level.
495
496 If wpa_supplicant is started via D-Bus, then you must edit
497 /usr/share/dbus-1/system-services/fi.epitest.hostap.WPASupplicant.service and
498 add the debugging command line option to the Exec field.
499
500 It is also possible to have wpa_supplicant write all debug output to a text
501 file with the -f command line option. You may specify a file to log to with
502 the wpa-logfile in /etc/network/interfaces if starting wpa_supplicant via
503 ifupdown.
504
505 Another method is to start `wpa_cli -i <interface>` in another shell before
506 starting the interface. Use the command 'level 0' first, to get all debug
507 messages sent to the control socket by wpa_supplicant.
508
509 To debug the ifupdown scripts that start wpa_supplicant and friends, use
510 `ifup --verbose <interface>` to get verbose messages, or set
511 wpa-maint-debug to any value to see shell code execution (set -x).
512
513 Hidden ssids
514 ============
515
516 For reference, see #358137 [1]. In order to be able to associate to hidden
517 ssids, please try to set the option 'ap_scan=1' in the global section, and
518 'scan_ssid=1' in your network block section of your wpa_supplicant.conf file.
519 If you are using the managed mode, you can do so by these stanzas:
520
521 iface eth1 inet dhcp
522 wpa-ap-scan 1
523 wpa-scan-ssid 1
524 # ... additional options for your setup
525
526 According to #368770 [2], association can take a very long time under certain
527 circumstances. In some cases, setting the parameter 'ap_scan=2' in the
528 config file, (or using a 'wpa-ap-scan 2' stanza, which is equivalent) can
529 greatly help to speed up association. Please note that setting ap_scan to the
530 value of 2 also requires that all networks have a precisely defined security
531 policy for for key_mgmt, pairwise, group and proto network policy variables.
532
533 [1] http://bugs.debian.org/358137
534 [2] http://bugs.debian.org/368770
535
536
537 5. Security Considerations
538 ==========================
539
540 Configuration File Permissions
541 ==============================
542 It is important to keep PSK's and other sensitive information concerning your
543 network settings private, therefore ensure that important configuration files
544 containing such data are only readable by their owner. For example:
545
546 chmod 0600 /etc/network/interfaces
547 chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf
548
549 By default, /etc/network/interfaces is world readable, and thus unsuitable for
550 containing secret keys and passwords.

  ViewVC Help
Powered by ViewVC 1.1.5