wpa_supplicant
wpa_supplicant is an app for Wi-Fi authentication (a "supplicant" [1] in the technical jargon.)
Installation
As a precondition, wireless support might need to be activated in the kernel as described in IEEE 802.11 section as well as necessary wireless device drivers.[1]
USE flags
USE flags for net-wireless/wpa_supplicant IEEE 802.1X/WPA supplicant for secure wireless transfers
+fils
|
Add support for Fast Initial Link Setup (802.11ai) |
+hs2-0
|
Add support for 802.11u and Passpoint for HotSpot 2.0 |
+mbo
|
Add support Multiband Operation |
+mesh
|
Add support for mesh mode |
ap
|
Add support for access point mode |
broadcom-sta
|
Flag to help users disable features not supported by broadcom-sta driver |
dbus
|
Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc) |
eap-sim
|
Add support for EAP-SIM authentication algorithm |
eapol-test
|
Build and install eapol_test binary |
fasteap
|
Add support for FAST-EAP authentication algorithm |
macsec
|
Add support for wired macsec |
p2p
|
Add support for Wi-Fi Direct mode |
privsep
|
Enable wpa_priv privledge separation binary |
ps3
|
Add support for ps3 hypervisor driven gelic wifi |
qt5
|
Add support for the Qt 5 application and UI framework |
readline
|
Enable support for libreadline, a GNU line-editing library that almost everyone wants |
selinux
|
!!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur |
smartcard
|
Add support for smartcards |
tdls
|
Add support for Tunneled Direct Link Setup (802.11z) |
tkip
|
Add support for WPA TKIP (deprecated due to security flaws in 2009) |
uncommon-eap-types
|
Add support for GPSK, SAKE, GPSK_SHA256, IKEV2 and EKE |
wep
|
Add support for Wired Equivalent Privacy (deprecated due to security flaws in 2004) |
wimax
|
Add support for Wimax EAP-PEER authentication algorithm |
wps
|
Add support for Wi-Fi Protected Setup |
Emerge
After USE flags have been reviewed, install net-wireless/wpa_supplicant using Portage's emerge command:
root #
emerge --ask net-wireless/wpa_supplicant
Direct connect
Quick Connect
To not store any clear text password in history, history is disabled. This should be used temporarily to test that it is possible to connect to the access point.
root #
set +o history
root #
wpa_supplicant -i wlp0s20f3 -c <(wpa_passphrase ssid password) &
root #
set -o history
In case the ssid contains whitespace or special characters it needs double quotes, e.g. "FRITZ!Box 7530 LA"
Process output when connect direct: 'wpa_supplicant -iwlan0 -c /dev/fd/63
Connection for two interfaces
wpa_supplicant can control multiple interfaces (radios) either by running one process for each interface separately or by running just one process and list of options at command line. Each interface is separated with -N argument. Following command would start wpa_supplicant for two interfaces
user $
wpa_supplicant -c wpa1.conf -i wlan0 -D nl80211 -N -c wpa2.conf -i ath0 -D wext
Configuration
Files
Minimal configuration
wpa_supplicant includes a tool to quickly write a network block from the command line for pre-shared key (WPA-PSK aka password) networks, wpa_passphrase.
root #
wpa_passphrase ssid password >> /etc/wpa_supplicant/wpa_supplicant.conf
When password is stored as hash instead of clear text it is required to add key_MGMT=WPA-EAP and eap=PEAP to the configuration file that is not generated by default
Setup for wireless interface
For usage with a single wireless interface only one configuration file will be needed.
# Allow users in the 'wheel' group to control wpa_supplicant
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
# Make this file writable for wpa_gui / wpa_cli
update_config=1
To allow unprivileged users to control the connection using wpa_gui / wpa_cli, make sure the users are in the wheel group.
This file does not exist by default; a well documented template configuration file can be copied from /usr/share/doc/${P}/wpa_supplicant.conf.bz2 where the value of the P variable is the name and version of the currently emerged wpa_supplicant:
root #
bzcat /usr/share/doc/${P}/wpa_supplicant.conf.bz2 > /etc/wpa_supplicant/wpa_supplicant.conf
WPA2 with wpa_supplicant
Connecting to any wireless access point serving YourSSID
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
#ap_scan=0
#update_config=1
network={
ssid="YourSSID"
psk="your-secret-key"
scan_ssid=1
proto=RSN
key_mgmt=WPA-PSK
group=CCMP TKIP
pairwise=CCMP TKIP
priority=5
}
Configuration file with dynamic WEP keys
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="1x-test"
scan_ssid=1
key_mgmt=IEEE8021X
eap=TLS
identity="user@example.com"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
eapol_flags=3
}
Allows more or less all configuration modes
The configuration options are used based on what security policy is used in the selected SSID. This is mostly for testing and is not recommended for normal use
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
network={
ssid="example"
scan_ssid=1
key_mgmt=WPA-EAP WPA-PSK IEEE8021X NONE
pairwise=CCMP TKIP
group=CCMP TKIP WEP104 WEP40
psk="very secret passphrase"
eap=TTLS PEAP TLS
identity="user@example.com"
password="foobar"
ca_cert="/etc/cert/ca.pem"
client_cert="/etc/cert/user.pem"
private_key="/etc/cert/user.prv"
private_key_passwd="password"
phase1="peaplabel=0"
ca_cert2="/etc/cert/ca2.pem"
client_cert2="/etc/cer/user.pem"
private_key2="/etc/cer/user.prv"
private_key2_passwd="password"
}
Setup wired 802.1X
It's possible to have wired connections handled via wpa_supplicant, which is useful for networks using 802.1X. Create a separate configuration file containing the wired configuration. Below example use certificates for authentication, check the wpa_supplicant.conf man page for examples of other methods.
This can be used with wired or roboswitch interface (-Dwired or -Droboswitch on command line)
ctrl_interface=/var/run/wpa_supplicant
eapol_version=1
ap_scan=0
fast_reauth=1
network={
key_mgmt=IEEE8021X
eap=TLS
identity="COMPUTERAACT$@DOMAIN"
ca_cert="/etc/wpa_supplicant/ca.pem"
client_cert="/etc/wpa_supplicant/COMPUTERACCT.pem"
private_key="/etc/wpa_supplicant/COMPUTERAACT.key"
private_key_passwd="secret_password"
eapol_flags=0
}
Since the configuration file contains sensitive information, chmod accordingly.
root #
chmod 600 /etc/wpa_supplicant/wpa_supplicant_wired.conf
wpa_supplicant needs some extra parameters to apply above configuration to the wired interface (eth0) Note that below wpa_supplicant arguments assumes wpa_supplicant is version >=2.6-r2 (-M, CONFIG_MATCH_IFACE=y)
wpa_supplicant_args="-ieth0 -Dwired -c/etc/wpa_supplicant/wpa_supplicant_wired.conf -M -c/etc/wpa_supplicant/wpa_supplicant.conf"
Let wpa_supplicant handle start/stop of the interfaces by removing them from /etc/init.d and enabling the wpa_supplicant daemon
root #
/etc/init.d/net.eth0 stop
root #
/etc/init.d/net.wlan0 stop
root #
rm /etc/init.d/net.wlan0 /etc/init.d/net.eth0
root #
rc-update add wpa_supplicant
root #
/etc/init.d/wpa_supplicant start
Check the status of the wired interface via wpa_cli
Connect directly to the wireless access point from the command line
root #
wpa_cli
wpa_cli v2.8 Copyright (c) 2004-2019, Jouni Malinen <j@w1.fi> and contributors This software may be distributed under the terms of the BSD license. See README for more details. Selected interface 'p2p-dev-wlan0' Interactive mode > interface eth0 Connected to interface 'eth0. > status bssid=00:00:00:00:00:00 freq=0 ssid= id=0 mode=station pairwise_cipher=NONE group_cipher=NONE key_mgmt=IEEE 802.1X (no WPA) wpa_state=COMPLETED ip_address=10.10.10.100 p2p_device_address=bb:bb:bb:bb:bb:bb address=aa:aa:aa:aa:aa:aa Supplicant PAE state=AUTHENTICATED suppPortStatus=Authorized EAP state=SUCCESS selectedMethod=13 (EAP-TLS) eap_tls_version=TLSv1 EAP TLS cipher=ECDHE-RSA-AES256-SHA ...
Setup the network manager
The solutions listed in Network management typically do not work together. Be sure only one of those services is running at a time. Starting more than one network management service will lead to unpredictable results!
Be sure to choose the corresponding setup.
Setup for dhcpcd as network manager
First follow the setup guide for dhcpcd.
Emerge wpa_supplicant (Version >=2.6-r2 is needed in order to get the CONFIG_MATCH_IFACE option added in April 2017):
root #
emerge --ask net-wireless/wpa_supplicant
Using OpenRC
Complete its conf.d file with the -M
option for the wireless network interface:
wpa_supplicant_args="-B -M -c /etc/wpa_supplicant/wpa_supplicant.conf"
In case authentication for the wired interface is needed, this configuration file should look like:
wpa_supplicant_args="-ieth0 -Dwired -c/etc/wpa_supplicant/wpa_supplicant_wired.conf -B -M -c/etc/wpa_supplicant/wpa_supplicant.conf"
With the configuration done, run it as a service:
root #
rc-update add wpa_supplicant default
root #
rc-service wpa_supplicant start
Using Systemd
Systemd allows a simpler per-device setup without needing to create the above conf.d files. As explained under wpa_supplicant item in the Native services section, a service symlink such as wpa_supplicant@wlan0.service
looks for a separate configuration file to manage the device wlan0
in this case.
To configure a specific device this way, first copy or rename the /etc/wpa_supplicant/wpa_supplicant.conf file as /etc/wpa_supplicant/wpa_supplicant-DEVNAME.conf where DEVNAME
should be the name of the device, such as wlan0
.
Then, navigate to /etc/systemd/system/multi-user.target.wants and create the symlink:
root #
ln -s /lib/systemd/system/wpa_supplicant@.service wpa_supplicant@DEVNAME.service
where DEVNAME
is same device name as in the conf file above.
Note the @ signs on both arguments in the symlink step.
Test the system:
root #
systemctl daemon-reload
root #
systemctl start wpa_supplicant@DEVNAME
root #
systemctl status wpa_supplicant@DEVNAME
In case the deprecated WEXT driver is needed, changing the wireless driver can help resolve cases where it associates then immediately disconnects with reason 3. Run wpa_supplicant -h to see a list of the available drivers that were built at compile-time.
wpa_supplicant_args="-D wext"
Setup for Netifrc
To configure Netifrc to use wpa_supplicant:
modules_wlan0="wpa_supplicant"
config_wlan0="dhcp"
After configuration above it is a good idea to change the permissions to ensure that WiFi passwords can not be viewed in plaintext by anyone using the computer:[2]
root #
chmod 600 /etc/wpa_supplicant/wpa_supplicant.conf
Setup for NetworkManager
NetworkManager configured with wpa_supplicant as WiFi backend is able to use D-Bus to start wpa_supplicant when needed. Therefore it is recommended to keep the wpa_supplicant service itself stopped at boot time.
Usage
Using wpa_gui
The simplest way to use wpa_supplicant is by using its interface called wpa_gui. To enable it, build wpa_supplicant with the qt5
USE flag enabled.
Using wpa_cli
Wpa_supplicant also has a command-line user interface. Typing wpa_cli starts its interactive mode with tab-completion. Typing help
at this prompt will list the commands available (click "Expand" to view the output for the wpa_cli command below):
user $
wpa_cli
wpa_cli v2.5 Copyright (c) 2004-2015, Jouni Malinen <j@w1.fi> and contributors This software may be distributed under the terms of the BSD license. See README for more details. Selected interface 'wlan0' Interactive mode > scan OK > scan_results bssid / frequency / signal level / flags / ssid 01:23:45:67:89:ab 2437 0 [WPA-PSK-CCMP+TKIP][WPA2-PSK-CCMP+TKIP][ESS] hotel-free-wifi > add_network 0 > set_network 0 ssid "hotel-free-wifi" OK > set_network 0 psk "password" OK > enable_network 0 OK <3>CTRL-EVENT-SCAN-RESULTS <3>WPS-AP-AVAILABLE <3>Trying to associate with 01:23:45:67:89:ab (SSID='hotel-free-wifi' freq=2437 MHz) <3>Associated with 01:23:45:67:89:ab <3>WPA: Key negotiation completed with 01:23:45:67:89:ab [PTK=CCMP GTK=TKIP] <3>CTRL-EVENT-CONNECTED - Connection to 01:23:45:67:89:ab completed [id=0 id_str=] > save_config OK > quit
For switching to another Wi-Fi:
user $
wpa_cli
wpa_cli v2.5 Copyright (c) 2004-2015, Jouni Malinen <j@w1.fi> and contributors This software may be distributed under the terms of the BSD license. See README for more details. > list_networks network id / ssid / bssid / flags 0 TAMO any 1 ORBI705 any 2 ORBI any 3 Tangerine any 4 271 any 5 POCO X3 Pro any 6 Orbi Guest any 7 hackerspace any 8 HUAWEI-25 a-2 any 9 A1-13 any > select_network 1
More details on how to connect can be found in the Arch Linux wiki.[3]
Editing manually
Of course, the configuration file /etc/wpa_supplicant/wpa_supplicant.conf could also be edited manually. However this can be very laborious if the computer needs to connect to many different access points.
Examples can be found in wpa_supplicant.conf(5) man page and /usr/share/doc/wpa_supplicant-2.4-r3/wpa_supplicant.conf.bz2.
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=wheel
ap_scan=1
network={
bssid=00:50:17:31:1a:11
ssid="YourSSID"
psk="your-secret-key"
scan_ssid=1
proto=RSN
key_mgmt=WPA-PSK
group=CCMP TKIP
pairwise=CCMP TKIP
priority=5
}
Auto-connect to any unsecured network
network={
key_mgmt=NONE
priority=-999
}
Troubleshooting
Name can have spaces postfix
See point in the scan but not connecting? Check SSID for spaces: in wpa_cli scan_results select that point - so you will "see" the space at the end.
In case it does not work as expected try some of the following and analyze the output.
Check for known bugs
Check USE Flags
Two use flags are disabled by default for older wifi protocols due to known security flas: tkip and wep. Enable those use flags for older wifi routers and re-install wpa_supplicant.
rfkill: WLAN soft blocked
If rfkill is blocking the interface, first find the interface number with:
user $
rfkill list
0: ideapad_wlan: Wireless LAN Soft blocked: yes Hard blocked: no 1: ideapad_bluetooth: Bluetooth Soft blocked: yes Hard blocked: no 2: hci0: Bluetooth Soft blocked: yes Hard blocked: no 3: phy0: Wireless LAN Soft blocked: yes Hard blocked: no
Then the interface can be unblocked with:
root #
rfkill unblock 3
Run wpa_supplicant in debug mode
Be sure to stop any running instance of the supplicant:
root #
killall wpa_supplicant
Something like the following options can be used for debugging (click "Expand" to view the output below):
root #
wpa_supplicant -Dnl80211 -iwlan0 -C/var/run/wpa_supplicant/ -c/etc/wpa_supplicant/wpa_supplicant.conf -dd
wpa_supplicant v2.2 random: Trying to read entropy from /dev/random Successfully initialized wpa_supplicant Initializing interface 'wlp8s0' conf '/etc/wpa_supplicant/wpa_supplicant.conf' driver 'nl80211' ctrl_interface '/var/run/wpa_supplicant' bridge 'N/A' Configuration file '/etc/wpa_supplicant/wpa_supplicant.conf' -> '/etc/wpa_supplicant/wpa_supplicant.conf' Reading configuration file '/etc/wpa_supplicant/wpa_supplicant.conf' ctrl_interface='DIR=/var/run/wpa_supplicant GROUP=wheel' update_config=1 Line: 6 - start of a new network block
Enable logging
Enable logging for Gentoo net.* scripts
modules_wlan0="wpa_supplicant"
wpa_supplicant_wlan0="-Dnl80211 -d -f /var/log/wpa_supplicant.log"
config_wlan0="dhcp"
Now, within one terminal issue a tail command to monitor output and restart the net.wlan0 device in another:
root #
tail -f /var/log/wpa_supplicant.log
root #
/etc/init.d/net.wlan0 restart
References
See also
- iwd — a wireless daemon intended to replace wpa_supplicant
External resources
- wpa_supplicant / hostapd Developers' documentation for wpa_supplicant and hostapd
- sample config for wpa_supplicant
- HOWTO: Remote access point with wpa_supplicant (Gentoo Forums)
- Extensible Authentication Protocol (Wikipedia)
- Extensible Authentication Protocol (wiki.freeradius.org)
- wpa_supplicant upstream just accepted patch to allow interface matching
- https://www.kb.cert.org/vuls/id/CHEU-AQNN3Z