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