Difference between revisions of "WPA supplicant"

From ArchWiki
Jump to: navigation, search
(Starting with systemd: added tip)
(revert structural change and nix verbosity. it is the manual association that is done first. related articles are structured this way for the same reason. also, single subsections are a no-no)
Line 20: Line 20:
  
 
Optionally {{Pkg|wpa_supplicant_gui}} can be installed which provides ''wpa_gui'', a graphical frontend for ''wpa_supplicant'' using the {{Pkg|qt4}} toolkit.
 
Optionally {{Pkg|wpa_supplicant_gui}} can be installed which provides ''wpa_gui'', a graphical frontend for ''wpa_supplicant'' using the {{Pkg|qt4}} toolkit.
 +
 +
== Association ==
 +
 +
The ''wpa_cli'' utility is the command line interface to the ''wpa_supplicant'' daemon.  In order to use ''wpa_cli'', a "control interface" (socket) must be specified for ''wpa_supplicant''.  Do this by creating a configuration file containing:
 +
 +
  ctrl_interface=/run/wpa_supplicant
 +
 +
To enable saving changes to the daemon into the configuration file, such as adding wireless networks, keys, and other information, append {{ic|update_config=1}} to the configuration file.  Start ''wpa_supplicant'' by issuing
 +
 +
  # wpa_supplicant -B -i ''interface'' -c ''/path/to/config''
 +
 +
Invoke {{ic|# wpa_cli}} to get an interactive prompt ({{ic|>}}). The prompt has tab completion and descriptions of completed commands.  At the prompt, initiate a scan with {{ic|> scan}}. A notification is shown 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 {{ic|''MYSSID''}}, tell ''wpa_supplicant'' about it. Each network is indexed numerically, so the first network will have index zero. The [[wikipedia:Pre-shared_key|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=]
 +
 +
The notification indicates the supplicant has successfully associated to the access point.  Now one can obtain an IP address via {{Pkg|dhcpcd}} or the {{Pkg|iproute2}} tools.  See the '''Related''' articles for more information.
 +
 +
To write the changes to the configuration file:
 +
 +
> save_config
 +
OK
  
 
== Configuration ==
 
== Configuration ==
Line 62: Line 95:
  
 
  # dhcpcd ''interface''
 
  # dhcpcd ''interface''
 
=== Using wpa_cli ===
 
 
''wpa_supplicant'' can be controlled manually at runtime using the ''wpa_cli'' utility. In order to use ''wpa_cli'', the ''wpa_supplicant'' daemon must be configured to create a "control interface" (socket). This is done in the configuration file using the {{ic|ctrl_interface}} variable, the following example will create the socket in {{ic|/run/wpa_supplicant/}} and allow the members of {{ic|adm}} group to access it:
 
 
ctrl_interface=DIR=/run/wpa_supplicant GROUP=adm
 
 
It is possible to enable ''wpa_supplicant'' to modify the configuration file when a command from ''wpa_cli'' is received. This is useful to manually add new networks to the roaming configuration file without the need to restart ''wpa_supplicant'' daemon. Simply add the following to the configuration file:
 
 
update_config=1
 
 
After the ''wpa_supplicant'' daemon is started, you can start ''wpa_cli''. It will try to find the socket file, use the {{ic|-p}} option if it fails. You can specify the interface that will be configured with the {{ic|-i}} option, otherwise the first found wireless interface managed by ''wpa_supplicant'' will be used. When ''wpa_cli'' is invoked, you will get an interactive prompt ({{ic|>}}). The prompt has tab completion and descriptions of completed commands.
 
 
==== Adding new network ====
 
 
Initiate a scan, a notification is showed when the scan is complete:
 
 
> scan
 
 
Show 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'', tell ''wpa_supplicant'' about it. Each network is indexed numerically, so the first network will have index zero. The [[wikipedia:Pre-shared_key|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=]
 
 
Write the changes to the configuration file:
 
 
> save_config
 
OK
 
  
 
== Starting with systemd ==
 
== Starting with systemd ==

Revision as of 21:19, 15 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 WEP, WPA and WPA2 (IEEE 802.11i / RSN (Robust Secure Network)). It is suitable for both desktop and laptop computers and even 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 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.

Association

The wpa_cli utility is the command line interface to the wpa_supplicant daemon. In order to use wpa_cli, a "control interface" (socket) must be specified for wpa_supplicant. Do this by creating a configuration file containing:

 ctrl_interface=/run/wpa_supplicant

To enable saving changes to the daemon into the configuration file, such as adding wireless networks, keys, and other information, append update_config=1 to the configuration file. Start wpa_supplicant by issuing

 # wpa_supplicant -B -i interface -c /path/to/config

Invoke # wpa_cli to get an interactive prompt (>). The prompt has tab completion and descriptions of completed commands. At the prompt, initiate a scan with > scan. A notification is shown 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=]

The notification indicates the supplicant has successfully associated to the access point. Now one can obtain an IP address via dhcpcd or the iproute2 tools. See the Related articles for more information.

To write the changes to the configuration file:

> save_config
OK

Configuration

wpa_supplicant provides a reference configuration file located at /etc/wpa_supplicant/wpa_supplicant.conf which contains detailed documentation for all the 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
}
Tip: Some unusually complex passphrases may require input from a file:
# wpa_passphrase essid < passphrase.txt > /etc/wpa_supplicant/wpa_supplicant-interface.conf

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

You might need to specify a driver to be used. For a list of supported drivers see the output of wpa_supplicant -h, nl80211 is preferred over the deprecated wext driver. Use the -D switch to specify the driver:

# wpa_supplicant -B -i interface -c configuration_file -D driver
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

Starting with systemd

Most common configuration involves enabling wpa_supplicant and dhcpcd on a particular interface (see systemd#Using units for details):

# systemctl enable wpa_supplicant@interface
# systemctl enable dhcpcd@interface

The [Install] section of systemd services in the current version of wpa_supplicant is incorrect (bug report). If your interface name is not wlan0, it will be necessary to copy the service file to /etc/systemd/system/ and replace the [Install] section with:

[Install]
WantedBy=multi-user.target

See systemd#Editing provided unit files for help with the editing.

Note: If you use dhcpcd@.service, you might also want to replace the -w flag with -b so that it does not wait until it is assigned an address before forking to the background.
Tip: dhcpcd contains a hook (enabled by default) to automatically launch wpa_supplicant on wireless interfaces. It is started only if a configuration file at /etc/wpa_supplicant.conf exists and no wpa_supplicant process is listening on that interface. You do not need to use wpa_supplicant@interface at all and just enable dhcpcd@interface.

See also