1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> 2 3 <refentry> 4 <refmeta> 5 <refentrytitle>wpa_cli</refentrytitle> 6 <manvolnum>8</manvolnum> 7 </refmeta> 8 <refnamediv> 9 <refname>wpa_cli</refname> 10 11 <refpurpose>WPA command line client</refpurpose> 12 </refnamediv> 13 14 <refsynopsisdiv> 15 <cmdsynopsis> 16 <command>wpa_cli</command> 17 <arg>-p <replaceable>path to ctrl sockets</replaceable></arg> 18 <arg>-g <replaceable>path to global ctrl_interface socket</replaceable></arg> 19 <arg>-i <replaceable>ifname</replaceable></arg> 20 <arg>-hvB</arg> 21 <arg>-a <replaceable>action file</replaceable></arg> 22 <arg>-P <replaceable>pid file</replaceable></arg> 23 <arg>-G <replaceable>ping interval</replaceable></arg> 24 <arg><replaceable>command ...</replaceable></arg> 25 </cmdsynopsis> 26 </refsynopsisdiv> 27 28 <refsect1> 29 <title>Overview</title> 30 31 <para>wpa_cli is a text-based frontend program for interacting 32 with wpa_supplicant. It is used to query current status, change 33 configuration, trigger events, and request interactive user 34 input.</para> 35 36 <para>wpa_cli can show the current authentication status, selected 37 security mode, dot11 and dot1x MIBs, etc. In addition, it can 38 configure some variables like EAPOL state machine parameters and 39 trigger events like reassociation and IEEE 802.1X 40 logoff/logon. wpa_cli provides a user interface to request 41 authentication information, like username and password, if these 42 are not included in the configuration. This can be used to 43 implement, e.g., one-time-passwords or generic token card 44 authentication where the authentication is based on a 45 challenge-response that uses an external device for generating the 46 response.</para> 47 48 <para>The control interface of wpa_supplicant can be configured to 49 allow non-root user access (ctrl_interface GROUP= parameter in the 50 configuration file). This makes it possible to run wpa_cli with a 51 normal user account.</para> 52 53 <para>wpa_cli supports two modes: interactive and command 54 line. Both modes share the same command set and the main 55 difference is in interactive mode providing access to unsolicited 56 messages (event messages, username/password requests).</para> 57 58 <para>Interactive mode is started when wpa_cli is executed without 59 including the command as a command line parameter. Commands are 60 then entered on the wpa_cli prompt. In command line mode, the same 61 commands are entered as command line arguments for wpa_cli.</para> 62 </refsect1> 63 <refsect1> 64 <title>Interactive authentication parameters request</title> 65 66 <para>When wpa_supplicant need authentication parameters, like 67 username and password, which are not present in the configuration 68 file, it sends a request message to all attached frontend programs, 69 e.g., wpa_cli in interactive mode. wpa_cli shows these requests 70 with "CTRL-REQ-<type>-<id>:<text>" 71 prefix. <type> is IDENTITY, PASSWORD, or OTP 72 (one-time-password). <id> is a unique identifier for the 73 current network. <text> is description of the request. In 74 case of OTP request, it includes the challenge from the 75 authentication server.</para> 76 77 <para>The reply to these requests can be given with 78 <emphasis>identity</emphasis>, <emphasis>password</emphasis>, and 79 <emphasis>otp</emphasis> commands. <id> needs to be copied from 80 the matching request. <emphasis>password</emphasis> and 81 <emphasis>otp</emphasis> commands can be used regardless of whether 82 the request was for PASSWORD or OTP. The main difference between these 83 two commands is that values given with <emphasis>password</emphasis> are 84 remembered as long as wpa_supplicant is running whereas values given 85 with <emphasis>otp</emphasis> are used only once and then forgotten, 86 i.e., wpa_supplicant will ask frontend for a new value for every use. 87 This can be used to implement one-time-password lists and generic token 88 card -based authentication.</para> 89 90 <para>Example request for password and a matching reply:</para> 91 92 <blockquote><programlisting> 93 CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 94 > password 1 mysecretpassword 95 </programlisting></blockquote> 96 97 <para>Example request for generic token card challenge-response:</para> 98 99 <blockquote><programlisting> 100 CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 101 > otp 2 9876 102 </programlisting></blockquote> 103 104 </refsect1> 105 <refsect1> 106 <title>Command Arguments</title> 107 <variablelist> 108 <varlistentry> 109 <term>-p path</term> 110 111 <listitem><para>Change the path where control sockets should 112 be found.</para></listitem> 113 </varlistentry> 114 115 <varlistentry> 116 <term>-g control socket path</term> 117 118 <listitem><para>Connect to the global control socket at the 119 indicated path rather than an interface-specific control 120 socket.</para></listitem> 121 </varlistentry> 122 123 <varlistentry> 124 <term>-i ifname</term> 125 126 <listitem><para>Specify the interface that is being 127 configured. By default, choose the first interface found with 128 a control socket in the socket path.</para></listitem> 129 </varlistentry> 130 131 <varlistentry> 132 <term>-h</term> 133 <listitem><para>Help. Show a usage message.</para></listitem> 134 </varlistentry> 135 136 137 <varlistentry> 138 <term>-v</term> 139 <listitem><para>Show version information.</para></listitem> 140 </varlistentry> 141 142 143 <varlistentry> 144 <term>-B</term> 145 <listitem><para>Run as a daemon in the background.</para></listitem> 146 </varlistentry> 147 148 <varlistentry> 149 <term>-a file</term> 150 151 <listitem><para>Run in daemon mode executing the action file 152 based on events from wpa_supplicant. The specified file will 153 be executed with the first argument set to interface name and 154 second to "CONNECTED" or "DISCONNECTED" depending on the event. 155 This can be used to execute networking tools required to configure 156 the interface.</para> 157 158 <para>Additionally, three environmental variables are available to 159 the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR 160 contains the absolute path to the ctrl_interface socket. WPA_ID 161 contains the unique network_id identifier assigned to the active 162 network, and WPA_ID_STR contains the content of the id_str option. 163 </para></listitem> 164 </varlistentry> 165 166 <varlistentry> 167 <term>-P file</term> 168 169 <listitem><para>Set the location of the PID 170 file.</para></listitem> 171 </varlistentry> 172 173 <varlistentry> 174 <term>-G ping interval</term> 175 176 <listitem><para>Set the interval (in seconds) at which 177 wpa_cli pings the supplicant.</para></listitem> 178 </varlistentry> 179 180 <varlistentry> 181 <term>command</term> 182 183 <listitem><para>Run a command. The available commands are 184 listed in the next section.</para></listitem> 185 186 </varlistentry> 187 </variablelist> 188 </refsect1> 189 <refsect1> 190 <title>Commands</title> 191 <para>The following commands are available:</para> 192 193 <variablelist> 194 <varlistentry> 195 <term>status</term> 196 <listitem> 197 <para>get current WPA/EAPOL/EAP status</para> 198 </listitem> 199 </varlistentry> 200 201 <varlistentry> 202 <term>mib</term> 203 <listitem> 204 <para>get MIB variables (dot1x, dot11)</para> 205 </listitem> 206 </varlistentry> 207 208 <varlistentry> 209 <term>help</term> 210 <listitem> 211 <para>show this usage help</para> 212 </listitem> 213 </varlistentry> 214 215 <varlistentry> 216 <term>interface [ifname]</term> 217 <listitem> 218 <para>show interfaces/select interface</para> 219 </listitem> 220 </varlistentry> 221 222 <varlistentry> 223 <term>level <debug level></term> 224 <listitem> 225 <para>change debug level</para> 226 </listitem> 227 </varlistentry> 228 229 <varlistentry> 230 <term>license</term> 231 <listitem> 232 <para>show full wpa_cli license</para> 233 </listitem> 234 </varlistentry> 235 236 <varlistentry> 237 <term>logoff</term> 238 <listitem> 239 <para>IEEE 802.1X EAPOL state machine logoff</para> 240 </listitem> 241 </varlistentry> 242 243 <varlistentry> 244 <term>logon</term> 245 <listitem> 246 <para>IEEE 802.1X EAPOL state machine logon</para> 247 </listitem> 248 </varlistentry> 249 250 <varlistentry> 251 <term>set</term> 252 <listitem> 253 <para>set variables (shows list of variables when run without arguments)</para> 254 </listitem> 255 </varlistentry> 256 <varlistentry> 257 <term>pmksa</term> 258 <listitem> 259 <para>show PMKSA cache</para> 260 </listitem> 261 </varlistentry> 262 <varlistentry> 263 <term>reassociate</term> 264 <listitem> 265 <para>force reassociation</para> 266 </listitem> 267 </varlistentry> 268 <varlistentry> 269 <term>reconfigure</term> 270 <listitem> 271 <para>force wpa_supplicant to re-read its configuration file</para> 272 </listitem> 273 </varlistentry> 274 275 <varlistentry> 276 <term>preauthenticate <BSSID></term> 277 <listitem> 278 <para>force preauthentication</para> 279 </listitem> 280 </varlistentry> 281 282 <varlistentry> 283 <term>identity <network id> <identity></term> 284 <listitem> 285 <para>configure identity for an SSID</para> 286 </listitem> 287 </varlistentry> 288 289 <varlistentry> 290 <term>password <network id> <password></term> 291 <listitem> 292 <para>configure password for an SSID</para> 293 </listitem> 294 </varlistentry> 295 296 <varlistentry> 297 <term>pin <network id> <pin></term> 298 <listitem> 299 <para>configure pin for an SSID</para> 300 </listitem> 301 </varlistentry> 302 303 <varlistentry> 304 <term>otp <network id> <password></term> 305 <listitem> 306 <para>configure one-time-password for an SSID</para> 307 </listitem> 308 </varlistentry> 309 310 <varlistentry> 311 <term>bssid <network id> <BSSID></term> 312 <listitem> 313 <para>set preferred BSSID for an SSID</para> 314 </listitem> 315 </varlistentry> 316 317 <varlistentry> 318 <term>list_networks</term> 319 <listitem> 320 <para>list configured networks</para> 321 </listitem> 322 </varlistentry> 323 324 <varlistentry> 325 <term>terminate</term> 326 <listitem> 327 <para>terminate <command>wpa_supplicant</command></para> 328 </listitem> 329 </varlistentry> 330 331 <varlistentry> 332 <term>quit</term> 333 <listitem><para>exit wpa_cli</para></listitem> 334 </varlistentry> 335 </variablelist> 336 </refsect1> 337 <refsect1> 338 <title>See Also</title> 339 <para> 340 <citerefentry> 341 <refentrytitle>wpa_supplicant</refentrytitle> 342 <manvolnum>8</manvolnum> 343 </citerefentry> 344 </para> 345 </refsect1> 346 <refsect1> 347 <title>Legal</title> 348 <para>wpa_supplicant is copyright (c) 2003-2016, 349 Jouni Malinen <email>j (a] w1.fi</email> and 350 contributors. 351 All Rights Reserved.</para> 352 353 <para>This program is licensed under the BSD license (the one with 354 advertisement clause removed).</para> 355 </refsect1> 356 </refentry> 357
