wpa_supplicant

Related articles
Network configuration
Wireless network configuration
iwd
wpa_supplicant
is a cross-platform
supplicant
with support for WPA, WPA2 and WPA3 (
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_gui
AUR
which provides
wpa_gui
, a graphical front-end for
wpa_supplicant
, or
wpa-cute
AUR
which is a fork from an earlier version of
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.
Once you are authenticated you need to assign an IP address, see
Network configuration#IP addresses
.
Connecting with wpa_cli
This connection method allows scanning for available networks, making use of
wpa_cli
, a command line tool which can be used to  configure
wpa_supplicant
. 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/wpa_supplicant.conf
ctrl_interface=/run/wpa_supplicant
update_config=1
Warning
Setting
update_config
to 1 allows
wpa_supplicant
to overwrite the configuration file. When overwriting,
wpa_supplicant
will reset file permissions according to your default
umask
. It might accidentally make the file readable to everyone thus exposing your passwords, if your system is multiuser.
wpa_supplicant
can now be started with:
# wpa_supplicant -B -i
interface
-c /etc/wpa_supplicant/wpa_supplicant.conf
Note
The
wpa_cli terminate
command can be used to stop the
wpa_supplicant
instance.
Tip
To determine your wireless network interface name, see
Network configuration#Listing network interfaces
.
At this point run:
# wpa_cli
This will present an interactive prompt (
>
), which has tab completion and descriptions of completed commands. There is also a
help
command.
Tip
The default location of the control socket is
/var/run/wpa_supplicant/
. A custom path can be set manually with the
-p
option to match the
wpa_supplicant
configuration.
It is 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=]
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
Multiple network configurations can be added. Each network is indexed numerically, so the first network will have index 0.
If no connection can be established, some information will be printed, and periodic attempts will be made. As part of the periodic attempts, a user prompt will also be given periodically. Issuing the
disable_network 0
command will stop the periodic attempts and return to a steady user prompt.
If a passphrase is given to
set_network
, the
PSK
will be computed from the
quoted
"passphrase" string. Alternatively, you can use the
wpa_passphrase
command and enter the PSK directly by passing it to
psk
without
quotes.
Finally save this network in the configuration file and quit
wpa_cli
:
> save_config
OK
> quit
Once association is complete, you must obtain an IP address. See
Network configuration#Network management
for details.
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 started with:
# wpa_supplicant -B -i
interface
-c <(wpa_passphrase
MYSSID
passphrase
)
Tip
The previous command requires a
root shell
.
Use quotes, if the input contains spaces. For example:
"secret passphrase"
.
To determine your wireless network interface name, see
Network configuration#Listing network interfaces
.
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.
Finally, you should obtain an IP address, see
Network configuration#IP addresses
.
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]
Configuration
As explained in
#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 also the ability of
#Connecting with wpa_cli
and some other common options may look like:
/etc/wpa_supplicant/example.conf
# Giving configuration update rights to wpa_cli
ctrl_interface=/run/wpa_supplicant
ctrl_interface_group=wheel
update_config=1

# AP scanning
ap_scan=1

# ISO/IEC alpha2 country code in which the device is operating
country=US

# network section generated by wpa_passphrase
network={
    ssid="MYSSID"
    psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
}
If security is not a concern, the passphrase can also be defined in clear text in the
network
section by enclosing it in quotes:
psk="passphrase"
If the network does not have a passphrase, e.g. a public Wi-Fi:
network={
   ssid="MYSSID"
   key_mgmt=NONE
}
To connect to a WPA-Enterprise network, see
#802.1x/radius
.
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.
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
followed by a method to obtain an ip address manually as indicated in the
#Overview
, for example:
# dhcpcd
interface
Tip
dhcpcd
has a hook that can launch
wpa_supplicant
implicitly, see
dhcpcd#10-wpa_supplicant
.
While testing arguments/configuration it may be helpful to launch
wpa_supplicant
in the foreground (i.e.
without
the
-B
option) for better debugging messages.
At boot (systemd)
The
wpa_supplicant
package provides multiple
systemd
service files:
wpa_supplicant.service
- uses
D-Bus
, recommended for
NetworkManager
users.
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. Useful when using
systemd-networkd
.
wpa_supplicant-nl80211@
interface
.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@
interface
.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 an instance of one of the above services on a particular wireless interface. For example,
enable
the
wpa_supplicant@
interface
systemd unit.
Now choose and
enable
an instance of a service to obtain an ip address for the particular
interface
as indicated in the
#Overview
. For example,
enable
the
dhcpcd@
interface
systemd unit.
Tip
dhcpcd
has a hook that can launch
wpa_supplicant
implicitly, see
dhcpcd#10-wpa_supplicant
.
802.1x/radius
To connect a wired adapter using 802.1x/
radius
you will need to specify some configurations and enable the necessary service for the adapter. This is useful for headless servers using
systemd-networkd
.
You may need to specify the
wired
driver with the
-D wired
command line option (see
#Manual
) if the default driver does not support your adapter.
Replace
adapter
with the wired adapter you wish to connect, and adapt the settings to match your 802.1x/radius requirements.
/etc/wpa_supplicant/wpa_supplicant-wired-
adapter
.conf
ctrl_interface=/run/wpa_supplicant
ap_scan=0
network={
  key_mgmt=IEEE8021X
  eap=PEAP
  identity="
user_name
"
  password="
user_password
"
  phase2="autheap=MSCHAPV2"
}
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
.
To use the hash instead of the plaintext password, you can use the
hash
keyword:
password=hash:
hash_of_plaintext_password
To hash your password:
$ iconv -t utf16le | openssl dgst -md4 -provider legacy
After invoking the command above, provide your plain password and then press
Ctrl+d
.
Note
Hashing the password does not improve the security nor avoid the risk of exposing secrets.
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.
The following example will use
notify-send
to notify the user about the events:
#!/bin/sh

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
Roaming
When connected to a wireless network with multiple access points,
wpa_supplicant
is typically responsible for roaming between access points.  Choosing a new access point requires
wpa_supplicant
to perform a scan of available networks, which causes a brief interruption in connectivity to the current access point while the wireless radio scans other frequencies.  After a scan, if
wpa_supplicant
detects a closer access point (BSSID) in the current network (SSID), in terms of signal strength (RSSI), it will re-associate to the closer access point.
The default configuration of
wpa_supplicant
has relatively timid roaming: it will rescan only when the association to the current access point is lost.  This means that, if a client moves far away from its current access point, but not far enough to completely lose signal, the client will keep using the weak signal instead of roaming to a closer access point.
To make
wpa_supplicant
more aggressive about roaming, set the
bgscan
parameter in the configuration file, such as:
bgscan="simple:30:-70:3600"
The above example will cause
wpa_supplicant
to scan every 30 seconds when the signal is weak (below -70), and every 3600 seconds otherwise.
bgscan
can be specified either in specific
network
blocks or globally for all networks.
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 to random errors in practice (
FS#40661
).
Debugging connection failures
In order to determine why you are unable to connect to an access point you can run
wpa_supplicant
with the
-d
flag for debug messages, wait a couple seconds then look for lines that list SSIDs and the reason they were not connected to. For example:
# wpa_supplicant -i wlan0 -c /etc/wpa_supplicant/example.conf -d
wlan0: Selecting BSS from priority group 0
wlan0: 0: d2:93:5b:b7:5d:d2 ssid=
wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
wlan0:    skip - SSID not known
wlan0: 1: f2:93:5b:b7:5d:d2 ssid=
wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
wlan0:    skip - SSID not known
wlan0: 2: b2:93:5b:b7:5d:d2 ssid=
wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
wlan0:    skip - SSID not known
wlan0: 3: b0:93:5b:b7:5d:d2 ssid='Access Point 1' wpa_ie_len=0 rsn_ie_len=20 caps=0x511 level=-55 freq=5180  wps
wlan0:    skip - SSID mismatch
wlan0: 4: c4:13:e2:33:42:20 ssid='\x00\x00\x00\x00' wpa_ie_len=22 rsn_ie_len=0 caps=0x111 level=-69 freq=5260
wlan0:    skip - SSID mismatch
wlan0: 5: c4:13:e2:33:42:24 ssid='Home' wpa_ie_len=0 rsn_ie_len=26 caps=0x1111 level=-69 freq=5260
wlan0:    skip RSN IE - no mgmt frame protection enabled but AP requires it
wlan0:    reject due to mismatch with WPA/WPA2
...
In this case we are trying to connect to an access point with the SSID
home
. The reason the connection fails is
skip RSN IE - no mgmt frame protection enabled but AP requires it
, so we need to add
ieee80211w=2
to our configuration file.
nl80211 driver not supported on some hardware
On some (especially old) hardware,
wpa_supplicant
may fail with the following error:
Successfully initialized wpa_supplicant
nl80211: Driver does not support authentication/association or connect commands
wlan0: Failed to initialize driver interface
This indicates that the standard
nl80211
driver does not support the given hardware. The deprecated
wext
driver might still support the device:
# wpa_supplicant -B -i wlan0
-D wext
-c /etc/wpa_supplicant/example.conf
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:
/etc/systemd/system/wpa_supplicant@.service.d/wext.conf
[Service]
ExecStart=
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/wpa_supplicant-%I.conf -i%I
-Dnl80211,wext
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) § EXAMPLES
). 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.conf
network
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
If the institution the user studies or works at did not upgrade their network tunnel's encryption to at least TLS 1.2 yet and still uses TLS 1.0 or 1.1 for network traffic encryption in their Eduroam Wi-Fi infrastructure, OpenSSL 3.x throws an "unsupported protocol" error and the client machine's Wi-Fi backend (either
wpa_supplicant
or
iwd
) refuses to establish a connection any further. Fortunately, an easy workaround exists for OpenSSL's TLS 1.0 and 1.1 deprecation without making the client computer's whole Wi-Fi connection stack globally vulnerable to attacks, although it only works with
NetworkManager
.
Consult
NetworkManager#WPA Enterprise connections fail to authenticate with OpenSSL "unsupported protocol" error
for the solution.
Connman users can visit the
ConnMan#Connecting to eduroam (802.1X)
article for their own version of the fix.
Connections to pure WPA3-SAE access points
Make sure to define the following within the network block of the configuration to enable connections to pure WPA3 access points:
ssid="network SSID"
key_mgmt=SAE
sae_password="the.literal.wifi.password"
ieee80211w=2
Additionally, Intel Wi-Fi 6 cards may need
sae_pwe=1
in the main (non network) section of the config file.
Connections to mixed WPA2-PSK/WPA3-SAE access points
Mixed WPA2-PSK/WPA3-SAE access points will require an alternative setting for key_mgmt as shown below:
ssid="network SSID"
key_mgmt=WPA-PSK-SHA256
psk=xxx
ieee80211w=2
Hardware 802.11w support
You can check for hardware support of MFP/PMF (
M
anagement
F
rame
P
rotection /
P
rotected
M
anagement
F
rames) on the interface client by running:
$ iw phy phy0 info | grep 00-0f-ac:6
Most Wi-Fi devices support this standard introduced in 2009, except some limited (aka non x86_64 related) or old hardware.
Non-ASCII characters in wpa_cli scan_result
/etc/wpa_supplicant/wpa_supplicant.conf
uses normalized access points names in UTF-8. If in
wpa_cli scan_result
you see something like
KEBAP\xc3\x87I HAL\xc4\xb0L
, we want to convert escaped hex sequences into their actual characters:
$ echo -e 'KEBAP\xc3\x87I HAL\xc4\xb0L'
will result into
KEBAPÇI HALİL
to be inserted into the configuration file.
See the
echo(1)
man page for details about the
-e
option.
Tips and tricks
Suppress excessive log entries in journal
With the default configuration,
wpa_supplicant
will sometimes excessively log information to the
journal
, such as the following every second:
Aug 23 15:11:15 mainpc wpa_supplicant[1206]: wlp12s0: CTRL-EVENT-SIGNAL-CHANGE above=1 signal=-60 noise=9999 txrate=154800
The factual accuracy of this article or section is disputed.
Reason:
"impossible to eliminate these log entries by setting the log level to WARNING or higher"?
LogLevelMax=4
does exactly that: logs above the warning level are discarded. (Discuss in
Talk:Wpa supplicant
)
It is impossible to eliminate these log entries by setting
wpa_supplicant'
s own log level to WARNING or higher. The simplest way to do so is by instead adding a systemd configuration file:
/etc/systemd/system/wpa_supplicant.service.d/quieter_logs.conf
[Service]
LogLevelMax=4
Then,
daemon-reload
systemd and
restart
wpa_supplicant.service
.
Note
Remember to reset the log level (e.g. by deleting this file), when troubleshooting internet connectivity or
wpa_supplicant
issues, as it can suppress log entries that contain useful information.
See also
wpa_supplicant home
wpa_supplicant README
- contains full documentation of project, including
wpa_cli
commands not listed in manpage.
wpa_cli usage examples
wpa_supplicant(8)
wpa_supplicant.conf(5)
wpa_cli(8)
Kernel.org wpa_supplicant documentation