| <!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-<type>-<id>:<text>" |
| prefix. <type> is IDENTITY, PASSWORD, or OTP |
| (one-time-password). <id> is a unique identifier for the |
| current network. <text> 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 |
| <emphasis>identity</emphasis>, <emphasis>password</emphasis>, and |
| <emphasis>otp</emphasis> commands. <id> needs to be copied from |
| the matching request. <emphasis>password</emphasis> and |
| <emphasis>otp</emphasis> 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 <emphasis>password</emphasis> are |
| remembered as long as wpa_supplicant is running whereas values given |
| with <emphasis>otp</emphasis> 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 <debug level></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 <BSSID></term> |
| <listitem> |
| <para>force preauthentication</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>identity <network id> <identity></term> |
| <listitem> |
| <para>configure identity for an SSID</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>password <network id> <password></term> |
| <listitem> |
| <para>configure password for an SSID</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>pin <network id> <pin></term> |
| <listitem> |
| <para>configure pin for an SSID</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>otp <network id> <password></term> |
| <listitem> |
| <para>configure one-time-password for an SSID</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>bssid <network id> <BSSID></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-2012, |
| Jouni Malinen <email>j@w1.fi</email> and |
| contributors. |
| All Rights Reserved.</para> |
| |
| <para>This program is licensed under the BSD license (the one with |
| advertisement clause removed).</para> |
| </refsect1> |
| </refentry> |