usr.sbin/wpa/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 .Dd January 24, 2017
  26 .Dt WPA_CLI 8
  27 .Os
  28 .Sh NAME
  29 .Nm wpa_cli
  30 .Nd "text-based frontend program for interacting with wpa_supplicant"
  31 .Sh SYNOPSIS
  32 .Nm wpa_cli
  33 .Op Fl p Ar path_to_ctrl_sockets
  34 .Op Fl i Ar ifname
  35 .Op Fl hvB
  36 .Op Fl a Ar action_file
  37 .Op Fl P Ar pid_file
  38 .Op Fl g Ar global_ctrl
  39 .Op Fl G Ar ping_interval
  40 .Ar command ...
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 utility
  45 is a text-based frontend program for interacting with
  46 .Xr wpa_supplicant 8 .
  47 It is used to query current status,
  48 change configuration,
  49 trigger events,
  50 and
  51 request interactive user input.
  52 .Pp
  53 The
  54 .Nm
  55 utility
  56 can show the
  57 current authentication status,
  58 selected security
  59 mode, dot11 and dot1x MIBs, etc.
  60 In addition,
  61 .Nm
  62 can configure EAPOL state machine
  63 parameters and trigger events such as reassociation
  64 and IEEE 802.1X logoff/logon.
  65 .Pp
  66 The
  67 .Nm
  68 utility
  69 provides an interface to supply authentication information
  70 such as username and password when it is not provided in the
  71 .Xr wpa_supplicant.conf 5
  72 configuration file.
  73 This can be used, for example, to implement
  74 one-time passwords or generic token card
  75 authentication where the authentication is based on a
  76 challenge-response that uses an external device for generating the
  77 response.
  78 .Pp
  79 The
  80 .Nm
  81 utility
  82 supports two modes: interactive and command line.
  83 Both modes share the same command set and the main difference
  84 is in interactive mode providing 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 : 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,
 131 .Aq Ar text
 132 is a description of the request.
 133 In the case of an
 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 > 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 > otp 2 9876
 151 .Ed
 152 .Sh OPTIONS
 153 These options are available:
 154 .Bl -tag -width indent
 155 .It Fl p Ar path
 156 Control sockets path.
 157 This should match the
 158 .Ic ctrl_interface
 159 in
 160 .Xr wpa_supplicant.conf 5 .
 161 The default path is
 162 .Pa /var/run/wpa_supplicant .
 163 .It Fl i Ar ifname
 164 Interface to be configured.
 165 By default, the first interface found in the socket path is used.
 166 .It Fl h
 167 Show help.
 168 .It Fl v
 169 Show version information.
 170 .It Fl B
 171 Run the daemon in the background.
 172 .It Fl a Ar action_file
 173 Run in daemon mode, executing the action file based on events from
 174 .Xr wpa_supplicant 8 .
 175 .It Fl P Ar pid_file
 176 PID file location.
 177 .It Fl g Ar global_ctrl
 178 Use a global control interface to
 179 .Xr wpa_supplicant 8
 180 rather than the default Unix domain sockets.
 181 .It Fl G Ar ping_interval
 182 Wait
 183 .Dq ping_interval
 184 seconds before sending each ping to
 185 .Xr wpa_supplicant 8 .
 186 See the
 187 .Ic ping
 188 command.
 189 .It command
 190 See available commands in the next section.
 191 .El
 192 .Sh COMMANDS
 193 These commands can be supplied on the command line
 194 or at a prompt when operating interactively.
 195 .Bl -tag -width indent
 196 .It Ic status
 197 Report the current WPA/EAPOL/EAP status for the current interface.
 198 .It Ic ifname
 199 Show the current interface name.
 200 The default interface is the first interface found in the socket path.
 201 .It Ic ping
 202 Ping the
 203 .Xr wpa_supplicant 8
 204 utility.
 205 This command can be used to test the status of the
 206 .Xr wpa_supplicant 8
 207 daemon.
 208 .It Ic mib
 209 Report MIB variables (dot1x, dot11) for the current interface.
 210 .It Ic help
 211 Show usage help.
 212 .It Ic interface Op Ar ifname
 213 Show available interfaces and/or set the current interface
 214 when multiple interfaces are available.
 215 .It Ic level Ar debug_level
 216 Change the debugging level in
 217 .Xr wpa_supplicant 8 .
 218 Larger numbers generate more messages.
 219 .It Ic license
 220 Display the full license for
 221 .Nm .
 222 .It Ic logoff
 223 Send the IEEE 802.1X EAPOL state machine into the
 224 .Dq logoff
 225 state.
 226 .It Ic logon
 227 Send the IEEE 802.1X EAPOL state machine into the
 228 .Dq logon
 229 state.
 230 .It Ic set Op Ar settings
 231 Set variables.
 232 When no arguments are supplied, the known variables and their settings
 233 are displayed.
 234 .It Ic pmksa
 235 Show the contents of the PMKSA cache.
 236 .It Ic reassociate
 237 Force a reassociation to the current access point.
 238 .It Ic reconfigure
 239 Force
 240 .Xr wpa_supplicant 8
 241 to re-read its configuration file.
 242 .It Ic preauthenticate Ar BSSID
 243 Force preauthentication of the specified
 244 .Ar BSSID .
 245 .It Ic identity Ar network_id identity
 246 Configure an identity for an SSID.
 247 .It Ic password Ar network_id password
 248 Configure a password for an SSID.
 249 .It Ic new_password Ar network_id password
 250 Change the password for an SSID.
 251 .It Ic PIN Ar network_id pin
 252 Configure a PIN for an SSID.
 253 .It Ic passphrase Ar network_id passphrase
 254 Configure a private key passphrase for an SSID.
 255 .It Ic bssid Ar network_id bssid
 256 Set a preferred BSSID for an SSID
 257 .It Ic blacklist Op Ar bssid | clear
 258 Add a BSSID to the blacklist.
 259 When invoked without any extra arguments, display the blacklist.
 260 Specifying
 261 .Ar clear
 262 causes
 263 .Nm
 264 to clear the blacklist.
 265 .It Ic list_networks
 266 List configured networks.
 267 .It Ic select_network Ar network_id
 268 Select a network and disable others.
 269 .It Ic enable_network Ar network_id
 270 Enable a network.
 271 .It Ic disable_network Ar network_id
 272 Disable a network.
 273 .It Ic add_network
 274 Add a network.
 275 .It Ic remove_network Ar network_id
 276 Remove a network.
 277 .It Ic set_network Op Ar network_id variable value
 278 Set network variables.
 279 Shows a list of variables when run without arguments.
 280 .It Ic get_network Ar network_id variable
 281 Get network variables.
 282 .It Ic disconnect
 283 Disconnect and wait for reassociate/reconnect command before connecting.
 284 .It Ic reconnect
 285 Similar to
 286 .Ic reassociate ,
 287 but only takes effect if already disconnected.
 288 .It Ic scan
 289 Request new BSS scan.
 290 .It Ic scan_results
 291 Get the latest BSS scan results.
 292 This command can be invoked after running a BSS scan with
 293 .Ic scan .
 294 .It Ic bss Op Ar idx | bssid
 295 Get a detailed BSS scan result for the network identified by
 296 .Dq bssid
 297 or
 298 .Dq idx .
 299 .It Ic otp Ar network_id password
 300 Configure a one-time password for an SSID.
 301 .It Ic terminate
 302 Force
 303 .Xr wpa_supplicant 8
 304 to terminate.
 305 .It Ic interface_add Ar ifname Op Ar confname driver ctrl_interface driver_param bridge_name
 306 Add a new interface with the given parameters.
 307 .It Ic interface_remove Ar ifname
 308 Remove the interface.
 309 .It Ic interface_list
 310 List available interfaces.
 311 .It Ic quit
 312 Exit
 313 .Nm .
 314 .El
 315 .Sh SEE ALSO
 316 .Xr wpa_supplicant.conf 5 ,
 317 .Xr wpa_supplicant 8
 318 .Sh HISTORY
 319 The
 320 .Nm
 321 utility first appeared in
 322 .Fx 6.0 .
 323 .Sh AUTHORS
 324 The
 325 .Nm
 326 utility was written by
 327 .An Jouni Malinen Aq Mt j@w1.fi .
 328 This manual page is derived from the
 329 .Pa README
 330 and
 331 .Pa wpa_cli.c
 332 files included in the
 333 .Nm wpa_supplicant
 334 distribution.