xref: /dragonfly/usr.sbin/802_11/wpa_cli/wpa_cli.8 (revision 9a92bb4c) 
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: src/usr.sbin/wpa/wpa_cli/wpa_cli.8,v 1.2.2.1 2005/07/16 19:02:21 brueffer Exp $
26.\" $DragonFly: src/usr.sbin/802_11/wpa_cli/wpa_cli.8,v 1.1 2006/07/07 15:05:18 sephe Exp $
27.\"
28.Dd July 7, 2006
29.Dt WPA_CLI 8
30.Os
31.Sh NAME
32.Nm wpa_cli
33.Nd "text-based frontend program for interacting with wpa_supplicant"
34.Sh SYNOPSIS
35.Nm
36.Op Ar commands
37.Sh DESCRIPTION
38The
39.Nm
40utility
41is a text-based frontend program for interacting with
42.Xr wpa_supplicant 8 .
43It is used to query current status,
44change configuration,
45trigger events,
46and
47request interactive user input.
48.Pp
49The
50.Nm
51utility
52can show the
53current authentication status,
54selected security
55mode, dot11 and dot1x MIBs, etc.
56In addition,
57.Nm
58can configure EAPOL state machine
59parameters and trigger events such as reassociation
60and IEEE 802.1X logoff/logon.
61.Pp
62The
63.Nm
64utility
65provides an interface to supply authentication information
66such as username and password when it is not provided in the
67.Xr wpa_supplicant.conf 5
68configuration file.
69This can be used, for example, to implement
70one-time passwords or generic token card
71authentication where the authentication is based on a
72challenge-response that uses an external device for generating the
73response.
74.Pp
75The
76.Nm
77utility
78supports two modes: interactive and command line.
79Both modes share the same command set and the main difference
80is in interactive mode providing access to unsolicited messages
81(event messages, username/password requests).
82.Pp
83Interactive mode is started when
84.Nm
85is executed without any parameters on the command line.
86Commands are then entered from the controlling terminal in
87response to the
88.Nm
89prompt.
90In command line mode, the same commands are
91entered as command line arguments.
92.Pp
93The control interface of
94.Xr wpa_supplicant 8
95can be configured to allow
96non-root user access by using the
97.Va ctrl_interface_group
98parameter
99in the
100.Xr wpa_supplicant.conf 5
101configuration file.
102This makes it possible to run
103.Nm
104with a normal user account.
105.Sh AUTHENTICATION PARAMETERS
106When
107.Xr wpa_supplicant 8
108needs authentication parameters, such as username and password,
109that are not present in the configuration file, it sends a
110request message to all attached frontend programs, e.g.,
111.Nm
112in interactive mode.
113The
114.Nm
115utility
116shows these requests with a
117.Dq Li CTRL-REQ- Ns Ao Ar type Ac Ns Li - Ns Ao Ar id Ac Ns Li : Ns Aq Ar text
118prefix, where
119.Aq Ar type
120is
121.Li IDENTITY , PASSWORD ,
122or
123.Li OTP
124(One-Time Password),
125.Aq Ar id
126is a unique identifier for the current network,
127.Aq Ar text
128is a description of the request.
129In the case of an
130.Li OTP
131(One-Time Password) request,
132it includes the challenge from the authentication server.
133.Pp
134A user must supply
135.Xr wpa_supplicant 8
136the needed parameters in response to these requests.
137.Pp
138For example,
139.Bd -literal -offset indent
140CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
141> password 1 mysecretpassword
142
143Example request for generic token card challenge-response:
144
145CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
146> otp 2 9876
147.Ed
148.Sh COMMANDS
149The following commands may be supplied on the command line
150or at a prompt when operating interactively.
151.Bl -tag -width indent
152.It Ic status
153Report the current WPA/EAPOL/EAP status for the current interface.
154.It Ic mib
155Report MIB variables (dot1x, dot11) for the current interface.
156.It Ic help
157Show usage help.
158.It Ic interface Op Ar ifname
159Show available interfaces and/or set the current interface
160when multiple are available.
161.It Ic level Ar debug_level
162Change the debugging level in
163.Xr wpa_supplicant 8 .
164Larger numbers generate more messages.
165.It Ic license
166Display the full
167license for
168.Nm .
169.It Ic logoff
170Send the IEEE 802.1X EAPOL state machine into the
171.Dq logoff
172state.
173.It Ic logon
174Send the IEEE 802.1X EAPOL state machine into the
175.Dq logon
176state.
177.It Ic set Op Ar settings
178Set variables.
179When no arguments are supplied, the known variables and their settings
180are displayed.
181.It Ic pmksa
182Show the contents of the PMKSA cache.
183.It Ic reassociate
184Force a reassociation to the current access point.
185.It Ic reconfigure
186Force
187.Xr wpa_supplicant 8
188to re-read its configuration file.
189.It Ic preauthenticate Ar BSSID
190Force preauthentication of the specified
191.Ar BSSID .
192.It Ic identity Ar network_id identity
193Configure an identity for an SSID.
194.It Ic password Ar network_id password
195Configure a password for an SSID.
196.It Ic otp Ar network_id password
197Configure a one-time password for an SSID.
198.It Ic terminate
199Force
200.Xr wpa_supplicant 8
201to terminate.
202.It Ic quit
203Exit
204.Nm .
205.El
206.Sh SEE ALSO
207.Xr wpa_supplicant.conf 5 ,
208.Xr wpa_supplicant 8
209.Sh HISTORY
210The
211.Nm
212utility first appeared in
213.Fx 6.0 .
214.Sh AUTHORS
215The
216.Nm
217utility was written by
218.An Jouni Malinen Aq jkmaline@cc.hut.fi .
219This manual page is derived from the
220.Pa README
221file included in the
222.Nm wpa_supplicant
223distribution.
224