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.Op Ar command ... 43.Sh DESCRIPTION 44.Nm 45is a text-based frontend program for interacting with wpa_supplicant. It is 46used to query current status, change configuration, trigger events, and request 47interactive user input. 48.Pp 49.Nm 50can show the current authentication status, selected security mode, dot11 and 51dot1x MIBs, etc. In addition, it can configure some variables like EAPOL state 52machine parameters and trigger events like reassociation and IEEE 802.1X 53logoff/logon. wpa_cli provides a user interface to request 54authentication information, like username and password, if these 55are not included in the configuration. This can be used to 56implement, e.g., one-time-passwords or generic token card 57authentication where the authentication is based on a 58challenge-response that uses an external device for generating the 59response. 60.Pp 61The control interface of wpa_supplicant can be configured to 62allow non-root user access (ctrl_interface GROUP= parameter in the 63configuration file). This makes it possible to run wpa_cli with a 64normal user account. 65.Pp 66wpa_cli supports two modes: interactive and command 67line. Both modes share the same command set and the main 68difference is in interactive mode providing access to unsolicited 69messages (event messages, username/password requests). 70.Pp 71Interactive mode is started when wpa_cli is executed without 72including the command as a command line parameter. Commands are 73then entered on the wpa_cli prompt. In command line mode, the same 74commands are entered as command line arguments for wpa_cli. 75.Sh "INTERACTIVE AUTHENTICATION PARAMETERS REQUEST" 76When wpa_supplicant need authentication parameters, like 77username and password, which are not present in the configuration 78file, it sends a request message to all attached frontend programs, 79e.g., wpa_cli in interactive mode. wpa_cli shows these requests 80with "CTRL-REQ-<type>-<id>:<text>" 81prefix. <type> is IDENTITY, PASSWORD, or OTP 82(one-time-password). <id> is a unique identifier for the 83current network. <text> is description of the request. In 84case of OTP request, it includes the challenge from the 85authentication server. 86.Pp 87The reply to these requests can be given with 88\fBidentity\fR, \fBpassword\fR, and 89\fBotp\fR commands. <id> needs to be copied from 90the matching request. \fBpassword\fR and 91\fBotp\fR commands can be used regardless of whether 92the request was for PASSWORD or OTP. The main difference between these 93two commands is that values given with \fBpassword\fR are 94remembered as long as wpa_supplicant is running whereas values given 95with \fBotp\fR are used only once and then forgotten, 96i.e., wpa_supplicant will ask frontend for a new value for every use. 97This can be used to implement one-time-password lists and generic token 98card -based authentication. 99.Pp 100Example request for password and a matching reply: 101.sp 102.nf 103CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 104> password 1 mysecretpassword 105.fi 106.Pp 107Example request for generic token card challenge-response: 108.sp 109.nf 110CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 111> otp 2 9876 112.fi 113.Sh Options 114.Bl -tag -width indent 115.It Fl p 116Change the path where control sockets should 117be found. 118.It Fl g 119Connect to the global control socket at the 120indicated path rather than an interface-specific control 121socket. 122.It Fl i 123Specify the interface that is being 124configured. By default, choose the first interface found with 125a control socket in the socket path. 126.It Fl h 127Help. Show a usage message. 128.It Fl v 129Show version information. 130.It Fl B 131Run as a daemon in the background. 132.It Fl a 133Run in daemon mode executing the action file 134based on events from wpa_supplicant. The specified file will 135be executed with the first argument set to interface name and 136second to "CONNECTED" or "DISCONNECTED" depending on the event. 137This can be used to execute networking tools required to configure 138the interface. 139.Pp 140Additionally, three environmental variables are available to 141the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR 142contains the absolute path to the ctrl_interface socket. WPA_ID 143contains the unique network_id identifier assigned to the active 144network, and WPA_ID_STR contains the content of the id_str option. 145.It Fl P 146Set the location of the PID 147file. 148.It Fl G 149Set the interval (in seconds) at which 150wpa_cli pings the supplicant. 151.El 152.Sh Commands 153The following commands are available: 154.Bl -tag -width indent 155.It Ic status 156get current WPA/EAPOL/EAP status 157.It Ic mib 158get MIB variables (dot1x, dot11) 159.It Ic help 160show this usage help 161.It Ic interface Ar ifname 162show interfaces/select interface 163.It Ic level Ar debug level 164change debug level 165.It Ic license 166show full wpa_cli license 167.It Ic logoff 168IEEE 802.1X EAPOL state machine logoff 169.It Ic logon 170IEEE 802.1X EAPOL state machine logon 171.It Ic set 172set variables (shows list of variables when run without arguments) 173.It Ic pmksa 174show PMKSA cache 175.It Ic reassociate 176force reassociation 177.It Ic reconfigure 178force wpa_supplicant to re-read its configuration file 179.It Ic preauthenticate Ar BSSID 180force preauthentication 181.It Ic identity Ar network_id identity 182configure identity for an SSID 183.It Ic password Ar network_id password 184configure password for an SSID 185.It Ic pin Ar network_id pin 186configure pin for an SSID 187.It Ic otp Ar network_id password 188configure one-time-password for an SSID 189.It Ic bssid Ar network_id BSSID 190set preferred BSSID for an SSID 191.It Ic \fBlist_networks\fR 192list configured networks 193.It Ic terminate 194terminate \fBwpa_supplicant\fR 195.It Ic quit 196exit wpa_cli 197.El 198.Sh "SEE ALSO" 199.Xr wpa_supplicant.conf 5 , 200.Xr wpa_supplicant 8 201.Sh AUTHORS 202wpa_supplicant is copyright (c) 2003-2019, 203Jouni Malinen <j@w1.fi> and 204contributors. 205All Rights Reserved. 206.Pp 207This program is licensed under the BSD license (the one with 208advertisement clause removed). 209