usr.sbin/wpa/wpa_cli/wpa_cli.8

   1 .\" $NetBSD: wpa_cli.8,v 1.1 2005/10/01 18:50:12 scw 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
  40 The
  41 .Nm
  42 utility
  43 is a text-based frontend program for interacting with
  44 .Xr wpa_supplicant 8 .
  45 It is used to query current status,
  46 change configuration,
  47 trigger events,
  48 and
  49 request interactive user input.
  50 .Pp
  51 The
  52 .Nm
  53 utility
  54 can show the
  55 current authentication status,
  56 selected security
  57 mode, dot11 and dot1x MIBs, etc.
  58 In addition,
  59 .Nm
  60 can configure EAPOL state machine
  61 parameters and trigger events such as reassociation
  62 and IEEE 802.1X logoff/logon.
  63 .Pp
  64 The
  65 .Nm
  66 utility
  67 provides an interface to supply authentication information
  68 such as username and password when it is not provided in the
  69 .Xr wpa_supplicant.conf 5
  70 configuration file.
  71 This can be used, for example, to implement
  72 one-time passwords or generic token card
  73 authentication where the authentication is based on a
  74 challenge-response that uses an external device for generating the
  75 response.
  76 .Pp
  77 The
  78 .Nm
  79 utility
  80 supports two modes: interactive and command line.
  81 Both modes share the same command set and the main difference
  82 is that in interactive mode,
  83 .Nm
  84 provides access to unsolicited messages
  85 (event messages, username/password requests).
  86 .Pp
  87 Interactive mode is started when
  88 .Nm
  89 is executed without any parameters on the command line.
  90 Commands are then entered from the controlling terminal in
  91 response to the
  92 .Nm
  93 prompt.
  94 In command line mode, the same commands are
  95 entered as command line arguments.
  96 .Pp
  97 The control interface of
  98 .Xr wpa_supplicant 8
  99 can be configured to allow
 100 non-root user access by using the
 101 .Va ctrl_interface_group
 102 parameter
 103 in the
 104 .Xr wpa_supplicant.conf 5
 105 configuration file.
 106 This makes it possible to run
 107 .Nm
 108 with a normal user account.
 109 .Sh AUTHENTICATION PARAMETERS
 110 When
 111 .Xr wpa_supplicant 8
 112 needs authentication parameters, such as username and password,
 113 that are not present in the configuration file, it sends a
 114 request message to all attached frontend programs, e.g.,
 115 .Nm
 116 in interactive mode.
 117 The
 118 .Nm
 119 utility
 120 shows 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
 122 prefix, where
 123 .Aq Ar type
 124 is
 125 .Li IDENTITY , PASSWORD ,
 126 or
 127 .Li OTP
 128 (one-time password),
 129 .Aq Ar id
 130 is a unique identifier for the current network, and
 131 .Aq Ar text
 132 is description of the request.
 133 In the case of a
 134 .Li OTP
 135 (One Time Password) request,
 136 it includes the challenge from the authentication server.
 137 .Pp
 138 A user must supply
 139 .Xr wpa_supplicant 8
 140 the needed parameters in response to these requests.
 141 .Pp
 142 For example,
 143 .Bd -literal -offset indent
 144 CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
 145 \*[Gt] password 1 mysecretpassword
 146
 147 Example request for generic token card challenge-response:
 148
 149 CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
 150 \*[Gt] otp 2 9876
 151 .Ed
 152 .Sh COMMANDS
 153 The following commands may be supplied on the command line
 154 or at a prompt when operating interactively.
 155 .Bl -tag -width indent
 156 .It Ic status
 157 Report the current WPA/EAPOL/EAP status for the current interface.
 158 .It Ic mib
 159 Report MIB variables (dot1x, dot11) for the current interface.
 160 .It Ic help
 161 Show usage help.
 162 .It Ic interface Op Ar ifname
 163 Show available interfaces and/or set the current interface
 164 when multiple are available.
 165 .It Ic level Ar debug_level
 166 Change the debugging level in
 167 .Xr wpa_supplicant 8 .
 168 Larger numbers generate more messages.
 169 .It Ic license
 170 Display the full
 171 license for
 172 .Nm .
 173 .It Ic logoff
 174 Send the IEEE 802.1X EAPOL state machine into the
 175 .Dq logoff
 176 state.
 177 .It Ic logon
 178 Send the IEEE 802.1X EAPOL state machine into the
 179 .Dq logon
 180 state.
 181 .It Ic set Op Ar settings
 182 Set variables.
 183 When no arguments are supplied, the known variables and their settings
 184 are displayed.
 185 .It Ic pmksa
 186 Show the contents of the PMKSA cache.
 187 .It Ic reassociate
 188 Force a reassociation to the current access point.
 189 .It Ic reconfigure
 190 Force
 191 .Xr wpa_supplicant 8
 192 to re-read its configuration file.
 193 .It Ic preauthenticate Ar BSSID
 194 Force preauthentication of the specified
 195 .Ar BSSID .
 196 .It Ic identity Ar network_id identity
 197 Configure an identity for an SSID.
 198 .It Ic password Ar network_id password
 199 Configure a password for an SSID.
 200 .It Ic otp Ar network_id password
 201 Configure a one-time password for an SSID.
 202 .It Ic terminate
 203 Force
 204 .Xr wpa_supplicant 8
 205 to terminate.
 206 .It Ic quit
 207 Exit
 208 .Nm .
 209 .El
 210 .Sh SEE ALSO
 211 .Xr wpa_supplicant.conf 5 ,
 212 .Xr wpa_supplicant 8
 213 .Sh HISTORY
 214 The
 215 .Nm
 216 utility first appeared in
 217 .Nx 4.0 .
 218 .Sh AUTHORS
 219 The
 220 .Nm
 221 utility was written by
 222 .An Jouni Malinen Aq jkmaline@cc.hut.fi .
 223 This manual page is derived from the
 224 .Pa README
 225 file included in the
 226 .Nm wpa_supplicant
 227 distribution.