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.Dd January 24, 2017 26.Dt WPA_CLI 8 27.Os 28.Sh NAME 29.Nm wpa_cli 30.Nd "text-based frontend program for interacting with wpa_supplicant" 31.Sh SYNOPSIS 32.Nm wpa_cli 33.Op Fl p Ar path_to_ctrl_sockets 34.Op Fl i Ar ifname 35.Op Fl hvB 36.Op Fl a Ar action_file 37.Op Fl P Ar pid_file 38.Op Fl g Ar global_ctrl 39.Op Fl G Ar ping_interval 40.Ar command ... 41.Sh DESCRIPTION 42The 43.Nm 44utility 45is a text-based frontend program for interacting with 46.Xr wpa_supplicant 8 . 47It is used to query current status, 48change configuration, 49trigger events, 50and 51request interactive user input. 52.Pp 53The 54.Nm 55utility 56can show the 57current authentication status, 58selected security 59mode, dot11 and dot1x MIBs, etc. 60In addition, 61.Nm 62can configure EAPOL state machine 63parameters and trigger events such as reassociation 64and IEEE 802.1X logoff/logon. 65.Pp 66The 67.Nm 68utility 69provides an interface to supply authentication information 70such as username and password when it is not provided in the 71.Xr wpa_supplicant.conf 5 72configuration file. 73This can be used, for example, to implement 74one-time passwords or generic token card 75authentication where the authentication is based on a 76challenge-response that uses an external device for generating the 77response. 78.Pp 79The 80.Nm 81utility 82supports two modes: interactive and command line. 83Both modes share the same command set and the main difference 84is in interactive mode providing access to unsolicited messages 85(event messages, username/password requests). 86.Pp 87Interactive mode is started when 88.Nm 89is executed without any parameters on the command line. 90Commands are then entered from the controlling terminal in 91response to the 92.Nm 93prompt. 94In command line mode, the same commands are 95entered as command line arguments. 96.Pp 97The control interface of 98.Xr wpa_supplicant 8 99can be configured to allow 100non-root user access by using the 101.Va ctrl_interface_group 102parameter 103in the 104.Xr wpa_supplicant.conf 5 105configuration file. 106This makes it possible to run 107.Nm 108with a normal user account. 109.Sh AUTHENTICATION PARAMETERS 110When 111.Xr wpa_supplicant 8 112needs authentication parameters, such as username and password, 113that are not present in the configuration file, it sends a 114request message to all attached frontend programs, e.g., 115.Nm 116in interactive mode. 117The 118.Nm 119utility 120shows these requests with a 121.Dq Li CTRL-REQ- Ns Ao Ar type Ac Ns Li - Ns Ao Ar id Ac Ns : Ns Aq Ar text 122prefix, where 123.Aq Ar type 124is 125.Li IDENTITY , PASSWORD , 126or 127.Li OTP 128(One-Time Password), 129.Aq Ar id 130is a unique identifier for the current network, 131.Aq Ar text 132is a description of the request. 133In the case of an 134.Li OTP 135(One-Time Password) request, 136it includes the challenge from the authentication server. 137.Pp 138A user must supply 139.Xr wpa_supplicant 8 140the needed parameters in response to these requests. 141.Pp 142For example, 143.Bd -literal -offset indent 144CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 145> password 1 mysecretpassword 146 147Example request for generic token card challenge-response: 148 149CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 150> otp 2 9876 151.Ed 152.Sh OPTIONS 153These options are available: 154.Bl -tag -width indent 155.It Fl p Ar path 156Control sockets path. 157This should match the 158.Ic ctrl_interface 159in 160.Xr wpa_supplicant.conf 5 . 161The default path is 162.Pa /var/run/wpa_supplicant . 163.It Fl i Ar ifname 164Interface to be configured. 165By default, the first interface found in the socket path is used. 166.It Fl h 167Show help. 168.It Fl v 169Show version information. 170.It Fl B 171Run the daemon in the background. 172.It Fl a Ar action_file 173Run in daemon mode, executing the action file based on events from 174.Xr wpa_supplicant 8 . 175.It Fl P Ar pid_file 176PID file location. 177.It Fl g Ar global_ctrl 178Use a global control interface to 179.Xr wpa_supplicant 8 180rather than the default Unix domain sockets. 181.It Fl G Ar ping_interval 182Wait 183.Dq ping_interval 184seconds before sending each ping to 185.Xr wpa_supplicant 8 . 186See the 187.Ic ping 188command. 189.It command 190See available commands in the next section. 191.El 192.Sh COMMANDS 193These commands can be supplied on the command line 194or at a prompt when operating interactively. 195.Bl -tag -width indent 196.It Ic status 197Report the current WPA/EAPOL/EAP status for the current interface. 198.It Ic ifname 199Show the current interface name. 200The default interface is the first interface found in the socket path. 201.It Ic ping 202Ping the 203.Xr wpa_supplicant 8 204utility. 205This command can be used to test the status of the 206.Xr wpa_supplicant 8 207daemon. 208.It Ic mib 209Report MIB variables (dot1x, dot11) for the current interface. 210.It Ic help 211Show usage help. 212.It Ic interface Op Ar ifname 213Show available interfaces and/or set the current interface 214when multiple interfaces are available. 215.It Ic level Ar debug_level 216Change the debugging level in 217.Xr wpa_supplicant 8 . 218Larger numbers generate more messages. 219.It Ic license 220Display the full license for 221.Nm . 222.It Ic logoff 223Send the IEEE 802.1X EAPOL state machine into the 224.Dq logoff 225state. 226.It Ic logon 227Send the IEEE 802.1X EAPOL state machine into the 228.Dq logon 229state. 230.It Ic set Op Ar settings 231Set variables. 232When no arguments are supplied, the known variables and their settings 233are displayed. 234.It Ic pmksa 235Show the contents of the PMKSA cache. 236.It Ic reassociate 237Force a reassociation to the current access point. 238.It Ic reconfigure 239Force 240.Xr wpa_supplicant 8 241to re-read its configuration file. 242.It Ic preauthenticate Ar BSSID 243Force preauthentication of the specified 244.Ar BSSID . 245.It Ic identity Ar network_id identity 246Configure an identity for an SSID. 247.It Ic password Ar network_id password 248Configure a password for an SSID. 249.It Ic new_password Ar network_id password 250Change the password for an SSID. 251.It Ic PIN Ar network_id pin 252Configure a PIN for an SSID. 253.It Ic passphrase Ar network_id passphrase 254Configure a private key passphrase for an SSID. 255.It Ic bssid Ar network_id bssid 256Set a preferred BSSID for an SSID 257.It Ic blacklist Op Ar bssid | clear 258Add a BSSID to the blacklist. 259When invoked without any extra arguments, display the blacklist. 260Specifying 261.Ar clear 262causes 263.Nm 264to clear the blacklist. 265.It Ic list_networks 266List configured networks. 267.It Ic select_network Ar network_id 268Select a network and disable others. 269.It Ic enable_network Ar network_id 270Enable a network. 271.It Ic disable_network Ar network_id 272Disable a network. 273.It Ic add_network 274Add a network. 275.It Ic remove_network Ar network_id 276Remove a network. 277.It Ic set_network Op Ar network_id variable value 278Set network variables. 279Shows a list of variables when run without arguments. 280.It Ic get_network Ar network_id variable 281Get network variables. 282.It Ic disconnect 283Disconnect and wait for reassociate/reconnect command before connecting. 284.It Ic reconnect 285Similar to 286.Ic reassociate , 287but only takes effect if already disconnected. 288.It Ic scan 289Request new BSS scan. 290.It Ic scan_results 291Get the latest BSS scan results. 292This command can be invoked after running a BSS scan with 293.Ic scan . 294.It Ic bss Op Ar idx | bssid 295Get a detailed BSS scan result for the network identified by 296.Dq bssid 297or 298.Dq idx . 299.It Ic otp Ar network_id password 300Configure a one-time password for an SSID. 301.It Ic terminate 302Force 303.Xr wpa_supplicant 8 304to terminate. 305.It Ic interface_add Ar ifname Op Ar confname driver ctrl_interface driver_param bridge_name 306Add a new interface with the given parameters. 307.It Ic interface_remove Ar ifname 308Remove the interface. 309.It Ic interface_list 310List available interfaces. 311.It Ic quit 312Exit 313.Nm . 314.El 315.Sh SEE ALSO 316.Xr wpa_supplicant.conf 5 , 317.Xr wpa_supplicant 8 318.Sh HISTORY 319The 320.Nm 321utility first appeared in 322.Fx 6.0 . 323.Sh AUTHORS 324The 325.Nm 326utility was written by 327.An Jouni Malinen Aq Mt j@w1.fi . 328This manual page is derived from the 329.Pa README 330and 331.Pa wpa_cli.c 332files included in the 333.Nm wpa_supplicant 334distribution. 335