Difference between revisions of "WPA supplicant"

From ArchWiki
Jump to: navigation, search
(tagged article for refinement)
(Undo revision 433909 by Mrechte (talk) - wpa_supplicant is already started on specific interface, this example is about scan and scan_results)
 
(207 intermediate revisions by 30 users not shown)
Line 1: Line 1:
 +
[[Category:Wireless networking]]
 +
[[Category:Network configuration]]
 
[[es:WPA supplicant]]
 
[[es:WPA supplicant]]
 
[[it:WPA supplicant]]
 
[[it:WPA supplicant]]
[[ru:WPA Supplicant]]
+
[[ja:WPA supplicant]]
[[zh-CN:WPA Supplicant]]
+
[[ru:WPA supplicant]]
[[Category:Wireless Networking]]
+
[[zh-cn:WPA supplicant]]
{{Poor writing|Excessive wording, lack of flow, arbitrary subsection scheme}}
+
{{Related articles start}}
A network protected by a static (and even dynamic) WEP key can ''very easily'' be compromised by a nefarious user. WPA corrects the problem of the static key, by changing the key at a packet transmitted/received frequency, or once a certain amount of time has passed. This process is performed by a daemon which is tightly bound to your wireless hardware.
+
{{Related|Network configuration}}
 +
{{Related|Wireless network configuration}}
 +
{{Related articles end}}
  
Inferior drivers (in particular those used through ndiswrapper) can provide much frustration when used in conjunction with [http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant]. Therefore, if at all possible, use hardware with proper support and high quality drivers.
+
[http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant] is a cross-platform [[Wikipedia:Supplicant (computer)|supplicant]] with support for WEP, WPA and WPA2 ([[wikipedia:IEEE_802.11i|IEEE 802.11i]] / RSN (Robust Secure Network)). It is suitable for desktops, laptops and embedded systems.
  
==Considerations==
+
''wpa_supplicant'' is the IEEE 802.1X/WPA component that is used in the client stations. It implements key negotiation with a WPA authenticator and it controls the roaming and IEEE 802.11 authentication/association of the wireless driver.
This article assumes that you are familiar with your hardware, and are capable of finding your way around configuration files and configuring your system. It is critical that you have '''read and understood''' the [[Wireless Setup]] article because it is the basis for all that we are going to explain here.
+
  
This document is not a prerequisite if your hardware works out of the box and is handled through a network connection daemon like [[NetworkManager]] or the like. If you prefer to connect to the network using a graphical tool, you should not be reading this.
+
== Installation ==
  
In this article, the '''passphrase''' will refer to the string of [[wikipedia:ASCII|ASCII]] characters provided by the network administrator.  It will typically be enclosed in quotes when used.  The '''psk''' is the hexadecimal form of the passphrase and will not be enclosed in quotes.
+
[[Install]] the {{Pkg|wpa_supplicant}} package.
  
==Installation==
+
Optionally also install {{Pkg|wpa_supplicant_gui}}, which provides ''wpa_gui'', a graphical front-end for ''wpa_supplicant''.
WPA supplicant can be [[Pacman|installed]] with the package {{Pkg|wpa_supplicant}}, available in the [[official repositories]].
+
  
This package has been built with support for a very broad range of wireless hardware. For your information, here is the list, which can be obtained by executing '{{ic|wpa_supplicant}}':
+
== Overview ==
# wpa_supplicant
+
...
+
+
Driver list:
+
+
*HostAP
+
*Prism54
+
*NDISWrapper
+
*AMTEL
+
*IPW (both 2100 and 2200 drivers)
+
*WEXT (Generic Linux wireless extensions)
+
*Wired ethernet
+
  
Most wireless hardware is supported by default by ''wpa_supplicant''. Even if your chipset manufacturer is not listed (which is the most probable case), you can still make use of the Generic Wireless Extensions (WEXT) to connect to a WPA-secured network. Most (~75%) hardware is supported by WEXT, whereas ~20% is compatible by recompiling ''wpa_supplicant'' and/or hardware drivers from scratch, and, unfortunately, the missing 5% which is definitely incompatible. The WPA Supplicant PKGBUILD is available under: {{ic|/var/abs/core/wpa_supplicant}}, with the [[ABS]] tree installed.
+
The first step to connect to an encrypted wireless network is having ''wpa_supplicant'' obtain authentication from a WPA authenticator. In order to do this, ''wpa_supplicant'' must be configured so that it will be able to submit the correct credentials to the authenticator.
  
===Optional: Install the GUI version===
+
Once the authentication is successful, it will be possible to connect to the network by normally obtaining an IP address by setting it manually with the [[Core utilities#ip|iproute2]] suite or using some networking program, like [[systemd-networkd]] or [[dhcpcd]], to configure an ''interface'' to obtain an IP address automatically via DHCP. See also the [[Wireless_network_configuration#Systemd_with_wpa_supplicant_and_static_IP|wireless]] and  [[Network configuration#Configure the IP address|wired]] network configuration articles for methods and examples.
  
Users who prefer a graphical interface can install the {{Pkg|wpa_supplicant_gui}} package, a GUI developed by the same team, from the official repositories.
+
== Connecting with wpa_cli ==
  
==Configuring and connecting==
+
This connection method allows scanning for the available networks, making use of ''wpa_cli'', a command line tool which can be used to interactively configure ''wpa_supplicant'' at runtime. See [http://linux.die.net/man/8/wpa_cli wpa_cli(8)] for details.
WPA Supplicant is packaged with a sample configuration file: {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}. It is well commented and provides many details about network mechanics. All the variables used in this article are described in this file. It also features a lot of configuration samples. It is highly recommended to read it, as well as the manpages {{ic|man wpa_supplicant}} and {{ic|man wpa_supplicant.conf}}.
+
  
A WPA_Supplicant configuration file contains all configuration settings for {{Ic|wpa_supplicant}}. You can create as many as you want and put them anywhere you want, since you must specify which config file to use on each {{ic|wpa_supplicant}} call. Its content is quite simple:
+
In order to use ''wpa_cli'', a control interface must be specified for ''wpa_supplicant'', and it must be given the rights to update the configuration. Do this by creating a minimal configuration file:
* The first part is the global config. It is a series of ''key-value'' lines.
+
* The second part is composed of ''network blocks'', one for each "profile" you want to set.
+
  
For the purpose of simplifying,  we will leave the sample config file where it is and work on a brand new file {{ic|/etc/wpa_supplicant.conf}}.
+
{{hc|/etc/wpa_supplicant/example.conf|2=
 
+
ctrl_interface=/run/wpa_supplicant
There are several ways to manage wpa_supplicant configuration. You can choose among one of the following methods.
+
update_config=1
 
+
===Manual===
+
 
+
====Configuration file====
+
 
+
First you must retrieve all parameters needed to connect to your access point.
+
# iw wlan0 scan
+
More details [[Wireless Setup#Access point discovery|here]].
+
 
+
So now you should know the following parameters for wpa_supplicant:
+
* ssid
+
* proto (optional on unencrypted networks)
+
* key_mgmt
+
* pairwise
+
* group
+
Additionally, you may need authentication parameters (EAP, PEAP, etc.) if you are on such a network, as it is often the case in universities for example.
+
 
+
'''First touch'''
+
 
+
Now you can create a network block in the config file:
+
{{hc|wpa_supplicant.conf|<nowiki>
+
network={
+
        ssid="mywireless_ssid"
+
        psk="secretpassphrase"
+
        # Additional parameters (proto, key_mgmt, etc.)
+
}</nowiki>
+
 
}}
 
}}
  
This is the basic configuration required to get WPA working. The first line is the opening statement for the network block, the second is the SSID of the base station you are wanting to connect to, the third line is the passphrase.
+
Now start ''wpa_supplicant'' with:
  
{{Warning|Do not forget the double quotes around the SSID and the PSK.}}
+
# wpa_supplicant -B -i ''interface'' -c /etc/wpa_supplicant/example.conf
  
'''Passphrase to PSK'''
+
{{Tip|To discover your wireless network interface name, issue the {{ic|ip link}} command.}}
  
On the network-level, the passphrase is never directly used, it is only a convenient way to handle the key for humans.
+
At this point run:
  
You may provide the hex version directly by utilizing the {{Ic|wpa_passphrase}} utility, which is part of the {{Pkg|wpa_supplicant}} package.
+
# wpa_cli
  
*For example:
+
This will present an interactive prompt ({{ic|>}}), which has tab completion and descriptions of completed commands.
{{hc| # wpa_passphrase "mywireless_ssid" "secretpassphrase"|<nowiki>
+
network={
+
        ssid="mywireless_ssid"
+
        #psk="secretpassphrase"
+
        psk=7b271c9a7c8a6ac07d12403a1f0792d7d92b5957ff8dfd56481ced43ec6a6515
+
}
+
</nowiki>}}
+
  
{{Tip| If you're having trouble using this function with certain special characters under your shell, use a temporary text file for the passphrase. You can then direct input so that it is not interpreted by the shell: {{ic| <nowiki># cat passphrase_noquotes.txt | wpa_passphrase "ssid" </nowiki>}} }}
+
{{Tip|The default location of the control socket is {{ic|/var/run/wpa_supplicant/}}, custom path can be set manually with the {{ic|-p}} option to match the ''wpa_supplicant'' configuration. It is also possible to specify the interface to be configured with the {{ic|-i}} option, otherwise the first found wireless interface managed by ''wpa_supplicant'' will be used.}}
  
Note the third line (commented out) is the passphrase, and the fourth line is the PSK. Either is valid to connect, but the PSK is more portable in config files.
+
Use the {{ic|scan}} and {{ic|scan_results}} commands to see the available networks:
  
*Utilizing {{Ic|wpa_passphrase}}, specify your actual SSID and passphrase, and redirect the output to {{ic|/etc/wpa_supplicant.conf}}:
+
> scan
  # wpa_passphrase mywireless_ssid "secretpassphrase" >> /etc/wpa_supplicant.conf
+
  OK
The {{Ic|>>}} will ''append'' the output to {{ic|/etc/wpa_supplicant.conf}}.
+
<3>CTRL-EVENT-SCAN-RESULTS
You can add as many network blocks as you want. wpa_supplicant will know which one to use based upon the detected SSIDs in the area.
+
> scan_results
 +
bssid / frequency / signal level / flags / ssid
 +
00:00:00:00:00:00 2462 -49 [WPA2-PSK-CCMP][ESS] MYSSID
 +
11:11:11:11:11:11 2437 -64 [WPA2-PSK-CCMP][ESS] ANOTHERSSID
  
'''Network block options'''
+
To associate with {{ic|MYSSID}}, add the network, set the credentials and enable it:
  
All of the security parameters need to be specified here. Note that if you are unsure about which value your access point requires, you can use several of them, wpa_supplicant will automatically use the one that works. For example, you can add
+
> add_network
  proto=WEP WPA
+
  0
so that if your access point uses WEP or WPA, it will work in both case. But if it uses RSN (aka WPA2) it will not find it by itself, you have to append it to the other values.
+
> set_network 0 ssid "MYSSID"
 +
> set_network 0 psk "passphrase"
 +
> enable_network 0
 +
<2>CTRL-EVENT-CONNECTED - Connection to 00:00:00:00:00:00 completed (reauth) [id=0 id_str=]
  
If the SSID is hidden, add the following option to the block:
+
If the SSID does not have password authentication, you must explicitly configure the network as keyless by replacing the command {{ic|set_network 0 psk "passphrase"}} with {{ic|set_network 0 key_mgmt NONE}}.
scan_ssid=1
+
If you need to connect to several networks, just define another network block in the same file.
+
You can specify a priority for each network block:
+
priority=17
+
Change the priority at will, recalling that priorities with big numbers are tried first.
+
  
There are a large number of options which are available to set under the network which you can investigate by looking at the original configuration file. In most cases you can use the defaults, and not specify anything further in that section at the moment.
+
{{Note|
 +
* Each network is indexed numerically, so the first network will have index 0.
 +
* The [[wikipedia:Pre-shared_key|PSK]] is computed from the ''quoted'' "passphrase" string, as also shown by the [[#Connecting with wpa_passphrase|wpa_passphrase]] command. Nonetheless, you can enter the PSK directly by passing it to {{ic|psk}} ''without'' quotes.}}
  
'''Global options'''
+
Finally save this network in the configuration file:
  
Lastly, you will need to specify some global options.
+
> save_config
Specify these additional lines at the top of {{ic|/etc/wpa_supplicant.conf}}, with your editor of choice. The following is mandatory.
+
  OK
  ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel
+
  
{{Note|1=For use with {{Pkg|netcfg}}>=2.6.1-1, this should be {{ic|/run/wpa_supplicant}} (note: ''not'' {{ic|/var/run/wpa_supplicant}}). This will, however, break the default for {{Ic|wpa_cli}} (use the {{Ic|-p}} option to override). If this is not changed, one gets errors like "Failed to connect to wpa_supplicant - wpa_ctrl_open: no such file or directory".}}
+
Once association is complete, all that is left to do is obtain an IP address as indicated in the [[#Overview]], for example:
  
There is a lot of optional parameters (have a look at {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}). For example:
+
  # dhcpcd ''interface''
  ap_scan=0
+
fast_reauth=1
+
  
{{Note|Your network information will be stored in plain text format; therefore, it may be desirable to change permissions on the newly created {{ic|/etc/wpa_supplicant.conf}} file (e.g. {{Ic|chmod 0600 /etc/wpa_supplicant.conf}} to make it readable by root only), depending upon how security conscious you are.}}
+
== Connecting with wpa_passphrase ==
  
'''Complete example'''
+
This connection method allows quickly connecting to a network whose SSID is already known, making use of ''wpa_passphrase'', a command line tool which generates the minimal configuration needed by ''wpa_supplicant''. For example:
{{hc|wpa_supplicant.conf|<nowiki>
+
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel
+
fast_reauth = 1
+
ap_scan = 1
+
  
network ={
+
{{hc|$ wpa_passphrase MYSSID passphrase|2=
     ssid     = "mySSID"
+
network={
     proto    = RSN
+
     ssid="MYSSID"
    key_mgmt = WPA-EAP
+
     #psk="passphrase"
    pairwise = TKIP CCMP
+
     psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
    auth_alg = OPEN
+
}
    group    = TKIP
+
    eap      = PEAP
+
    identity = "myUsername"
+
     password = "********"
+
}</nowiki>
+
 
}}
 
}}
  
More sophisticated configurations, like EAPOL or RADIUS authentication are very well detailed in the {{ic|wpa_supplicant.conf}} man page ({{ic|man wpa_supplicant.conf}}). Do not forget to have a look at {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}. These configurations fall out of the scope of this document.
+
This means that ''wpa_supplicant'' can be associated with ''wpa_passphrase'' and simply started with:
  
==== Connection ====
+
# wpa_supplicant -B -i ''interface'' -c <(wpa_passphrase MYSSID passphrase)
  
Now you can try connecting manually.
+
{{Note|Because of the process substitution, you '''cannot''' run this command with [[sudo]] - you will need a root shell. Just pre-pending ''sudo'' will lead to the following error:
 +
Successfully initialized wpa_supplicant
 +
Failed to open config file '/dev/fd/63', error: No such file or directory
 +
Failed to read or parse configuration '/dev/fd/63'
 +
See also [[Help:Reading#Regular user or root]].}}
  
First, bring the Wi-Fi interface up. For the purposes of this example, we will use the interface ''wlan0''.
+
{{Tip|
# ip link set wlan0 up
+
* Use quotes, if the input contains spaces. For example: {{ic|"secret passphrase"}}
 +
* To discover your wireless network interface name, issue the {{ic|ip link}} command.
 +
* Some unusually complex passphrases may require input from a file, e.g. {{ic|wpa_passphrase MYSSID < passphrase.txt}}, or here strings, e.g. {{ic|wpa_passphrase MYSSID <<< "passphrase"}}.
 +
}}
  
Typically, you will be able to use the '''W'''ireless '''EXT'''ensions driver for wpa_supplicant; if you cannot, then you might need to check how to do it with your specific wireless device on the Internet.
+
Finally, you should obtain an IP address as indicated in the [[#Overview]], for example:
  
Issue the following as root:
+
  # dhcpcd ''interface''
  # wpa_supplicant -B -Dwext -i wlan0 -c /etc/wpa_supplicant.conf
+
  
The previous syntax tells wpa_supplicant to use its default hardware configuration (WEXT - Linux '''W'''ireless '''EXT'''ensions) and to associate with the SSID which is specified in {{ic|/etc/wpa_supplicant.conf}}. Also, this association should be performed through the ''wlan0'' wireless interface, and the process should move to the background, ({{Ic|-B}}). For verbose output, add {{Ic|-d}} or {{Ic|-dd}} (for debug) to dump more information to the console. You can find additional examples [http://www.examplenow.com/wpa_supplicant here].
+
== Advanced usage ==
  
In the console output, there should be a line that reads ''''Associated:'''' followed by a MAC address. All that is required now is an IP address.
+
For networks of varying complexity, possibly employing extensive use of [[wikipedia:Extensible_Authentication_Protocol|EAP]], it will be useful to maintain a customised configuration file. For an overview of the configuration with examples, refer to [http://linux.die.net/man/5/wpa_supplicant.conf wpa_supplicant.conf(5)]; for details on all the supported configuration parameters, refer to the example file {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.  
  
{{Note|If you don't want or need to touch {{ic|/etc/wpa_supplicant.conf}} (e.g., when installing Arch), you can pipe {{ic|wpa_passphrase}} to {{ic|wpa_supplicant}}:
+
=== Configuration ===
{{bc|wpa_passphrase essid pass <nowiki>|</nowiki> wpa_supplicant -B -i wlan0 -c /dev/stdin}} }}
+
  
As root, issue:
+
As is clear after reading [[#Connecting with wpa_passphrase]], a basic configuration file can be generated with:
# dhcpcd wlan0
+
  
{{Note|*Do not* request an IP address immediately! You must wait to ensure that you are properly associated with the access point. If you use a script, you can use {{Ic|sleep 10s}} to wait for 10 seconds.}}
+
# wpa_passphrase MYSSID passphrase > /etc/wpa_supplicant/example.conf
  
Verify the interface has received an IP address using the {{Ic|iproute}} package:
+
This will only create a {{ic|network}} section. A configuration file with some more common options may look like:
# ip addr show wlan0
+
+
    wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000
+
    link/ether 00:1C:BF:66:4E:E0 brd ff:ff:ff:ff:ff:ff
+
    inet 192.168.0.62/24 brd 192.168.0.255 scope global eth0
+
    inet6 fe80::224:2bff:fed3:759e/64 scope link
+
      valid_lft forever preferred_lft forever
+
+
If the output is close to the above, you are now connected.
+
  
===wpa_gui and wpa_cli===
+
{{hc|/etc/wpa_supplicant/example.conf|2=<nowiki>
 +
ctrl_interface=/var/run/wpa_supplicant
 +
ctrl_interface_group=wheel
 +
update_config=1
 +
fast_reauth=1
 +
ap_scan=1
  
There are two frontends to wpa_supplicant actually written by the wpa_supplicant developers themselves, "wpa_cli", and "wpa_gui".  wpa_cli is, as you might expect, a command line front end, while "wpa_gui" is a Qt-based frontend to wpa_supplicant. wpa_cli is included with the {{Ic|wpa_supplicant}} package, whereas {{Ic|wpa_supplicant_gui}} is its own package.
+
network={
 +
    ssid="MYSSID"
 +
    psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
 +
}</nowiki>
 +
}}
  
 +
The passphrase can alternatively be defined in clear text by enclosing it in quotes, if the resulting security problems are not of concern:
  
wpa_gui or wpa_cli require a very minimal {{ic|/etc/wpa_supplicant.conf}}. A simple example:
+
{{bc|1=
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=network
+
network={
update_config=1
+
    ssid="MYSSID"
 +
    psk="passphrase"
 +
}
 +
}}
  
This configuration will allow users in the {{Ic|network}} group to control {{Ic|wpa_supplicant}} via the wpa_gui/wpa_cli frontends. The {{Ic|update_config<nowiki>=</nowiki>1}} variable allows these programs {wpa_cli, wpa_gui} to automatically modify the {{ic|/etc/wpa_supplicant.conf}} file, to save new networks, or to make modifications to existing networks.
+
If the network does not have a passphrase, e.g. a public Wi-Fi:
  
Start wpa_supplicant:
+
{{bc|1=
# wpa_supplicant -Dwext -i wlan0 -c /etc/wpa_supplicant.conf -B
+
network={
 +
    ssid="MYSSID"
 +
    key_mgmt=NONE
 +
}
 +
}}
  
where the {{Ic|-D}} option specifies your wireless driver (which is almost always {{Ic|wext}}), {{Ic|-i}} specifies the interface (replace {{Ic|wlan0}} with your wireless interface's name) and {{Ic|-c}} specifies the configuration file to use (normally {{ic|/etc/wpa_supplicant.conf}}). {{Ic|-B}} instructs wpa_supplicant to run as a daemon. You will have to run wpa_supplicant as root (or with root permissions using [[sudo]]), but any user in the {{Ic|network}} group can run wpa_gui or wpa_cli.
+
Further {{ic|network}} blocks may be added manually, or using ''wpa_cli'' as illustrated in [[#Connecting with wpa_cli]]. In order to use ''wpa_cli'', a control interface must be set with the {{ic|ctrl_interface}} option. Setting {{ic|1=ctrl_interface_group=wheel}} allows users belonging to such group to execute ''wpa_cli''. This setting can be used to enable users without root access (or equivalent via sudo etc) to connect to wireless networks. Also add {{ic|1=update_config=1}} so that changes made with ''wpa_cli'' to {{ic|example.conf}} can be saved. Note that any user that is a member of the {{ic|ctrl_interface_group}} group will be able to make changes to the file if this is turned on.
  
wpa_gui or wpa_cli should now be operable.
+
{{ic|<nowiki>fast_reauth=1</nowiki>}} and {{ic|<nowiki>ap_scan=1</nowiki>}} are the ''wpa_supplicant'' options active globally at the time of writing. Whether you need them, or other global options too for that matter, depends on the type of network to connect to. If you need other global options, simply copy them over to the file from {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}.  
  
{{Ic|wpa_cli}}, when invoked without options, will give you a prompt environment, try typing {{Ic|help}} for help.
+
Alternatively, {{ic|wpa_cli set}} can be used to see options' status or set new ones. Multiple network blocks may be appended to this configuration: the supplicant will handle association to and roaming between all of them. The strongest signal defined with a network block usually is connected to by default, one may define {{ic|priority<nowiki>=</nowiki>}} to influence behaviour.  
  
wpa_gui is quite straightforward. If you hit "scan", you will be presented with a list of detected SSIDs, you can double click to add one, you will be given a dialogue box that will let you enter information that you need to associate with your network. Most likely, you will only have to enter your pre-shared key (PSK) if you use WPA/WPA2 or your {{Ic|key0}} for a WEP connection.  The protocol for WPA/WPA2/WEP/Unencrypted should be automatically detected. Things like 802.1X will require a bit more configuration.
+
An advantage to be mentioned in using a customized configuration file at {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} is that it is used by default by [[dhcpcd]]. If you do so, you might want to make a backup of the original and delete the extensive network block examples in it. Otherwise, do not be surprised if your device suddenly connects to networks defined in them. In any case, changes to new versions of the configuration file should of course be [[Pacnew and Pacsave files|merged]].
  
{{Warning|WEP is ''seriously'' broken and should ''never'' be used outside of a laboratory/testing environment. Use ''at least'' WPA (WPA2 is recommended) for a more secure wireless network.}}
+
{{Tip|To configure a network block to a hidden wireless ''SSID'', which by definition will not turn up in a regular scan, the option {{ic|scan_ssid<nowiki>=</nowiki>1}} has to be defined in the network block.}}
  
After you add a network, you can modify it if you do something like changing the PSK. Switch to the 'Manage Networks' tab and select the network you want to Edit / Remove.  You can also add a network without scanning, which you will need to do if you do not broadcast your SSID.
+
=== Connection ===
  
{{Note|Configuring your wireless network to not broadcast its SSID does '''not''' increase the security of your wireless network. It is a trivial exercise to identify hidden SSIDs.}}
+
==== Manual ====
  
{{Note|wpa_cli and wpa_gui will not get you an IP address or set up a proper routing table. They will ''only'' associate you with a wireless access point. }}
+
First start ''wpa_supplicant'' command, whose most commonly used arguments are:
  
==== Action script ====
+
* {{ic|-B}} - Fork into background.
 +
* {{ic|-c ''filename''}} - Path to configuration file.
 +
* {{ic|-i ''interface''}} - Interface to listen on.
 +
* {{ic|-D ''driver''}} - Optionally specify the driver to be used. For a list of supported drivers see the output of {{ic|wpa_supplicant -h}}.
 +
** {{ic|nl80211}} is the current standard, but not all wireless chip's modules support it.
 +
** {{ic|wext}} is currently deprecated, but still widely supported.
  
Write a script like this:
+
See [http://linux.die.net/man/8/wpa_supplicant wpa_supplicant(8)] for the full argument list. For example:
{{hc|~/libexec/wpa_cli-action.sh|
+
case $2 in
+
CONNECTED)
+
dhcpcd -x $1 >/dev/null
+
dhcpcd $1 >/dev/null
+
;;
+
esac
+
}}
+
  
Make it executable and launch {{Ic|wpa_supplicant}} with the preferred configuration file:
+
  # wpa_supplicant -B -i ''interface'' -c /etc/wpa_supplicant/example.conf
  # wpa_supplicant -B -c /etc/wpa_supplicant.conf -i wlan0
+
{{Note|The configuration file must have the {{Ic|ctrl_interface}} setting so that {{Ic|wpa_cli}} can work.}}
+
  
Now launch {{Ic|wpa_cli}} in daemon mode, pointing it to the previously saved script:
+
followed by a method to obtain an ip address manually as indicated in the [[#Overview]], for example:
# wpa_cli -B -a ~/libexec/wpa_cli-action.sh
+
  
=== Automatically start at boot ===
+
# dhcpcd ''interface''
  
Note that the whole process we have been through is ''not'' permanent. It means that on next reboot you will have to provide all the commands again. Here are some method to make the change permanent.
+
{{Tip|''dhcpcd'' has a hook that can lauch ''wpa_supplicant'' implicitly, see [[dhcpcd#10-wpa_supplicant]].}}
  
==== Using systemd ====
+
==== At boot (systemd) ====
This is a two step process. The first step is to enable the wpa_supplicant service. The second is to enable the adapter specific dhcpcd service.
+
  
===== Step 1 =====
+
The ''wpa_supplicant'' package provides multiple [[systemd]] service files:
Copy your configuration file to an adapter specific file (wlan0 is used here):
+
# cp /etc/wpa_supplicant.conf /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
+
  
Enable the systemd target:
+
* {{ic|wpa_supplicant.service}} - uses [[D-Bus]], recommended for [[NetworkManager]] users.
# systemctl enable wpa_supplicant@wlan0.service
+
* {{ic|wpa_supplicant@.service}} - accepts the interface name as an argument and starts the ''wpa_supplicant'' daemon for this interface. It reads the configuration file in {{ic|/etc/wpa_supplicant/wpa_supplicant-''interface''.conf}}.
 +
* {{ic|wpa_supplicant-nl80211@.service}} - also interface specific, but explicitly forces the {{ic|nl80211}} driver (see below). The configuration file path is {{ic|/etc/wpa_supplicant/wpa_supplicant-nl80211-''interface''.conf}}.
 +
* {{ic|wpa_supplicant-wired@.service}} - also interface specific, uses the {{ic|wired}} driver. The configuration file path is {{ic|/etc/wpa_supplicant/wpa_supplicant-wired-''interface''.conf}}.
  
Start the service:
+
To enable wireless at boot, enable an instance of one of the above services on a particular wireless interface. For example, [[enable]] the {{ic|wpa_supplicant@''interface''}} systemd unit.
# systemctl start wpa_supplicant@wlan0.service
+
  
Check the status of the service:
+
Now choose and [[enable]] an instance of a service to obtain an ip address for the particular ''interface'' as indicated in the [[#Overview]]. For example, [[enable]] the {{ic|dhcpcd@''interface''}} systemd unit.
# systemctl status wpa_supplicant@wlan0.service
+
  
After "Active:" it should report "active (running)"
+
{{Tip|''dhcpcd'' has a hook that can lauch ''wpa_supplicant'' implicitly, see [[dhcpcd#10-wpa_supplicant]].}}
===== Step 2 =====
+
We probably already have a dhcpcd service for eth0, but we need to add one, specifically, for the wireless device:
+
  
Enable the systemd target:
+
=== wpa_cli action script ===
# systemctl enable dhcpcd@wlan0.service
+
  
Start the service:
+
''wpa_cli'' can run in daemon mode and execute a specified script based on events from ''wpa_supplicant''. Two events are supported: {{ic|CONNECTED}} and {{ic|DISCONNECTED}}. Some [[environment variables]] are available to the script, see [http://linux.die.net/man/8/wpa_cli wpa_cli(8)] for details.
# systemctl start dhcpcd@wlan0.service
+
  
Check the status of the service:
+
The following example will use [[desktop notifications]] to notify the user about the events:
# systemctl status dhcpcd@wlan0.service
+
  
After "Active:" it should report "active (running)"
+
{{bc|
 +
#!/bin/bash
  
The next reboot should bring up the wireless adapter, associate it with the network, and obtain an IP address. Verify this by:
+
case "$2" in
# ip a
+
    CONNECTED)
 +
        notify-send "WPA supplicant: connection established";
 +
        ;;
 +
    DISCONNECTED)
 +
        notify-send "WPA supplicant: connection lost";
 +
        ;;
 +
esac
 +
}}
  
==== Using boot script ====
+
Remember to make the script executable, then use the {{ic|-a}} flag to pass the script path to ''wpa_cli'':
{{Out of date|Should change to systemd service.}}
+
To automatically start {{Ic|wpa_supplicant}} & {{Ic|wpa_cli}} at boot, add the following lines to {{ic|/etc/rc.local}}:
+
wpa_supplicant -B -D wext -i wlan0 -c /etc/wpa_supplicant.conf
+
wpa_cli -B -a  /path/to/your/wpa_cli-action.sh
+
  
==== Using wpa auto ====
+
$ wpa_cli -a ''/path/to/script''
The {{AUR|wpa_auto}} scripts from the [[AUR]] can be used to start {{Ic|wpa_supplicant}} at boot and automatically run a DHCP client to configure your network connection after you associate to a wireless network, or you could write your own scripts to do so. Higher level wireless/network management utilities are also available that are capable of managing both wireless and wired connections.
+
  
==== netcfg====
+
== Troubleshooting ==
  
[[Pacman|Install]] {{Pkg|netcfg}} from the official repositories.
+
{{Warning|Make sure that you are '''not''' using the default configuration file at {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}}, which is filled with uncommented examples that will lead to lots of random errors in practice. This is a known packaging bug of the {{Pkg|wpa_supplicant}} package: {{Bug|40661}}.}}
  
Create a network profile configuration by copying the example file:
+
=== nl80211 driver not supported on some hardware ===
# cp /etc/network.d/examples/wireless-wpa-config /etc/network.d/wpa_suppl
+
  
Edit the new file to make sure it specifies the right interface, e.g.
+
On some (especially old) hardware, ''wpa_supplicant'' may fail with the following error:
  
  INTERFACE="wlan0"
+
  Successfully initialized wpa_supplicant
 +
nl80211: Driver does not support authentication/association or connect commands
 +
wlan0: Failed to initialize driver interface
  
The rest of the file should be left as-is.
+
This indicates that the standard {{ic|nl80211}} driver does not support the given hardware. The deprecated {{ic|wext}} driver might still support the device:
  
Next, edit {{ic|/etc/conf.d/netcfg}}. Add the network profile to the NETWORKS array:
+
# wpa_supplicant -B -i wlan0 '''-D wext''' -c /etc/wpa_supplicant/example.conf
  
NETWORKS=(... wpa_suppl)
+
If the command works to connect, and the user wishes to use [[systemd]] to manage the wireless connection, it is necessary to [[systemd#Editing provided units|edit]] the {{ic|wpa_supplicant@.service}} unit provided by the package and modify the {{ic|ExecStart}} line accordingly:
  
Finally, add the net-profiles to {{Pkg|systemd}}:
+
{{hc|/etc/systemd/system/wpa_supplicant@.service.d/wext.conf|2=
# systemctl enable netcfg@wpa_suppl
+
[Service]
 +
ExecStart=
 +
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/wpa_supplicant-%I.conf -i%I '''-Dwext'''
 +
}}
  
On the next reboot, the wireless interface will be brought up and wpa_supplicant started. If a known network is available, a connection will be established. For more information on netcfg see [[Network Profiles]].
+
=== Problem with mounted network shares (cifs) and shutdown (Date: 1st Oct. 2015) ===
 +
When you use [[WPA supplicant]] (wlan) to connect to your network you might have the problem that the shutdown takes a very long time. That is because systemd runs against a 3 minute timeout. The reason is that WPA supplicant is shut down to early and you do not have the network online when systemd tries to unmount your share(-s). As a workaround (fix) you can add the following settings to the {{ic|wpa_supplicant.service}} file. This can be done by [[Systemd#Drop-in snippets]]. The result looks like this:
  
==== Wicd ====
+
{{hc|/etc/systemd/system/wpa_supplicant.service.d/override.conf|<nowiki>
Install {{Pkg|wicd}} from the official repositories.
+
[Unit]
 
+
After=dbus.service
Wicd is very straightforward; scan for networks, fill in the required data and connect. You might need to add {{ic|/usr/lib/wicd/autoconnect.py}} to init and power management scripts for reconnecting to networks if auto-connection behavior is expected.
+
Before=network.target
 
+
Wants=network.target
==Troubleshooting==
+
</nowiki>}}
 
+
{{Accuracy}}
+
 
+
Most of the issues are related to the association process; therefore, you should have a deep look at wpa_supplicant's output when you suspect it is misbehaving. Add {{Ic|-d}} (for debug) to increase the verbosity. Usually {{Ic|-dd}} is enough. {{Ic|-dddd}} might be overkill.
+
 
+
When you are inspecting the log, have a look at entries like this one:
+
ioctl[''WHATEVER'']: Operation not supported
+
  
If this is the case, you are experiencing a driver issue. Upgrade your WLAN drivers, or change the {{Ic|-D}} parameter for wpa_supplicant.
+
See more about this bug here: https://github.com/systemd/systemd/issues/1435
  
Another common problem is ''No suitable AP found'' messages. wpa_supplicant seems to have trouble finding hidden ESSIDs. Usually, setting {{Ic|scan_ssid<nowiki>=</nowiki>1}} in your {{Ic|network}} block will take care of this.
+
This bug is not fixed in version 2.3 of {{Pkg|wpa_supplicant}}. In version 2.5 they added {{ic|<nowiki>Before=network.target</nowiki>}} and {{ic|<nowiki>Wants=network.target</nowiki>}} but still miss {{ic|<nowiki>After=dbus.service</nowiki>}}. So after an update to 2.5 you can remove the {{ic|<nowiki>Before=network.target</nowiki>}} and {{ic|<nowiki>Wants=network.target</nowiki>}} from your {{ic|/etc/systemd/system/wpa_supplicant.service.d/override.conf}}. After this bug has been fixed you can just remove {{ic|/etc/systemd/system/wpa_supplicant.service.d/override.conf}}.
  
===Fallback: Recompiling wpa_supplicant===
+
=== Password-related problems ===
Grab a copy of wpa_supplicant's source code from the homepage or from the [[ABS]]. Once downloaded and extracted, have a look at the file '{{ic|.config}}' (yes, it is hidden). The file looks like a kernel configuration file, only much smaller. Have a look at the sections named {{Ic|CONFIG_DRIVER_''DRIVERNAME''}} and choose yes or no, depending upon your driver. Be careful with the options chosen, because you will need to specify an additional path to your wireless drivers' source code in order to correctly compile the low-level association component. Some weird Atheros-based cards may need a fresh wpa_supplicant build compiled against the latest {{Ic|madwifi-svn}} release available. If this is the case, here is an example to help you through the compilation process:
+
  
'''madwifi example''': edit the following lines in the configuration file to look like this. This assumes that you have built madwifi with the ABS and that the source code from the build is stored in {{ic|/var/abs/local/madwifi/src/}}.
+
{{Pkg|wpa_supplicant}} may not work properly if directly passed via stdin particularly long or complex passphrases which include special characters. This may lead to errors such as {{ic|failed 4-way WPA handshake, PSK may be wrong}} when launching {{Pkg|wpa_supplicant}}.
#Driver interface for madwifi driver
+
CONFIG_DRIVER_MADWIFI=y
+
#Change include directories to match with the local settings
+
CFLAGS += -I/var/abs/local/madwifi/src/madwifi
+
  
Once configured, you can proceed with makepkg as usual.
+
In order to solve this try using here strings {{ic|wpa_passphrase <MYSSID> <<< "<passphrase>"}} or passing a file to the {{ic|-c}}  flag instead:
  
=== Unable to use wpa_gui for configuring new networks ===
+
$ wpa_supplicant -i <interface> -c /etc/wpa_supplicant/wpa_supplicant.conf
By default the {{Ic|ap_scan}} variable is set to {{Ic|0}}, which means that wpa_supplicant lets the wireless LAN driver perform AP scanning. If your driver does not support scanning, wpa_supplicant will quit when prompted to scan for wireless networks.
+
In this case, add:
+
ap_scan=1
+
to your {{ic|/etc/wpa_supplicant.conf}}
+
  
=== No IP Address from the DHCP Server ===
+
In some instances it was found that storing the passphrase cleartext in the {{ic|psk}} key of the {{ic|wpa_supplicant.conf}} {{ic|network}} block gave positive results (see [http://www.linuxquestions.org/questions/linux-wireless-networking-41/wpa-4-way-handshake-failed-843394/]). However, this approach is rather insecure. Using {{ic|wpa_cli}} to create this file instead of manually writing it gives the best results most of the time and therefore is the recommended way to proceed.
If you can not get an IP address from the DHCP server when runing {{ic|dhcpcd wlan0}}, use the following command to stop wpa_supplicant and try again:
+
# wpa_cli terminate
+
# iwconfig wlan0 essid "myEssid" key on #maybe "key on" is optional
+
# sleep 15; dhcpcd wlan0
+
  
=== Netcfg association error on boot ===
+
== See also ==
The following is a personal experience. My Broadcom BCM4322 WLAN card is quite slow in associating with the access point on boot up.
+
In {{ic|/etc/network.d/<your_profile>}}, try adding the following line:
+
TIMEOUT=30
+
Reboot to see if that helps.
+
{{Note|{{Ic|TIMEOUT<nowiki>=</nowiki>30}} may be a bit high, but you can always adjust the value to an ideal timeout for your own configuration.}}
+
  
=== Wireless connection frequently drops ===
+
* [http://hostap.epitest.fi/wpa_supplicant/ WPA Supplicant home]
If you connection frequently drops and dmesg show this message:
+
* [https://gist.github.com/buhman/7162560 wpa_cli usage examples]
wlan0: deauthenticating from XX:XX:XX:XX:XX:XX by local choice (reason=3)
+
* [http://linux.die.net/man/8/wpa_supplicant wpa_supplicant(8)]
A workaround is trying disable "group key update interval" option from your router.
+
* [http://linux.die.net/man/5/wpa_supplicant.conf wpa_supplicant.conf(5)]
 +
* [http://linux.die.net/man/8/wpa_cli wpa_cli(8)]
 +
* [http://wireless.kernel.org/en/users/Documentation/wpa_supplicant Kernel.org wpa_supplicant documentation]

Latest revision as of 07:26, 5 May 2016

wpa_supplicant is a cross-platform supplicant with support for WEP, WPA and WPA2 (IEEE 802.11i / RSN (Robust Secure Network)). It is suitable for desktops, laptops and embedded systems.

wpa_supplicant is the IEEE 802.1X/WPA component that is used in the client stations. It implements key negotiation with a WPA authenticator and it controls the roaming and IEEE 802.11 authentication/association of the wireless driver.

Installation

Install the wpa_supplicant package.

Optionally also install wpa_supplicant_gui, which provides wpa_gui, a graphical front-end for wpa_supplicant.

Overview

The first step to connect to an encrypted wireless network is having wpa_supplicant obtain authentication from a WPA authenticator. In order to do this, wpa_supplicant must be configured so that it will be able to submit the correct credentials to the authenticator.

Once the authentication is successful, it will be possible to connect to the network by normally obtaining an IP address by setting it manually with the iproute2 suite or using some networking program, like systemd-networkd or dhcpcd, to configure an interface to obtain an IP address automatically via DHCP. See also the wireless and wired network configuration articles for methods and examples.

Connecting with wpa_cli

This connection method allows scanning for the available networks, making use of wpa_cli, a command line tool which can be used to interactively configure wpa_supplicant at runtime. See wpa_cli(8) for details.

In order to use wpa_cli, a control interface must be specified for wpa_supplicant, and it must be given the rights to update the configuration. Do this by creating a minimal configuration file:

/etc/wpa_supplicant/example.conf
ctrl_interface=/run/wpa_supplicant
update_config=1

Now start wpa_supplicant with:

# wpa_supplicant -B -i interface -c /etc/wpa_supplicant/example.conf
Tip: To discover your wireless network interface name, issue the ip link command.

At this point run:

# wpa_cli

This will present an interactive prompt (>), which has tab completion and descriptions of completed commands.

Tip: The default location of the control socket is /var/run/wpa_supplicant/, custom path can be set manually with the -p option to match the wpa_supplicant configuration. It is also possible to specify the interface to be configured with the -i option, otherwise the first found wireless interface managed by wpa_supplicant will be used.

Use the scan and scan_results commands to see the available networks:

> scan
OK
<3>CTRL-EVENT-SCAN-RESULTS
> scan_results
bssid / frequency / signal level / flags / ssid
00:00:00:00:00:00 2462 -49 [WPA2-PSK-CCMP][ESS] MYSSID
11:11:11:11:11:11 2437 -64 [WPA2-PSK-CCMP][ESS] ANOTHERSSID

To associate with MYSSID, add the network, set the credentials and enable it:

> add_network
0
> set_network 0 ssid "MYSSID"
> set_network 0 psk "passphrase"
> enable_network 0
<2>CTRL-EVENT-CONNECTED - Connection to 00:00:00:00:00:00 completed (reauth) [id=0 id_str=]

If the SSID does not have password authentication, you must explicitly configure the network as keyless by replacing the command set_network 0 psk "passphrase" with set_network 0 key_mgmt NONE.

Note:
  • Each network is indexed numerically, so the first network will have index 0.
  • The PSK is computed from the quoted "passphrase" string, as also shown by the wpa_passphrase command. Nonetheless, you can enter the PSK directly by passing it to psk without quotes.

Finally save this network in the configuration file:

> save_config
OK

Once association is complete, all that is left to do is obtain an IP address as indicated in the #Overview, for example:

# dhcpcd interface

Connecting with wpa_passphrase

This connection method allows quickly connecting to a network whose SSID is already known, making use of wpa_passphrase, a command line tool which generates the minimal configuration needed by wpa_supplicant. For example:

$ wpa_passphrase MYSSID passphrase
network={
    ssid="MYSSID"
    #psk="passphrase"
    psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
}

This means that wpa_supplicant can be associated with wpa_passphrase and simply started with:

# wpa_supplicant -B -i interface -c <(wpa_passphrase MYSSID passphrase)
Note: Because of the process substitution, you cannot run this command with sudo - you will need a root shell. Just pre-pending sudo will lead to the following error:
Successfully initialized wpa_supplicant
Failed to open config file '/dev/fd/63', error: No such file or directory
Failed to read or parse configuration '/dev/fd/63'
See also Help:Reading#Regular user or root.
Tip:
  • Use quotes, if the input contains spaces. For example: "secret passphrase"
  • To discover your wireless network interface name, issue the ip link command.
  • Some unusually complex passphrases may require input from a file, e.g. wpa_passphrase MYSSID < passphrase.txt, or here strings, e.g. wpa_passphrase MYSSID <<< "passphrase".

Finally, you should obtain an IP address as indicated in the #Overview, for example:

# dhcpcd interface

Advanced usage

For networks of varying complexity, possibly employing extensive use of EAP, it will be useful to maintain a customised configuration file. For an overview of the configuration with examples, refer to wpa_supplicant.conf(5); for details on all the supported configuration parameters, refer to the example file /etc/wpa_supplicant/wpa_supplicant.conf.

Configuration

As is clear after reading #Connecting with wpa_passphrase, a basic configuration file can be generated with:

# wpa_passphrase MYSSID passphrase > /etc/wpa_supplicant/example.conf

This will only create a network section. A configuration file with some more common options may look like:

/etc/wpa_supplicant/example.conf
ctrl_interface=/var/run/wpa_supplicant
ctrl_interface_group=wheel
update_config=1
fast_reauth=1
ap_scan=1

network={
    ssid="MYSSID"
    psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
}

The passphrase can alternatively be defined in clear text by enclosing it in quotes, if the resulting security problems are not of concern:

network={
    ssid="MYSSID"
    psk="passphrase"
}

If the network does not have a passphrase, e.g. a public Wi-Fi:

network={
    ssid="MYSSID"
    key_mgmt=NONE
}

Further network blocks may be added manually, or using wpa_cli as illustrated in #Connecting with wpa_cli. In order to use wpa_cli, a control interface must be set with the ctrl_interface option. Setting ctrl_interface_group=wheel allows users belonging to such group to execute wpa_cli. This setting can be used to enable users without root access (or equivalent via sudo etc) to connect to wireless networks. Also add update_config=1 so that changes made with wpa_cli to example.conf can be saved. Note that any user that is a member of the ctrl_interface_group group will be able to make changes to the file if this is turned on.

fast_reauth=1 and ap_scan=1 are the wpa_supplicant options active globally at the time of writing. Whether you need them, or other global options too for that matter, depends on the type of network to connect to. If you need other global options, simply copy them over to the file from /etc/wpa_supplicant/wpa_supplicant.conf.

Alternatively, wpa_cli set can be used to see options' status or set new ones. Multiple network blocks may be appended to this configuration: the supplicant will handle association to and roaming between all of them. The strongest signal defined with a network block usually is connected to by default, one may define priority= to influence behaviour.

An advantage to be mentioned in using a customized configuration file at /etc/wpa_supplicant/wpa_supplicant.conf is that it is used by default by dhcpcd. If you do so, you might want to make a backup of the original and delete the extensive network block examples in it. Otherwise, do not be surprised if your device suddenly connects to networks defined in them. In any case, changes to new versions of the configuration file should of course be merged.

Tip: To configure a network block to a hidden wireless SSID, which by definition will not turn up in a regular scan, the option scan_ssid=1 has to be defined in the network block.

Connection

Manual

First start wpa_supplicant command, whose most commonly used arguments are:

  • -B - Fork into background.
  • -c filename - Path to configuration file.
  • -i interface - Interface to listen on.
  • -D driver - Optionally specify the driver to be used. For a list of supported drivers see the output of wpa_supplicant -h.
    • nl80211 is the current standard, but not all wireless chip's modules support it.
    • wext is currently deprecated, but still widely supported.

See wpa_supplicant(8) for the full argument list. For example:

# wpa_supplicant -B -i interface -c /etc/wpa_supplicant/example.conf

followed by a method to obtain an ip address manually as indicated in the #Overview, for example:

# dhcpcd interface
Tip: dhcpcd has a hook that can lauch wpa_supplicant implicitly, see dhcpcd#10-wpa_supplicant.

At boot (systemd)

The wpa_supplicant package provides multiple systemd service files:

  • wpa_supplicant.service - uses D-Bus, recommended for NetworkManager users.
  • wpa_supplicant@.service - accepts the interface name as an argument and starts the wpa_supplicant daemon for this interface. It reads the configuration file in /etc/wpa_supplicant/wpa_supplicant-interface.conf.
  • wpa_supplicant-nl80211@.service - also interface specific, but explicitly forces the nl80211 driver (see below). The configuration file path is /etc/wpa_supplicant/wpa_supplicant-nl80211-interface.conf.
  • wpa_supplicant-wired@.service - also interface specific, uses the wired driver. The configuration file path is /etc/wpa_supplicant/wpa_supplicant-wired-interface.conf.

To enable wireless at boot, enable an instance of one of the above services on a particular wireless interface. For example, enable the wpa_supplicant@interface systemd unit.

Now choose and enable an instance of a service to obtain an ip address for the particular interface as indicated in the #Overview. For example, enable the dhcpcd@interface systemd unit.

Tip: dhcpcd has a hook that can lauch wpa_supplicant implicitly, see dhcpcd#10-wpa_supplicant.

wpa_cli action script

wpa_cli can run in daemon mode and execute a specified script based on events from wpa_supplicant. Two events are supported: CONNECTED and DISCONNECTED. Some environment variables are available to the script, see wpa_cli(8) for details.

The following example will use desktop notifications to notify the user about the events:

#!/bin/bash

case "$2" in
    CONNECTED)
        notify-send "WPA supplicant: connection established";
        ;;
    DISCONNECTED)
        notify-send "WPA supplicant: connection lost";
        ;;
esac

Remember to make the script executable, then use the -a flag to pass the script path to wpa_cli:

$ wpa_cli -a /path/to/script

Troubleshooting

Warning: Make sure that you are not using the default configuration file at /etc/wpa_supplicant/wpa_supplicant.conf, which is filled with uncommented examples that will lead to lots of random errors in practice. This is a known packaging bug of the wpa_supplicant package: FS#40661.

nl80211 driver not supported on some hardware

On some (especially old) hardware, wpa_supplicant may fail with the following error:

Successfully initialized wpa_supplicant
nl80211: Driver does not support authentication/association or connect commands
wlan0: Failed to initialize driver interface

This indicates that the standard nl80211 driver does not support the given hardware. The deprecated wext driver might still support the device:

# wpa_supplicant -B -i wlan0 -D wext -c /etc/wpa_supplicant/example.conf

If the command works to connect, and the user wishes to use systemd to manage the wireless connection, it is necessary to edit the wpa_supplicant@.service unit provided by the package and modify the ExecStart line accordingly:

/etc/systemd/system/wpa_supplicant@.service.d/wext.conf
[Service]
ExecStart=
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/wpa_supplicant-%I.conf -i%I -Dwext

Problem with mounted network shares (cifs) and shutdown (Date: 1st Oct. 2015)

When you use WPA supplicant (wlan) to connect to your network you might have the problem that the shutdown takes a very long time. That is because systemd runs against a 3 minute timeout. The reason is that WPA supplicant is shut down to early and you do not have the network online when systemd tries to unmount your share(-s). As a workaround (fix) you can add the following settings to the wpa_supplicant.service file. This can be done by Systemd#Drop-in snippets. The result looks like this:

/etc/systemd/system/wpa_supplicant.service.d/override.conf
[Unit]
After=dbus.service
Before=network.target
Wants=network.target

See more about this bug here: https://github.com/systemd/systemd/issues/1435

This bug is not fixed in version 2.3 of wpa_supplicant. In version 2.5 they added Before=network.target and Wants=network.target but still miss After=dbus.service. So after an update to 2.5 you can remove the Before=network.target and Wants=network.target from your /etc/systemd/system/wpa_supplicant.service.d/override.conf. After this bug has been fixed you can just remove /etc/systemd/system/wpa_supplicant.service.d/override.conf.

Password-related problems

wpa_supplicant may not work properly if directly passed via stdin particularly long or complex passphrases which include special characters. This may lead to errors such as failed 4-way WPA handshake, PSK may be wrong when launching wpa_supplicant.

In order to solve this try using here strings wpa_passphrase <MYSSID> <<< "<passphrase>" or passing a file to the -c flag instead:

$ wpa_supplicant -i <interface> -c /etc/wpa_supplicant/wpa_supplicant.conf

In some instances it was found that storing the passphrase cleartext in the psk key of the wpa_supplicant.conf network block gave positive results (see [1]). However, this approach is rather insecure. Using wpa_cli to create this file instead of manually writing it gives the best results most of the time and therefore is the recommended way to proceed.

See also