Skip to content

Instantly share code, notes, and snippets.

Forked from holomorph/wpa_supplicant.asciidoc
Last active August 29, 2015 14:20
Show Gist options
  • Save modulitos/abb7ad192e2e39a12bab to your computer and use it in GitHub Desktop.
Save modulitos/abb7ad192e2e39a12bab to your computer and use it in GitHub Desktop.

WPA Supplicant

wpa_supplicant is a cross-platform WPA Supplicant with support for WPA and WPA2 (IEEE 802.11i/RSN (Robust Secure Network)). It is suitable for desktops, laptops and 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 wlan driver.


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

Connecting with wpa_cli

wpa_cli is a command line tool which can be used to interactively configure wpa_supplicant in order to associate with a wireless access point (WAP). In order to use wpa_cli, a control interface must be specified for wpa_supplicant. Do this by creating a config file containing ctrl_interface=/run/wpa_supplicant. Refer to wpa_supplicant.conf(5) and the example file /etc/wpa_supplicant/wpa_supplicant.conf for details.

Start wpa_supplicant with wpa_supplicant -B -i _interface_ -c _/path/to/config_.

To discover your wireless network interface name, issue the ip link command.

Invoke wpa_cli with no arguments to get an interactive prompt (>). The prompt has tab completion and descriptions of completed commands. The command scan initiates a scan; a notification is issued when the scan is complete. Then:

> 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 is indexed numerically, so the first network will have index zero. The PSK can be provided without quotes as an alternative to providing the passphrase in this example, and computed with wpa_passphrase.

> add_network
> set_network 0 ssid "MYSSID"
> set_network 0 psk "passphrase"
> enable_network 0
<2>CTRL-EVENT-CONNECTED - Connection to 00:00:00:00:00:00 completed (reauth) [id=0 id_str=]

To enable saving changes made using wpa_cli, the setting update_config must be enabled. To save this network in the configuration file,

> set update_config 1
> save_config

Now that association with the WAP is complete, obtain an IP address by setting it manually with the iproute2 suite or some networking program, like systemd-networkd or dhcpcd.


wpa_supplicant provides a reference configuration file located at /etc/wpa_supplicant/wpa_supplicant.conf containing detailed documentation for the all available options and their utilisation.

In its simplest form, a configuration file requires only a network block. This can easily be generated using the wpa_passphrase tool. For example:

$ wpa_passphrase essid passphrase

Now both wpa_supplicant and wpa_passphrase can be combined to associate with almost all WPA2 (Personal) networks:

# wpa_supplicant -B -i wlp2s0 -c <(wpa_passphrase essid passphrase)

All that remains is to simply connect using a static IP or DHCP. For example:

# dhcpcd wlp2s0
If dhcpcd is invoked without specifying an interface, it will bind to all interfaces it can find. During booting, this introduces a race with udev, where dhcpcd may prevent udev from renaming interfaces.

Maintaining a custom configuration

As discussed above, wpa_passphrase is useful for generating a basic configuration to which additional networks and options can be added. This may be necessary for more advanced wireless networks employing extensive use of EAP. For networks of varying complexity, please study the examples provided in the default /etc/wpa_supplicant/wpa_supplicant.conf file.

Two pieces of configuration are key. First, use wpa_passphrase to create a basic configuration file.

# wpa_passphrase essid passphrase > /etc/wpa_supplicant/foobar.conf
Some unusually complex passphrases may require input from a file: wpa_passphrase essid < passphrase.txt > /etc/wpa_supplicant/foobar.conf

Next, add a ctrl_interface so that wpa_cli can be used to control the wpa_supplicant daemon. Either by using wpa_cli interactively or manually adding update_config=1 to the config file, changes to foobar.conf can be saved. Ultimately, the configuration should resemble:

# /etc/wpa_supplicant/foobar.conf
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel

Multiple network blocks may be appended to this configuration. To connect to the configured wireless network, simply run the following:

# wpa_supplicant -B -D nl80211 -i wlp2s0 -c /etc/wpa_supplicant/foobar.conf
# dhcpcd -A wlp2s0
nl80211 is preferred over the deprecated wext driver. For a list of supported drivers see the output of wpa_supplicant -h.

Enabling with systemd

It is likely that wpa_supplicant@.service will have to be modified so that it will read the desired configuration file. To override the ExecStart= line, create the following file:

# /etc/systemd/system/wpa_supplicant@.service.d/foo.conf
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/bar.conf -i%i

Then enable wireless at boot, enable wpa_supplicant@ on a particular wireless interface:

# systemctl enable wpa_supplicant@wlp2s0

The supplicant handles assocation to and roaming between all the networks in its configuration file.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment