LinuxCommandLibrary

wpa_supplicant

Connect to Wi-Fi networks

TLDR

Join a protected wireless network

$ wpa_supplicant -i [interface] -c [path/to/wpa_supplicant_conf.conf]
copy

Join a protected wireless network and run it in a daemon
$ wpa_supplicant -B -i [interface] -c [path/to/wpa_supplicant_conf.conf]
copy

SYNOPSIS

wpa_supplicant [options] -i <ifname> -c <config_file>

PARAMETERS

-i <ifname>
    Specifies the wireless interface name (e.g., wlan0) to be controlled by wpa_supplicant.

-c <config_file>
    Path to the configuration file containing network definitions and global settings. This file specifies how to connect to various Wi-Fi networks.

-D <driver>
    Selects the wireless driver to use (e.g., nl80211 for modern kernels, wext for older ones, hostap for access points). Defaults to nl80211 if not specified.

-B
    Runs wpa_supplicant as a background daemon, detaching from the controlling terminal.

-P <pid_file>
    Specifies a file where the process ID (PID) of the background daemon will be written.

-f <log_file>
    Redirects all debug output and messages to the specified log file instead of standard output/error.

-K
    Enables debugging output of key material, but without logging sensitive key data itself. Useful for understanding authentication flows.

-e <entropy_file>
    Specifies a file to read/write random data (entropy) for internal cryptographic operations.

-o
    Overwrites the configuration file with current network state, typically when using wpa_cli save_config.

-s
    Enables daemonization for systemd, causing wpa_supplicant to use a control socket for communication with systemd.

-u
    Enables the UNIX domain socket control interface, allowing tools like wpa_cli to communicate with the running daemon.

-v
    Increases the verbosity of the debug output. Can be specified multiple times for more detailed logs.

-t
    Adds timestamps to the debug messages, which is useful for analyzing logs over time.

-q
    Enables quiet mode, reducing the amount of standard output messages.

-h
    Displays a help message with available command-line options and exits.

DESCRIPTION

wpa_supplicant is a crucial daemon for secure wireless networking on Linux and other Unix-like systems. It implements the IEEE 802.1X supplicant, WPA (Wi-Fi Protected Access), and WPA2 protocols for client devices. Its primary role involves managing authentication, key negotiation, and association with Wi-Fi networks. It supports a wide array of EAP methods (e.g., PEAP, TTLS, TLS), PSK (Pre-Shared Key), and older WEP connections.

Typically, wpa_supplicant runs in the background, interacting with the wireless driver and network interfaces to handle the complex authentication handshake required for modern secure wireless connections. While it can be invoked directly, it's often started and managed by higher-level network management tools like NetworkManager or systemd-networkd, or interactively controlled via its dedicated clients, wpa_cli and wpa_gui. It ensures data confidentiality and integrity for wireless communications.

CAVEATS

wpa_supplicant generally requires root privileges to operate due to its interaction with low-level network device drivers and system resources. Its configuration can be complex, especially for enterprise-grade EAP methods, requiring precise syntax in the configuration file. Compatibility with specific wireless hardware and drivers can vary, though nl80211 is the modern and preferred driver interface. Directly running wpa_supplicant might conflict with other network management services (e.g., NetworkManager, systemd-networkd) if they are also attempting to control the same wireless interface.

CONFIGURATION FILE FORMAT

The wpa_supplicant configuration file (typically /etc/wpa_supplicant/wpa_supplicant.conf) defines the behavior of the daemon and the wireless networks it should attempt to connect to. It consists of global parameters and one or more network={...} blocks. Each network block specifies details like SSID, PSK (or password), key management (key_mgmt), and EAP method configurations, allowing for highly flexible and secure network setups.

CONTROL INTERFACE

wpa_supplicant exposes a control interface, typically a UNIX domain socket (e.g., /var/run/wpa_supplicant/wlan0), that allows other applications to interact with it. This interface is utilized by client utilities such as wpa_cli (command-line) and wpa_gui (graphical) to query status, add/remove networks, initiate scans, and manage connections dynamically without restarting the daemon.

HISTORY

wpa_supplicant was initially developed by Jouni Malinen, with its first public release around 2003. It quickly became the definitive implementation for WPA and WPA2 client functionality on Linux and other Unix-like operating systems. Its development has been continuous, adapting to new Wi-Fi standards, security enhancements, and driver interfaces (moving from wext to nl80211). Its widespread adoption by distributions and integration into network management frameworks highlights its critical role in enabling secure and robust wireless connectivity for Linux users worldwide.

SEE ALSO

wpa_cli(8), wpa_gui(8), iw(8), ip(8), networkctl(1), systemctl(1)

Copied to clipboard