# WPA supplicant

Related articles

- Network configuration
- Wireless network configuration

wpa_supplicant is a cross-platform supplicant with support for WEP, 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 wireless driver.

## Installation

Install wpa_supplicant from the official repositories.

Optionally install also wpa_supplicant_gui, which provides wpa_gui, a graphical front-end for wpa_supplicant.

## 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. Once the authentication is successful, it will be possible to connect to the network by normally obtaining an IP address.

## Connecting with wpa_cli

This connection method allows scanning for the available networks, making use of wpa_cli, a command line tool which can be used to interactively configure wpa_supplicant at runtime. See wpa_cli(8) for details.

In order to use wpa_cli, a control interface must be specified for wpa_supplicant, and it must be given the rights to update the configuration. Do this by creating a minimal configuration file:

    /etc/wpa_supplicant/example.conf

    ctrl_interface=/run/wpa_supplicant
    update_config=1

Now start wpa_supplicant with:

    # wpa_supplicant -B -i interface -c /etc/wpa_supplicant/example.conf

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

At this point run:

    # wpa_cli

This will present an interactive prompt (`>`), which has tab completion and descriptions of completed commands.

Tip: The location of the socket can be set manually with the `-p` option. It is also possible to specify the interface to be configured with the `-i` option, otherwise the first found wireless interface managed by wpa_supplicant will be used.

Use the `scan` and `scan_results` commands to see the available networks:

    > scan
    OK
    <3>CTRL-EVENT-SCAN-RESULTS
    > 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`, add the network, set the credentials and enable it:

    > add_network
    0
    > 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=]

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 `psk` without quotes.

Finally save this network in the configuration file:

    > save_config
    OK

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. See also Network configuration#Configure the IP address. For example:

    # dhcpcd interface

## 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:

    $ wpa_passphrase MYSSID passphrase

    network={
        ssid="MYSSID"
        #psk="passphrase"
        psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
    }

This means that wpa_supplicant can be associated with wpa_passphrase and simply started with:

    # wpa_supplicant -B -i interface -c <(wpa_passphrase MYSSID passphrase)

Tip:

- To discover your wireless network interface name, issue the `ip link` command.
- Some unusually complex passphrases may require input from a file: `wpa_passphrase MYSSID < passphrase.txt`

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. See also Network configuration#Configure the IP address. For example:

    # dhcpcd interface

Warning: 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.

## 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 `/etc/wpa_supplicant/wpa_supplicant.conf`.

### Configuration

As is clear after reading #Connecting with wpa_passphrase, a basic configuration file can be generated with:

    # wpa_passphrase MYSSID passphrase > /etc/wpa_supplicant/example.conf

This will only create a `network` section. A configuration file with some more common options may look like:

    /etc/wpa_supplicant/example.conf

    ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel
    update_config=1
    fast_reauth=1
    ap_scan=1
    network={
        ssid="MYSSID"
        #psk="passphrase"
        psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
    }

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 `GROUP=wheel` allows users belonging to such group to execute wpa_cli. Also add `update_config=1` so that changes made with wpa_cli to `example.conf` can be saved.

`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 `/etc/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.

An advantage to be mentioned in using a customized configuration file at `/etc/wpa_supplicant/wpa_supplicant.conf` is that it is used by default by dhcpcd. If you do so, you might want to make a backup of the original and delete the extensive network block examples in it. Otherwise, do not be surprised if your device suddenly connects to networks defined in them. In any case, changes to new versions of the configuration file should of course be merged.

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.
  - `wext` is currently deprecated, but still widely supported.

See wpa_supplicant(8) for the full argument list. For example:

    # wpa_supplicant -B -i interface -c /etc/wpa_supplicant/example.conf

Now obtain an IP address by setting it manually with the iproute2 suite or some networking program, like systemd-networkd or dhcpcd. See also Network configuration#Configure the IP address. For example:

    # dhcpcd interface

Note: dhcpcd has a hook that can lauch wpa_supplicant implicitly, see dhcpcd#10-wpa_supplicant.

#### At boot (systemd)

The wpa_supplicant package provides multiple systemd service files:

- `wpa_supplicant.service` - uses D-Bus, recommended for NetworkManager users.
- `wpa_supplicant@.service` - accepts the interface name as an argument and starts the wpa_supplicant daemon for this interface. It reads the configuration file in `/etc/wpa_supplicant/wpa_supplicant-interface.conf`.
- `wpa_supplicant-nl80211@.service` - also interface specific, but explicitly forces the `nl80211` driver (see below). The configuration file path is `/etc/wpa_supplicant/wpa_supplicant-nl80211-interface.conf`.
- `wpa_supplicant-wired@.service` - also interface specific, uses the `wired` driver. The configuration file path is `/etc/wpa_supplicant/wpa_supplicant-wired-interface.conf`.

To enable wireless at boot, enable one of the services above on a particular wireless interface, for example:

    # systemctl enable wpa_supplicant@interface

Also enable dhcpcd on the interface:

    # systemctl enable dhcpcd@interface

Note: dhcpcd has a hook that can lauch wpa_supplicant implicitly, see dhcpcd#10-wpa_supplicant.

### 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.

The following example will use desktop notifications to notify the user about the events:

    #!/bin/bash

    case "$2" in
        CONNECTED)
            notify-send "WPA supplicant: connection established";
            ;;
        DISCONNECTED)
            notify-send "WPA supplicant: connection lost";
            ;;
    esac

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

## See also

- WPA Supplicant home
- wpa_cli usage examples
- wpa_supplicant(8)
- wpa_supplicant.conf(5)
- wpa_cli(8)
- Kernel.org wpa_supplicant documentation

Category:

- Wireless Networking