339 lines
9.9 KiB
Text
339 lines
9.9 KiB
Text
<!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>
|