]>
Commit | Line | Data |
---|---|---|
6fc6879b JM |
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> | |
32185f54 | 18 | <arg>-g <replaceable>path to global ctrl_interface socket</replaceable></arg> |
6fc6879b JM |
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> | |
32185f54 | 23 | <arg>-G <replaceable>ping interval</replaceable></arg> |
6fc6879b JM |
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 | ||
eff06a7c KM |
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> | |
6fc6879b JM |
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 | ||
32185f54 DW |
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 | ||
6fc6879b JM |
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 | ||
32185f54 DW |
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 | ||
6fc6879b JM |
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> | |
937403b5 | 348 | <para>wpa_supplicant is copyright (c) 2003-2015, |
6fc6879b JM |
349 | Jouni Malinen <email>j@w1.fi</email> and |
350 | contributors. | |
351 | All Rights Reserved.</para> | |
352 | ||
d755e01b JM |
353 | <para>This program is licensed under the BSD license (the one with |
354 | advertisement clause removed).</para> | |
6fc6879b JM |
355 | </refsect1> |
356 | </refentry> |