| Updated: October 28, 2024 |
WPA command-line client for interacting with wpa_supplicant
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 ...]
QNX Neutrino
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.
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.
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.
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.
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.
#!/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
CTRL-REQ-PASSWORD-1:Password needed for SSID foobar > password 1 mysecretpassword
CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar > otp 2 9876