Difference between revisions of "WPA supplicant"

From ArchWiki
Jump to: navigation, search
(Configuration: fixed my last edit)
(Use the config paths expected by the wpa_supplicant service files, various small content and stylistic changes)
Line 11: Line 11:
 
{{Article summary 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 WPA [[Wikipedia:Supplicant (computer)|Supplicant]] with support for WPA, WPA2 ([https://en.wikipedia.org/wiki/IEEE_802.11i IEEE 802.11i] / RSN (Robust Secure Network)) and WEP. 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.
  
 
== Installation ==
 
== Installation ==
Line 21: Line 21:
 
== 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}}.
+
To associate with a wireless access point using {{ic|wpa_supplicant}}, use the included 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}} in {{ic|/etc/wpa_supplicant/wpa_supplicant-''interface''.conf}}.
 +
 
 +
Replace all following instances of ''interface'' in italics with the wireless network interface you want to run wpa_supplicant on, which you can find using {{ic|ip link}}.
  
 
{{Tip|Refer to the provided {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} for details.}}
 
{{Tip|Refer to the provided {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} for details.}}
  
To enable saving changes made using wpa_cli, append the line {{ic|update_config=1}} to the configuration file. Start wpa_supplicant with
+
To enable saving changes made using wpa_cli, append the line {{ic|update_config=1}} to the configuration file, then start wpa_supplicant with
  
  # wpa_supplicant -B -i ''interface'' -c ''/path/to/config''
+
{{bc|# wpa_supplicant -B -i ''interface'' -c /etc/wpa_supplicant/wpa_supplicant-''interface''.conf}}
  
 
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:
 
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:
  
  > scan_results
+
{{bc|
  bssid / frequency / signal level / flags / ssid
+
> scan_results
  00:00:00:00:00:00 2462 -49 [WPA2-PSK-CCMP][ESS] MYSSID
+
bssid / frequency / signal level / flags / ssid
  11:11:11:11:11:11 2437 -64 [WPA2-PSK-CCMP][ESS] ANOTHERSSID
+
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:
 
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:
  
  > add_network
+
{{bc|1=
  0
+
> add_network
  > set_network 0 ssid "''MYSSID''"
+
0
  > set_network 0 psk "''passphrase''"
+
> set_network 0 ssid "''MYSSID''"
  > enable_network 0
+
> set_network 0 psk "''passphrase''"
  <2>CTRL-EVENT-CONNECTED - Connection to 00:00:00:00:00:00 completed (reauth) [id=0 id_str=]
+
> 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,
+
To save this network in the configuration file:
  
  > save_config
+
{{bc|
  OK
+
> save_config
 +
OK
 +
}}
  
Now that association with the WAP is complete, obtain an IP address via {{Pkg|dhcpcd}} or using the {{Pkg|iproute2}} tools.
+
Now that association with the wireless access point is complete, obtain an IP address via {{Pkg|dhcpcd}} or using the {{Pkg|iproute2}} tools.
  
 
== Configuration ==
 
== Configuration ==
Line 76: Line 84:
 
Once you have a configuration file, you can run ''wpa_supplicant'' daemon and connect to the wireless network:
 
Once you have a configuration file, you can run ''wpa_supplicant'' daemon and connect to the wireless network:
  
# wpa_supplicant -B -i ''interface'' -c ''configuration_file''
+
{{bc|# wpa_supplicant -B -i ''interface'' -c ''configuration_file''}}
  
 
{{Tip|Both {{ic|wpa_supplicant}} and {{ic|wpa_passphrase}} can be combined to associate with almost all WPA2 (Personal) networks:
 
{{Tip|Both {{ic|wpa_supplicant}} and {{ic|wpa_passphrase}} can be combined to associate with almost all WPA2 (Personal) networks:
# wpa_supplicant -B -i ''interface'' -c <(wpa_passphrase ''essid'' ''passphrase'')
+
{{bc|# wpa_supplicant -B -i ''interface'' -c <(wpa_passphrase ''essid'' ''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:
 
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:
  
# dhcpcd ''interface''
+
{{bc|# dhcpcd ''interface''}}
  
 
== Maintaining a custom configuration ==
 
== Maintaining a custom configuration ==
  
 
{{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.}}
 
{{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.}}
 
{{Note|To discover your network interface name, issue the {{ic|ip link}} command.}}
 
  
 
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].
 
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].
Line 96: Line 102:
 
Firstly we will use {{ic|wpa_passphrase}} to create our basic configuration file.
 
Firstly we will use {{ic|wpa_passphrase}} to create our basic configuration file.
  
# wpa_passphrase ''essid'' ''passphrase'' > /etc/wpa_supplicant/foobar.conf
+
{{bc|# wpa_passphrase ''essid'' ''passphrase'' > /etc/wpa_supplicant/wpa_supplicant-''interface''.conf}}
  
{{Tip|Some unusually complex passphrases may require input from a file: {{bc|# wpa_passphrase ''essid'' < ''passphrase.txt'' > /etc/wpa_supplicant/foobar.conf}} }}
+
{{Tip|Some unusually complex passphrases may require input from a file: {{bc|# wpa_passphrase ''essid'' < ''passphrase.txt'' > /etc/wpa_supplicant/wpa_supplicant-''interface''.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}}.
 
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}}.
  
{{hc|/etc/wpa_supplicant/foobar.conf|2=
+
{{hc|/etc/wpa_supplicant/wpa_supplicant-''interface''.conf|2=
 
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel # allow control for members in the 'wheel' group
 
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel # allow control for members in the 'wheel' group
 
update_config=1
 
update_config=1
Line 116: Line 122:
 
To start your network simply run the following:
 
To start your network simply run the following:
  
# ip link set ''interface'' up
+
{{bc|
# wpa_supplicant -B -D nl80211 -i ''interface'' -c /etc/wpa_supplicant/foobar.conf
+
# ip link set ''interface'' up
# dhcpcd -A ''interface''
+
# wpa_supplicant -B -D nl80211 -i ''interface'' -c /etc/wpa_supplicant/wpa_supplicant-''interface''.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}}.}}
 
{{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}}.}}
Line 124: Line 132:
 
For networks of varying complexity please study the examples provided in the default {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} file.
 
For networks of varying complexity please study the examples provided in the default {{ic|/etc/wpa_supplicant/wpa_supplicant.conf}} file.
  
=== Enabling with systemd ===
+
=== Starting with systemd ===
  
 
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
 
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
  
# systemctl enable wpa_supplicant@wlp3s1
+
{{bc|
# systemctl enable dhcpcd
+
# systemctl enable wpa_supplicant@wlp3s1
# systemctl enable ifplugd@enp5s2
+
# 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.
 
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.
  
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:
+
The provided {{ic|wpa_supplicant@.service}} is incorrect and will have to be modified so that it will install the service properly until the fixed version is packaged ([http://hostap.epitest.fi/bugz/show_bug.cgi?id=477 bug report]). To override it, copy {{ic|/usr/lib/systemd/system/wpa_supplicant@.service}} to {{ic|/etc/systemd/system/wpa_supplicant@.service}} and replace the {{ic|[Install]}} section with:
  
{{hc|/etc/systemd/system/wpa_supplicant@.service.d/foo.conf|<nowiki>
+
{{bc|1=
[Service]
+
[Install]
ExecStart=
+
WantedBy=multi-user.target
ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/bar.conf -i%i
+
}}
</nowiki>}}
+
  
The {{ic|1=WantedBy=}} section in the current version is incorrect ([http://w1.fi/bugz/show_bug.cgi?id=477 bug report]). 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
+
And then run {{ic|systemctl daemon-reload}} to make systemd see the new service file before enabling it.
  
[Install]
+
{{Note|If you choose to use the interface specific version of {{Pkg|dhcpcd}} you might want to replace the {{ic|-w}} flag with {{ic|-b}} so that it doesn't wait until it's assigned an address before forking to the background.}}
WantedBy=multi-user.target
+
  
 
== Related Links ==
 
== Related Links ==
  
 
* [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]
 +
|

Revision as of 09:22, 11 October 2013

Template:Article summary start Template:Article summary text Template:Article summary heading Template:Article summary wiki Template:Article summary wiki Template:Article summary end

wpa_supplicant is a cross-platform WPA Supplicant with support for WPA, WPA2 (IEEE 802.11i / RSN (Robust Secure Network)) and WEP. It is suitable for both desktop/laptop computers 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 wlan driver.

Installation

Install wpa_supplicant from the official repositories.

Optionally wpa_supplicant_gui can be installed which provides wpa_gui; a graphical frontend for wpa_supplicant using the qt4 toolkit.

Connecting with wpa_cli

To associate with a wireless access point using wpa_supplicant, use the included command line tool wpa_cli. In order to use wpa_cli a control interface must be specified for wpa_supplicant. Do this by creating a config file containing ctrl_interface=/var/run/wpa_supplicant in /etc/wpa_supplicant/wpa_supplicant-interface.conf.

Replace all following instances of interface in italics with the wireless network interface you want to run wpa_supplicant on, which you can find using ip link.

Tip: Refer to the provided /etc/wpa_supplicant/wpa_supplicant.conf for details.

To enable saving changes made using wpa_cli, append the line update_config=1 to the configuration file, then start wpa_supplicant with

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

Invoke wpa_cli with no arguments to get an interactive prompt (>). The prompt has tab completion and descriptions of completed commands. The command scan initiates a scan; a notification is issued when the scan is complete. Then:

> 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, tell wpa_supplicant about it. Each network is indexed numerically, so the first network will have index zero. The PSK can be provided without quotes as an alternative to providing the passphrase in this 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=]

To save this network in the configuration file:

> save_config
OK

Now that association with the wireless access point is complete, obtain an IP address via dhcpcd or using the iproute2 tools.

Configuration

wpa_supplicant provides a reference configuration file located at /etc/wpa_supplicant/wpa_supplicant.conf which contains detailed documentation for the all available options and their utilisation.

In its simplest form, a configuration file requires only a network block. For example:

/etc/wpa_supplicant/foobar.conf
network={
    ssid="..."
}

This can easily be generated using the wpa_passphrase tool. For example:

$ wpa_passphrase essid passphrase
network={
    ssid="essid"
    #psk="passphrase"
    psk=f5d1c49e15e679bebe385c37648d4141bc5c9297796a8a185d7bc5ac62f954e3
}

Once you have a configuration file, you can run wpa_supplicant daemon and connect to the wireless network:

# wpa_supplicant -B -i interface -c configuration_file
Tip: Both wpa_supplicant and wpa_passphrase can be combined to associate with almost all WPA2 (Personal) networks:
# wpa_supplicant -B -i interface -c <(wpa_passphrase essid passphrase)

All that remains is to simply connect using a static IP or DHCP. For example:

# dhcpcd interface

Maintaining a custom configuration

Tango-edit-clear.pngThis article or section needs language, wiki syntax or style improvements.Tango-edit-clear.png

Reason: 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. (Discuss in Talk:WPA supplicant#)

As discussed above we can make use of 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 EAP.

Firstly we will use wpa_passphrase to create our basic configuration file.

# wpa_passphrase essid passphrase > /etc/wpa_supplicant/wpa_supplicant-interface.conf
Tip: Some unusually complex passphrases may require input from a file:
# wpa_passphrase essid < passphrase.txt > /etc/wpa_supplicant/wpa_supplicant-interface.conf

Next add a ctrl_interface so that we may control the wpa_supplicant daemon. We can allow wpa_cli to edit this configuration by setting update_config=1.

/etc/wpa_supplicant/wpa_supplicant-interface.conf
ctrl_interface=DIR=/run/wpa_supplicant GROUP=wheel # allow control for members in the 'wheel' group
update_config=1

network={
    ssid="foobarssid"
    psk=f5d1c49e15e679bebe385c37648d4141bc5c9297796a8a185d7bc5ac62f954e3
}

Multiple network blocks may be appended to this configuration.

To start your network simply run the following:

# ip link set interface up
# wpa_supplicant -B -D nl80211 -i interface -c /etc/wpa_supplicant/wpa_supplicant-interface.conf
# dhcpcd -A interface
Note: nl80211 is preferred over the deprecated wext driver. For a list of supported drivers see the output of wpa_supplicant -h.

For networks of varying complexity please study the examples provided in the default /etc/wpa_supplicant/wpa_supplicant.conf file.

Starting with systemd

In order to enable wireless at boot, enable wpa_supplicant on your particular wireless interface. To get connectivity with DHCP, enable dhcpcd.service as well. Finally, to handle possible ethernet connections, install ifplugd and enable it on your ethernet interface. For instance, the invocations might look like

# systemctl enable wpa_supplicant@wlp3s1
# systemctl enable dhcpcd
# systemctl enable ifplugd@enp5s2

WPA Supplicant handles roaming for all the SSIDs in its configuration file, and ifplugd will configure ethernet and bring down wireless when an ethernet cable is plugged into the machine. dhcpcd takes care of leasing an IP on all interfaces.

The provided wpa_supplicant@.service is incorrect and will have to be modified so that it will install the service properly until the fixed version is packaged (bug report). To override it, copy /usr/lib/systemd/system/wpa_supplicant@.service to /etc/systemd/system/wpa_supplicant@.service and replace the [Install] section with:

[Install]
WantedBy=multi-user.target

And then run systemctl daemon-reload to make systemd see the new service file before enabling it.

Note: If you choose to use the interface specific version of dhcpcd you might want to replace the -w flag with -b so that it doesn't wait until it's assigned an address before forking to the background.

Related Links

|