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