1 Modes of Operation in wpasupplicant for Debian
2 ==============================================
4 The Debian wpasupplicant package provides two (2) convenient modes of operation
5 that are closely integrated to the core networking infrastructure; ifupdown.
10 1. Specifying the wpa_supplicant driver backend
11 - Table of supported drivers
12 - Choosing driver backend
14 2. Mode #1: Managed Mode
16 - Table of Common Options
17 - Important Notes About Managed Mode
20 3. Mode #2: Roaming Mode
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
27 - Using External Mapping Scripts (e.g. guessnet)
28 - /etc/network/interfaces with external mapping
33 5. Security Considerations
34 - Configuration File Permissions
37 1. Specifying the wpa_supplicant driver backend
38 ===============================================
40 The wext driver backend will be used for all interfaces that do not explicitly
41 set 'wpa-driver' to the driver type required for that device. Users of linux
42 2.4 kernels, or 2.6 kernels less than 2.6.14 will be required to specify a
45 Table of supported drivers
46 ==========================
48 A summary of supported drivers follows:
52 atmel ATMEL AT76C5XXx (USB, PCMCIA)
53 wext Linux wireless extensions (generic)
54 wired wired Ethernet driver
56 Choosing driver backend
57 =======================
59 Set the driver type in the interfaces(5) stanza for your device with the
60 'wpa-driver' option. For example:
64 . . . . . more options
66 If no wpa-driver configuration is supplied, the wext backend is used.
68 2. Mode #1: Managed Mode
69 ========================
71 This mode provides the ability to establish a connection via wpa_supplicant to
72 one known network. It is similar to how the wireless-tools package works. Each
73 element required to establish the connection via wpa_supplicant is prefixed
74 with 'wpa-' and followed by the value that will be used for that element.
79 NOTE: the 'wpa-psk' value is only valid if:
80 1) It is a plaintext (ascii) string between 8 and 63 characters in
82 2) It is a hexadecimal string of 64 characters
84 # Connect to access point of ssid 'NETBEER' with an encryption type of
85 # WPA-PSK/WPA2-PSK. It assumes the driver will use the 'wext' driver backend
86 # of wpa_supplicant because no wpa-driver option has been specified.
87 # The passphrase is given as a ASCII (plaintext) string. DHCP is used to
88 # obtain a network address.
92 # plaintext passphrase
93 wpa-psk plaintextsecret
95 # Connect to access point of ssid 'homezone' with an encryption type of
96 # WPA-PSK/WPA2-PSK, using the 'wext' driver backend of wpa_supplicant.
97 # The psk is given as an encoded hexadecimal string. DHCP is used to obtain
100 iface wlan0 inet dhcp
103 # hexadecimal psk is encoded from a plaintext passphrase
104 wpa-psk 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
106 # Connect to access point of ssid 'HotSpot1' and bssid of '00:1a:2b:3c:4d:5e'
107 # with an encryption type of WPA-PSK/WPA2-PSK, using the the 'madwifi' driver
108 # backend of wpa_supplicant. The passphrase is given as a plaintext string.
109 # A static network address assignment is used.
111 iface ath0 inet static
114 wpa-bssid 00:1a:2b:3c:4d:5e
115 # plaintext passphrase
118 wpa-pairwise TKIP CCMP
122 address 192.168.0.100
123 netmask 255.255.255.0
125 broadcast 192.168.0.255
128 # User supplied wpa_supplicant.conf is used for eth1. All network information
129 # is contained within the user supplied wpa_supplicant.conf. No wpa-driver type
130 # is specified, so wext is used. DHCP is used to obtain a network address.
133 wpa-conf /path/to/wpa_supplicant.conf
135 Table of Common Options
136 =======================
138 A brief summary of common 'wpa-' options that may be used in the
139 /etc/network/interfaces stanza for a wireless device. See the
140 'Important Notes About Managed Mode' section for information about
141 valid and invalid 'wpa-' values.
143 NOTE: ALL values are CASE SeNsItVe
145 Element Example Value Description
146 ======= ============= ===========
147 wpa-ssid plaintextstring sets the ssid of your network
149 wpa-bssid 00:1a:2b:3c:4d:5e the bssid of your AP
151 wpa-psk 0123456789...... your preshared wpa key. Use
152 wpa_passphrase(8) to generate your psk
153 from a passphrase and ssid pair
155 wpa-key-mgmt NONE, WPA-PSK, WPA-EAP, list of accepted authenticated key
156 IEEE8021X management protocols
158 wpa-group CCMP, TKIP, WEP104, list of accepted group ciphers for WPA
161 wpa-pairwise CCMP, TKIP, NONE list of accepted pairwise ciphers for
164 wpa-auth-alg OPEN, SHARED, LEAP list of allowed IEEE 802.11
165 authentication algorithms
167 wpa-proto WPA, RSN list of accepted protocols
169 wpa-identity myplaintextname administrator provided username
172 wpa-password myplaintextpassword your password (EAP authentication)
174 wpa-scan-ssid 0 or 1 toggles scanning of ssid with specific
177 wpa-ap-scan 0 or 1 or 2 adjusts the scanning logic of
180 The complete functionality of wpa_cli(8) should be implemented. Anything
181 missing is considered a bug and should be reported as such. Patches are always
184 Important Notes About Managed Mode
185 ==================================
187 Almost all 'wpa-' options require there is at least a ssid specified. Only a
188 handful of options have a global effect. These are: 'wpa-ap-scan' and
189 'wpa-preauthenticate'.
191 Any 'wpa-' option given for a device in the interfaces(5) file is sufficient to
192 trigger the wpa_supplicant daemon into action.
194 The wpasupplicant ifupdown script makes assumptions about the 'type' of input
195 that is valid for each option. For example, it assumes that some input is
196 plaintext and wraps quotation marks around the input before passing it on
197 to wpa_cli, which then adds the input to the network block being formed via
198 the wpa_supplicant ctrl_interface socket. Running ifup manually with the
199 '--verbose' option will reveal all of the commands used to form the network
200 block via wpa_cli. If the value you used for any wpa-* option in
201 /etc/network/interfaces is surrounded by double quotes, than it has been
202 assumed to be of "plaintext" or "ascii" type input.
204 Some input is assumed to be a hexadecimal string (eg. wpa-wep-key*). The value
205 'type' of the wpa-psk option however, is determined via a simple check for more
206 than one non hexadecimal character.
212 As mentioned earlier, each wpa_supplicant specific element is prefixed with
213 'wpa-'. Each element correlates to a property of wpa_supplicant described in
214 the wpa_supplicant.conf(5), wpa_supplicant(8) and wpa_cli(8) manpages. The
215 supplicant is launched without any pre-configuration whatsoever, and wpa_cli
216 forms a network configuration from the input provided by the 'wpa-*' lines.
217 Initially, wpa_supplicant/wpa_cli does not directly set the properties of the
218 device (like setting an essid with iwconfig, for example), rather it informs
219 the device of what access point is suitable to associate with. Once the device
220 has scanned the area, and found that the suitable access point is available for
221 use, these properties are set.
223 The scripts that do all the work are located at:
225 /etc/wpa_supplicant/ifupdown.sh
226 /etc/wpa_supplicant/functions.sh
228 ifupdown.sh is executed by run-parts, which in turn is invoked by ifupdown
229 during the 'pre-up', 'pre-down' and 'post-down' phases.
231 In the 'pre-up' phase, a wpa_supplicant daemon is launched followed by a series
232 of wpa_cli commands that set up a network configuration according to what
233 'wpa-' options were used in /etc/network/interfaces for the physical device.
235 If wpa-roam is used, a wpa_cli daemon is launched in the 'post-up' phase.
237 In the 'pre-down' phase, the wpa_cli daemon is terminated.
239 In the 'post-down' phase, the wpa_supplicant daemon is terminated.
242 3. Mode #2: Roaming Mode
243 ========================
245 A self contained, simplistic roaming mechanism is provided by this package. It
246 is in the form of a wpa_cli action script, /sbin/wpa_action, and it assumes
247 control of ifupdown once activated. The wpa_action(8) manpage describes its
248 technical details in great depth.
250 To activate a roaming interface, adapt the following example interfaces(5)
253 iface eth1 inet manual
255 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
257 Two daemons are spawned from the above example; wpa_supplicant and wpa_cli. It
258 is required to provide a wpa_supplicant.conf containing a minimal amount of
259 global options, and any known network blocks that should be connected to
260 without interaction. A good starting point is provided by an example
263 # copy the template to /etc/wpa_supplicant/
264 cp /usr/share/doc/wpasupplicant/examples/wpa-roam.conf \
265 /etc/wpa_supplicant/wpa_supplicant.conf
266 # allow only root to read and write to file
267 chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf
269 NOTE: it is critical that the used wpa_supplicant.conf defines the location of
270 the 'ctrl_interface' so that a communication socket is created for the
271 wpa_cli (wpa-roam daemon) to attach. The mentioned example configuration,
272 /usr/share/doc/wpasupplicant/examples/wpa-roam.conf, has been set to a
275 It is required to edit this configuration file, and add the network blocks for
276 all known networks. If you do not understand what this means, start reading the
277 wpa_supplicant.conf(5) manpage now.
279 For each network, you may specify a special option 'id_str'. It should be set to
280 a simple text string. This text string forms the basis for network profiling; it
281 correlates to a logical interface defined in the interfaces(5) file. When no
282 'id_str' is given for a network, wpa_action assumes it will use the 'default'
283 logical interface as fallback. The fallback interface can be chosen via the
284 'wpa-roam-default-iface' option.
286 So what does all this mean? Lets illustrate it with a small example taken from
287 the wpa_action(8) manpage.
294 # this id_str will notify /sbin/wpa_action to 'ifup uni'
301 # this id_str will notify /sbin/wpa_action to 'ifup home_static'
308 # no 'id_str' parameter is given, /sbin/wpa_action will 'ifup default'
311 /etc/network/interfaces
312 =======================
313 # the roaming interface MUST use the manual inet method
314 # 'allow-hotplug' or 'auto' ensures the daemon starts automatically
316 iface eth1 inet manual
318 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
320 # no id_str, 'default' is used as the fallback mapping target
321 iface default inet dhcp
326 # id_str="home_static"
327 iface home_static inet static
329 netmask 255.255.255.0
331 broadcast 192.168.0.255
334 A logical interface is brought up via ifup, and taken down via ifdown, as
335 wpa_supplicant associates and de-associates with the network associated
336 to it by the 'id_str' option used in the wpa_supplicant.conf configuration file.
338 A log of /sbin/wpa_action's actions is created at
339 /var/log/wpa_action.$IFACE.log, please attach the log when reporting problems.
341 Interacting with wpa_supplicant with wpa_cli and wpa_gui
342 ========================================================
344 The wpa_supplicant process can be interacted with by members of the "netdev"
345 group if the example roaming configuration was used as is (or by whatever
346 group or gid specified by the GROUP= crtl_interface parameter).
348 # the default ctrl_interface option used in the example file
349 # /usr/share/doc/wpasupplicant/examples/wpa-roam.conf
350 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
352 To interact with the supplicant, the wpa_cli (command line) and wpa_gui (QT)
353 have been provided. With these you may connect, disconnect, add/delete new
354 network blocks, provide required interactive security information and so on.
356 Controlling the Roaming Daemon with wpa_action
357 ==============================================
359 Once the roaming daemon is started, it assumes control of ifupdown. That is;
360 wpa_cli calls ifup when wpa_supplicant has successfully associated with an
361 access point, and calls ifdown when the connection is lost or terminated.
362 While the roaming daemon is active, ifupdown should not be controlled directly
363 by manually issued commands, rather /sbin/wpa_action is supplied to stop and
364 reload the roaming daemon. For example, to stop the
365 romaing daemon on the device 'eth1':
369 When it is required to update the roaming daemon with a new networks details,
370 it can be done without stopping it. Edit the wpa_supplicant.conf file that is
371 being used by the daemon with the new networks details, add optional network
372 settings to /etc/network/interfaces that are specific to the new network
373 (linked by the 'id_str') and then 'reload' the daemon like so:
375 wpa_action eth1 reload
377 For the complete technical details of what wpa_action can do, read the
378 wpa_action(8) manpage.
380 Fine Tuning the Roaming Setup
381 =============================
383 You may face situations where multiple known access points are in close
384 proximity. You can choose which one is preferred manually, with wpa_cli or
385 wpa_gui, or you can give each network its own priority. This is provided by the
386 'priority' option of wpa_supplicant.conf.
391 All activity of the roaming dameon is logged to /var/log/wpa_action.log. The
392 following information is logged:
395 * interface name and action event
396 * values of enviromental variables (WPA_ID, WPA_ID_STR, WPA_CTRL_DIR)
397 * ifupdown command executed
398 * wpa_cli status (based on WPA-PSK network, may display different info)
409 Using External Mapping Scripts (e.g. guessnet)
410 ==============================================
412 In addition to the internal mapping of logical interfaces via 'id_str',
413 wpa_action can call external mapping scripts. A mapping script should return
414 the name of the logical interface which should be brought up. Any mapping
415 script that works from ifupdowns mapping mechanism (see man interfaces) should
416 also work when called from wpa_action.
418 To call a mapping script add a line 'wpa-mapping-script name-of-the-script' to
419 the interfaces stanza of the physical roaming device. (You may have to specify
420 the absolute path to the mapping script.)
422 The contents of lines starting with wpa-map are passed to stdin of the mapping
423 script. Since ifupdown allows only one wpa-map line you can append any number
424 to wpa-map for additional lines. For example:
426 iface wlan0 inet manual
428 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
429 wpa-mapping-script guessnet-ifupdown
433 # ... additional wpa-mapX lines as required
436 By default the mapping script will only be used when no 'id_str' is available
437 for the current network. If you want to completely disable 'id_str' matching
438 and use only an external mapping script, use the
439 'wpa-mapping-script-priority 1' option to override default behaviour.
441 If the mapping script returns an empty string wpa_action will fallback to using
442 the 'default' interface, unless an alternative is defined by the
443 'wpa-roam-default-iface' option.
445 Below is an advanced example, using guessnet-ifupdown as the external mapping
448 /etc/network/interfaces with external mapping
449 =============================================
452 iface wlan0 inet manual
454 wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf
455 wpa-roam-default-iface default-wparoam
456 wpa-mapping-script guessnet-ifupdown
457 wpa-map default: default-guessnet
461 # school can only be chosen via 'id_str' matching
462 iface school inet dhcp
464 dns-nameservers 11.22.33.44 55.66.77.88
466 iface home_static inet static
468 netmask 255.255.255.0
470 broadcast 192.168.0.255
472 test peer address 192.168.0.1 mac 00:01:02:03:04:05
474 iface work_static inet static
475 address 192.168.3.200
476 netmask 255.255.255.0
478 broadcast 192.168.3.255
480 test peer address 192.168.3.1 mac 00:01:02:03:04:05
482 iface default-guessnet inet dhcp
484 iface default-wparoam inet dhcp
486 In this example wpa_action will use guessnet for the selection of a suitable
487 logical interface only when no 'id_str' option has been provided for the
488 current network in the provided wpa_supplicant.conf.
490 The 'wpa-map' lines provide guessnet with the logical interfaces that are to be
491 tested as well as the default interface to be used when all tests fail. The
492 'test' lines of each logical interface are used by guessnet to determine if
493 we are actually connected to that network. For instance, guessnet will choose
494 the logical interface 'home_static' if there's a device with an IP address of
495 192.168.0.1 and MAC of 00:01:02:03:04:05 on the current network. If all tests
496 fail, the 'default-guessnet' interface will be configured.
498 Please, read the guessnet(8) manpage for more information.
504 In order to debug connection, association and authentication problems,
505 increase the verbosity level of wpa_supplicant to log debug output to
506 /var/log/wpa_supplicant.$iface.log.
512 Debug level number 3 starts the supplicant with the -ddd command line option,
513 level 2 with -dd an level 1 with -d. Values of -1 and -2 will cause
514 wpa_supplicant to be started with -q and -qq options respectively (quiet mode).
515 Any other wpa-debug-level value will cause the supplicant to be started
516 with default debug level.
518 Another method is to start `wpa_cli -i <interface>` in another shell before
519 starting the interface. Use the command 'level 0' first, to get all debug
520 messages sent to the control socket by wpa_supplicant.
522 To debug the ifupdown scripts that start wpa_supplicant and friends, use
523 `ifup --verbose <interface>` to get verbose messages, or set
524 wpa-maint-debug to any value to see shell code execution (set -x).
529 For reference, see #358137 [1]. In order to be able to associate to hidden
530 ssids, please try to set the option 'ap_scan=1' in the global section, and
531 'scan_ssid=1' in your network block section of your wpa_supplicant.conf file.
532 If you are using the managed mode, you can do so by these stanzas:
537 # ... additional options for your setup
539 According to #368770 [2], association can take a very long time under certain
540 circumstances. In some cases, setting the parameter 'ap_scan=2' in the
541 config file, (or using a 'wpa-ap-scan 2' stanza, which is equivalent) can
542 greatly help to speed up association. Please note that setting ap_scan to the
543 value of 2 also requires that all networks have a precisely defined security
544 policy for for key_mgmt, pairwise, group and proto network policy variables.
546 [1] http://bugs.debian.org/358137
547 [2] http://bugs.debian.org/368770
550 5. Security Considerations
551 ==========================
553 Configuration File Permissions
554 ==============================
555 It is important to keep PSK's and other sensitive information concerning your
556 network settings private, therefore ensure that important configuration files
557 containing such data are only readable by their owner. For example:
559 chmod 0600 /etc/network/interfaces
560 chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf
562 By default, /etc/network/interfaces is world readable, and thus unsuitable for
563 containing secret keys and passwords.