WPA supplicant

wpa_supplicant is a cross-platform supplicant with support for WEP, WPA and WPA2 (IEEE 802.11i). It is suitable for desktops, laptops and embedded systems. It 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.

Installation

Install the wpa_supplicant package, which includes the main program wpa_supplicant, the passphrase tool wpa_passphrase, and the text front-end wpa_cli.

Optionally, also install the official wpa_supplicant_guiAUR which provides wpa_gui, a graphical front-end for wpa_supplicant, or wpa-cuteAUR which is a fork from wpa_gui with a couple of fixes and improvements.

Overview

The first step to connect to an encrypted wireless network is having wpa_supplicant obtain authentication from a WPA authenticator. In order to do this, wpa_supplicant must be configured so that it will be able to submit the correct credentials to the authenticator.

If the SSID does not have password authentication, you must explicitly configure the network as keyless by replacing the command set_network 0 psk "passphrase" with set_network 0 key_mgmt NONE.

Note:

Each network is indexed numerically, so the first network will have index 0.

The PSK is computed from the quoted "passphrase" string, as also shown by the wpa_passphrase command. Nonetheless, you can enter the PSK directly by passing it to pskwithout quotes.

Finally save this network in the configuration file:

> save_config
OK

Once association is complete, you must obtain an IP address, for example, using dhcpcd.

Connecting with wpa_passphrase

This connection method allows quickly connecting to a network whose SSID is already known, making use of wpa_passphrase, a command line tool which generates the minimal configuration needed by wpa_supplicant. For example:

Note: Because of the process substitution, you cannot run this command with sudo and must use a root shell, see Help:Reading#Regular user or root for more explanations. Just pre-pending sudo will lead to the following error:

Successfully initialized wpa_supplicant
Failed to open config file '/dev/fd/63', error: No such file or directory
Failed to read or parse configuration '/dev/fd/63'

Tip:

Use quotes, if the input contains spaces. For example: "secret passphrase".

Alternatively, when using special characters in the passphrase, rather than escaping them, simply invoke wpa_passphrase without specifying the passphrase. It will then prompt for it to be entered in the standard input where users can paste it even if it contains special characters.

Advanced usage

For networks of varying complexity, possibly employing extensive use of EAP, it will be useful to maintain a customised configuration file. For an overview of the configuration with examples, refer to wpa_supplicant.conf(5); for details on all the supported configuration parameters, refer to the example file /usr/share/doc/wpa_supplicant/wpa_supplicant.conf.[1]

Further network blocks may be added manually, or using wpa_cli as illustrated in #Connecting with wpa_cli. In order to use wpa_cli, a control interface must be set with the ctrl_interface option. Setting ctrl_interface_group=wheel allows users belonging to such group to execute wpa_cli. This setting can be used to enable users without root access (or equivalent via sudo etc) to connect to wireless networks. Also add update_config=1 so that changes made with wpa_cli to example.conf can be saved. Note that any user that is a member of the ctrl_interface_group group will be able to make changes to the file if this is turned on.

fast_reauth=1 and ap_scan=1 are the wpa_supplicant options active globally at the time of writing. Whether you need them, or other global options too for that matter, depends on the type of network to connect to. If you need other global options, simply copy them over to the file from /usr/share/doc/wpa_supplicant/wpa_supplicant.conf.

Alternatively, wpa_cli set can be used to see options' status or set new ones. Multiple network blocks may be appended to this configuration: the supplicant will handle association to and roaming between all of them. The strongest signal defined with a network block usually is connected to by default, one may define priority= to influence behaviour. For example to auto-connect to any unsecured network as a fallback with the lowest priority:

network={
key_mgmt=NONE
priority=-999
}

Once you have finished the configuration file, you can optionally use it as a system-wide or per-interface default configuration by naming it according to the paths listed in #At boot (systemd). This also applies if you use additional network manager tools, which may rely on the paths (for example Dhcpcd#10-wpa_supplicant).

Tip: To configure a network block to a hidden wireless SSID, which by definition will not turn up in a regular scan, the option scan_ssid=1 has to be defined in the network block.

Connection

Manual

First start wpa_supplicant command, whose most commonly used arguments are:

-B - Fork into background.

-c filename - Path to configuration file.

-i interface - Interface to listen on.

-D driver - Optionally specify the 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.

At boot (systemd)

wpa_supplicant@interface.service - accepts the interface name as an argument and starts the wpa_supplicant daemon for this interface. It reads a /etc/wpa_supplicant/wpa_supplicant-interface.conf configuration file.

Tip: The same configuration, but for a wireless adapter, would require changing IEEE8021X to WPA-EAP and removing the ap_scan=0 line

Since this file is storing a plaintext password, chown it to root:root and chmod it to 600.

Before running the wpa_supplicant-wired@adapter.service service, make sure to set the device down:

# ip link set adapter down

Tip: This setup can be used during system installation as well, though you may want to run using dhcpcd@adapter.service to solicit an address.

wpa_cli action script

wpa_cli can run in daemon mode and execute a specified script based on events from wpa_supplicant. Two events are supported: CONNECTED and DISCONNECTED. Some environment variables are available to the script, see wpa_cli(8) for details.

Remember to make the script executable, then use the -a flag to pass the script path to wpa_cli:

$ wpa_cli -a /path/to/script

Troubleshooting

Note: Make sure that you do not have remnant configuration files based on the full documentation example /usr/share/doc/wpa_supplicant/wpa_supplicant.conf. It is filled with uncommented network examples that may lead random errors in practice (FS#40661).

nl80211 driver not supported on some hardware

On some (especially old) hardware, wpa_supplicant may fail with the following error:

If the command works to connect, and the user wishes to use systemd to manage the wireless connection, it is necessary to edit the wpa_supplicant@.service unit provided by the package and modify the ExecStart line accordingly:

Note: Multiple comma separated driver wrappers in option -Dnl80211,wext makes wpa_supplicant use the first driver wrapper that is able to initialize the interface (see wpa_supplicant(8)). This is useful when using mutiple or removable (e.g. USB) wireless devices which use different drivers.

Problem with mounted network shares (cifs) and shutdown

When you use wireless to connect to network shares you might have the problem that the shutdown takes a very long time. That is because systemd runs against a 3 minute timeout. The reason is that WPA supplicant is shut down too early, i.e. before systemd tries to unmount the share(s). A bug report suggests a work-around by editing the wpa_supplicant@.service as follows:

/etc/systemd/system/wpa_supplicant.service.d/override.conf

[Unit]
After=dbus.service

Password-related problems

wpa_supplicant may not work properly if directly passed via stdin particularly long or complex passphrases which include special characters. This may lead to errors such as failed 4-way WPA handshake, PSK may be wrong when launching wpa_supplicant.

In order to solve this try using here strings wpa_passphrase <MYSSID> <<< "<passphrase>" or passing a file to the -c flag instead:

# wpa_supplicant -i <interface> -c /etc/wpa_supplicant/example.conf

In some instances it was found that storing the passphrase cleartext in the psk key of the wpa_supplicant.confnetwork block gave positive results (see [2]). However, this approach is rather insecure. Using wpa_cli to create this file instead of manually writing it gives the best results most of the time and therefore is the recommended way to proceed.

Problems with eduroam and other MSCHAPv2 connections

Ensure that your config uses

phase2="auth=MSCHAPV2"

with a capital "v" (see FS#51358). You could even omit this setting entirely, since MSCHAPV2 is the default.