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