aboutsummaryrefslogtreecommitdiffstats
path: root/wpa_supplicant/doc/docbook/wpa_cli.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'wpa_supplicant/doc/docbook/wpa_cli.sgml')
-rw-r--r--wpa_supplicant/doc/docbook/wpa_cli.sgml338
1 files changed, 338 insertions, 0 deletions
diff --git a/wpa_supplicant/doc/docbook/wpa_cli.sgml b/wpa_supplicant/doc/docbook/wpa_cli.sgml
new file mode 100644
index 0000000..d55aee4
--- /dev/null
+++ b/wpa_supplicant/doc/docbook/wpa_cli.sgml
@@ -0,0 +1,338 @@
+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<refentry>
+ <refmeta>
+ <refentrytitle>wpa_cli</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </refmeta>
+ <refnamediv>
+ <refname>wpa_cli</refname>
+
+ <refpurpose>WPA command line client</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>wpa_cli</command>
+ <arg>-p <replaceable>path to ctrl sockets</replaceable></arg>
+ <arg>-i <replaceable>ifname</replaceable></arg>
+ <arg>-hvB</arg>
+ <arg>-a <replaceable>action file</replaceable></arg>
+ <arg>-P <replaceable>pid file</replaceable></arg>
+ <arg><replaceable>command ...</replaceable></arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Overview</title>
+
+ <para>wpa_cli is a text-based frontend program for interacting
+ with wpa_supplicant. It is used to query current status, change
+ configuration, trigger events, and request interactive user
+ input.</para>
+
+ <para>wpa_cli can show the current authentication status, selected
+ security mode, dot11 and dot1x MIBs, etc. In addition, it can
+ configure some variables like EAPOL state machine parameters and
+ trigger events like reassociation and IEEE 802.1X
+ logoff/logon. wpa_cli provides a user interface to request
+ authentication information, like username and password, if these
+ are not included in the configuration. This can be used to
+ implement, e.g., one-time-passwords or generic token card
+ authentication where the authentication is based on a
+ challenge-response that uses an external device for generating the
+ response.</para>
+
+ <para>The control interface of wpa_supplicant can be configured to
+ allow non-root user access (ctrl_interface GROUP= parameter in the
+ configuration file). This makes it possible to run wpa_cli with a
+ normal user account.</para>
+
+ <para>wpa_cli supports two modes: interactive and command
+ line. Both modes share the same command set and the main
+ difference is in interactive mode providing access to unsolicited
+ messages (event messages, username/password requests).</para>
+
+ <para>Interactive mode is started when wpa_cli is executed without
+ including the command as a command line parameter. Commands are
+ then entered on the wpa_cli prompt. In command line mode, the same
+ commands are entered as command line arguments for wpa_cli.</para>
+ </refsect1>
+ <refsect1>
+ <title>Interactive authentication parameters request</title>
+
+ <para>When wpa_supplicant need authentication parameters, like
+ username and password, which are not present in the configuration
+ file, it sends a request message to all attached frontend programs,
+ e.g., wpa_cli in interactive mode. wpa_cli shows these requests
+ with "CTRL-REQ-&lt;type&gt;-&lt;id&gt;:&lt;text&gt;"
+ prefix. &lt;type&gt; is IDENTITY, PASSWORD, or OTP
+ (one-time-password). &lt;id&gt; is a unique identifier for the
+ current network. &lt;text&gt; is description of the request. In
+ case of OTP request, it includes the challenge from the
+ authentication server.</para>
+
+ <para>The reply to these requests can be given with 'identity',
+ 'password', and 'otp' commands. &lt;id&gt; needs to be copied from the
+ the matching request. 'password' and 'otp' commands can be used
+ regardless of whether the request was for PASSWORD or OTP. The
+ main difference between these two commands is that values given
+ with 'password' are remembered as long as wpa_supplicant is
+ running whereas values given with 'otp' are used only once and
+ then forgotten, i.e., wpa_supplicant will ask frontend for a new
+ value for every use. This can be used to implement
+ one-time-password lists and generic token card -based
+ authentication.</para>
+
+ <para>Example request for password and a matching reply:</para>
+
+<blockquote><programlisting>
+CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
+> password 1 mysecretpassword
+</programlisting></blockquote>
+
+ <para>Example request for generic token card challenge-response:</para>
+
+<blockquote><programlisting>
+CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
+> otp 2 9876
+</programlisting></blockquote>
+
+ </refsect1>
+ <refsect1>
+ <title>Command Arguments</title>
+ <variablelist>
+ <varlistentry>
+ <term>-p path</term>
+
+ <listitem><para>Change the path where control sockets should
+ be found.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-i ifname</term>
+
+ <listitem><para>Specify the interface that is being
+ configured. By default, choose the first interface found with
+ a control socket in the socket path.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-h</term>
+ <listitem><para>Help. Show a usage message.</para></listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>-v</term>
+ <listitem><para>Show version information.</para></listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>-B</term>
+ <listitem><para>Run as a daemon in the background.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-a file</term>
+
+ <listitem><para>Run in daemon mode executing the action file
+ based on events from wpa_supplicant. The specified file will
+ be executed with the first argument set to interface name and
+ second to "CONNECTED" or "DISCONNECTED" depending on the event.
+ This can be used to execute networking tools required to configure
+ the interface.</para>
+
+ <para>Additionally, three environmental variables are available to
+ the file: WPA_CTRL_DIR, WPA_ID, and WPA_ID_STR. WPA_CTRL_DIR
+ contains the absolute path to the ctrl_interface socket. WPA_ID
+ contains the unique network_id identifier assigned to the active
+ network, and WPA_ID_STR contains the content of the id_str option.
+ </para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>-P file</term>
+
+ <listitem><para>Set the location of the PID
+ file.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>command</term>
+
+ <listitem><para>Run a command. The available commands are
+ listed in the next section.</para></listitem>
+
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Commands</title>
+ <para>The following commands are available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>status</term>
+ <listitem>
+ <para>get current WPA/EAPOL/EAP status</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>mib</term>
+ <listitem>
+ <para>get MIB variables (dot1x, dot11)</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>help</term>
+ <listitem>
+ <para>show this usage help</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>interface [ifname]</term>
+ <listitem>
+ <para>show interfaces/select interface</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>level &lt;debug level&gt;</term>
+ <listitem>
+ <para>change debug level</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>license</term>
+ <listitem>
+ <para>show full wpa_cli license</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>logoff</term>
+ <listitem>
+ <para>IEEE 802.1X EAPOL state machine logoff</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>logon</term>
+ <listitem>
+ <para>IEEE 802.1X EAPOL state machine logon</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>set</term>
+ <listitem>
+ <para>set variables (shows list of variables when run without arguments)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>pmksa</term>
+ <listitem>
+ <para>show PMKSA cache</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reassociate</term>
+ <listitem>
+ <para>force reassociation</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>reconfigure</term>
+ <listitem>
+ <para>force wpa_supplicant to re-read its configuration file</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>preauthenticate &lt;BSSID&gt;</term>
+ <listitem>
+ <para>force preauthentication</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>identity &lt;network id&gt; &lt;identity&gt;</term>
+ <listitem>
+ <para>configure identity for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>password &lt;network id&gt; &lt;password&gt;</term>
+ <listitem>
+ <para>configure password for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pin &lt;network id&gt; &lt;pin&gt;</term>
+ <listitem>
+ <para>configure pin for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>otp &lt;network id&gt; &lt;password&gt;</term>
+ <listitem>
+ <para>configure one-time-password for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>bssid &lt;network id&gt; &lt;BSSID&gt;</term>
+ <listitem>
+ <para>set preferred BSSID for an SSID</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>list_networks</term>
+ <listitem>
+ <para>list configured networks</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>terminate</term>
+ <listitem>
+ <para>terminate <command>wpa_supplicant</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>quit</term>
+ <listitem><para>exit wpa_cli</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>wpa_supplicant</refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Legal</title>
+ <para>wpa_supplicant is copyright (c) 2003-2007,
+ Jouni Malinen <email>j@w1.fi</email> and
+ contributors.
+ All Rights Reserved.</para>
+
+ <para>This program is dual-licensed under both the GPL version 2
+ and BSD license. Either license may be used at your option.</para>
+ </refsect1>
+</refentry>