Difference between revisions of "WPA supplicant"

From ArchWiki
Jump to: navigation, search
(Connecting with wpa_cli: ctrl_interface)
(Undo revision 433909 by Mrechte (talk) - wpa_supplicant is already started on specific interface, this example is about scan and scan_results)
 
(171 intermediate revisions by 25 users not shown)
Line 1: Line 1:
[[Category:Wireless Networking]]  
+
[[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]]
{{Article summary start}}
+
[[zh-cn:WPA supplicant]]
{{Article summary text|Setup and usage of wpa_supplicant}}
+
{{Related articles start}}
{{Article summary heading|Related}}
+
{{Related|Network configuration}}
{{Article summary wiki|Network Configuration}}
+
{{Related|Wireless network configuration}}
{{Article summary wiki|Wireless Setup}}
+
{{Related articles end}}
{{Article summary end}}
+
  
[http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant] is a cross-platform [[Wikipedia:Supplicant (computer)|WPA Supplicant]] with support for WPA and WPA2 ([https://en.wikipedia.org/wiki/IEEE_802.11i IEEE 802.11i] / RSN (Robust Secure Network)). It is suitable for both desktop/laptop computers and embedded systems. {{ic|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 wlan driver.
+
[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.
 +
 
 +
''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 ==
 
== Installation ==
  
Install {{Pkg|wpa_supplicant}} from the [[official repositories]].
+
[[Install]] the {{Pkg|wpa_supplicant}} package.
 +
 
 +
Optionally also install {{Pkg|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.
  
Optionally {{Pkg|wpa_supplicant_gui}} can be installed which provides {{ic|wpa_gui}}; a graphical frontend for {{ic|wpa_supplicant}} using the {{pkg|qt4}} toolkit.
+
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.
  
 
== Connecting with wpa_cli ==
 
== Connecting with wpa_cli ==
  
To associate with a wireless access point (WAP) using {{ic|wpa_supplicant}}, use the including command line tool {{ic|wpa_cli}}. In order to use {{ic|wpa_cli}}, a ''control interface'' must be specified for {{ic|wpa_supplicant}}. Do this by creating a config file containing {{ic|ctrl_interface=/var/run/wpa_supplicant}}.
+
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.
  
{{Tip|Refer to the provided {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} 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:
  
To enable saving changes made using wpa_cli, append the line {{ic|update_config=1}} to the configuration file. Start wpa_supplicant with
+
{{hc|/etc/wpa_supplicant/example.conf|2=
 +
ctrl_interface=/run/wpa_supplicant
 +
update_config=1
 +
}}
  
  # wpa_supplicant -B -i ''interface'' -c ''/path/to/config''
+
Now start ''wpa_supplicant'' with:
  
Invoke {{ic|wpa_cli}} with no arguments to get an interactive prompt ({{ic|>}}). The prompt has tab completion and descriptions of completed commands. The command {{ic|scan}} initiates a scan; a notification is issued when the scan is complete. Then:
+
# wpa_supplicant -B -i ''interface'' -c /etc/wpa_supplicant/example.conf
  
  > scan_results
+
{{Tip|To discover your wireless network interface name, issue the {{ic|ip link}} command.}}
  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'', tell {{ic|wpa_supplicant}} about it. Each network is indexed numerically, so the first network will have index zero. The [http://en.wikipedia.org/wiki/Pre-shared_key PSK] can be provided without quotes as an alternative to providing the passphrase in this example:
+
At this point run:
  
  > add_network
+
# wpa_cli
  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=]
+
  
To save this network in the configuration file,
+
This will present an interactive prompt ({{ic|>}}), which has tab completion and descriptions of completed commands.
  
  > save_config
+
{{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.}}
  OK
+
  
Now that association with the WAP is complete, obtain an IP address via {{Pkg|dhcpcd}} or using the {{Pkg|iproute2}} tools.
+
Use the {{ic|scan}} and {{ic|scan_results}} commands to see the available networks:
  
== Configuration ==
+
> 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
  
{{Pkg|wpa_supplicant}} provides a reference configuration file located at {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} which contains detailed documentation for the all available options and their utilisation.
+
To associate with {{ic|MYSSID}}, add the network, set the credentials and enable it:
  
In its simplest form, a configuration file requires only a network block. For example:
+
> 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=]
  
{{hc|/etc/wpa_supplicant/foobar.conf|2=
+
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}}.
network={
+
    ssid="..."
+
}
+
}}
+
  
This can easily be generated using the {{ic|wpa_passphrase}} tool. For example:
+
{{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.}}
  
{{hc|$ wpa_passphrase ''essid'' ''passphrase''|2=
+
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:
 +
 
 +
{{hc|$ wpa_passphrase MYSSID passphrase|2=
 
network={
 
network={
     ssid="''essid''"
+
     ssid="MYSSID"
     #psk="''passphrase''"
+
     #psk="passphrase"
     psk=f5d1c49e15e679bebe385c37648d4141bc5c9297796a8a185d7bc5ac62f954e3
+
     psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
 
}
 
}
 
}}
 
}}
  
Now both {{ic|wpa_supplicant}} and {{ic|wpa_passphrase}} can be combined to associate with almost all WPA2 (Personal) networks:
+
This means that ''wpa_supplicant'' can be associated with ''wpa_passphrase'' and simply started with:
  
  # wpa_supplicant -B -i ''interface'' -c <(wpa_passphrase ''essid'' ''passphrase'')
+
  # wpa_supplicant -B -i ''interface'' -c <(wpa_passphrase MYSSID passphrase)
  
All that remains is to simply connect using a [[Network Configuration#Static IP Address|static IP]] or [[Network Configuration#Dynamic IP Address|DHCP]]. For example:
+
{{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]].}}
  
# dhcpcd -A ''interface''
+
{{Tip|
 +
* 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"}}.
 +
}}
  
== Maintaining a custom configuration ==
+
Finally, you should obtain an IP address as indicated in the [[#Overview]], for example:
  
{{Poor writing|This section is planned to be rewritten with a clearer structure and direction and more attention will be given to maintaining networks and controlling them effectively.}}
+
# dhcpcd ''interface''
  
{{Note|To discover your network interface name, issue the {{ic|ip link}} command.}}
+
== Advanced usage ==
  
As discussed above we can make use of {{ic|wpa_passphrase}} to generate a basic configuration which we can augment with additional networks and options of our choosing. This may be necessary for more advanced networks employing extensive use of [https://en.wikipedia.org/wiki/Extensible_Authentication_Protocol EAP].
+
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}}.  
  
Firstly we will use {{ic|wpa_passphrase}} to create our basic configuration file.
+
=== Configuration ===
  
# wpa_passphrase ''essid'' ''passphrase'' > /etc/wpa_supplicant/foobar.conf
+
As is clear after reading [[#Connecting with wpa_passphrase]], a basic configuration file can be generated with:
  
{{Tip|Some unusually complex passphrases may require input from a file: {{bc|# wpa_passphrase ''essid'' < ''passphrase.txt'' > /etc/wpa_supplicant/foobar.conf}} }}
+
# wpa_passphrase MYSSID passphrase > /etc/wpa_supplicant/example.conf
  
Next add a {{ic|ctrl_interface}} so that we may control the {{ic|wpa_supplicant}} daemon. We can allow {{ic|wpa_cli}} to edit this configuration by setting {{ic|1=update_config=1}}.
+
This will only create a {{ic|network}} section. A configuration file with some more common options may look like:
  
{{hc|/etc/wpa_supplicant/foobar.conf|2=
+
{{hc|/etc/wpa_supplicant/example.conf|2=<nowiki>
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel # allow control for members in the 'wheel' group
+
ctrl_interface=/var/run/wpa_supplicant
 +
ctrl_interface_group=wheel
 
update_config=1
 
update_config=1
 +
fast_reauth=1
 +
ap_scan=1
  
 
network={
 
network={
     ssid="foobarssid"
+
     ssid="MYSSID"
     psk=f5d1c49e15e679bebe385c37648d4141bc5c9297796a8a185d7bc5ac62f954e3
+
     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:
 +
 
 +
{{bc|1=
 +
network={
 +
    ssid="MYSSID"
 +
    psk="passphrase"
 
}
 
}
 
}}
 
}}
  
Multiple network blocks may be appended to this configuration.
+
If the network does not have a passphrase, e.g. a public Wi-Fi:
  
To start your network simply run the following:
+
{{bc|1=
 +
network={
 +
    ssid="MYSSID"
 +
    key_mgmt=NONE
 +
}
 +
}}
  
# ip link set ''interface'' up
+
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_supplicant -B -D nl80211 -i ''interface'' -c /etc/wpa_supplicant/foobar.conf
+
# dhcpcd -A ''interface''
+
  
{{Note|{{ic|nl80211}} is preferred over the deprecated {{ic|wext}} driver. For a list of supported drivers see the output of {{ic|wpa_supplicant -h}}.}}
+
{{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}}.
  
For networks of varying complexity please study the examples provided in the default {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} file.
+
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.  
  
=== Enabling with systemd ===
+
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]].
  
In order to enable wireless at boot, enable {{ic|wpa_supplicant}} on your particular wireless interface. To get connectivity with DHCP, enable {{ic|dhcpcd.service}} as well. Finally, to handle possible ethernet connections, install {{ic|ifplugd}} and enable it on your ethernet interface. For instance, the invocations might look like
+
{{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.}}
  
# systemctl enable wpa_supplicant@wlp3s1
+
=== Connection ===
# systemctl enable dhcpcd
+
# systemctl enable ifplugd@enp5s2
+
  
WPA Supplicant handles roaming for all the SSIDs in its configuration file, and {{ic|ifplugd}} will configure ethernet and bring down wireless when an ethernet cable is plugged into the machine. {{ic|dhcpcd}} takes care of leasing an IP on all interfaces.
+
==== Manual ====
  
It is likely that {{ic|wpa_supplicant@.service}} will have to be modified so that it will read the proper configuration file. To override the {{ic|ExecStart&#61;}} line, create the following:
+
First start ''wpa_supplicant'' command, whose most commonly used arguments are:
  
{{hc|/etc/systemd/system/wpa_supplicant@.service.d/foo.conf|<nowiki>
+
* {{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.
 +
 
 +
See [http://linux.die.net/man/8/wpa_supplicant 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:
 +
 
 +
* {{ic|wpa_supplicant.service}} - uses [[D-Bus]], recommended for [[NetworkManager]] users.
 +
* {{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}}.
 +
 
 +
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.
 +
 
 +
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.
 +
 
 +
{{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: {{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.
 +
 
 +
The following example will use [[desktop notifications]] to notify the user about the events:
 +
 
 +
{{bc|
 +
#!/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 {{ic|-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 {{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}}.}}
 +
 
 +
=== 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 {{ic|nl80211}} driver does not support the given hardware. The deprecated {{ic|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 [[systemd#Editing provided units|edit]] the {{ic|wpa_supplicant@.service}} unit provided by the package and modify the {{ic|ExecStart}} line accordingly:
 +
 
 +
{{hc|/etc/systemd/system/wpa_supplicant@.service.d/wext.conf|2=
 
[Service]
 
[Service]
 
ExecStart=
 
ExecStart=
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/bar.conf -i%i
+
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 {{ic|wpa_supplicant.service}} file. This can be done by [[Systemd#Drop-in snippets]]. The result looks like this:
 +
 
 +
{{hc|/etc/systemd/system/wpa_supplicant.service.d/override.conf|<nowiki>
 +
[Unit]
 +
After=dbus.service
 +
Before=network.target
 +
Wants=network.target
 
</nowiki>}}
 
</nowiki>}}
  
The {{ic|1=WantedBy=}} section in the current version is incorrect. If the line in {{ic|wpa_supplicant@.service}} does not match your interface name (wlan0), it will be necessary to copy the service file to {{ic|/etc/systemd/system}} and edit it to reflect
+
See more about this bug here: https://github.com/systemd/systemd/issues/1435
 +
 
 +
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}}.
 +
 
 +
=== Password-related problems ===
 +
 
 +
{{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}}.
 +
 
 +
In order to solve this try using here strings {{ic|wpa_passphrase <MYSSID> <<< "<passphrase>"}} or passing a file to the {{ic|-c}}  flag instead:
  
  [Install]
+
  $ wpa_supplicant -i <interface> -c /etc/wpa_supplicant/wpa_supplicant.conf
WantedBy=multi-user.target
+
  
The issue is fixed in this [http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap.git;a=commitdiff;h=893a0a558cd8fd9a7dc5827f379e0f8a273a4fe5 commit]
+
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.
  
== Related Links ==
+
== See also ==
  
 +
* [http://hostap.epitest.fi/wpa_supplicant/ WPA Supplicant home]
 +
* [https://gist.github.com/buhman/7162560 wpa_cli usage examples]
 +
* [http://linux.die.net/man/8/wpa_supplicant wpa_supplicant(8)]
 +
* [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]
 
* [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