wpa_cli.8 (6646B)
- .\" This manpage has been automatically generated by docbook2man
- .\" from a DocBook document. This tool can be found at:
- .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
- .\" Please send any bug reports, improvements, comments, patches,
- .\" etc. to Steve Cheng <steve@ggi-project.org>.
- .TH "WPA_CLI" "8" "07 August 2019" "" ""
- .SH NAME
- wpa_cli \- WPA command line client
- .SH SYNOPSIS
- \fBwpa_cli\fR [ \fB-p \fIpath to ctrl sockets\fB\fR ] [ \fB-g \fIpath to global ctrl_interface socket\fB\fR ] [ \fB-i \fIifname\fB\fR ] [ \fB-hvB\fR ] [ \fB-a \fIaction file\fB\fR ] [ \fB-P \fIpid file\fB\fR ] [ \fB-G \fIping interval\fB\fR ] [ \fB\fIcommand ...\fB\fR ]
- .SH "OVERVIEW"
- .PP
- wpa_cli is a text-based frontend program for interacting
- with wpa_supplicant. It is used to query current status, change
- configuration, trigger events, and request interactive user
- input.
- .PP
- wpa_cli can show the current authentication status, selected
- security mode, dot11 and dot1x MIBs, etc. In addition, it can
- configure some variables like EAPOL state machine parameters and
- trigger events like reassociation and IEEE 802.1X
- logoff/logon. wpa_cli provides a user interface to request
- authentication information, like username and password, if these
- are not included in the configuration. This can be used to
- implement, e.g., 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.
- .PP
- The control interface of wpa_supplicant can be configured to
- allow non-root user access (ctrl_interface GROUP= parameter in the
- configuration file). This makes it possible to run wpa_cli with a
- normal user account.
- .PP
- wpa_cli supports two modes: interactive and command
- line. 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).
- .PP
- Interactive mode is started when wpa_cli is executed without
- including the command as a command line parameter. Commands are
- then entered on the wpa_cli prompt. In command line mode, the same
- commands are entered as command line arguments for wpa_cli.
- .SH "INTERACTIVE AUTHENTICATION PARAMETERS REQUEST"
- .PP
- When wpa_supplicant need authentication parameters, like
- username and password, which are not present in the configuration
- file, it sends a request message to all attached frontend programs,
- e.g., wpa_cli in interactive mode. wpa_cli shows these requests
- with "CTRL-REQ-<type>-<id>:<text>"
- prefix. <type> is IDENTITY, PASSWORD, or OTP
- (one-time-password). <id> is a unique identifier for the
- current network. <text> is description of the request. In
- case of OTP request, it includes the challenge from the
- authentication server.
- .PP
- The reply to these requests can be given with
- \fBidentity\fR, \fBpassword\fR, and
- \fBotp\fR commands. <id> needs to be copied from
- the matching request. \fBpassword\fR and
- \fBotp\fR 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 \fBpassword\fR are
- remembered as long as wpa_supplicant is running whereas values given
- with \fBotp\fR are used only once and then forgotten,
- i.e., wpa_supplicant will ask frontend for a new value for every use.
- This can be used to implement one-time-password lists and generic token
- card -based authentication.
- .PP
- Example request for password and a matching reply:
- .sp
- .RS
- .nf
- CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
- > password 1 mysecretpassword
- .fi
- .RE
- .PP
- Example request for generic token card challenge-response:
- .sp
- .RS
- .nf
- CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
- > otp 2 9876
- .fi
- .RE
- .SH "COMMAND ARGUMENTS"
- .TP
- \fB-p path\fR
- Change the path where control sockets should
- be found.
- .TP
- \fB-g control socket path\fR
- Connect to the global control socket at the
- indicated path rather than an interface-specific control
- socket.
- .TP
- \fB-i ifname\fR
- Specify the interface that is being
- configured. By default, choose the first interface found with
- a control socket in the socket path.
- .TP
- \fB-h\fR
- Help. Show a usage message.
- .TP
- \fB-v\fR
- Show version information.
- .TP
- \fB-B\fR
- Run as a daemon in the background.
- .TP
- \fB-a file\fR
- 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 "CONNECTED" or "DISCONNECTED" depending on the event.
- This can be used to execute networking tools required to configure
- the interface.
- Additionally, three environmental variables are available to
- the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR
- contains the absolute path to the ctrl_interface socket. WPA_ID
- contains the unique network_id identifier assigned to the active
- network, and WPA_ID_STR contains the content of the id_str option.
- .TP
- \fB-P file\fR
- Set the location of the PID
- file.
- .TP
- \fB-G ping interval\fR
- Set the interval (in seconds) at which
- wpa_cli pings the supplicant.
- .TP
- \fBcommand\fR
- Run a command. The available commands are
- listed in the next section.
- .SH "COMMANDS"
- .PP
- The following commands are available:
- .TP
- \fBstatus\fR
- get current WPA/EAPOL/EAP status
- .TP
- \fBmib\fR
- get MIB variables (dot1x, dot11)
- .TP
- \fBhelp\fR
- show this usage help
- .TP
- \fBinterface [ifname]\fR
- show interfaces/select interface
- .TP
- \fBlevel <debug level>\fR
- change debug level
- .TP
- \fBlicense\fR
- show full wpa_cli license
- .TP
- \fBlogoff\fR
- IEEE 802.1X EAPOL state machine logoff
- .TP
- \fBlogon\fR
- IEEE 802.1X EAPOL state machine logon
- .TP
- \fBset\fR
- set variables (shows list of variables when run without arguments)
- .TP
- \fBpmksa\fR
- show PMKSA cache
- .TP
- \fBreassociate\fR
- force reassociation
- .TP
- \fBreconfigure\fR
- force wpa_supplicant to re-read its configuration file
- .TP
- \fBpreauthenticate <BSSID>\fR
- force preauthentication
- .TP
- \fBidentity <network id> <identity>\fR
- configure identity for an SSID
- .TP
- \fBpassword <network id> <password>\fR
- configure password for an SSID
- .TP
- \fBpin <network id> <pin>\fR
- configure pin for an SSID
- .TP
- \fBotp <network id> <password>\fR
- configure one-time-password for an SSID
- .TP
- \fBbssid <network id> <BSSID>\fR
- set preferred BSSID for an SSID
- .TP
- \fBlist_networks\fR
- list configured networks
- .TP
- \fBterminate\fR
- terminate \fBwpa_supplicant\fR
- .TP
- \fBquit\fR
- exit wpa_cli
- .SH "SEE ALSO"
- .PP
- \fBwpa_supplicant\fR(8)
- .SH "LEGAL"
- .PP
- wpa_supplicant is copyright (c) 2003-2022,
- Jouni Malinen <j@w1.fi> and
- contributors.
- All Rights Reserved.
- .PP
- This program is licensed under the BSD license (the one with
- advertisement clause removed).