1.\" $NetBSD: wpa_cli.8,v 1.2 2013/07/20 21:40:04 wiz 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 October 1, 2005 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 interface Op Ar ifname 163Show available interfaces and/or set the current interface 164when multiple are available. 165.It Ic level Ar debug_level 166Change the debugging level in 167.Xr wpa_supplicant 8 . 168Larger numbers generate more messages. 169.It Ic license 170Display the full 171license for 172.Nm . 173.It Ic logoff 174Send the IEEE 802.1X EAPOL state machine into the 175.Dq logoff 176state. 177.It Ic logon 178Send the IEEE 802.1X EAPOL state machine into the 179.Dq logon 180state. 181.It Ic set Op Ar settings 182Set variables. 183When no arguments are supplied, the known variables and their settings 184are displayed. 185.It Ic pmksa 186Show the contents of the PMKSA cache. 187.It Ic reassociate 188Force a reassociation to the current access point. 189.It Ic reconfigure 190Force 191.Xr wpa_supplicant 8 192to re-read its configuration file. 193.It Ic preauthenticate Ar BSSID 194Force preauthentication of the specified 195.Ar BSSID . 196.It Ic identity Ar network_id identity 197Configure an identity for an SSID. 198.It Ic password Ar network_id password 199Configure a password for an SSID. 200.It Ic otp Ar network_id password 201Configure a one-time password for an SSID. 202.It Ic terminate 203Force 204.Xr wpa_supplicant 8 205to terminate. 206.It Ic quit 207Exit 208.Nm . 209.El 210.Sh SEE ALSO 211.Xr wpa_supplicant.conf 5 , 212.Xr wpa_supplicant 8 213.Sh HISTORY 214The 215.Nm 216utility first appeared in 217.Nx 4.0 . 218.Sh AUTHORS 219The 220.Nm 221utility was written by 222.An Jouni Malinen Aq Mt jkmaline@cc.hut.fi . 223This manual page is derived from the 224.Pa README 225file included in the 226.Nm wpa_supplicant 227distribution. 228