How to use wpa_supplicant
Which modes of Operation has wpa_supplicant?
The Debian wpasupplicant package provides two (2) convenient modes of operation that are closely integrated to the core networking infrastructure: ifupdown.
Table of Contents
1. Specifying the wpa_supplicant driver backend
- Specifying the wpa_supplicant driver backend
- Table of supported drivers
- Common Driver Recommendations
- Mode #1: Managed Mode
- How It Works
- Table of Common Options
- Notes About Managed Mode
- Mode #2: Roaming Mode
- Controlling the Roaming Daemon with wpa_action
- Fine Tuning the Roaming Setup
- Hidden ssids
The wext driver backend will be used for all interfaces that do not explicitly set 'wpa-driver' to the driver type required for that device. Users of linux 2.4 kernels, or 2.6 kernels less than 2.6.14 will be required to specify a wpa-driver type.
Common Driver Recommendations
|hostap||Host AP driver (Intersil Prism2/2.5/3)|
|madwifi||MADWIFI 802.11 support (Atheros, etc.)|
|atmel||ATMEL AT76C5XXx (USB, PCMCIA)|
|wext||Linux wireless extensions (generic)|
|ipw||Intel ipw2100/2200 driver|
|wired||wired Ethernet driver|
The Intel Pro Wireless adapters (ipw2100, ipw2200 and ipw3945) all use the 'wext' backend, unless your kernel is older than 2.6.14.
Madwifi supports both the 'wext' and 'madwifi' driver backends, but 'wext' is preferred.
Ndiswrapper NO LONGER SUPPORTS the 'ndiswrapper' driver backend as of version 1.16. Therefore, 'wext' must be used unless you use an outdated ndiswrapper release.
Set the driver type in the interfaces(5) stanza for your device with the 'wpa-driver' option. For example:
iface eth0 inet dhcp
. . . . . more options
2. Mode #1: Managed Mode
This mode provides the ability to establish a connection via wpa_supplicant to one known network. It is similar to how the wireless-tools package works. Each element required to establish the connection via wpa_supplicant is prefixed with 'wpa-' and followed by the value that will be used for that element.
# Connect to access point of ssid 'homezone' with an encryption type of
# WPA-PSK/WPA2-PSK, using the the 'wext' driver backend of wpa_supplicant
# The psk is given as a hexadecimal string, without quotes. DHCP is used to
# obtain a network address.
iface wlan0 inet dhcp
# Connect to access point of ssid 'HotSpot1' and bssid of '00:1a:2b:3c:4d:5e'
# with an encryption type of WPA-PSK/WPA2-PSK, using the the 'madwifi' driver
# backend of wpa_supplicant. The passphrase is given as a plaintext string,
# without quotes. A static network address assignment is used.
iface ath0 inet static
wpa-pairwise TKIP CCMP
wpa-group TKIP CCMP
wpa-proto WPA RSN
# User supplied wpa_supplicant.conf is used for eth1. All network information
# is contained within the user supplied wpa_supplicant.conf. No wpa-driver type
# is specified, so wext is used. DHCP is used to obtain a network address.
iface eth1 inet dhcp
How It Works
As mentioned earlier, each wpa_supplicant specific element is prefixed with 'wpa-'. Each element correlates to a property of wpa_supplicant described in the wpa_supplicant.conf(5), wpa_supplicant(8) and wpa_cli(8) manpages. The supplicant is launched without any pre-configuration whatsoever, and wpa_cli forms a network configuration from the input provided by the 'wpa-*' lines.
Initially, wpa_supplicant/wpa_cli does not directly set the properties of the device (like setting an essid with iwconfig, for example), rather it informs the device of what access point is suitable to associate with. Once the device has scanned the area, and found that the suitable access point is available for use, these properties are set.
Table of Common Options
A brief summary of common 'wpa-' options that may be used in the /etc/network/interfaces stanza for a wireless device:
NOTE: ALL values are CASE SeNsItVe
Notes About Managed Mode
|wpa-ssid||plaintextstring||sets the ssid of your network|
|wpa-bssid||00:1a:2b:3c:4d:5e||the bssid of your AP|
|wpa-psk||0123456789||your preshared wpa key. Use wpa_passphrase(8) to generate your psk from a passphrase|
|wpa-passphrase||plaintextphrase||plaintext string, which is then converted to a hexadecimal psk via wpa_passphrase logic|
|wpa-key-mgmt||NONE, WPA-PSK, WPA-EAP,IEEE8021X||list of accepted authenticated key management protocols|
|wpa-group||CCMP, TKIP, WEP104,WEP40||list of accepted group ciphers for WPA|
|wpa-pairwise||CCMP, TKIP, NONE||list of accepted pairwise ciphers for WPA|
|wpa-auth-alg||OPEN, SHARED, LEAP||list of allowed IEEE 802.11 authentication algorithms|
|wpa-proto||WPA, RSN||list of accepted protocols|
|wpa-identity||myplaintextname||administrator provided username (EAP authentication)|
|wpa-password||myplaintextpassword||your password (EAP authentication)|
|wpa-scan-ssid||0 or 1||toggles scanning of ssid with specific Probe Request frames|
|wpa-ap-scan||0 or 1 or 2||adjusts the scanning logic of wpa_supplicant|
Almost all 'wpa-' options require there is at least a ssid specified. Only a handful of options have a global effect. These are: 'wpa-ap-scan' and 'wpa-preauthenticate'.
Any 'wpa-' option given for a device in the interfaces(5) file is sufficient to trigger the wpa_supplicant daemon into action.
The wpasupplicant ifupdown script makes assumptions about the 'type' of input that is valid for each option. For example, it assumes that some input is plaintext and wraps quotation marks around the input before passing it on to wpa_cli, which then adds the input to the network block being formed via the wpa_supplicant ctrl_interface socket. This can be a point of confusion, and something that has tricked more than a few people in the past. For example:
# Invalid, wpa-ssid expects unquoted plaintext ssid's only
# If you need to use a hexadecimal ssid, please supply a
# wpa_supplicant.conf, and use the 'wpa-conf' option.
# Valid, unquoted plaintext string
# Invalid, wpa-psk expects hexadecimal strings only
# NOTE: wpa-psk will accept a plaintext string enclosed in quotation
# marks this is equivalent to the 'wpa-passphrase' option
# Invalid, wpa-passphrase accepts only plaintext strings, as it
# automattically quotes the input
# Valid, unquoted plaintext string
3. Mode #2: Roaming Mode
A self contained, simplistic roaming mechanism is provided by this package. It is in the form of a wpa_cli action script, /sbin/wpa_action, and it assumes control of ifupdown once activated. The wpa_action(8) manpage describes its technical details in great depth.
To activate a roaming interface, adapt the following example interfaces(5) stanza:
iface eth1 inet manual
Two daemons are spawned from the above example; wpa_supplicant and wpa_cli. It is required to provide a wpa_supplicant.conf. A good starting point is provided by an example configuration file:
cp /usr/share/doc/wpasupplicant/examples/wpa_connect_open_ap.conf \
It is required to edit this configuration file, and add the network blocks for all known networks. If you do not understand what this means, start reading the wpa_supplicant.conf(5) manpage now.
For each network, you may specify a special option 'id_str'. It should be set to a simple text string. This text string forms the basis for network profiling; it correlates to a logical interface defined in the interfaces(5) file. When no 'id_str' is given for a network, wpa_action assumes it will use the 'default' logical interface. So what does all this mean? Lets illustrate it with a small example taken from wpa_action(8):
# this id_str will notify /sbin/wpa_action to 'ifup uni'
# this id_str will notify /sbin/wpa_action to 'ifup home_static'
# no 'id_str' is given, /sbin/wpa_action will 'ifup default'
# the roaming interface MUST use the manual inet method
iface eth1 inet manual
# no id_str
iface default inet dhcp
iface uni inet dhcp
post-up /usr/sbin/foo --bar
iface home_static inet static
A logical interface is brought up via ifup, and taken down via ifdown, as wpa_supplicant associates and de-associates with the ssid or network associated to it by the 'id_str' option used in the wpa_supplicant.conf configuration file.
A log of /sbin/wpa_action's actions is created at /var/log/wpa_action.log, please attach the log when reporting problems.
Controlling the Roaming Daemon with wpa_action
Once the roaming daemon is started, it assumes control of ifupdown. That is;
wpa_cli calls ifup when wpa_supplicant has successfully associated with an
access point, and calls ifdown when the connection is lost or terminated.
While the roaming daemon is active, ifupdown should not be controlled directly
by manually issued commands, rather /sbin/wpa_action is supplied to stop and
reload the roaming daemon. For example, to stop the
romaing daemon on the device 'eth1':
wpa_action eth1 stop
When it is required to update the roaming daemon with a new networks details,
it can be done without stopping it. Edit the wpa_supplicant.conf file that is
being used by the daemon with the new networks details, add optional network
settings to /etc/network/interfaces that are specific to the new network
(linked by the 'id_str') and then 'reload' the daemon like so:
wpa_action eth1 reload
For the complete technical details of what wpa_action can do, read the
Fine Tuning the Roaming Setup
You may face situations where multiple known access points are in close proximity. You can choose which one is preferred manually, with wpa_cli or wpa_gui, or you can give each network its own priority. This is provided by the 'priority' option of wpa_supplicant.conf.
In order to debug connection, association and authentication problems, we suggest starting `wpa_cli -i "interface"` in a different shell, before starting the interface. Use the command 'level 0' first, to get all debug messages. Then use `ifup --verbose "interface"` to get verbose debug messages from the script starting wpasupplicant.
In order to be able to associate to hidden ssids, please try to set the option 'ap_scan=1' in the global section, and 'scan_ssid=1' in your network block section of your wpa_supplicant.conf file. If you are using the managed mode, you can do so by these stanzas:
iface eth1 inet dhcp
# .. additional options for your setup
Association can take a very long time to associate to WEP. In some cases, setting the parameter 'ap_scan=2' in the config file, (or using a 'wpa-ap-scan 2' stanza, which is equivalent) can greatly help to speed up association.
Thanks to Kelmo.