WPA supplicant

From ArchWiki
Revision as of 21:38, 7 February 2014 by Indigo (Talk | contribs) (Setup for dhcpcd: update for 6.2.1)

Jump to: navigation, search

wpa_supplicant is a cross-platform WPA Supplicant with support for WEP, WPA and WPA2 (IEEE 802.11i / RSN (Robust Secure Network)). It is suitable for both desktop and laptop computers and even embedded systems.

wpa_supplicant is the IEEE 802.1X/WPA component that is used in the client stations. It implements key negotiation with a WPA Authenticator and it controls the roaming and IEEE 802.11 authentication/association of the wireless driver.


Install wpa_supplicant from the official repositories.

Optionally wpa_supplicant_gui can be installed which provides wpa_gui, a graphical frontend for wpa_supplicant using the qt4 toolkit.

Setup for dhcpcd

dhcpcd contains a hook (enabled by default) to automatically launch wpa_supplicant on wireless interfaces. It is started only if:

  • no wpa_supplicant process is already listening on that interface. This means that dhcpcd will not invoke wpa_supplicant if it has already been started for that interface through systemd or other method.
  • a wpa_supplicant configuration file exists. Since dhcpcd dhcpcd 6.2.1-1 (February 2014) the wpa_supplicant's default location /etc/wpa_supplicant/wpa_supplicant.conf is checked as well as the historic /etc/wpa_supplicant.conf.

The hook is located at /usr/lib/dhcpcd/dhcpcd-hooks/10-wpa_supplicant.


wpa_supplicant provides a reference configuration file located at /etc/wpa_supplicant/wpa_supplicant.conf which contains detailed documentation for all the available options and their utilisation, as well as examples. Consider making a backup of it first, because some of the methods decribed below for automatically adding network configurations to wpa_supplicant.conf will strip all comments from the file.

$ sudo cp /etc/wpa_supplicant/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant.conf.bak

In its simplest form, a configuration file requires only a network configuration block. For example:


A network configuration can be automatically generated using the wpa_passphrase tool, and added to the configuration file. This is useful for routers and access points that require a passkey. For example:

$ wpa_passphrase essid passphrase

Some unusually complex passphrases may require input from a file.

wpa_passphrase essid < passphrase.txt >
Tip: wpa_passphrase can append the network configuration directly to the configuration file, but you will need to account for the link to the protected configuration file being applied before the sudo command. Make sure you use a double >>, otherwise you'll overwrite the entire configuration file.:
$ sudo sh -c "wpa_passphrase essid passphrase >> /etc/wpa_supplicant/wpa_supplicant.conf"

Once you have a configuration file, you can run the wpa_supplicant daemon and connect to the wireless network:

# wpa_supplicant -B -i interface -c configuration_file

You might need to specify a driver to be used. For a list of supported drivers see the output of wpa_supplicant -h.

  • nl80211 is the current standard, but not all wireless chip's modules support it.
  • wext is currently deprecated, but still widely supported.

Use the -D switch to specify the driver:

# wpa_supplicant -B -i interface -c configuration_file -D driver
Tip: Both wpa_supplicant and wpa_passphrase can be combined to associate with almost all WPA2 (Personal) networks, but you need to switch to superuser, because the link to the protected configuration file is applied before any sudo command.:
$ sudo -i
# wpa_supplicant -B -i interface -c <(wpa_passphrase essid passphrase)

Once wpa_supplicant is configured for your network, all that's left to to do is to connect to it, using a static IP or DHCP. For example:

# dhcpcd interface

Using wpa_cli

Wpa_supplicant can be controlled manually at runtime, by using the wpa_cli utility. To enable wpa_cli, the wpa_supplicant daemon must be configured to create a "control interface" (socket) by setting the ctrl_interface variable in the wpa_supplicant configuration file (default location /etc/wpa_supplicant/wpa_supplicant.conf).

The user will also need to be given access to this socket, by specifying which group has access to it. A new group might be created for this purpose, and users added to it, or an already existing group can be used - typically wheel, so users with sudo permission can have access to wpa_cli. The following setting will create the socket in /run/wpa_supplicant/ and allow the members of group wheel to access it:

ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel

It is possible to modify the wpa_supplicant configuration file itself through the wpa_cli. This is useful for manually adding new networks to the roaming configuration file without needing to restart the wpa_supplicant daemon. To enable this, in the configuration file set the update_config variable to 1:


The wpa_supplicant daemon must be running, before wpa_cli can start. Typically dhcpcd invokes it when it creates a wireless connection. If necessary, you can start the wpa_supplicant daemon manually, providing your wireless interface name (i.e. wlp1s2), and the location of the configuration file.

$ sudo wpa_supplicant -B -i interface -c /etc/wpa_supplicant/wpa_supplicant.conf

Then start

$ wpa_cli

It will look for the control socket at the location given in the configuration file, or the location can be set manually with the -p option). You can specify the interface that will be configured with the -i option, otherwise the first found wireless interface managed by wpa_supplicant will be used.

When wpa_cli is invoked, an interactive prompt (>) will appear. The prompt has tab completion and descriptions of completed commands.

Adding a new network using wpa_cli

To scan for available networks, enter "scan" at the > prompt. A notification will appear when the scan is complete:

> scan

Then enter "scan_results" to display them:

> scan_results
bssid / frequency / signal level / flags / ssid
00:00:00:00:00:00 2462 -49 [WPA2-PSK-CCMP][ESS] MYSSID
11:11:11:11:11:11 2437 -64 [WPA2-PSK-CCMP][ESS] ANOTHERSSID

To associate with MYSSID, tell wpa_supplicant about it. Each network in the configuration file is indexed numerically, beginning with zero. If you add a new network, it will be assigned a new number accordingly.

> add_network

Use this number to specify which network your settings apply to. For a new network, set its SSID, in quotes:

> set_network 0 ssid "MYSSID"

Even if your access point is not is protected, the cli apparently still requires a PSK, again in quotes. The passkey must be 8-63 characters.:

> set_network 0 psk "passkey"

Enable it:

> enable_network 0

And write the changes to the configuration file:

> save_config

Action script

Tango-view-fullscreen.pngThis article or section needs expansion.Tango-view-fullscreen.png

Reason: To be re-added from this old revision with a meanigful example. (Discuss in Talk:WPA supplicant#)

Enabling with systemd

A possible setup involves enabling wpa_supplicant and dhcpcd on a particular interface (see systemd#Using units for details):

# systemctl enable wpa_supplicant@interface
# systemctl enable dhcpcd@interface

The [Install] section of systemd services in the current version of wpa_supplicant is incorrect (bug report). If your interface name is not wlan0, it will be necessary to copy the service file to /etc/systemd/system/ and replace the [Install] section with:


See systemd#Editing provided unit files for help with the editing.

Note: If you use dhcpcd@.service, you might also want to replace the -w flag with -b so that it does not wait until it is assigned an address before forking to the background.

See also