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