1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2005 Sam Leffler <sam@errno.com> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd June 21, 2024 29.Dt WPA_CLI 8 30.Os 31.Sh NAME 32.Nm wpa_cli 33.Nd console utility for WiFi authentication with wpa_supplicant 34.Sh SYNOPSIS 35.Nm wpa_cli 36.Op Fl p Ar path_to_ctrl_sockets 37.Op Fl i Ar ifname 38.Op Fl hvB 39.Op Fl a Ar action_file 40.Op Fl P Ar pid_file 41.Op Fl g Ar global_ctrl 42.Op Fl G Ar ping_interval 43.Ar command ... 44.Sh DESCRIPTION 45The 46.Nm 47utility 48is a text-based frontend program for interacting with 49.Xr wpa_supplicant 8 . 50It is used to query current status, 51change configuration, 52trigger events, 53and 54request interactive user input. 55.Pp 56The 57.Nm 58utility 59can show the 60current authentication status, 61selected security 62mode, dot11 and dot1x MIBs, etc. 63In addition, 64.Nm 65can configure EAPOL state machine 66parameters and trigger events such as reassociation 67and IEEE 802.1X logoff/logon. 68.Pp 69The 70.Nm 71utility 72provides an interface to supply authentication information 73such as username and password when it is not provided in the 74.Xr wpa_supplicant.conf 5 75configuration file. 76This can be used, for example, to implement 77one-time passwords or generic token card 78authentication where the authentication is based on a 79challenge-response that uses an external device for generating the 80response. 81.Pp 82The 83.Nm 84utility 85supports two modes: interactive and command line. 86Both modes share the same command set and the main difference 87is in interactive mode providing access to unsolicited messages 88(event messages, username/password requests). 89.Pp 90Interactive mode is started when 91.Nm 92is executed without any parameters on the command line. 93Commands are then entered from the controlling terminal in 94response to the 95.Nm 96prompt. 97In command line mode, the same commands are 98entered as command line arguments. 99.Pp 100The control interface of 101.Xr wpa_supplicant 8 102can be configured to allow 103non-root user access by using the 104.Va ctrl_interface_group 105parameter 106in the 107.Xr wpa_supplicant.conf 5 108configuration file. 109This makes it possible to run 110.Nm 111with a normal user account. 112.Sh AUTHENTICATION PARAMETERS 113When 114.Xr wpa_supplicant 8 115needs authentication parameters, such as username and password, 116that are not present in the configuration file, it sends a 117request message to all attached frontend programs, e.g., 118.Nm 119in interactive mode. 120The 121.Nm 122utility 123shows these requests with a 124.Dq Li CTRL-REQ- Ns Ao Ar type Ac Ns Li - Ns Ao Ar id Ac : Ns Aq Ar text 125prefix, where 126.Aq Ar type 127is 128.Li IDENTITY , PASSWORD , 129or 130.Li OTP 131(One-Time Password), 132.Aq Ar id 133is a unique identifier for the current network, 134.Aq Ar text 135is a description of the request. 136In the case of an 137.Li OTP 138(One-Time Password) request, 139it includes the challenge from the authentication server. 140.Pp 141A user must supply 142.Xr wpa_supplicant 8 143the needed parameters in response to these requests. 144.Pp 145For example, 146.Bd -literal -offset indent 147CTRL-REQ-PASSWORD-1:Password needed for SSID foobar 148> password 1 mysecretpassword 149 150Example request for generic token card challenge-response: 151 152CTRL-REQ-OTP-2:Challenge 1235663 needed for SSID foobar 153> otp 2 9876 154.Ed 155.Sh OPTIONS 156These options are available: 157.Bl -tag -width indent 158.It Fl p Ar path 159Control sockets path. 160This should match the 161.Ic ctrl_interface 162in 163.Xr wpa_supplicant.conf 5 . 164The default path is 165.Pa /var/run/wpa_supplicant . 166.It Fl i Ar ifname 167Interface to be configured. 168By default, the first interface found in the socket path is used. 169.It Fl h 170Show help. 171.It Fl v 172Show version information. 173.It Fl B 174Run the daemon in the background. 175.It Fl a Ar action_file 176Run in daemon mode, executing the action file based on events from 177.Xr wpa_supplicant 8 . 178.It Fl P Ar pid_file 179PID file location. 180.It Fl g Ar global_ctrl 181Use a global control interface to 182.Xr wpa_supplicant 8 183rather than the default Unix domain sockets. 184.It Fl G Ar ping_interval 185Wait 186.Dq ping_interval 187seconds before sending each ping to 188.Xr wpa_supplicant 8 . 189See the 190.Ic ping 191command. 192.It command 193See available commands in the next section. 194.El 195.Sh COMMANDS 196These commands can be supplied on the command line 197or at a prompt when operating interactively. 198.Bl -tag -width indent 199.It Ic status 200Report the current WPA/EAPOL/EAP status for the current interface. 201.It Ic ifname 202Show the current interface name. 203The default interface is the first interface found in the socket path. 204.It Ic ping 205Ping the 206.Xr wpa_supplicant 8 207utility. 208This command can be used to test the status of the 209.Xr wpa_supplicant 8 210daemon. 211.It Ic mib 212Report MIB variables (dot1x, dot11) for the current interface. 213.It Ic help 214Show usage help. 215.It Ic interface Op Ar ifname 216Show available interfaces and/or set the current interface 217when multiple interfaces are available. 218.It Ic level Ar debug_level 219Change the debugging level in 220.Xr wpa_supplicant 8 . 221Larger numbers generate more messages. 222.It Ic license 223Display the full license for 224.Nm . 225.It Ic logoff 226Send the IEEE 802.1X EAPOL state machine into the 227.Dq logoff 228state. 229.It Ic logon 230Send the IEEE 802.1X EAPOL state machine into the 231.Dq logon 232state. 233.It Ic set Op Ar settings 234Set variables. 235When no arguments are supplied, the known variables and their settings 236are displayed. 237.It Ic pmksa 238Show the contents of the PMKSA cache. 239.It Ic reassociate 240Force a reassociation to the current access point. 241.It Ic reconfigure 242Force 243.Xr wpa_supplicant 8 244to re-read its configuration file. 245.It Ic preauthenticate Ar BSSID 246Force preauthentication of the specified 247.Ar BSSID . 248.It Ic identity Ar network_id identity 249Configure an identity for an SSID. 250.It Ic password Ar network_id password 251Configure a password for an SSID. 252.It Ic new_password Ar network_id password 253Change the password for an SSID. 254.It Ic PIN Ar network_id pin 255Configure a PIN for an SSID. 256.It Ic passphrase Ar network_id passphrase 257Configure a private key passphrase for an SSID. 258.It Ic bssid Ar network_id bssid 259Set a preferred BSSID for an SSID 260.It Ic blacklist Op Ar bssid | clear 261Add a BSSID to the blacklist. 262When invoked without any extra arguments, display the blacklist. 263Specifying 264.Ar clear 265causes 266.Nm 267to clear the blacklist. 268.It Ic list_networks 269List configured networks. 270.It Ic select_network Ar network_id 271Select a network and disable others. 272.It Ic enable_network Ar network_id 273Enable a network. 274.It Ic disable_network Ar network_id 275Disable a network. 276.It Ic add_network 277Add a network. 278.It Ic remove_network Ar network_id 279Remove a network. 280.It Ic set_network Op Ar network_id variable value 281Set network variables. 282Shows a list of variables when run without arguments. 283.It Ic get_network Ar network_id variable 284Get network variables. 285.It Ic disconnect 286Disconnect and wait for reassociate/reconnect command before connecting. 287.It Ic reconnect 288Similar to 289.Ic reassociate , 290but only takes effect if already disconnected. 291.It Ic scan 292Request new BSS scan. 293.It Ic scan_results 294Get the latest BSS scan results. 295This command can be invoked after running a BSS scan with 296.Ic scan . 297.It Ic bss Op Ar idx | bssid 298Get a detailed BSS scan result for the network identified by 299.Dq bssid 300or 301.Dq idx . 302.It Ic otp Ar network_id password 303Configure a one-time password for an SSID. 304.It Ic terminate 305Force 306.Xr wpa_supplicant 8 307to terminate. 308.It Ic interface_add Ar ifname Op Ar confname driver ctrl_interface driver_param bridge_name 309Add a new interface with the given parameters. 310.It Ic interface_remove Ar ifname 311Remove the interface. 312.It Ic interface_list 313List available interfaces. 314.It Ic quit 315Exit 316.Nm . 317.El 318.Sh SEE ALSO 319.Xr wpa_supplicant.conf 5 , 320.Xr wpa_supplicant 8 321.Sh HISTORY 322The 323.Nm 324utility first appeared in 325.Fx 6.0 . 326.Sh AUTHORS 327The 328.Nm 329utility was written by 330.An Jouni Malinen Aq Mt j@w1.fi . 331This manual page is derived from the 332.Pa README 333and 334.Pa wpa_cli.c 335files included in the 336.Nm wpa_supplicant 337distribution. 338