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-&lt;type&gt;-&lt;id&gt;:&lt;text&gt;"
75   prefix. &lt;type&gt; is IDENTITY, PASSWORD, or OTP
76   (one-time-password). &lt;id&gt; is a unique identifier for the
77   current network. &lt;text&gt; 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. &lt;id&gt; 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 &lt;debug level&gt;</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 &lt;BSSID&gt;</term>
281	<listitem>
282	  <para>force preauthentication</para>
283	</listitem>
284      </varlistentry>
285
286      <varlistentry>
287	<term>identity &lt;network id&gt; &lt;identity&gt;</term>
288	<listitem>
289	  <para>configure identity for an SSID</para>
290	</listitem>
291      </varlistentry>
292
293      <varlistentry>
294	<term>password &lt;network id&gt; &lt;password&gt;</term>
295	<listitem>
296	  <para>configure password for an SSID</para>
297	</listitem>
298      </varlistentry>
299
300      <varlistentry>
301	<term>pin &lt;network id&gt; &lt;pin&gt;</term>
302	<listitem>
303	  <para>configure pin for an SSID</para>
304	</listitem>
305      </varlistentry>
306
307      <varlistentry>
308	<term>otp &lt;network id&gt; &lt;password&gt;</term>
309	<listitem>
310	  <para>configure one-time-password for an SSID</para>
311	</listitem>
312      </varlistentry>
313
314      <varlistentry>
315	<term>bssid &lt;network id&gt; &lt;BSSID&gt;</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-2019,
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