Wi-Fi Protected Access (WPA) command-line client for interacting with wpa_supplicant
Syntax:
wpa_cli-version [-Bhv] [-a action_file] [-G ping_interval] [-g global_ctrl]
[-i ifname] [-P pid_file] [-p ctrl_interface_path]
[-s socket_path] [-t timeout] [command ... ]
Options:
- -a action_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
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
- Set the interval (in seconds) at which wpa_cli pings the supplicant.
- -g global_ctrl
- Connect to the global control socket at the indicated path rather than an interface-specific
control socket.
- -h
- Show a help 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_interface_path
- Change the path to the control interface directory.
This is where wpa_supplicant creates socket files to communicate with wpa_cli.
The default is /var/run/wpa_supplicant.
This setting should match the ctrl_interface setting in the wpa_supplicant.conf file.
- -s socket_path
- Specify the path of the client socket directory. The default path is /tmp.
This argument is used by wpa_cli to bind a name to the wpa_supplicant socket to complete
the connection.
- -t timeout
- Set the command timeout, in seconds. The default value is 10, and the minimum value is 1.
- -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.5
supports version 2.5.
The wpa_cli utility can show the current authentication status, selected
security mode, dot11 and dot1x MIBs, and more. In addition, it can 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 user name 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 (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, user name/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
The wpa_cli utility currently supports the following commands:
- add_network
- Add a network.
- bssid network_id BSSID
- Set the preferred BSSID for an SSID.
- disable_network network_id
- Disable a network.
- disconnect
- Disconnect and wait for a reassociate command before connecting.
- enable_network network_id
- Enable a network.
- get_capability
eap | pairwise | group | key_mgmt | proto | auth_alg
- Get capabilities.
- get_network network_id variable
- Get network variables.
- 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.
- logoff
- IEEE 802.1X EAPOL state machine logoff.
- logon
- IEEE 802.1X EAPOL state machine logon.
- mib
- Get 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 a reassociation.
- reconfigure
- Force wpa_supplicant to reread its configuration file.
- remove_network network_id
- Remove a network.
- 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 others).
- set [variable value]
- Set variables (shows list of variables when run without arguments).
- set_network network_id variable value
- Set network variables (shows list of variables when run without arguments).
- terminate
- Terminate wpa_supplicant.
- vendor id cmd [cmd_arg]
- (QNX Neutrino extension; QNX Neutrino 7.0 or later)
Issue a vendor-specific command. The vendor option name must be followed by the vendor ID (id)
and the command to execute (cmd). Both values must be unsigned numbers, either decimal or hexadecimal.
For Broadcom drivers, the vendor ID is 0; for Marvell drivers, it's 1.
You may also provide the command's argument value (cmd_arg); the format and acceptable values are command-specific.
The option arguments are opaque to the wpa_cli utility and wpa_supplicant service;
these utilities just pass their strings to the driver.
For information about the supported commands, see your wireless driver's documentation.
Interactive authentication parameters request
When wpa_supplicant needs authentication parameters (for example, a username
and password, which are not contained in the configuration file), it sends a request message to all
attached front-end programs (for example, wpa_cli) in interactive mode.
The wpa_cli utility shows these requests with the
CTRL-REQ-type-id:text prefix.
- type
- IDENTITY, PASSWORD, or OTP
(one-time-password).
- id
- A unique identifier for the current network.
- text
- A description of the request. In the case of an OTP request, it includes the challenge from the
authentication server.
The reply to these requests can be given with identity,
password, and otp commands. The id needs to be copied from
the matching request. The password and otp commands can be
used regardless of 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 the wpa_supplicant utility
is running whereas values given with otp are used only once and then forgotten.
The wpa_supplicant utility 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
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