1.\" $NetBSD: wpa_cli.8,v 1.5 2019/06/19 03:23:56 gutteridge Exp $ 2.\" 3.\" Copyright (c) 2005 Sam Leffler <sam@errno.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Based on: 28.\" $FreeBSD: /repoman/r/ncvs/src/usr.sbin/wpa/wpa_cli/wpa_cli.8,v 1.2 2005/06/27 06:40:43 ru Exp $ 29.\" 30.Dd June 19, 2019 31.Dt WPA_CLI 8 32.Os 33.Sh NAME 34.Nm wpa_cli 35.Nd text-based frontend program for interacting with wpa_supplicant 36.Sh SYNOPSIS 37.Nm 38.Op Ar commands 39.Sh DESCRIPTION 40The 41.Nm 42utility 43is a text-based frontend program for interacting with 44.Xr wpa_supplicant 8 . 45It is used to query current status, 46change configuration, 47trigger events, 48and 49request interactive user input. 50.Pp 51The 52.Nm 53utility 54can show the 55current authentication status, 56selected security 57mode, dot11 and dot1x MIBs, etc. 58In addition, 59.Nm 60can configure EAPOL state machine 61parameters and trigger events such as reassociation 62and IEEE 802.1X logoff/logon. 63.Pp 64The 65.Nm 66utility 67provides an interface to supply authentication information 68such as username and password when it is not provided in the 69.Xr wpa_supplicant.conf 5 70configuration file. 71This can be used, for example, to implement 72one-time passwords or generic token card 73authentication where the authentication is based on a 74challenge-response that uses an external device for generating the 75response. 76.Pp 77The 78.Nm 79utility 80supports two modes: interactive and command line. 81Both modes share the same command set and the main difference 82is that in interactive mode, 83.Nm 84provides 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 Li : 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, and 131.Aq Ar text 132is description of the request. 133In the case of a 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\*[Gt] password 1 mysecretpassword 146 147Example request for generic token card challenge-response: 148 149CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 150\*[Gt] otp 2 9876 151.Ed 152.Sh COMMANDS 153The following commands may be supplied on the command line 154or at a prompt when operating interactively. 155.Bl -tag -width indent 156.It Ic status 157Report the current WPA/EAPOL/EAP status for the current interface. 158.It Ic mib 159Report MIB variables (dot1x, dot11) for the current interface. 160.It Ic help 161Show usage help. 162.It Ic status 163Get current WPA/EAPOL/EAP status. 164.It Ic add_network 165Add a network. Returns a number to be used in set_network commands. 166.It Ic set_network Ar network_id ssid Ar my_ssid_name 167Make network_id use the SSID my_ssid_name. 168.It Ic set_network Ar network_id psk Ar my_ssid_password 169Make network_id use the password my_ssid_password 170.It Ic enable_network Ar network_id 171Begin using the network at network_id. 172.It Ic list_network 173List the networks configured. 174.It Ic scan 175Begin a scan of nearby APs. Results can be obtained with 176.Ic scan_results . 177.It Ic interface Op Ar ifname 178Show available interfaces and/or set the current interface 179when multiple are available. 180.It Ic level Ar debug_level 181Change the debugging level in 182.Xr wpa_supplicant 8 . 183Larger numbers generate more messages. 184.It Ic license 185Display the full 186license for 187.Nm . 188.It Ic logoff 189Send the IEEE 802.1X EAPOL state machine into the 190.Dq logoff 191state. 192.It Ic logon 193Send the IEEE 802.1X EAPOL state machine into the 194.Dq logon 195state. 196.It Ic set Op Ar settings 197Set variables. 198When no arguments are supplied, the known variables and their settings 199are displayed. 200.It Ic pmksa 201Show the contents of the PMKSA cache. 202.It Ic reassociate 203Force a reassociation to the current access point. 204.It Ic reconfigure 205Force 206.Xr wpa_supplicant 8 207to re-read its configuration file. 208.It Ic preauthenticate Ar BSSID 209Force preauthentication of the specified 210.Ar BSSID . 211.It Ic identity Ar network_id identity 212Configure an identity for an SSID. 213.It Ic password Ar network_id password 214Configure a password for an SSID. 215.It Ic otp Ar network_id password 216Configure a one-time password for an SSID. 217.It Ic terminate 218Force 219.Xr wpa_supplicant 8 220to terminate. 221.It Ic quit 222Exit 223.Nm . 224.El 225.Sh SEE ALSO 226.Xr wpa_supplicant.conf 5 , 227.Xr wpa_passphrase 8 , 228.Xr wpa_supplicant 8 229.Sh EXAMPLES 230A sample run of discovering and connecting to a network 231with SSID "MyWifiNetwork" and with a password "MyWifiPassword". 232.Pp 233If wpa_supplicant isn't already running, start it with the command 234.Ic service wpa_supplicant onestart . 235.Pp 236Find the network 237.Bd -literal -offset indent 238.Ic scan 239.Ic scan_results 24017:07:08.868: bssid / frequency / signal level / flags / ssid 24114:aa:ff:ee:aa:cc 2437 187 [WPA-PSK-CCMP+TKIP][ESS] MyWifiNetwork 24244:ee:ff:bb:33:33 2452 168 [WPA2-PSK-CCMP][ESS] SomeOtherNetwork 243.Ed 244.Pp 245Now, let's create a network and configure it. 246.Bd -literal -offset indent 247.Ic add_network 24817:08:13.047: 1 249.Ed 250.Pp 251That means the new network_id we should use is 1. 252.Bd -literal -offset indent 253.Ic set_network 1 ssid \[dq]MyWifiNetwork\[dq] 254.Ic set_network 1 psk \[dq]MyWifiPassword\[dq] 255.Ic enable_network 1 256.Ed 257.Pp 258After this point, you should be connected, but no IP address 259is configured. You will likely want to configure the address using 260.Xr dhcpcd 8 . 261.Sh HISTORY 262The 263.Nm 264utility first appeared in 265.Nx 4.0 . 266.Sh AUTHORS 267The 268.Nm 269utility was written by 270.An Jouni Malinen Aq Mt jkmaline@cc.hut.fi . 271This manual page is derived from the 272.Pa README 273file included in the 274.Nm wpa_supplicant 275distribution. 276