Modes of Operation in wpasupplicant for Debian ============================================== The Debian wpasupplicant package provides two (2) convenient modes of operation that are closely integrated to the core networking infrastructure; ifupdown. Apart from that, wpa_supplicant supports D-Bus-activated operation, when the daemon is spawned on demand by software needing it, e.g. NetworkManager or connman. When used in that mode, wpa_supplicant does't require any manual configuration and is configured using its D-Bus API. Table of Contents ================= 1. Specifying the wpa_supplicant driver backend - Table of supported drivers - Choosing driver backend 2. Mode #1: Managed Mode - Examples - Table of Common Options - Important Notes About Managed Mode - How It Works 3. Mode #2: Roaming Mode - wpa_supplicant.conf - /etc/network/interfaces - Interacting with wpa_supplicant with wpa_cli and wpa_gui - Controlling the Roaming Daemon with wpa_action - Fine Tuning the Roaming Setup - Using External Mapping Scripts (e.g. guessnet) - /etc/network/interfaces with external mapping 4. Troubleshooting - Hidden ssids 5. Security Considerations - Configuration File Permissions 1. Specifying the wpa_supplicant driver backend =============================================== 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. Table of supported drivers ========================== A summary of supported drivers follows: Driver Description ====== =========== nl80211 Linux 802.11 netlink interface wext Linux wireless extensions (generic) wired driver for wired Ethernet Choosing driver backend ======================= Set the driver type in the interfaces(5) stanza for your device with the 'wpa-driver' option. For example: iface eth0 inet dhcp wpa-driver wext . . . . . more options If no wpa-driver configuration is supplied, the wext backend is used. 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. Examples ======== NOTE: the 'wpa-psk' value is only valid if: 1) It is a plaintext (ascii) string between 8 and 63 characters in length 2) It is a hexadecimal string of 64 characters # Connect to access point of ssid 'NyNetWork' with an encryption type of # WPA-PSK/WPA2-PSK. It assumes the driver will use the 'wext' driver backend # of wpa_supplicant because no wpa-driver option has been specified. # The passphrase is given as a ASCII (plaintext) string. DHCP is used to # obtain a network address. # iface wlan0 inet dhcp wpa-ssid MyNetWork # plaintext passphrase wpa-psk plaintextsecret # Connect to access point of ssid 'homezone' with an encryption type of # WPA-PSK/WPA2-PSK, using the 'wext' driver backend of wpa_supplicant. # The psk is given as an encoded hexadecimal string. DHCP is used to obtain # a network address. # iface wlan0 inet dhcp wpa-driver wext wpa-ssid homezone # hexadecimal psk is encoded from a plaintext passphrase wpa-psk 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f # 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 'nl80211' driver # backend of wpa_supplicant. The passphrase is given as a plaintext string. # A static network address assignment is used. # iface wlan0 inet static wpa-driver nl80211 wpa-ssid HotSpot1 wpa-bssid 00:1a:2b:3c:4d:5e # plaintext passphrase wpa-psk madhotspot wpa-key-mgmt WPA-PSK wpa-pairwise TKIP CCMP wpa-group TKIP CCMP wpa-proto WPA RSN # static ip settings address 192.168.0.100 netmask 255.255.255.0 network 192.168.0.0 broadcast 192.168.0.255 gateway 192.168.0.1 # 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 wpa-conf /path/to/wpa_supplicant.conf 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. See the 'Important Notes About Managed Mode' section for information about valid and invalid 'wpa-' values. NOTE: ALL values are CASE SeNsItVe Element Example Value Description ======= ============= =========== 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 and ssid pair wpa-key-mgmt NONE, WPA-PSK, WPA-EAP, list of accepted authenticated key IEEE8021X management protocols wpa-group CCMP, TKIP, WEP104, list of accepted group ciphers for WPA WEP40 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 The complete functionality of wpa_cli(8) should be implemented. Anything missing is considered a bug and should be reported as such. Patches are always welcome. Important Notes About Managed Mode ================================== 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. Running ifup manually with the '--verbose' option will reveal all of the commands used to form the network block via wpa_cli. If the value you used for any wpa-* option in /etc/network/interfaces is surrounded by double quotes, than it has been assumed to be of "plaintext" or "ascii" type input. Some input is assumed to be a hexadecimal string (eg. wpa-wep-key*). The value 'type' of the wpa-psk option however, is determined via a simple check for more than one non hexadecimal character. 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. The scripts that do all the work are located at: /etc/wpa_supplicant/ifupdown.sh /etc/wpa_supplicant/functions.sh ifupdown.sh is executed by run-parts, which in turn is invoked by ifupdown during the 'pre-up', 'pre-down' and 'post-down' phases. In the 'pre-up' phase, a wpa_supplicant daemon is launched followed by a series of wpa_cli commands that set up a network configuration according to what 'wpa-' options were used in /etc/network/interfaces for the physical device. If wpa-roam is used, a wpa_cli daemon is launched in the 'post-up' phase. In the 'pre-down' phase, the wpa_cli daemon is terminated. In the 'post-down' phase, the wpa_supplicant daemon is terminated. 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 wpa-driver wext wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf Two daemons are spawned from the above example; wpa_supplicant and wpa_cli. It is required to provide a wpa_supplicant.conf containing a minimal amount of global options, and any known network blocks that should be connected to without interaction. A good starting point is provided by an example configuration file: # copy the template to /etc/wpa_supplicant/ cp /usr/share/doc/wpasupplicant/examples/wpa-roam.conf \ /etc/wpa_supplicant/wpa_supplicant.conf # allow only root to read and write to file chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf NOTE: it is critical that the used wpa_supplicant.conf defines the location of the 'ctrl_interface' so that a communication socket is created for the wpa_cli (wpa-roam daemon) to attach. The mentioned example configuration, /usr/share/doc/wpasupplicant/examples/wpa-roam.conf, has been set to a sane default. 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 as fallback. The fallback interface can be chosen via the 'wpa-roam-default-iface' option. So what does all this mean? Lets illustrate it with a small example taken from the wpa_action(8) manpage. wpa_supplicant.conf =================== network={ ssid="foo" key_mgmt=NONE # this id_str will notify /sbin/wpa_action to 'ifup uni' id_str="uni" } network={ ssid="bar" psk=123456789... # this id_str will notify /sbin/wpa_action to 'ifup home_static' id_str="home_static" } network={ ssid="" key_mgmt=NONE # no 'id_str' parameter is given, /sbin/wpa_action will 'ifup default' } /etc/network/interfaces ======================= # the roaming interface MUST use the manual inet method # 'allow-hotplug' or 'auto' ensures the daemon starts automatically allow-hotplug eth1 iface eth1 inet manual wpa-driver wext wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf # no id_str, 'default' is used as the fallback mapping target iface default inet dhcp # id_str="uni" iface uni inet dhcp # id_str="home_static" iface home_static inet static address 192.168.0.20 netmask 255.255.255.0 network 192.168.0.0 broadcast 192.168.0.255 gateway 192.168.0.1 A logical interface is brought up via ifup, and taken down via ifdown, as wpa_supplicant associates and de-associates with the network associated to it by the 'id_str' option used in the wpa_supplicant.conf configuration file. /sbin/wpa_action's actions are logged to syslog. Interacting with wpa_supplicant with wpa_cli and wpa_gui ======================================================== The wpa_supplicant process can be interacted with by members of the "netdev" group if the example roaming configuration was used as is (or by whatever group or gid specified by the GROUP= crtl_interface parameter). # the default ctrl_interface option used in the example file # /usr/share/doc/wpasupplicant/examples/wpa-roam.conf ctrl_interface=DIR=/run/wpa_supplicant GROUP=netdev To interact with the supplicant, the wpa_cli (command line) and wpa_gui (QT) have been provided. With these you may connect, disconnect, add/delete new network blocks, provide required interactive security information and so on. 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 wpa_action(8) manpage. 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. Using External Mapping Scripts (e.g. guessnet) ============================================== In addition to the internal mapping of logical interfaces via 'id_str', wpa_action can call external mapping scripts. A mapping script should return the name of the logical interface which should be brought up. Any mapping script that works from ifupdowns mapping mechanism (see man interfaces) should also work when called from wpa_action. To call a mapping script add a line 'wpa-mapping-script name-of-the-script' to the interfaces stanza of the physical roaming device. (You may have to specify the absolute path to the mapping script.) The contents of lines starting with wpa-map are passed to stdin of the mapping script. Since ifupdown allows only one wpa-map line you can append any number to wpa-map for additional lines. For example: iface wlan0 inet manual wpa-driver wext wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf wpa-mapping-script guessnet-ifupdown wpa-map0 home wpa-map1 work wpa-map2 school # ... additional wpa-mapX lines as required By default the mapping script will only be used when no 'id_str' is available for the current network. If you want to completely disable 'id_str' matching and use only an external mapping script, use the 'wpa-mapping-script-priority 1' option to override default behaviour. If the mapping script returns an empty string wpa_action will fallback to using the 'default' interface, unless an alternative is defined by the 'wpa-roam-default-iface' option. Below is an advanced example, using guessnet-ifupdown as the external mapping script. /etc/network/interfaces with external mapping ============================================= allow-hotplug wlan0 iface wlan0 inet manual wpa-driver wext wpa-roam /etc/wpa_supplicant/wpa_supplicant.conf wpa-roam-default-iface default-wparoam wpa-mapping-script guessnet-ifupdown wpa-map default: default-guessnet wpa-map0 home_static wpa-map1 work_static # school can only be chosen via 'id_str' matching iface school inet dhcp # resolvconf dns-nameservers 11.22.33.44 55.66.77.88 iface home_static inet static address 192.168.0.20 netmask 255.255.255.0 network 192.168.0.0 broadcast 192.168.0.255 gateway 192.168.0.1 test peer address 192.168.0.1 mac 00:01:02:03:04:05 iface work_static inet static address 192.168.3.200 netmask 255.255.255.0 network 192.168.3.0 broadcast 192.168.3.255 gateway 192.168.3.1 test peer address 192.168.3.1 mac 00:01:02:03:04:05 iface default-guessnet inet dhcp iface default-wparoam inet dhcp In this example wpa_action will use guessnet for the selection of a suitable logical interface only when no 'id_str' option has been provided for the current network in the provided wpa_supplicant.conf. The 'wpa-map' lines provide guessnet with the logical interfaces that are to be tested as well as the default interface to be used when all tests fail. The 'test' lines of each logical interface are used by guessnet to determine if we are actually connected to that network. For instance, guessnet will choose the logical interface 'home_static' if there's a device with an IP address of 192.168.0.1 and MAC of 00:01:02:03:04:05 on the current network. If all tests fail, the 'default-guessnet' interface will be configured. Please, read the guessnet(8) manpage for more information. 4. Troubleshooting ================== In order to debug connection, association and authentication problems, increase the verbosity level of wpa_supplicant to log debug output by adding the wpa-debug-level option to /etc/network/interfaces like in the following example: iface eth1 inet dhcp wpa-debug-level 3 ... Debug level number 3 starts the supplicant with the -ddd command line option, level 2 with -dd an level 1 with -d. Values of -1 and -2 will cause wpa_supplicant to be started with -q and -qq options respectively (quiet mode). Any other wpa-debug-level value will cause the supplicant to be started with default debug level. If wpa_supplicant is started via D-Bus, then you must edit /usr/share/dbus-1/system-services/fi.epitest.hostap.WPASupplicant.service and add the debugging command line option to the Exec field. It is also possible to have wpa_supplicant write all debug output to a text file with the -f command line option. You may specify a file to log to with the wpa-logfile in /etc/network/interfaces if starting wpa_supplicant via ifupdown. Another method is to start `wpa_cli -i ` in another shell before starting the interface. Use the command 'level 0' first, to get all debug messages sent to the control socket by wpa_supplicant. To debug the ifupdown scripts that start wpa_supplicant and friends, use `ifup --verbose ` to get verbose messages, or set wpa-maint-debug to any value to see shell code execution (set -x). Hidden ssids ============ For reference, see #358137 [1]. 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 wpa-ap-scan 1 wpa-scan-ssid 1 # ... additional options for your setup According to #368770 [2], association can take a very long time under certain circumstances. 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. Please note that setting ap_scan to the value of 2 also requires that all networks have a precisely defined security policy for key_mgmt, pairwise, group and proto network policy variables. [1] http://bugs.debian.org/358137 [2] http://bugs.debian.org/368770 5. Security Considerations ========================== Configuration File Permissions ============================== It is important to keep PSK's and other sensitive information concerning your network settings private, therefore ensure that important configuration files containing such data are only readable by their owner. For example: chmod 0600 /etc/network/interfaces chmod 0600 /etc/wpa_supplicant/wpa_supplicant.conf By default, /etc/network/interfaces is world readable, and thus unsuitable for containing secret keys and passwords.