1 .\" Copyright (c) 2005 Sam Leffler <sam@errno.com>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
32 .Nd "text-based frontend program for interacting with wpa_supplicant"
35 .Op Fl p Ar path_to_ctrl_sockets
38 .Op Fl a Ar action_file
40 .Op Fl g Ar global_ctrl
41 .Op Fl G Ar ping_interval
47 is a text-based frontend program for interacting with
48 .Xr wpa_supplicant 8 .
49 It is used to query current status,
53 request interactive user input.
59 current authentication status,
61 mode, dot11 and dot1x MIBs, etc.
64 can configure EAPOL state machine
65 parameters and trigger events such as reassociation
66 and IEEE 802.1X logoff/logon.
71 provides an interface to supply authentication information
72 such as username and password when it is not provided in the
73 .Xr wpa_supplicant.conf 5
75 This can be used, for example, to implement
76 one-time passwords or generic token card
77 authentication where the authentication is based on a
78 challenge-response that uses an external device for generating the
84 supports two modes: interactive and command line.
85 Both modes share the same command set and the main difference
86 is in interactive mode providing access to unsolicited messages
87 (event messages, username/password requests).
89 Interactive mode is started when
91 is executed without any parameters on the command line.
92 Commands are then entered from the controlling terminal in
96 In command line mode, the same commands are
97 entered as command line arguments.
99 The control interface of
101 can be configured to allow
102 non-root user access by using the
103 .Va ctrl_interface_group
106 .Xr wpa_supplicant.conf 5
108 This makes it possible to run
110 with a normal user account.
111 .Sh AUTHENTICATION PARAMETERS
114 needs authentication parameters, such as username and password,
115 that are not present in the configuration file, it sends a
116 request message to all attached frontend programs, e.g.,
122 shows these requests with a
123 .Dq Li CTRL-REQ- Ns Ao Ar type Ac Ns Li - Ns Ao Ar id Ac Ns : Ns Aq Ar text
127 .Li IDENTITY , PASSWORD ,
132 is a unique identifier for the current network,
134 is a description of the request.
137 (One-Time Password) request,
138 it includes the challenge from the authentication server.
142 the needed parameters in response to these requests.
145 .Bd -literal -offset indent
146 CTRL-REQ-PASSWORD-1:Password needed for SSID foobar
147 > password 1 mysecretpassword
149 Example request for generic token card challenge-response:
151 CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar
155 These options are available:
156 .Bl -tag -width indent
158 Control sockets path.
159 This should match the
162 .Xr wpa_supplicant.conf 5 .
164 .Pa /var/run/wpa_supplicant .
166 Interface to be configured.
167 By default, the first interface found in the socket path is used.
171 Show version information.
173 Run the daemon in the background.
174 .It Fl a Ar action_file
175 Run in daemon mode, executing the action file based on events from
176 .Xr wpa_supplicant 8 .
179 .It Fl g Ar global_ctrl
180 Use a global control interface to
182 rather than the default Unix domain sockets.
183 .It Fl G Ar ping_interval
186 seconds before sending each ping to
187 .Xr wpa_supplicant 8 .
192 See available commands in the next section.
195 These commands can be supplied on the command line
196 or at a prompt when operating interactively.
197 .Bl -tag -width indent
199 Report the current WPA/EAPOL/EAP status for the current interface.
201 Show the current interface name.
202 The default interface is the first interface found in the socket path.
207 This command can be used to test the status of the
211 Report MIB variables (dot1x, dot11) for the current interface.
214 .It Ic interface Op Ar ifname
215 Show available interfaces and/or set the current interface
216 when multiple interfaces are available.
217 .It Ic level Ar debug_level
218 Change the debugging level in
219 .Xr wpa_supplicant 8 .
220 Larger numbers generate more messages.
222 Display the full license for
225 Send the IEEE 802.1X EAPOL state machine into the
229 Send the IEEE 802.1X EAPOL state machine into the
232 .It Ic set Op Ar settings
234 When no arguments are supplied, the known variables and their settings
237 Show the contents of the PMKSA cache.
239 Force a reassociation to the current access point.
243 to re-read its configuration file.
244 .It Ic preauthenticate Ar BSSID
245 Force preauthentication of the specified
247 .It Ic identity Ar network_id identity
248 Configure an identity for an SSID.
249 .It Ic password Ar network_id password
250 Configure a password for an SSID.
251 .It Ic new_password Ar network_id password
252 Change the password for an SSID.
253 .It Ic PIN Ar network_id pin
254 Configure a PIN for an SSID.
255 .It Ic passphrase Ar network_id passphrase
256 Configure a private key passphrase for an SSID.
257 .It Ic bssid Ar network_id bssid
258 Set a preferred BSSID for an SSID
259 .It Ic blacklist Op Ar bssid | clear
260 Add a BSSID to the blacklist.
261 When invoked without any extra arguments, display the blacklist.
266 to clear the blacklist.
268 List configured networks.
269 .It Ic select_network Ar network_id
270 Select a network and disable others.
271 .It Ic enable_network Ar network_id
273 .It Ic disable_network Ar network_id
277 .It Ic remove_network Ar network_id
279 .It Ic set_network Op Ar network_id variable value
280 Set network variables.
281 Shows a list of variables when run without arguments.
282 .It Ic get_network Ar network_id variable
283 Get network variables.
285 Disconnect and wait for reassociate/reconnect command before connecting.
289 but only takes effect if already disconnected.
291 Request new BSS scan.
293 Get the latest BSS scan results.
294 This command can be invoked after running a BSS scan with
296 .It Ic bss Op Ar idx | bssid
297 Get a detailed BSS scan result for the network identified by
301 .It Ic otp Ar network_id password
302 Configure a one-time password for an SSID.
307 .It Ic interface_add Ar ifname Op Ar confname driver ctrl_interface driver_param bridge_name
308 Add a new interface with the given parameters.
309 .It Ic interface_remove Ar ifname
310 Remove the interface.
311 .It Ic interface_list
312 List available interfaces.
318 .Xr wpa_supplicant.conf 5 ,
323 utility first appeared in
328 utility was written by
329 .An Jouni Malinen Aq j@w1.fi .
330 This manual page is derived from the
334 files included in the