wpa_cli-version

WPA command-line client for interacting with wpa_supplicant

Syntax:

wpa_cli-version [-Bhv] [-a action_file] [-G ping_interval]  
    [-g global_ctrl_interface] [-i ifname] [-P PID_file]
    [-p ctrl_sockets_path] [-s wpa_client_socket_path] [-t timeout] 
    [command ...]

Runs on:

QNX Neutrino

Options:

-a action_file
Run in daemon mode executing action_file based on events from wpa_supplicant. The specified file will be executed with the first argument set to the interface name, and the second to CONNECT or DISCONNECT, depending on the event.
-B
Run as a daemon in the background.
-G ping_interval
Specify the ping interval, in seconds.
-g global_ctrl_interface
Set the path to the global_ctrl_interface socket. If you specify this option, you can omit the interface definitions.
-h
Show a help (usage) message.
-i ifname
Specify the interface that is being configured. By default, choose the first interface found with a control socket in the socket path.
-P PID_file
Set the location of the PID file.
-p ctrl_sockets_path
Change the path where control sockets should be found.
-s wpa_client_socket_path
Specify the path of the socket used by the WPA client.
-t timeout
Set the command timeout, in seconds. The allowable range is 1 to 120; values outside this range make wpa_supplicant use the default timeout of 10 seconds.
-v
Show version information.
command
Run a command; see Supported commands, below.

Description:

The wpa_cli utility is a text-based front-end program for interacting with wpa_supplicant. You can use it to query the current status, change the configuration, trigger events, and request interactive user input.

The number in the wpa_cli utility name indicates the wpa_supplicant version it supports. For example, wpa_cli-2.9 supports version 2.9.

The default path is /var/run/wpa_supplicant-version. The default interface is the first interface found in the socket path.

The wpa_cli utility can show the current authentication status, selected security mode, dot11 and dot1x MIBs, etc. It can also configure some variables like EAPOL state machine parameters and trigger events like reassociation and IEEE 802.1X logoff/logon.

The utility provides a user interface to request authentication information, such as username and password, if these aren't included in the configuration. You can use this to implement, for example, one-time passwords or generic token card authentication where the authentication is based on a challenge-response that uses an external device for generating the response.

You can configure the control interface of wpa_supplicant to allow non-root user access (this is the ctrl_interface_group in the configuration file). This makes it possible to run wpa_cli with a normal user account.

The wpa_cli utility supports interactive and command-line modes. Both modes share the same command set, and the main difference is in interactive mode providing access to unsolicited messages (event messages, username/password requests). If you don't specify a command when you start wpa_cli, the utility goes into interactive mode. You then enter commands at the wpa_cli prompt.

Supported commands

add_network
Add a network. This command creates a new network with an empty configuration. This network is initially disabled but when it's been configured, it can be enabled with enable_network. The client utility outputs the network ID of the new network on success, or FAIL on failure.
bssid network_id BSSID
Set the preferred Basic Service Set ID (BSSID) for a network.
disable_network network_id
Disable the specified network. The special network ID of all can be used to disable all networks.
disconnect
Disconnect and wait for a reassociate command before connecting.
enable_network network_id
Enable the specified network. The special network ID of all can be used to enable all networks.
get_capability eap | pairwise | group | key_mgmt | proto | auth_alg [strict]
Get the supported capabilities for a feature. The first argument is mandatory and specifies the feature. The second argument is optional and if specified, must be strict, to display only those capabilities that the driver explicitly claims are supported. Otherwise, all available capabilities are listed.
get_network network_id variable
Get the value of a variable on a network. The supported variables are: ssid, psk, key_mgmt, identity, and password.
help
Display usage information.
identity network_id identity
Configure the identity for an SSID.
interface [ifname]
Show interfaces or select the specified interface.
level debug_level
Change the debugging level.
license
Show the full wpa_cli license.
list_networks
List the configured networks. For each network, the following fields are listed: network ID, SSID, BSSID, and flag settings.
logoff
Log off. IEEE 802.1X EAPOL state machine logoff.
logon
Log on. IEEE 802.1X EAPOL state machine logon.
mib
Get the MIB variables (dot1x, dot11).
otp network_id password
Configure a one-time password for an SSID.
passphrase network_id passphrase
Configure a private key passphrase for an SSID.
password network_id password
Configure a password for an SSID.
pin network_id pin
Configure a PIN for an SSID.
pmksa
Show the PMKSA cache.
preauthenticate BSSID
Force preauthentication.
quit
Exit wpa_cli.
reassociate
Force reassociation with an AP. If the client is already connected to one, it will disconnect and then reconnect.
reconfigure
Force wpa_supplicant to reread its configuration file.
remove_network network_id
Remove the specified network. The special network ID of all can be used to remove all networks.
save_config
Save the current configuration.
scan
Request a new BSS scan.
scan_results
Get the latest scan results.
select_network network_id
Select a network (disable all others).
set [variable value]
Set a variable. The variable can be one of:
  • EAPOL::heldPeriod
  • EAPOL::authPeriod
  • EAPOL::startPeriod
  • EAPOL::maxStart
  • dot11RSNAConfigPMKLifetime
  • dot11RSNAConfigPMKReauthThreshold
  • dot11RSNAConfigSATimeout
When no arguments are given, this command shows a list of supported variables.
set_network network_id variable value
Set the value of a variable on a network. The supported variables are: ssid, psk, key_mgmt, identity, and password. When no arguments are given, this command shows a list of supported network variables.
status
Get the current WPA/EAPOL/EAP status information. The output is a list of variable settings, one per line, in variable = value format.
terminate
Terminate wpa_supplicant.

Interactive authentication parameters request

When wpa_supplicant needs authentication parameters (for example, a username and password) that are not contained in the configuration file, it sends a request message to all attached front-end programs, such as wpa_cli, in interactive mode.

The wpa_cli utility shows these requests with the following prefix:
CTRL-REQ-type-id:text
 Here, id is a unique identifier for the current network, and text is a description of the request, one of IDENTITY, PASSWORD, or OTP (one-time-password). With an OTP request, the description includes the challenge from the authentication server.

These requests can be replied to with identity, password, and otp commands. The id needs to be copied from the matching request. The password and otp commands can be used whether the request was for PASSWORD or OTP. The main difference between these two commands is that values given with password are remembered as long as wpa_supplicant is running, whereas values given with otp are used only once and then forgotten (i.e., wpa_supplicant will ask the front end for a new value for every use). This behavior can be used to implement one-time-password lists and generic token card-based authentication.

Using wpa_cli to run external programs on wpa_supplicant connection/disconnection

You can use the wpa_cli utility to run external programs whenever wpa_supplicant connects or disconnects from a network. This can be used, for example, to update the network configuration and/or trigger a DHCP client to update its IP addresses.

One wpa_cli process needs to be started in interactive mode for each interface. In the following example, wpa_cli is started for the default interface (-i can be used to select a particular interface if more than one is being used concurrently): 
wpa_cli -a/sbin/wpa_action.sh -B

The action file (/sbin/wpa_action.sh in this example) will be executed whenever wpa_supplicant completes authentication or detects disconnection. The action script will be called with two command-line arguments: the interface name and the event (CONNECTED or DISCONNECTED). If the script needs more information about the current network, it can use wpa_cli status to query wpa_supplicant for that information.

The following code provides a template for an action script: 
#!/bin/sh

IFNAME=$1
CMD=$2

if [ "$CMD" = "CONNECTED" ]; then
    SSID=`wpa_cli -i$IFNAME status | grep ^ssid= | cut -f2- -d=`
    # configure network, signal DHCP client, etc.
fi

if [ "$CMD" = "DISCONNECTED" ]; then
    # remove network configuration, if needed
    SSID=
fi

Examples

The following example is a request for a password and a matching reply: 
CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
> password 1 mysecretpassword
The following example is a request for a generic token card challenge-response: 
CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
> otp 2 9876
Page updated: