wpa_supplicant - Arch Linux 中文维基

跳至內容

# wpa_supplicant

出自 Arch Linux 中文维基
翻譯狀態：

- 本文（或部分內容）譯自 WPA supplicant，最近一次同步於 2025-01-04，若英文版本有所更改，則您可以幫助同步與翻譯更改的內容。
- 您可以在 ArchWiki 的對應頁面找到本文翻譯的原始修訂歷史。
- 本文可能與英文原文存在出入。

相關文章

- 網絡配置
- 無線網絡配置
- iwd

wpa_supplicant 是跨平台的接入客戶端，支持 WPA，WPA2 和 WPA3（IEEE 802.11i），適用於桌面設備、筆記本及嵌入式系統。它是用於客戶端的 IEEE 802.1X/WPA 組件。它實現了與 WPA 驗證者交互，控制漫遊和無線驅動的 IEEE 802.11 驗證和關聯。

## 安裝

安裝 wpa_supplicant包 軟體包。此軟體包提供了主程序 wpa_supplicant，密碼工具 wpa_passphrase 和文字界面前端 wpa_cli。

還可以額外安裝官方的 wpa_supplicant_guiAUR，該軟體包提供了 wpa_supplicant 的圖形界面前端 wpa_gui。wpa-cuteAUR 是 wpa_gui 的一個分支，提供了額外的修正和改進。

## 概覽

連接到加密無線網絡的第一步是讓 wpa_supplicant 獲取 WPA 認證者的認證。為此，wpa_supplicant 必須進行配置以使其能夠向認證者提交認證信息。

完成認證後需要分配一個 IP 地址，具體步驟請參考網絡配置#IP 地址。

## 使用 wpa_cli 進行連接

這種方法使用了 wpa_cli 命令行工具，可以用其掃描可用網絡，並配置 wpa_supplicant。詳細信息可以參考 wpa_cli(8) 。

使用 wpa_cli 前，需要先為 wpa_supplicant 指定一個控制接口，且它需要獲得更新配置的權限。先創建一個最小配置：

    /etc/wpa_supplicant/wpa_supplicant.conf

    ctrl_interface=/run/wpa_supplicant
    update_config=1

警告：將 `update_config` 設為 `1` 會允許 wpa_supplicant 覆寫配置文件。wpa_supplicant 會在覆寫時根據您的默認 umask 重置文件權限，如果您的系統有多用戶，可能會意外使任何人能夠讀取該文件，由此而洩漏密碼。

接下來啟動 wpa_supplicant：

    # wpa_supplicant -B -i interface -c /etc/wpa_supplicant/wpa_supplicant.conf

提示：可以參考網絡配置#列出網絡接口查看你的無線網卡名稱。

完成後，執行：

    # wpa_cli

這一步完成後會顯示一個交互提示符（`>`），同時帶有 tab 補全及命令描述功能，還可以使用 `help` 命令查看幫助。

提示：控制接口的默認位置為 `/var/run/wpa_supplicant/`，可以使用 `-p` 選項手動指定位置，以與wpa_supplicant 的配置相符。另外，可以使用 `-i` 選項指定需配置的接口，否則將使用由 wpa_supplicant 管理的第一個網絡接口。
提示：

- 控制接口的默認位置為 `/var/run/wpa_supplicant/`，可以使用 `-p` 選項手動指定位置，以與wpa_supplicant 的配置相符。
- 可以使用 `-i` 選項指定需配置的接口，否則將使用由 wpa_supplicant 管理的第一個無線網絡接口。

使用 `scan` 和 `scan_results` 命令查看可用網絡：

    > scan
    OK
    <3>CTRL-EVENT-SCAN-RESULTS
    > scan_results
    bssid / frequency / signal level / flags / ssid
    00:00:00:00:00:00 2462 -49 [WPA2-PSK-CCMP][ESS] MYSSID
    11:11:11:11:11:11 2437 -64 [WPA2-PSK-CCMP][ESS] ANOTHERSSID

要將網絡與 `MYSSID` 進行關聯，先添加網絡，配置憑證並啟用：

    > add_network
    0
    > set_network 0 ssid "MYSSID"
    > set_network 0 psk "passphrase"
    > enable_network 0
    <2>CTRL-EVENT-CONNECTED - Connection to 00:00:00:00:00:00 completed (reauth) [id=0 id_str=]

如果對應的 SSID 無需密碼驗證，則需要將命令 `set_network 0 psk "passphrase"` 替換為 `set_network 0 key_mgmt NONE`，以將網絡指定為無密碼。

注意：

- 可以添加多個網絡配置，每個網絡都按照數字順序進行排列，所以第一個網絡的索引為 0。
- If no connection can be established, some information will be printed, and periodic attempts will be made. As part of the periodic attempts, a user prompt will also be given periodically. Issuing the `disable_network 0` command will stop the periodic attempts and return to a steady user prompt.
- 如果使用 `set_network` 提供了憑證，那麼就會由 引號 括起的 "passphrase" 字符串生成 PSK。另外，你也可以 不使用引號 通過 wpa_passphrase 直接向 `psk` 傳入 PSK。

最後，將網絡保存到配置文件中，並退出 wpa_cli：

    > save_config
    OK
    > quit

完成後，你需要獲取一個 IP 地址，具體步驟請參考網絡配置#網絡管理。

## 使用 wpa_passphrase 進行連接

通過使用命令行工具 wpa_passphrase 生成 wpa_supplicant 所需的最小配置，可以快速連接到已知 SSID 的無線網絡。例如：

    $ wpa_passphrase MYSSID passphrase

    network={
        ssid="MYSSID"
        #psk="passphrase"
        psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
    }

上例表明，wpa_supplicant 可以與 wpa_passphrase 協同工作，只需簡單地這樣做即可：

    # wpa_supplicant -B -i interface -c <(wpa_passphrase MYSSID passphrase)

提示：

- 上條命令需要使用 root shell。
- 如果輸入內容包含空格，請使用引號，例如：`"secret passphrase"`.
- 要找出無線網卡的名字，請參考網絡配置#列出網絡接口。
- 某些少見的複雜密碼需要從文件導入，例如：`wpa_passphrase MYSSID < passphrase.txt`，或者從命令行輸入，例如：`wpa_passphrase MYSSID <<< "passphrase"`。
- Alternatively, when using special characters in the passphrase, rather than escaping them, simply invoke `wpa_passphrase` without specifying the passphrase. It will then prompt for it to be entered in the standard input where users can paste it even if it contains special characters.

完成後需要獲取一個 IP 地址，具體步驟請參考網絡配置#IP 地址。

## 高級用法

對於各種紛繁複雜的網絡，更常見的場景是使用 EAP 管理配置文件。各種配置及其範例可參閱手冊頁 wpa_supplicant.conf(5)；所有可支持的配置參數可參考範例文件 `/usr/share/doc/wpa_supplicant/wpa_supplicant.conf`。[1]。

### 配置

如上文中#使用 wpa_passphrase 進行連接一節所述，一個基本的配置文件可以這樣生成：

    # wpa_passphrase MYSSID passphrase > /etc/wpa_supplicant/example.conf

這樣僅僅是創建了一個 `network` 網絡配置節段。 A configuration file with also the ability of #使用 wpa_cli 進行連接 and some other common options may look like：

    /etc/wpa_supplicant/example.conf

    # Giving configuration update rights to wpa_cli
    ctrl_interface=/run/wpa_supplicant
    ctrl_interface_group=wheel
    update_config=1

    # AP scanning
    ap_scan=1

    # ISO/IEC alpha2 country code in which the device is operating
    country=US

    # network section generated by wpa_passphrase
    network={
        ssid="MYSSID"
        psk=59e0d07fa4c7741797a4e394f38a5c321e3bed51d54ad5fcbd3f84bc7415d73d
    }

如果可以不顧及安全問題，`network` 中的通行字可以換成由引號包圍的純文本：

    psk="passphrase"

如果網絡沒有設置通行字，如公共無線網絡：

    network={
       ssid="MYSSID"
       key_mgmt=NONE
    }

To connect to a WPA-Enterprise network, see #802.1x/radius.

Further `network` blocks may be added manually, or using wpa_cli as illustrated in #使用 wpa_cli 進行連接. In order to use wpa_cli, a control interface must be set with the `ctrl_interface` option. Setting `ctrl_interface_group=wheel` allows users belonging to such group to execute wpa_cli. This setting can be used to enable users without root access (or equivalent via sudo etc) to connect to wireless networks. Also add `update_config=1` so that changes made with wpa_cli to `example.conf` can be saved. Note that any user that is a member of the `ctrl_interface_group` group will be able to make changes to the file if this is turned on.

`fast_reauth=1` and `ap_scan=1` are the wpa_supplicant options active globally at the time of writing. Whether you need them, or other global options too for that matter, depends on the type of network to connect to. If you need other global options, simply copy them over to the file from `/usr/share/doc/wpa_supplicant/wpa_supplicant.conf`.

Alternatively, `wpa_cli set` can be used to see options' status or set new ones. Multiple network blocks may be appended to this configuration: the supplicant will handle association to and roaming between all of them. The strongest signal defined with a network block usually is connected to by default, one may define `priority=` to influence behaviour. For example to auto-connect to any unsecured network as a fallback with the lowest priority:

    network={
       key_mgmt=NONE
       priority=-999
    }

Once you have finished the configuration file, you can optionally use it as a system-wide or per-interface default configuration by naming it according to the paths listed in #At boot (systemd). This also applies if you use additional network manager tools, which may rely on the paths (for example Dhcpcd#10-wpa_supplicant).

提示：To configure a network block to a hidden wireless SSID, which by definition will not turn up in a regular scan, the option `scan_ssid=1` has to be defined in the network block.

### 連接

#### 手動連接

首先啟動 wpa_supplicant 命令，其最常用的參數為：

- `-B` - 在後台運行。
- `-c filename` - 配置文件的路徑。
- `-i interface` - 要監聽的設備。
- `-D driver` - （可選）指定使用的驅動。運行 `wpa_supplicant -h` 以查看所支持的驅動列表。
  - `nl80211` 是目前的標準，但是不是所有無線網卡都支持。
  - `wext` 目前已經棄用，但是仍被廣泛支持。

見 wpa_supplicant(8) 獲取全部參數的列表。例如：

    # wpa_supplicant -B -i interface -c /etc/wpa_supplicant/example.conf

接著是用在#概覽中提到的方法手動獲取 IP，例如：

    # dhcpcd interface

提示：

- dhcpcd has a hook that can launch wpa_supplicant implicitly, see dhcpcd#10-wpa_supplicant.
- While testing arguments/configuration it may be helpful to launch wpa_supplicant in the foreground (i.e. without the `-B` option) for better debugging messages.

#### 引導時連接（systemd）

wpa_supplicant 軟體包中提供了多個 systemd 服務文件：

- `wpa_supplicant.service` - 使用 D-Bus ，建議 NetworkManager 用戶使用。
- `wpa_supplicant@interface.service` - 接受網口名作為參數，啟動服務於該網口的 wpa_supplicant 守護進程。這個服務將讀取 `/etc/wpa_supplicant/wpa_supplicant-interface.conf` 這個配置文件，在使用 systemd-networkd 時比較有用。
- `wpa_supplicant-nl80211@interface.service` - 同樣接受網口名作為參數，但明確限定使用 `nl80211` 驅動（詳閱下文）。它的配置文件是 `/etc/wpa_supplicant/wpa_supplicant-nl80211-interface.conf`。
- `wpa_supplicant-wired@interface.service` - 同樣接受網口名作為參數，使用 `wired`（有線網絡）驅動。它的配置文件是 `/etc/wpa_supplicant/wpa_supplicant-wired-interface.conf`。

在引導時激活無線網絡，就是激活服務於某個無線網絡接口的上述服務單元之一，例如啟用 `wpa_supplicant@interface`。

現在就可以像概覽一節所述，可以選定某個網絡接口並啟用其服務單元的一個實例，從而獲取一個 IP 地址，例如啟用 `dhcpcd@interface`。

提示：dhcpcd 可以後台加載 wpa_supplicant ，參閱 dhcpcd#10-wpa_supplicant。

##### 802.1x/radius

To connect a wired adapter using 802.1x/radius you will need to specify some configurations and enable the necessary service for the adapter. This is useful for headless servers using systemd-networkd.

You may need to specify the `wired` driver with the `-D wired` command line option (see #Manual) if the default driver does not support your adapter.

Replace `adapter` with the wired adapter you wish to connect, and adapt the settings to match your 802.1x/radius requirements.

    /etc/wpa_supplicant/wpa_supplicant-wired-adapter.conf

    ctrl_interface=/run/wpa_supplicant
    ap_scan=0
    network={
      key_mgmt=IEEE8021X
      eap=PEAP
      identity="user_name"
      password="user_password"
      phase2="autheap=MSCHAPV2"
    }

提示：The same configuration, but for a wireless adapter, would require changing `IEEE8021X` to `WPA-EAP` and removing the `ap_scan=0` line

Since this file is storing a plaintext password, chown it to `root:root` and chmod it to `600`.

To use the hash instead of the plaintext password, you can use the `hash` keyword:

    password=hash:hash_of_plaintext_password

To hash your password:

    $ iconv -t utf16le | openssl dgst -md4 -provider legacy

After invoking the command above, provide your plain password and then press `Ctrl+d`.

注意：Hashing the password does not improve the security nor avoid the risk of exposing secrets.

Before running the `wpa_supplicant-wired@adapter.service` service, make sure to set the device down:

    # ip link set adapter down

提示：This setup can be used during system installation as well, though you may want to run using `dhcpcd@adapter.service` to solicit an address.

### wpa_cli 操作腳本

wpa_cli can run in daemon mode and execute a specified script based on events from wpa_supplicant. Two events are supported: `CONNECTED` and `DISCONNECTED`. Some environment variables are available to the script, see wpa_cli(8) for details.

The following example will use notify-send to notify the user about the events:

    #!/bin/sh

    case "$2" in
        CONNECTED)
            notify-send "WPA supplicant: connection established";
            ;;
        DISCONNECTED)
            notify-send "WPA supplicant: connection lost";
            ;;
    esac

Remember to make the script executable, then use the `-a` flag to pass the script path to wpa_cli:

    $ wpa_cli -a /path/to/script

### 漫遊

When connected to a wireless network with multiple access points, wpa_supplicant is typically responsible for roaming between access points. Choosing a new access point requires wpa_supplicant to perform a scan of available networks, which causes a brief interruption in connectivity to the current access point while the wireless radio scans other frequencies. After a scan, if wpa_supplicant detects a closer access point (BSSID) in the current network (SSID), in terms of signal strength (RSSI), it will re-associate to the closer access point.

The default configuration of wpa_supplicant has relatively timid roaming: it will rescan only when the association to the current access point is lost. This means that, if a client moves far away from its current access point, but not far enough to completely lose signal, the client will keep using the weak signal instead of roaming to a closer access point.

To make wpa_supplicant more aggressive about roaming, set the `bgscan` parameter in the configuration file, such as:

    bgscan="simple:30:-70:3600"

The above example will cause wpa_supplicant to scan every 30 seconds when the signal is weak (below -70), and every 3600 seconds otherwise. `bgscan` can be specified either in specific `network` blocks or globally for all networks.

## 排錯

警告：Make sure that you do not have remnant configuration files based on the full documentation example `/usr/share/doc/wpa_supplicant/wpa_supplicant.conf`. It is filled with uncommented network examples that may lead to random errors in practice (FS#40661).

### Debugging connection failures

In order to determine why you are unable to connect to an access point you can run wpa_supplicant with the `-d` flag for debug messages, wait a couple seconds then look for lines that list SSIDs and the reason they were not connected to. For example:

    # wpa_supplicant -i wlan0 -c /etc/wpa_supplicant/example.conf -d

    wlan0: Selecting BSS from priority group 0
    wlan0: 0: d2:93:5b:b7:5d:d2 ssid= wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
    wlan0:    skip - SSID not known
    wlan0: 1: f2:93:5b:b7:5d:d2 ssid= wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
    wlan0:    skip - SSID not known
    wlan0: 2: b2:93:5b:b7:5d:d2 ssid= wpa_ie_len=26 rsn_ie_len=24 caps=0x511 level=-54 freq=5180
    wlan0:    skip - SSID not known
    wlan0: 3: b0:93:5b:b7:5d:d2 ssid='Access Point 1' wpa_ie_len=0 rsn_ie_len=20 caps=0x511 level=-55 freq=5180  wps
    wlan0:    skip - SSID mismatch
    wlan0: 4: c4:13:e2:33:42:20 ssid='\x00\x00\x00\x00' wpa_ie_len=22 rsn_ie_len=0 caps=0x111 level=-69 freq=5260
    wlan0:    skip - SSID mismatch
    wlan0: 5: c4:13:e2:33:42:24 ssid='Home' wpa_ie_len=0 rsn_ie_len=26 caps=0x1111 level=-69 freq=5260
    wlan0:    skip RSN IE - no mgmt frame protection enabled but AP requires it
    wlan0:    reject due to mismatch with WPA/WPA2
    ...

In this case we are trying to connect to an access point with the SSID home. The reason the connection fails is `skip RSN IE - no mgmt frame protection enabled but AP requires it`, so we need to add `ieee80211w=2` to our configuration file.

### 某些硬體不支持 nl80211 驅動

On some (especially old) hardware, wpa_supplicant may fail with the following error:

    Successfully initialized wpa_supplicant
    nl80211: Driver does not support authentication/association or connect commands
    wlan0: Failed to initialize driver interface

This indicates that the standard `nl80211` driver does not support the given hardware. The deprecated `wext` driver might still support the device:

    # wpa_supplicant -B -i wlan0 -D wext -c /etc/wpa_supplicant/example.conf

If the command works to connect, and the user wishes to use systemd to manage the wireless connection, it is necessary to edit the `wpa_supplicant@.service` unit provided by the package and modify the `ExecStart` line accordingly:

    /etc/systemd/system/wpa_supplicant@.service.d/wext.conf

    [Service]
    ExecStart=
    ExecStart=/usr/bin/wpa_supplicant -c/etc/wpa_supplicant/wpa_supplicant-%I.conf -i%I -Dnl80211,wext

注意：Multiple comma separated driver wrappers in option `-Dnl80211,wext` makes wpa_supplicant use the first driver wrapper that is able to initialize the interface (see wpa_supplicant(8) § EXAMPLES). This is useful when using mutiple or removable (e.g. USB) wireless devices which use different drivers.

### 掛載了網絡共享（CIFS）時的關機問題

When you use wireless to connect to network shares you might have the problem that the shutdown takes a very long time. That is because systemd runs against a 3 minute timeout. The reason is that WPA supplicant is shut down too early, i.e. before systemd tries to unmount the share(s). A bug report suggests a work-around by editing the `wpa_supplicant@.service` as follows:

    /etc/systemd/system/wpa_supplicant.service.d/override.conf

    [Unit]
    After=dbus.service

### 口令相關的問題

wpa_supplicant包 may not work properly if directly passed via stdin particularly long or complex passphrases which include special characters. This may lead to errors such as `failed 4-way WPA handshake, PSK may be wrong` when launching wpa_supplicant包.

In order to solve this try using here strings `wpa_passphrase <MYSSID> <<< "<passphrase>"` or passing a file to the `-c` flag instead:

    # wpa_supplicant -i <interface> -c /etc/wpa_supplicant/example.conf

In some instances it was found that storing the passphrase cleartext in the `psk` key of the `wpa_supplicant.conf` `network` block gave positive results (see [2]). However, this approach is rather insecure. Using `wpa_cli` to create this file instead of manually writing it gives the best results most of the time and therefore is the recommended way to proceed.

### Problems with Eduroam

If the institution the user studies or works at did not upgrade their network tunnel's encryption to at least TLS 1.2 yet and still uses TLS 1.0 or 1.1 for network traffic encryption in their Eduroam Wi-Fi infrastructure, OpenSSL 3.x throws an "unsupported protocol" error and the client machine's Wi-Fi backend (either wpa_supplicant or iwd) refuses to establish a connection any further. Fortunately, an easy workaround exists for OpenSSL's TLS 1.0 and 1.1 deprecation without making the client computer's whole Wi-Fi connection stack globally vulnerable to attacks, although it only works with NetworkManager.

Consult NetworkManager#WPA Enterprise connections fail to authenticate with OpenSSL "unsupported protocol" error for the solution.

Connman users can visit the ConnMan#Connecting to eduroam (802.1X) article for their own version of the fix.

### Connections to pure WPA3-SAE access points

Make sure to define the following within the network block of the configuration to enable connections to pure WPA3 access points:

    ssid="network SSID"
    key_mgmt=SAE
    sae_password="the.literal.wifi.password"
    ieee80211w=2

Additionally, Intel Wi-Fi 6 cards may need `sae_pwe=1` in the main (non network) section of the config file.

### Connections to mixed WPA2-PSK/WPA3-SAE access points

Mixed WPA2-PSK/WPA3-SAE access points will require an alternative setting for key_mgmt as shown below:

    ssid="network SSID"
    key_mgmt=WPA-PSK-SHA256
    psk=xxx
    ieee80211w=2

### Hardware 802.11w support

You can check for hardware support of MFP/PMF (Management Frame Protection / Protected Management Frames) on the interface client by running:

    $ iw phy phy0 info | grep 00-0f-ac:6

Most Wi-Fi devices support this standard introduced in 2009, except some limited (aka non x86_64 related) or old hardware.

## 參閱

- wpa_supplicant 主頁
- wpa_supplicant README - 項目完整文檔，包含了 manpage 未列出的 wpa_cli 命令
- wpa_cli 用例
- wpa_supplicant(8)
- wpa_supplicant.conf(5)
- wpa_cli(8)
- Kernel.org wpa_supplicant 文檔

分類：​

- 無線網絡
- 網絡配置

wpa_supplicant
新增話題