2 \page ctrl_iface_page Control interface
4 %wpa_supplicant implements a control interface that can be used by
5 external programs to control the operations of the %wpa_supplicant
6 daemon and to get status information and event notifications. There is
7 a small C library, in a form of a single C file, wpa_ctrl.c, that
8 provides helper functions to facilitate the use of the control
9 interface. External programs can link this file into them and then use
10 the library functions documented in wpa_ctrl.h to interact with
11 %wpa_supplicant. This library can also be used with C++. wpa_cli.c and
12 wpa_gui are example programs using this library.
14 There are multiple mechanisms for inter-process communication. For
15 example, Linux version of %wpa_supplicant is using UNIX domain sockets
16 for the control interface and Windows version UDP sockets. The use of
17 the functions defined in wpa_ctrl.h can be used to hide the details of
18 the used IPC from external programs.
21 \section using_ctrl_iface Using the control interface
23 External programs, e.g., a GUI or a configuration utility, that need to
24 communicate with %wpa_supplicant should link in wpa_ctrl.c. This
25 allows them to use helper functions to open connection to the control
26 interface with wpa_ctrl_open() and to send commands with
29 %wpa_supplicant uses the control interface for two types of communication:
30 commands and unsolicited event messages. Commands are a pair of
31 messages, a request from the external program and a response from
32 %wpa_supplicant. These can be executed using wpa_ctrl_request().
33 Unsolicited event messages are sent by %wpa_supplicant to the control
34 interface connection without specific request from the external program
35 for receiving each message. However, the external program needs to
36 attach to the control interface with wpa_ctrl_attach() to receive these
39 If the control interface connection is used both for commands and
40 unsolicited event messages, there is potential for receiving an
41 unsolicited message between the command request and response.
42 wpa_ctrl_request() caller will need to supply a callback, msg_cb,
43 for processing these messages. Often it is easier to open two
44 control interface connections by calling wpa_ctrl_open() twice and
45 then use one of the connections for commands and the other one for
46 unsolicited messages. This way command request/response pairs will
47 not be broken by unsolicited messages. wpa_cli is an example of how
48 to use only one connection for both purposes and wpa_gui demonstrates
49 how to use two separate connections.
51 Once the control interface connection is not needed anymore, it should
52 be closed by calling wpa_ctrl_close(). If the connection was used for
53 unsolicited event messages, it should be first detached by calling
57 \section ctrl_iface_cmds Control interface commands
59 Following commands can be used with wpa_ctrl_request():
61 \subsection ctrl_iface_PING PING
63 This command can be used to test whether %wpa_supplicant is replying
64 to the control interface commands. The expected reply is \c PONG if the
65 connection is open and %wpa_supplicant is processing commands.
68 \subsection ctrl_iface_MIB MIB
70 Request a list of MIB variables (dot1x, dot11). The output is a text
71 block with each line in \c variable=value format. For example:
74 dot11RSNAOptionImplemented=TRUE
75 dot11RSNAPreauthenticationImplemented=TRUE
76 dot11RSNAEnabled=FALSE
77 dot11RSNAPreauthenticationEnabled=FALSE
78 dot11RSNAConfigVersion=1
79 dot11RSNAConfigPairwiseKeysSupported=5
80 dot11RSNAConfigGroupCipherSize=128
81 dot11RSNAConfigPMKLifetime=43200
82 dot11RSNAConfigPMKReauthThreshold=70
83 dot11RSNAConfigNumberOfPTKSAReplayCounters=1
84 dot11RSNAConfigSATimeout=60
85 dot11RSNAAuthenticationSuiteSelected=00-50-f2-2
86 dot11RSNAPairwiseCipherSelected=00-50-f2-4
87 dot11RSNAGroupCipherSelected=00-50-f2-4
89 dot11RSNAAuthenticationSuiteRequested=00-50-f2-2
90 dot11RSNAPairwiseCipherRequested=00-50-f2-4
91 dot11RSNAGroupCipherRequested=00-50-f2-4
92 dot11RSNAConfigNumberOfGTKSAReplayCounters=0
93 dot11RSNA4WayHandshakeFailures=0
95 dot1xSuppHeldPeriod=60
96 dot1xSuppAuthPeriod=30
97 dot1xSuppStartPeriod=30
99 dot1xSuppSuppControlledPortStatus=Authorized
100 dot1xSuppBackendPaeState=2
101 dot1xSuppEapolFramesRx=0
102 dot1xSuppEapolFramesTx=440
103 dot1xSuppEapolStartFramesTx=2
104 dot1xSuppEapolLogoffFramesTx=0
105 dot1xSuppEapolRespFramesTx=0
106 dot1xSuppEapolReqIdFramesRx=0
107 dot1xSuppEapolReqFramesRx=0
108 dot1xSuppInvalidEapolFramesRx=0
109 dot1xSuppEapLengthErrorFramesRx=0
110 dot1xSuppLastEapolFrameVersion=0
111 dot1xSuppLastEapolFrameSource=00:00:00:00:00:00
115 \subsection ctrl_iface_STATUS STATUS
117 Request current WPA/EAPOL/EAP status information. The output is a text
118 block with each line in \c variable=value format. For example:
121 bssid=02:00:01:02:03:04
127 ip_address=192.168.1.21
128 Supplicant PAE state=AUTHENTICATED
129 suppPortStatus=Authorized
134 \subsection ctrl_iface_STATUS-VERBOSE STATUS-VERBOSE
136 Same as STATUS, but with more verbosity (i.e., more \c variable=value pairs).
139 bssid=02:00:01:02:03:04
145 ip_address=192.168.1.21
146 Supplicant PAE state=AUTHENTICATED
147 suppPortStatus=Authorized
153 Supplicant Backend state=IDLE
162 \subsection ctrl_iface_PMKSA PMKSA
167 Index / AA / PMKID / expiration (in seconds) / opportunistic
168 1 / 02:00:01:02:03:04 / 000102030405060708090a0b0c0d0e0f / 41362 / 0
169 2 / 02:00:01:33:55:77 / 928389281928383b34afb34ba4212345 / 362 / 1
173 \subsection ctrl_iface_SET SET <variable> <value>
180 - dot11RSNAConfigPMKLifetime
181 - dot11RSNAConfigPMKReauthThreshold
182 - dot11RSNAConfigSATimeout
186 SET EAPOL::heldPeriod 45
190 \subsection ctrl_iface_LOGON LOGON
192 IEEE 802.1X EAPOL state machine logon.
195 \subsection ctrl_iface_LOGOFF LOGOFF
197 IEEE 802.1X EAPOL state machine logoff.
200 \subsection ctrl_iface_REASSOCIATE REASSOCIATE
205 \subsection ctrl_iface_PREAUTH PREAUTH <BSSID>
207 Start pre-authentication with the given BSSID.
210 \subsection ctrl_iface_ATTACH ATTACH
212 Attach the connection as a monitor for unsolicited events. This can
213 be done with wpa_ctrl_attach().
216 \subsection ctrl_iface_DETACH DETACH
218 Detach the connection as a monitor for unsolicited events. This can
219 be done with wpa_ctrl_detach().
222 \subsection ctrl_iface_LEVEL LEVEL <debug level>
227 \subsection ctrl_iface_RECONFIGURE RECONFIGURE
229 Force %wpa_supplicant to re-read its configuration data.
232 \subsection ctrl_iface_TERMINATE TERMINATE
234 Terminate %wpa_supplicant process.
237 \subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
239 Set preferred BSSID for a network. Network id can be received from the
240 \c LIST_NETWORKS command output.
243 \subsection ctrl_iface_LIST_NETWORKS LIST_NETWORKS
245 List configured networks.
248 network id / ssid / bssid / flags
249 0 example network any [CURRENT]
252 (note: fields are separated with tabs)
255 \subsection ctrl_iface_DISCONNECT DISCONNECT
257 Disconnect and wait for \c REASSOCIATE command before connecting.
260 \subsection ctrl_iface_SCAN SCAN
262 Request a new BSS scan.
265 \subsection ctrl_iface_SCAN_RESULTS SCAN_RESULTS
267 Get the latest scan results.
270 bssid / frequency / signal level / flags / ssid
271 00:09:5b:95:e0:4e 2412 208 [WPA-PSK-CCMP] jkm private
272 02:55:24:33:77:a3 2462 187 [WPA-PSK-TKIP] testing
273 00:09:5b:95:e0:4f 2412 209 jkm guest
276 (note: fields are separated with tabs)
279 \subsection ctrl_iface_SELECT_NETWORK SELECT_NETWORK <network id>
281 Select a network (disable others). Network id can be received from the
282 \c LIST_NETWORKS command output.
285 \subsection ctrl_iface_ENABLE_NETWORK ENABLE_NETWORK <network id>
287 Enable a network. Network id can be received from the
288 \c LIST_NETWORKS command output.
291 \subsection ctrl_iface_DISABLE_NETWORK DISABLE_NETWORK <network id>
293 Disable a network. Network id can be received from the
294 \c LIST_NETWORKS command output.
297 \subsection ctrl_iface_ADD_NETWORK ADD_NETWORK
299 Add a new network. This command creates a new network with empty
300 configuration. The new network is disabled and once it has been
301 configured it can be enabled with \c ENABLE_NETWORK command. \c ADD_NETWORK
302 returns the network id of the new network or FAIL on failure.
305 \subsection ctrl_iface_REMOVE_NETWORK REMOVE_NETWORK <network id>
307 Remove a network. Network id can be received from the
308 \c LIST_NETWORKS command output.
311 \subsection ctrl_iface_SET_NETWORK SET_NETWORK <network id> <variable> <value>
313 Set network variables. Network id can be received from the
314 \c LIST_NETWORKS command output.
316 This command uses the same variables and data formats as the
317 configuration file. See example wpa_supplicant.conf for more details.
319 - ssid (network name, SSID)
320 - psk (WPA passphrase or pre-shared key)
321 - key_mgmt (key management protocol)
322 - identity (EAP identity)
323 - password (EAP password)
327 \subsection ctrl_iface_GET_NETWORK GET_NETWORK <network id> <variable>
329 Get network variables. Network id can be received from the
330 \c LIST_NETWORKS command output.
333 \subsection ctrl_iface_SAVE_CONFIG SAVE_CONFIG
335 Save the current configuration.
338 \section ctrl_iface_interactive Interactive requests
340 If %wpa_supplicant needs additional information during authentication
341 (e.g., password), it will use a specific prefix, \c CTRL-REQ-
342 (\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
343 program, e.g., a GUI, can provide such information by using
344 \c CTRL-RSP- (\a WPA_CTRL_RSP macro) prefix in a command with matching
347 The following fields can be requested in this way from the user:
348 - IDENTITY (EAP identity/user name)
349 - PASSWORD (EAP password)
350 - NEW_PASSWORD (New password if the server is requesting password change)
351 - PIN (PIN code for accessing a SIM or smartcard)
352 - OTP (one-time password; like password, but the value is used only once)
353 - PASSPHRASE (passphrase for a private key file)
356 CTRL-REQ-<field name>-<network id>-<human readable text>
357 CTRL-RSP-<field name>-<network id>-<value>
360 For example, request from %wpa_supplicant:
362 CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
365 And a matching reply from the GUI:
367 CTRL-RSP-PASSWORD-1-secret
371 \subsection ctrl_iface_GET_CAPABILITY GET_CAPABILITY <option>
373 Get list of supported functionality (eap, pairwise, group,
374 proto). Supported functionality is shown as space separate lists of
375 values used in the same format as in %wpa_supplicant configuration.
377 Example request/reply pairs:
381 AKA FAST GTC LEAP MD5 MSCHAPV2 OTP PAX PEAP PSK SIM TLS TTLS
385 GET_CAPABILITY pairwise
391 CCMP TKIP WEP104 WEP40
395 GET_CAPABILITY key_mgmt
396 WPA-PSK WPA-EAP IEEE8021X NONE
405 GET_CAPABILITY auth_alg