usr.sbin/802_11/wpa_cli/wpa_cli.8

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