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


As a precondition, wireless support needs to be activated in the kernel as described in Wifi/IEEE_802.11.

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
dbus Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc) global
eap-sim Add support for EAP-SIM authentication algorithm local
fasteap Add support for FAST-EAP authentication algorithm local
gnutls Add support for net-libs/gnutls (TLS 1.0 and SSL 3.0 support) global
hs2-0 Add support for 802.11u and Passpoint for HotSpot 2.0 local
libressl Use dev-libs/libressl as SSL provider (might need ssl USE flag), packages should not depend on this USE flag global
p2p Add support for Wi-Fi Direct mode local
ps3 Add support for ps3 hypervisor driven gelic wifi local
qt5 Add support for the Qt 5 application and UI framework global
readline Enable support for libreadline, a GNU line-editing library that almost everyone wants global
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur global
smartcard Add support for smartcards local
ssl Add support for Secure Socket Layer connections global
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 wpa_supplicant


The necessary wireless device drivers need to be installed. 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.

Setup for dhcpcd as network manager

Emerge wpa_supplicant version >=2.6-r1 in order to get the CONFIG_MATCH_IFACE option added in April 2017,

root #emerge -1 --ask >=net-wireless/wpa_supplicant-2.6-r1

complete its conf.d file with the new -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:[1]

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 qt4 or qt5 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.

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

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.

Run wpa_supplicant in debug mode

root #killall wpa_supplicant
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 flag enabled.

root #USE="debug" emerge --ask wpa_supplicant
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

External resources