From Gentoo Wiki
Jump to:navigation Jump to:search
This page contains changes which are not marked for translation.
Other languages:
English • ‎русский • ‎中文(中国大陆)‎ • ‎日本語

wpa_supplicant is a WiFi supplicant to handle the authentication part of network management, optionally also bringing up interfaces.


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.[1]

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
broadcom-sta Flag to help users disable features not supported by broadcom-sta driver
crda Use net-wireless/crda for regulatory domain loading instead of in-kernel (4.15+) support
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
fils Add support for Fast Initial Link Setup (802.11ai)
hs2-0 Add support for 802.11u and Passpoint for HotSpot 2.0
macsec Add support for wired macsec
mbo Add support Multiband Operation
mesh Add support for mesh mode
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 2009)
uncommon-eap-types Add support for GPSK, SAKE, GPSK_SHA256, IKEV2 and EKE
wep Add support for Wired Equivalent Privacy (deprecated 2004)
wimax Add support for Wimax EAP-PEER authentication algorithm
wps Add support for Wi-Fi Protected Setup


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

root #emerge --ask net-wireless/wpa_supplicant



Setup for wireless interface

For usage with a single wireless interface only one configuration file will be needed.

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

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 #bzless /usr/share/doc/${P}/wpa_supplicant.conf.bz2 > /etc/wpa_supplicant/wpa_supplicant.conf

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.

FILE /etc/wpa_supplicant/wpa_supplicant_wired.conf

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)

FILE /etc/conf.d/wpa_supplicant
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

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
key_mgmt=IEEE 802.1X (no WPA)
Supplicant PAE state=AUTHENTICATED
selectedMethod=13 (EAP-TLS)

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:

FILE /etc/conf.d/wpa_supplicant
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:

FILE /etc/conf.d/wpa_supplicant
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.

FILE /etc/conf.d/wpa_supplicantset the driver to wext
wpa_supplicant_args="-D wext"

Setup for Gentoo net.* scripts

Tell the network script to use wpa_supplicant:

FILE /etc/conf.d/net

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


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
 > 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
 > set_network 0 ssid "hotel-free-wifi"
 > set_network 0 psk "password"
 > enable_network 0
 <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 
 > 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]

Using wpa_passphrase

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>' '[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
        group=CCMP TKIP
        pairwise=CCMP TKIP

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
        group=CCMP TKIP
        pairwise=CCMP TKIP

Auto-connect to any unsecured network

FILE /etc/wpa_supplicant/wpa_supplicant.conf


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

Check for known bugs

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'
Line: 6 - start of a new network block

Enable logging

Enable logging for Gentoo net.* scripts

FILE /etc/conf.d/netfor usage with the Setup for Gentoo net.* scripts
wpa_supplicant_wlan0="-Dnl80211 -d -f /var/log/wpa_supplicant.log"

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.

External resources