← Back to branch summary

~ubuntu-branches/ubuntu/vivid/wpasupplicant/vivid

« back to all changes in this revision

Viewing changes to wpa_supplicant/doc/docbook/wpa_cli.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Kel Modderman
  • Date: 2008-03-12 20:03:04 UTC
  • mfrom: (1.1.10 upstream)
  • mto: This revision was merged to the branch mainline in revision 4.
  • Revision ID: james.westby@ubuntu.com-20080312200304-4331y9wj46pdd34z
Tags: 0.6.3-1
http://bugs.debian.org/466910
* New upstream release.
* Drop patches applied upstream:
  - debian/patches/30_wpa_gui_qt4_eventhistoryui_rework.patch
  - debian/patches/31_wpa_gui_qt4_eventhistory_always_scrollbar.patch
  - debian/patches/32_wpa_gui_qt4_eventhistory_scroll_with_events.patch
  - debian/patches/40_dbus_ssid_data.patch
* Tidy up the clean target of debian/rules. Now that the madwifi headers are
  handled differently we no longer need to do any cleanup.
* Fix formatting error in debian/ifupdown/wpa_action.8 to make lintian
  quieter.
* Add patch to fix formatting errors in manpages build from sgml source. Use
  <emphasis> tags to hightlight keywords instead of surrounding them in
  strong quotes.
  - debian/patches/41_manpage_format_fixes.patch
* wpasupplicant binary package no longer suggests pcscd, guessnet, iproute
  or wireless-tools, nor does it recommend dhcp3-client. These are not
  needed.
* Add debian/patches/10_silence_siocsiwauth_icotl_failure.patch to disable
  ioctl failure messages that occur under normal conditions.
* Cherry pick two upstream git commits concerning the dbus interface:
  - debian/patches/11_avoid_dbus_version_namespace.patch
  - debian/patches/12_fix_potential_use_after_free.patch
* Add debian/patches/42_manpage_explain_available_drivers.patch to explain
  that not all of the driver backends are available in the provided
  wpa_supplicant binary, and that the canonical list of supported driver
  backends can be retrieved from the wpa_supplicant -h (help) output.
  (Closes: #466910)
* Add debian/patches/20_wpa_gui_qt4_disable_link_prl.patch to remove
  link_prl CONFIG compile flag added by qmake-qt4 >= 4.3.4-2 to avoid excess
  linking.

Show diffs side-by-side

added added

removed removed

Lines of Context:
wpa_supplicant/doc/docbook/wpa_cli.sgml
 
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-&lt;type&gt;-&lt;id&gt;:&lt;text&gt;"
 
69
   prefix. &lt;type&gt; is IDENTITY, PASSWORD, or OTP
 
70
   (one-time-password). &lt;id&gt; is a unique identifier for the
 
71
   current network. &lt;text&gt; 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 'identity',
 
76
    'password', and 'otp' commands. &lt;id&gt; needs to be copied from the
 
77
    the matching request. 'password' and 'otp' commands can be used
 
78
    regardless of whether the request was for PASSWORD or OTP. The
 
79
    main difference between these two commands is that values given
 
80
    with 'password' are remembered as long as wpa_supplicant is
 
81
    running whereas values given with 'otp' are used only once and
 
82
    then forgotten, i.e., wpa_supplicant will ask frontend for a new
 
83
    value for every use. This can be used to implement
 
84
    one-time-password lists and generic token card -based
 
85
    authentication.</para>
 
86
 
 
87
    <para>Example request for password and a matching reply:</para>
 
88
 
 
89
<blockquote><programlisting>
 
90
CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
 
91
> password 1 mysecretpassword
 
92
</programlisting></blockquote>
 
93
 
 
94
    <para>Example request for generic token card challenge-response:</para>
 
95
 
 
96
<blockquote><programlisting>
 
97
CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
 
98
> otp 2 9876
 
99
</programlisting></blockquote>
 
100
 
 
101
  </refsect1>
 
102
  <refsect1>
 
103
    <title>Command Arguments</title>
 
104
    <variablelist>
 
105
      <varlistentry>
 
106
        <term>-p path</term>
 
107
 
 
108
        <listitem><para>Change the path where control sockets should
 
109
        be found.</para></listitem>
 
110
      </varlistentry>
 
111
 
 
112
      <varlistentry>
 
113
        <term>-i ifname</term>
 
114
 
 
115
        <listitem><para>Specify the interface that is being
 
116
        configured.  By default, choose the first interface found with
 
117
        a control socket in the socket path.</para></listitem>
 
118
      </varlistentry>
 
119
 
 
120
      <varlistentry>
 
121
        <term>-h</term>
 
122
        <listitem><para>Help.  Show a usage message.</para></listitem>
 
123
      </varlistentry>
 
124
 
 
125
 
 
126
      <varlistentry>
 
127
        <term>-v</term>
 
128
        <listitem><para>Show version information.</para></listitem>
 
129
      </varlistentry>
 
130
 
 
131
 
 
132
      <varlistentry>
 
133
        <term>-B</term>
 
134
        <listitem><para>Run as a daemon in the background.</para></listitem>
 
135
      </varlistentry>
 
136
 
 
137
      <varlistentry>
 
138
        <term>-a file</term>
 
139
 
 
140
        <listitem><para>Run in daemon mode executing the action file
 
141
        based on events from wpa_supplicant.  The specified file will
 
142
        be executed with the first argument set to interface name and
 
143
        second to "CONNECTED" or "DISCONNECTED" depending on the event.
 
144
        This can be used to execute networking tools required to configure
 
145
        the interface.</para>
 
146
 
 
147
        <para>Additionally, three environmental variables are available to
 
148
        the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR
 
149
        contains the absolute path to the ctrl_interface socket. WPA_ID
 
150
        contains the unique network_id identifier assigned to the active
 
151
        network, and WPA_ID_STR contains the content of the id_str option.
 
152
        </para></listitem>
 
153
      </varlistentry>
 
154
 
 
155
      <varlistentry>
 
156
        <term>-P file</term>
 
157
 
 
158
        <listitem><para>Set the location of the PID
 
159
        file.</para></listitem>
 
160
      </varlistentry>
 
161
 
 
162
      <varlistentry>
 
163
        <term>command</term>
 
164
 
 
165
        <listitem><para>Run a command.  The available commands are
 
166
        listed in the next section.</para></listitem>
 
167
 
 
168
      </varlistentry>
 
169
    </variablelist>
 
170
  </refsect1>
 
171
  <refsect1>
 
172
    <title>Commands</title>
 
173
    <para>The following commands are available:</para>
 
174
 
 
175
    <variablelist>
 
176
      <varlistentry>
 
177
        <term>status</term>
 
178
        <listitem>
 
179
          <para>get current WPA/EAPOL/EAP status</para>
 
180
        </listitem>
 
181
      </varlistentry>
 
182
 
 
183
      <varlistentry>
 
184
        <term>mib</term>
 
185
        <listitem>
 
186
          <para>get MIB variables (dot1x, dot11)</para>
 
187
        </listitem>
 
188
      </varlistentry>
 
189
 
 
190
      <varlistentry>
 
191
        <term>help</term>
 
192
        <listitem>
 
193
          <para>show this usage help</para>
 
194
        </listitem>
 
195
      </varlistentry>
 
196
 
 
197
      <varlistentry>
 
198
        <term>interface [ifname]</term>
 
199
        <listitem>
 
200
          <para>show interfaces/select interface</para>
 
201
        </listitem>
 
202
      </varlistentry>
 
203
 
 
204
      <varlistentry>
 
205
        <term>level &lt;debug level&gt;</term>
 
206
        <listitem>
 
207
          <para>change debug level</para>
 
208
        </listitem>
 
209
      </varlistentry>
 
210
 
 
211
      <varlistentry>
 
212
        <term>license</term>
 
213
        <listitem>
 
214
          <para>show full wpa_cli license</para>
 
215
        </listitem>
 
216
      </varlistentry>
 
217
 
 
218
      <varlistentry>
 
219
        <term>logoff</term>
 
220
        <listitem>
 
221
          <para>IEEE 802.1X EAPOL state machine logoff</para>
 
222
        </listitem>
 
223
      </varlistentry>
 
224
 
 
225
      <varlistentry>
 
226
        <term>logon</term>
 
227
        <listitem>
 
228
          <para>IEEE 802.1X EAPOL state machine logon</para>
 
229
        </listitem>
 
230
      </varlistentry>
 
231
 
 
232
      <varlistentry>
 
233
        <term>set</term>
 
234
        <listitem>
 
235
          <para>set variables (shows list of variables when run without arguments)</para>
 
236
        </listitem>
 
237
      </varlistentry>
 
238
      <varlistentry>
 
239
        <term>pmksa</term>
 
240
        <listitem>
 
241
          <para>show PMKSA cache</para>
 
242
        </listitem>
 
243
      </varlistentry>
 
244
      <varlistentry>
 
245
        <term>reassociate</term>
 
246
        <listitem>
 
247
          <para>force reassociation</para>
 
248
        </listitem>
 
249
      </varlistentry>
 
250
      <varlistentry>
 
251
        <term>reconfigure</term>
 
252
        <listitem>
 
253
          <para>force wpa_supplicant to re-read its configuration file</para>
 
254
        </listitem>
 
255
      </varlistentry>
 
256
 
 
257
      <varlistentry>
 
258
        <term>preauthenticate &lt;BSSID&gt;</term>
 
259
        <listitem>
 
260
          <para>force preauthentication</para>
 
261
        </listitem>
 
262
      </varlistentry>
 
263
 
 
264
      <varlistentry>
 
265
        <term>identity &lt;network id&gt; &lt;identity&gt;</term>
 
266
        <listitem>
 
267
          <para>configure identity for an SSID</para>
 
268
        </listitem>
 
269
      </varlistentry>
 
270
 
 
271
      <varlistentry>
 
272
        <term>password &lt;network id&gt; &lt;password&gt;</term>
 
273
        <listitem>
 
274
          <para>configure password for an SSID</para>
 
275
        </listitem>
 
276
      </varlistentry>
 
277
 
 
278
      <varlistentry>
 
279
        <term>pin &lt;network id&gt; &lt;pin&gt;</term>
 
280
        <listitem>
 
281
          <para>configure pin for an SSID</para>
 
282
        </listitem>
 
283
      </varlistentry>
 
284
 
 
285
      <varlistentry>
 
286
        <term>otp &lt;network id&gt; &lt;password&gt;</term>
 
287
        <listitem>
 
288
          <para>configure one-time-password for an SSID</para>
 
289
        </listitem>
 
290
      </varlistentry>
 
291
 
 
292
      <varlistentry>
 
293
        <term>bssid &lt;network id&gt; &lt;BSSID&gt;</term>
 
294
        <listitem>
 
295
          <para>set preferred BSSID for an SSID</para>
 
296
        </listitem>
 
297
      </varlistentry>
 
298
 
 
299
      <varlistentry>
 
300
        <term>list_networks</term>
 
301
        <listitem>
 
302
          <para>list configured networks</para>
 
303
        </listitem>
 
304
      </varlistentry>
 
305
 
 
306
      <varlistentry>
 
307
        <term>terminate</term>
 
308
        <listitem>
 
309
          <para>terminate <command>wpa_supplicant</command></para>
 
310
        </listitem>
 
311
      </varlistentry>
 
312
 
 
313
      <varlistentry>
 
314
        <term>quit</term>
 
315
        <listitem><para>exit wpa_cli</para></listitem>
 
316
      </varlistentry>
 
317
    </variablelist>
 
318
  </refsect1>
 
319
  <refsect1>
 
320
    <title>See Also</title>
 
321
    <para>
 
322
      <citerefentry>
 
323
        <refentrytitle>wpa_supplicant</refentrytitle>
 
324
        <manvolnum>8</manvolnum>
 
325
      </citerefentry>
 
326
    </para>
 
327
  </refsect1>
 
328
  <refsect1>
 
329
    <title>Legal</title>
 
330
    <para>wpa_supplicant is copyright (c) 2003-2007,
 
331
    Jouni Malinen <email>j@w1.fi</email> and
 
332
    contributors.
 
333
    All Rights Reserved.</para>
 
334
 
 
335
    <para>This program is dual-licensed under both the GPL version 2
 
336
    and BSD license. Either license may be used at your option.</para>
 
337
  </refsect1>
 
338
</refentry>