xref: /freebsd/usr.sbin/wpa/wpa_cli/wpa_cli.8 (revision 2be1a816b9ff69588e55be0a84cbe2a31efc0f2f) 
1.\" Copyright (c) 2005 Sam Leffler <sam@errno.com>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd June 16, 2005
28.Dt WPA_CLI 8
29.Os
30.Sh NAME
31.Nm wpa_cli
32.Nd "text-based frontend program for interacting with wpa_supplicant"
33.Sh SYNOPSIS
34.Nm
35.Op Ar commands
36.Sh DESCRIPTION
37The
38.Nm
39utility
40is a text-based frontend program for interacting with
41.Xr wpa_supplicant 8 .
42It is used to query current status,
43change configuration,
44trigger events,
45and
46request interactive user input.
47.Pp
48The
49.Nm
50utility
51can show the
52current authentication status,
53selected security
54mode, dot11 and dot1x MIBs, etc.
55In addition,
56.Nm
57can configure EAPOL state machine
58parameters and trigger events such as reassociation
59and IEEE 802.1X logoff/logon.
60.Pp
61The
62.Nm
63utility
64provides an interface to supply authentication information
65such as username and password when it is not provided in the
66.Xr wpa_supplicant.conf 5
67configuration file.
68This can be used, for example, to implement
69one-time passwords or generic token card
70authentication where the authentication is based on a
71challenge-response that uses an external device for generating the
72response.
73.Pp
74The
75.Nm
76utility
77supports two modes: interactive and command line.
78Both modes share the same command set and the main difference
79is in interactive mode providing access to unsolicited messages
80(event messages, username/password requests).
81.Pp
82Interactive mode is started when
83.Nm
84is executed without any parameters on the command line.
85Commands are then entered from the controlling terminal in
86response to the
87.Nm
88prompt.
89In command line mode, the same commands are
90entered as command line arguments.
91.Pp
92The control interface of
93.Xr wpa_supplicant 8
94can be configured to allow
95non-root user access by using the
96.Va ctrl_interface_group
97parameter
98in the
99.Xr wpa_supplicant.conf 5
100configuration file.
101This makes it possible to run
102.Nm
103with a normal user account.
104.Sh AUTHENTICATION PARAMETERS
105When
106.Xr wpa_supplicant 8
107needs authentication parameters, such as username and password,
108that are not present in the configuration file, it sends a
109request message to all attached frontend programs, e.g.,
110.Nm
111in interactive mode.
112The
113.Nm
114utility
115shows these requests with a
116.Dq Li CTRL-REQ- Ns Ao Ar type Ac Ns Li - Ns Ao Ar id Ac Ns Li : Ns Aq Ar text
117prefix, where
118.Aq Ar type
119is
120.Li IDENTITY , PASSWORD ,
121or
122.Li OTP
123(One-Time Password),
124.Aq Ar id
125is a unique identifier for the current network,
126.Aq Ar text
127is a description of the request.
128In the case of an
129.Li OTP
130(One-Time Password) request,
131it includes the challenge from the authentication server.
132.Pp
133A user must supply
134.Xr wpa_supplicant 8
135the needed parameters in response to these requests.
136.Pp
137For example,
138.Bd -literal -offset indent
139CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
140> password 1 mysecretpassword
141
142Example request for generic token card challenge-response:
143
144CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
145> otp 2 9876
146.Ed
147.Sh COMMANDS
148The following commands may be supplied on the command line
149or at a prompt when operating interactively.
150.Bl -tag -width indent
151.It Ic status
152Report the current WPA/EAPOL/EAP status for the current interface.
153.It Ic mib
154Report MIB variables (dot1x, dot11) for the current interface.
155.It Ic help
156Show usage help.
157.It Ic interface Op Ar ifname
158Show available interfaces and/or set the current interface
159when multiple are available.
160.It Ic level Ar debug_level
161Change the debugging level in
162.Xr wpa_supplicant 8 .
163Larger numbers generate more messages.
164.It Ic license
165Display the full
166license for
167.Nm .
168.It Ic logoff
169Send the IEEE 802.1X EAPOL state machine into the
170.Dq logoff
171state.
172.It Ic logon
173Send the IEEE 802.1X EAPOL state machine into the
174.Dq logon
175state.
176.It Ic set Op Ar settings
177Set variables.
178When no arguments are supplied, the known variables and their settings
179are displayed.
180.It Ic pmksa
181Show the contents of the PMKSA cache.
182.It Ic reassociate
183Force a reassociation to the current access point.
184.It Ic reconfigure
185Force
186.Xr wpa_supplicant 8
187to re-read its configuration file.
188.It Ic preauthenticate Ar BSSID
189Force preauthentication of the specified
190.Ar BSSID .
191.It Ic identity Ar network_id identity
192Configure an identity for an SSID.
193.It Ic password Ar network_id password
194Configure a password for an SSID.
195.It Ic otp Ar network_id password
196Configure a one-time password for an SSID.
197.It Ic terminate
198Force
199.Xr wpa_supplicant 8
200to terminate.
201.It Ic quit
202Exit
203.Nm .
204.El
205.Sh SEE ALSO
206.Xr wpa_supplicant.conf 5 ,
207.Xr wpa_supplicant 8
208.Sh HISTORY
209The
210.Nm
211utility first appeared in
212.Fx 6.0 .
213.Sh AUTHORS
214The
215.Nm
216utility was written by
217.An Jouni Malinen Aq jkmaline@cc.hut.fi .
218This manual page is derived from the
219.Pa README
220file included in the
221.Nm wpa_supplicant
222distribution.
223