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