wpa_supplicant

Resources

Home

Wikipedia

Package information

GitWeb

Bugs (upstream)

wpa_supplicant(8)

wpa_supplicant.conf(5)

wpa_supplicant is a wifi supplicant to handle network authentication.

Installation

As a precondition, wireless support might need to be activated in the kernel as described in Wifi/IEEE_802.11 as well as necessary wireless device drivers.

USE flags

USE flags for net-wireless/wpa_supplicant IEEE 802.1X/WPA supplicant for secure wireless transfers

+ap	Add support for access point mode
+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
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
gui	Enable support for a graphical user interface
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
qt6	Add support for the Qt 6 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

Data provided by the Gentoo Package Database · Last update: 2025-03-04 16:20 More information about USE flags

Emerge

After USE flags have been reviewed, install net-wireless/wpa_supplicant using Portage's emerge command:

root #emerge --ask net-wireless/wpa_supplicant

Configuration

Files

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

Global

For usage with a single wireless interface only one configuration file will be needed. This file does not exist by default; a 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 #bzless /usr/share/doc/${P}/wpa_supplicant.conf.bz2 > /etc/wpa_supplicant/wpa_supplicant.conf

Next, edit the file:

FILE /etc/wpa_supplicant/wpa_supplicant.conf

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

Setup for dhcpcd as network manager

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

complete its conf.d file with the -M option

FILE /etc/conf.d/wpa_supplicant

wpa_supplicant_args="-B -M -c/etc/wpa_supplicant/wpa_supplicant.conf"

and run it as a service:

root #rc-update add wpa_supplicant default

root #/etc/init.d/wpa_supplicant start

Setup for Gentoo net.* scripts

Tell the network script to use wpa_supplicant:

FILE /etc/conf.d/net

modules_wlan0="wpa_supplicant"
config_wlan0="dhcp"

After configuration below 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:

root #chmod 600 /etc/wpa_supplicant/wpa_supplicant.conf

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

root #echo "update_config=1" >>/etc/wpa_supplicant/wpa_supplicant.conf

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

More details on how to connect can be found in the Arch Linux wiki.

Using wpa_passphrase

wpa_supplicant includes a tool to quickly write a network block from the command line for Preshared-Key (PSK aka password) networks, wpa_passphrase.

root #wpa_passphrase <ssid> [passphrase]

The SSID is required. If omitted, the passphrase can be entered when prompted.

The resulting output can then be copied or piped to /etc/wpa_supplicant/wpa_supplicant.conf.

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 man 5 wpa_supplicant.conf and /usr/share/doc/wpa_supplicant-2.4-r3/wpa_supplicant.conf.bz2.

WPA2 with wpa_supplicant

Connecting to any wireless access point serving YourSSID

FILE /etc/wpa_supplicant/wpa_supplicant.conf

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
}

Using bssid to specify which access point it should connect to using its MAC address, in case there are repeaters in place. Remember to use wpa_passphrase <ssid> [passphrase] to generate the psk

FILE /etc/wpa_supplicant/wpa_supplicant.conf

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

FILE /etc/wpa_supplicant/wpa_supplicant.conf

network={
        key_mgmt=NONE
        priority=-999
}

Troubleshooting

In case it does not work as expected try some of the following and analyze the output.

Check for known bugs

• Gentoo bugtracker: known bugs
• Upstream's mailing list archive

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

SECTION NEEDS REVIEW

By default, wpa_supplicant performs very little debugging without the debug USE flag enabled.

root #USE="debug" emerge --ask wpa_supplicant

NOTE: As of my testing on Aug 6, 2018; debug is not a valid useflag for wpa_supplicant. You could add -dd to the wpa_supplicant_args var in /etc/conf.d/wpa_supplicant to enable debugging output. Additionally the section Enable logging for Gentoo net.* scripts has a valid way to enable debug messaging

Enable logging for Gentoo net.* scripts

FILE /etc/conf.d/netfor usage with the Setup 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

See also

• iwd — an up-and-coming wireless daemon for Linux. iwd is the intended replacement for wpa_supplicant.

External resources

• 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
• http://www.kb.cert.org/vuls/id/CHEU-AQNN3Z