Caution: This version of this document is no longer maintained. For the latest documentation, see


Wi-Fi Protected Access client and IEEE 802.1X supplicant


wpa_supplicant [-BddehLqqvw] [-iifname]  
               [-cconfig file]  

Runs on:



-p path
Change the path where control sockets should be found.
-i ifname
Specify the interface that is being configured. By default, choose the first interface found with a control socket in the socket path.
Help. Show a usage message.
Show version information.
Run as a daemon in the background.
-a file
Run in daemon mode executing the action file based on events from wpa_supplicant. The specified file will be executed with the first argument set to interface name and second to "CONNECT" or "DISCONNECT" depending on the event. This can be used
-P file
Set the location of the PID file.
Run a command. The available commands are listed in the next section.

The following commands are available:

Run daemon in the background.
-i ifname
Interface to listen on.
-c filename
Path to configuration file.
-D driver
Driver to use. See the available options below.
Increase debugging verbosity (-dd even more).
Include keys (passwords, etc.) in debug output.
Include timestamp in debug messages.
Use external IEEE 802.1X Supplicant (e.g., xsupplicant) (this disables the internal Supplicant).
Help. Show a usage message.
Show license (GPL and BSD).
Decrease debugging verbosity (-qq even less).
Show version.
Wait for the interface to be added, if needed. Normally, wpa_supplicant exits if the interface isn't there yet.
Start describing new interface.


Wireless networks don't require physical access to the network equipment in the same way as wired networks. This makes it easier for unauthorized users to passively monitor a network and capture all transmitted frames. In addition, unauthorized use of the network is much easier. In many cases, this can happen even without user's explicit knowledge, because the wireless LAN adapter may have been configured to automatically join any available network.

Link-layer encryption can be used to provide a layer of security for wireless networks. The original wireless LAN standard, IEEE 802.11, included a simple encryption mechanism, WEP. However, that proved to be flawed in many areas, and networks protected with WEP cannot be considered secure. IEEE 802.1X authentication and frequently changed dynamic WEP keys can be used to improve the network security, but even that has inherited security issues, due to the use of WEP for encryption. Wi-Fi Protected Access and IEEE 802.11i amendment to the wireless LAN standard introduce a much improvement mechanism for securing wireless networks. IEEE 802.11i-enabled networks that are using CCMP (an encryption mechanism based on strong cryptographic algorithm AES) can finally be called secure used for applications which require efficient protection against unauthorized access.

The wpa_supplicant utility is an implementation of the WPA Supplicant component, i.e., the part that runs in the client stations. It implements WPA key negotiation with a WPA Authenticator and EAP authentication with Authentication Server. In addition, it controls the roaming and IEEE 802.11 authentication/association of the wireless LAN driver.

The wpa_supplicant utility is designed to be a daemon that runs in the background and acts as the backend component controlling the wireless connection. It supports separate front-end programs and a sample text-based front-end, wpa_cli, is included with wpa_supplicant.

Before wpa_supplicant can do its work, the network interface must be available. That means that the physical device must be present and enabled, and the driver for the device must have be loaded. Note, however, that the -w option of the wpa_supplicant daemon instructs the daemon to continue to run and to wait for the interface to become available. Without the -w option, the daemon will exit immediately if the device isn't already available.

After wpa_supplicant has configured the network device, higher level configuration such as DHCP may proceed. There are a variety of ways to integrate wpa_supplicant into a machine's networking scripts, a few of which are described in sections below.

The following steps are used when associating with an AP using WPA:

  1. wpa_supplicant requests the driver to scan neighboring BSSes
  2. wpa_supplicant selects a BSS based on its configuration
  3. wpa_supplicant requests the driver to associate with the chosen BSS
  4. If WPA-EAP: integrated IEEE 802.1X Supplicant or external Xsupplicant completes EAP authentication with the authentication server (proxied by the Authenticator in the AP)
  5. If WPA-EAP: master key is received from the IEEE 802.1X Supplicant
  6. If WPA-PSK: wpa_supplicant uses PSK as the master session key
  7. wpa_supplicant completes WPA 4-Way Handshake and Group Key Handshake with the Authenticator (AP)
  8. wpa_supplicant configures encryption keys for unicast and broadcast
  9. normal data packets can be transmitted and received

Supported features

Supported WPA/IEEE 802.11i features:


The wpa_supplicant requires the following libraries and binaries be present:

The wpa_supplicant also needs a read/write filesystem for creation of a ctrl_interface directory (see the sample wpa_supplicant.conf configuration file).

Note: You can't use /dev/shmem because it isn't possible to create a directory there.

See also:

wpa_cli, wpa_passphrase

wpa_supplicant.conf in the NetBSD documentation.

WiFi Configuration Using WPA and WEP in the Core Networking User's Guide