From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

wpa_supplicant is a wifi supplicant to handle network authentication.


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 local
eap-sim Add support for EAP-SIM authentication algorithm local
eapol_test Build and install eapol_test binary local
fasteap Add support for FAST-EAP authentication algorithm local
hs2-0 Add support for 802.11u and Passpoint for HotSpot 2.0 local
p2p Add support for Wi-Fi Direct mode local
privsep Enable wpa_priv privledge separation binary local
ps3 Add support for ps3 hypervisor driven gelic wifi local
smartcard Add support for smartcards local
suiteb Enable enable NSA Suite B encryption local
tdls Add support for Tunneled Direct Link Setup (802.11z) local
uncommon-eap-types Add support for GPSK, SAKE, GPSK_SHA256, IKEV2 and EKE local
wimax Add support for Wimax EAP-PEER authentication algorithm local
wps Add support for Wi-Fi Protected Setup local


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

root #emerge --ask net-wireless/wpa_supplicant



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.


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

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

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


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

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

        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


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
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. iwd is the intended replacement for wpa_supplicant.

External resources