1.\" Copyright (c) 2005 Sam Leffler <sam@errno.com> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: head/usr.sbin/wpa/wpa_cli/wpa_cli.8 210763 2010-08-02 13:11:27Z uqs $ 26.\" 27.Dd May 21, 2020 28.Dt WPA_CLI 8 29.Os 30.Sh NAME 31.Nm wpa_cli 32.Nd "text-based frontend program for interacting with wpa_supplicant" 33.Sh SYNOPSIS 34.Nm 35.Op Fl Bhv 36.Op Fl p Ar path to ctrl sockets 37.Op Fl g Ar path to global ctrl_interface socket 38.Op Fl i Ar ifname 39.Op Fl a Ar action file 40.Op Fl P Ar pid file 41.Op Fl G Ar ping interval 42.No command ... 43.Oc 44.Sh DESCRIPTION 45.Pp 46.Nm 47is a text-based frontend program for interacting with wpa_supplicant. It is 48used to query current status, change configuration, trigger events, and request 49interactive user input. 50.Pp 51.Nm 52can show the current authentication status, selected security mode, dot11 and 53dot1x MIBs, etc. In addition, it can configure some variables like EAPOL state 54machine parameters and trigger events like reassociation and IEEE 802.1X 55logoff/logon. wpa_cli provides a user interface to request 56authentication information, like username and password, if these 57are not included in the configuration. This can be used to 58implement, e.g., one-time-passwords or generic token card 59authentication where the authentication is based on a 60challenge-response that uses an external device for generating the 61response. 62.Pp 63The control interface of wpa_supplicant can be configured to 64allow non-root user access (ctrl_interface GROUP= parameter in the 65configuration file). This makes it possible to run wpa_cli with a 66normal user account. 67.Pp 68wpa_cli supports two modes: interactive and command 69line. Both modes share the same command set and the main 70difference is in interactive mode providing access to unsolicited 71messages (event messages, username/password requests). 72.Pp 73Interactive mode is started when wpa_cli is executed without 74including the command as a command line parameter. Commands are 75then entered on the wpa_cli prompt. In command line mode, the same 76commands are entered as command line arguments for wpa_cli. 77.Sh "INTERACTIVE AUTHENTICATION PARAMETERS REQUEST" 78.Pp 79When wpa_supplicant need authentication parameters, like 80username and password, which are not present in the configuration 81file, it sends a request message to all attached frontend programs, 82e.g., wpa_cli in interactive mode. wpa_cli shows these requests 83with "CTRL-REQ-<type>-<id>:<text>" 84prefix. <type> is IDENTITY, PASSWORD, or OTP 85(one-time-password). <id> is a unique identifier for the 86current network. <text> is description of the request. In 87case of OTP request, it includes the challenge from the 88authentication server. 89.Pp 90The reply to these requests can be given with 91\fBidentity\fR, \fBpassword\fR, and 92\fBotp\fR commands. <id> needs to be copied from 93the matching request. \fBpassword\fR and 94\fBotp\fR commands can be used regardless of whether 95the request was for PASSWORD or OTP. The main difference between these 96two commands is that values given with \fBpassword\fR are 97remembered as long as wpa_supplicant is running whereas values given 98with \fBotp\fR are used only once and then forgotten, 99i.e., wpa_supplicant will ask frontend for a new value for every use. 100This can be used to implement one-time-password lists and generic token 101card -based authentication. 102.Pp 103Example request for password and a matching reply: 104.sp 105.nf 106CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 107> password 1 mysecretpassword 108.fi 109.Pp 110Example request for generic token card challenge-response: 111.sp 112.nf 113CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 114> otp 2 9876 115.fi 116.Sh Options 117.Bl -tag -width indent 118.It Fl p 119Change the path where control sockets should 120be found. 121.It Fl g 122Connect to the global control socket at the 123indicated path rather than an interface-specific control 124socket. 125.It Fl i 126Specify the interface that is being 127configured. By default, choose the first interface found with 128a control socket in the socket path. 129.It Fl h 130Help. Show a usage message. 131.It Fl v 132Show version information. 133.It Fl B 134Run as a daemon in the background. 135.It Fl a 136Run in daemon mode executing the action file 137based on events from wpa_supplicant. The specified file will 138be executed with the first argument set to interface name and 139second to "CONNECTED" or "DISCONNECTED" depending on the event. 140This can be used to execute networking tools required to configure 141the interface. 142 143Additionally, three environmental variables are available to 144the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR 145contains the absolute path to the ctrl_interface socket. WPA_ID 146contains the unique network_id identifier assigned to the active 147network, and WPA_ID_STR contains the content of the id_str option. 148.It Fl P 149Set the location of the PID 150file. 151.It Fl G 152Set the interval (in seconds) at which 153wpa_cli pings the supplicant. 154.Sh Commands 155.Pp 156The following commands are available: 157.Bl -tag -width indent 158.It Ic status 159get current WPA/EAPOL/EAP status 160.It Ic mib 161get MIB variables (dot1x, dot11) 162.It Ic help 163show this usage help 164.It Ic interface Ar ifname 165show interfaces/select interface 166.It Ic level Ar debug level 167change debug level 168.It Ic license 169show full wpa_cli license 170.It Ic logoff 171IEEE 802.1X EAPOL state machine logoff 172.It Ic logon 173IEEE 802.1X EAPOL state machine logon 174.It Ic set 175set variables (shows list of variables when run without arguments) 176.It Ic pmksa 177show PMKSA cache 178.It Ic reassociate 179force reassociation 180.It Ic reconfigure 181force wpa_supplicant to re-read its configuration file 182.It Ic preauthenticate Ar BSSID 183force preauthentication 184.It Ic identity Ar network_id identity 185configure identity for an SSID 186.It Ic password Ar network_id password 187configure password for an SSID 188.It Ic pin Ar network_id pin 189configure pin for an SSID 190.It Ic otp Ar network_id password 191configure one-time-password for an SSID 192.It Ic bssid Ar network_id BSSID 193set preferred BSSID for an SSID 194.It Ic \fBlist_networks\fR 195list configured networks 196.It Ic terminate 197terminate \fBwpa_supplicant\fR 198.It Ic quit 199exit wpa_cli 200.Sh "SEE ALSO" 201.Pp 202.Xr wpa_supplicant.conf 5 , 203.Xr wpa_supplicant 8 204.Sh AUTHORS 205.Pp 206wpa_supplicant is copyright (c) 2003-2019, 207Jouni Malinen <j@w1.fi> and 208contributors. 209All Rights Reserved. 210.Pp 211This program is licensed under the BSD license (the one with 212advertisement clause removed). 213