【工具使用】hostapd常用命令及配置

本文最后更新于 5 天前，其中的信息可能已经有所发展或是发生改变。

概述

在hostapd编译完成后，会生成一个hostapd_cli的可执行文件。hostapd_cli是一款用作无线AP功能的客户端程序。它需要与hostapd主程序配置使用，使用hostapd_cli -h命令可以看到支持的命令

pi@pi:~/code/hostapd-2.9/hostapd $ ./hostapd_cli -h
hostapd_cli v2.9
Copyright (c) 2004-2019, Jouni Malinen <j@w1.fi> and contributors

usage: hostapd_cli [-p<path>] [-i<ifname>] [-hvB] [-a<path>] \
                   [-P<pid file>] [-G<ping interval>] [command..]

Options:
   -h           help (show this usage text)
   -v           shown version information
   -p<path>     path to find control sockets (default: /var/run/hostapd)
   -s<dir_path> dir path to open client sockets (default: /var/run/hostapd)
   -a<file>     run in daemon mode executing the action file based on events
                from hostapd
   -B           run a daemon in the background
   -i<ifname>   Interface to listen on (default: first interface found in the
                socket path)

commands:
  ping = pings hostapd
  mib = get MIB variables (dot1x, dot11, radius)
  relog = reload/truncate debug log output file
  status = show interface status info
  sta <addr> = get MIB variables for one station
  all_sta = get MIB variables for all stations
  list_sta = list all stations
  new_sta <addr> = add a new station
  deauthenticate <addr> = deauthenticate a station
  disassociate <addr> = disassociate a station
  sa_query <addr> = send SA Query to a station
  disassoc_imminent = send Disassociation Imminent notification
  ess_disassoc = send ESS Dissassociation Imminent notification
  bss_tm_req = send BSS Transition Management Request
  get_config = show current configuration
  help = show this usage help
  interface [ifname] = show interfaces/select interface
  raw <params..> = send unprocessed command
  level <debug level> = change debug level
  license = show full hostapd_cli license
  quit = exit hostapd_cli
  set <name> <value> = set runtime variables
  get <name> = get runtime info
  set_qos_map_set <arg,arg,...> = set QoS Map set element
  send_qos_map_conf <addr> = send QoS Map Configure frame
  chan_switch <cs_count> <freq> [sec_channel_offset=] [center_freq1=]
    [center_freq2=] [bandwidth=] [blocktx] [ht|vht]
    = initiate channel switch announcement
  hs20_wnm_notif <addr> <url>
    = send WNM-Notification Subscription Remediation Request
  hs20_deauth_req <addr> <code (0/1)> <Re-auth-Delay(sec)> [url]
    = send WNM-Notification imminent deauthentication indication
  vendor <vendor id> <sub command id> [<hex formatted data>]
    = send vendor driver command
  enable = enable hostapd on current interface
  reload = reload configuration for current interface
  disable = disable hostapd on current interface
  update_beacon = update Beacon frame contents
  erp_flush = drop all ERP keys
  log_level [level] = show/change log verbosity level
  pmksa  = show PMKSA cache entries
  pmksa_flush  = flush PMKSA cache
  set_neighbor <addr> <ssid=> <nr=> [lci=] [civic=] [stat]
    = add AP to neighbor database
  remove_neighbor <addr> <ssid=> = remove AP from neighbor database
  req_lci <addr> = send LCI request to a station
  req_range  = send FTM range request
  driver_flags  = show supported driver flags
  accept_acl =Add/Delete/Show/Clear accept MAC ACL
  deny_acl =Add/Delete/Show/Clear deny MAC ACL
  poll_sta <addr> = poll a STA to check connectivity with a QoS null frame
  req_beacon <addr> [req_mode=] <measurement request hexdump>  = send a Beacon report request to a station
  reload_wpa_psk = reload wpa_psk_file only

1. hostapd_cli ping

当你执行hostapd_cli ping命令时，它将向 hostapd 发送一个简单的请求，hostapd会返回一个响应。这个命令主要用于测试hostapd是否正常工作，并检查与hostapd的连接是否通畅

2. hostapd_cli mib

显示MIB(管理信息库)变量，如dot1x/dot11/radius状态信息

3. hostapd_cli relog

relog命令会强制hostapd重新加载其日志配置，通常用于更新或更改日志设置后，确保新的日志配置立即生效，当修改了hostapd配置文件中的日志级别(logger_stdout_leve、logger_syslog_level等) 时，执行hostapd_cli relog命令可以应用这些更改

4. hostapd_cli status

通过status命令，你可以获取hostapd的当前运行状态，查看无线网络接口的配置信息、接入点状态、活动客户端的连接状态等

5. hostapd_cli all_sta

读取ap所有的下挂sta具体信息

6. hostapd_cli sta [sta_MAC]

读取ap的指定mac的下挂sta具体信息

7. hostapd_cli list_sta

列出所有已连接到当前AP的设备MAC地址

8. hostapd_cli new_sta [sta_MAC]

向hostapd的内部状态表中手动添加一个新的STA，多用于调试

9. hostapd_cli deauthenticate [sta_MAC]

hostapd_cli deauthenticate命令通过去认证(deauthentication)操作断开某个客户端与接入点的连接，适用于无线网络管理中需要控制客户端连接的场景

10. hostapd_cli disassociate [sta_MAC]

发送一个断开关联(disassociation)消息到客户端，强制它断开与接入点的连接。与deauthenticate不同，disassociate主要用于因某些原因而使客户端离开无线网络，而不一定是由于身份验证或安全问题

11. hostapd_cli signature [sta_MAC]

signature命令用于获取特定已连接STA的指纹特征字符串。这个字符串基于该设备在连接过程中发送的IEEE 802.11帧(如Probe Request或Association Request)中的信息元素(Information Elements, IEs)生成

12. hostapd_cli WPS相关功能

笔者注：由于无设备验证这里仅列出功能作用，没有运行结果截图

12.1 hostapd_cli wps_pin

在hostapd_cli中，wps_pin命令用于启动 WPS PIN 码认证模式，允许客户端(Enrollee)通过输入特定的 8 位数字 PIN 码连接到无线热点

命令如下：

hostapd_cli wps_pin <UUID|any> <PIN> [timeout] [MAC地址]

参数格式

UUID|any：指定允许连接的客户端UUID
如果不确定设备的UUID，通常使用 any，表示允许任何UUID的设备尝试使用该 PIN 码连接
PIN：设定的8位数字PIN码(例如12345670)
timeout(可选)：该PIN码的有效期(秒)。默认为0(永不过期)，建议设置一个合理的时间(如300秒)以增强安全性
MAC地址(可选)：限定只有该MAC地址的设备才能使用此PIN码连接

12.2 hostapd_cli wps_check_pin [pin]

用于预验证WPS PIN码格式和校验和

12.3 hostapd_cli wps_pbc

wps_pbc命令用于触发WPS按钮配置模式(Push Button Configuration)，这是目前最常用的无线配网方式，模拟了物理路由器上的WPS按钮

12.4 hostapd_cli wps_cancel

wps_cancel命令用于立即终止当前正在进行的WPS流程

12.5 hostapd_cli wps_nfc_tag_read

wps_nfc_tag_tag命令用于通过NFC(近场通信)标签获取的设备数据来授权或配置一个站点

12.6 hostapd_cli wps_nfc_config_token

wps_nfc_config_token命令用于生成一个包含当前无线热点(AP)配置信息的数据包。这个数据包通常会被写入一个NFC标签，让外部设备通过“碰一碰”的方式获取Wi-Fi凭据并自动连接

12.7 hostapd_cli wps_nfc_token

wps_nfc_token命令用于生成一个特定于当前AP的WPS密码令牌(Password Token)与之前的wps_nfc_config_token直接提供Wi-Fi密码不同，这个命令生成的令牌通常用于带外(Out-of-Band, OOB)身份验证流程，提供更高级别的安全性

12.8 hostapd_cli wps_ap_pin

此命令生成一个用于WPS配置的PIN，该PIN可以用于与设备进行配对。当设备支持WPS PIN配置时，可以输入该PIN来完成Wi-Fi网络的连接

12.9 hostapd_cli wps_config

查看WPS配置：通过运行此命令，可以查看当前hostapd配置中的WPS设置，确保接入点支持WPS功能并已正确配置

配置WPS：通过修改hostapd配置文件中的WPS设置，控制接入点如何与客户端进行配对

12.10 hostapd_cli wps_get_status

获取wps的当前状态，开启wps功能未触发时Disabled，wps触发后是Active，超时未连接时是Timed out

13. hostapd_cli disassoc_imminent

命令格式

hostapd_cli disassoc_imminent <MAC地址> <断开倒计时(TU)>

作用

hostapd_cli disassoc_imminent命令用于向某个无线STA发送Disassociation Imminent报文。该命令的作用是通知客户端即将与AP断开连接，并告知它即将失去与接入点的关联。通常，这种命令用于警告客户端准备断开连接

14. hostapd_cli ess_disassoc

命令格式

hostapd_cli ess_disassoc <MAC地址> <断开倒计时(秒)> <URL>

作用

ess_disassoc是802.11u协议中的一个高级命令。它用于通知客户端：“你将被断开连接，请访问以下URL以了解原因或处理账号问题(如欠费、服务条款更新等)”

15. hostapd_cli bss_tm_req

hostapd_cli bss_tm_req命令用于向无线客户端发送BSS过渡管理请求，要求设备切换到其他接入点。它通常用于网络负载均衡、无缝漫游和优化无线覆盖等场景。通过合理配置和使用此命令，管理员可以优化无线网络的性能和客户端设备的连接质量

16. hostapd_cli get_config

hostapd_cli get_config命令能查看当前hostapd的配置内容。通过该命令，可以轻松获取无线网络设置、加密方式、连接数等信息，帮助在调试、管理和优化无线网络时，获得关键的配置信息

17. hostapd_cli interface

interface命令的主要功能是显示当前hostapd*配置的所有接口

18. hostapd_cli raw

开发者调试新加的hostapd控制命令

脚本中发送动态命令
测试hostapd的响应行为
执行不常用、版本特有的命

19. hostapd_cli level

hostapd_cli level命令用于设置或查询hostapd日志记录的日志级别。该命令允许您控制hostapd打印的日志信息的详细程度。日志级别的设置会影响到输出到控制台、日志文件以及系统日志中的信息

20. hostapd_cli license

hostapd_cli license命令的意义在于向用户展示hostapd(Host Access Point Daemon)的许可信息。hostapd是一个开源项目，用于在Linux系统上创建和管理无线接入点。通过hostapd_cli license命令，用户可以查看hostapd的许可证信息，以确保他们遵循相应的开源许可协议

21. hostapd_cli quit

quit是一个最基础的控制命令，用于退出交互模式

22. hostapd_cli set

hostapd_cli set命令用于设置hostapd的某些配置参数。通过这个命令，您可以动态地修改运行中的hostapd配置，而不必重新启动hostapd服务。可以修改的配置项包括SSID、加密方式、信道等

23. hostapd_cli get

hostapd_cli get命令用于查询当前hostapd配置中的参数值。它允许您查看某些配置项的当前状态或值

24. hostapd_cli set_qos_map_set

命令格式

hostapd_cli set_qos_map_set <DSCP范围及映射值,用逗号分隔>

hostapd_cli set_qos_map_set命令用于设置QoS(Quality of Service)映射规则。QoS用于在网络中优先传输某些类型的流量，特别是对于实时应用，如视频和语音通话。这个命令用于设置QoS映射规则，将不同的服务类映射到不同的优先级

25. hostapd_cli send_qos_map_conf

hostapd_cli send_qos_map_conf命令用于将之前通过set_qos_map_set设置的QoS映射规则应用到无线网络。这个命令是一个触发命令，用于通知hostapd向无线客户端广播QoS映射规则

26. hostapd_cli chan_switch

hostapd_cli chan_switch命令用于hostapd中手动触发无线AP切换频道的操作

27. hostapd_cli hs20_wnm_notif

命令格式

hostapd_cli hs20_wnm_notif <MAC地址> <URL>

参数格式

MAC地址：接收该通知的特定已连接STA的MAC地址
URL：通知中携带的统一资源定位符(URL)

命令作用

命令作用该命令用于向指定的客户端发送WNM-Notification消息，特别用于Hotspot 2.0(HS2.0)功能

28. hostapd_cli hs20_deauth_req

命令格式

hostapd_cli hs20_deauth_req <MAC地址> <代码> <重新关联延迟(秒)> [URL]

参数格式

MAC地址：目标设备的 MAC 地址。
代码：表示断开原因的整数。
0: 保留。
1: 账户限制(如时长用尽)
2: 需要重新认证(服务条款更新)
重新关联延迟：以秒为单位，告诉客户端在这个时间内不要尝试重新连接此AP
URL(可选)：引导用户处理问题的地址(如充值页面)

命令作用

该命令用于发送Deauthentication Request(去认证请求)消息。该请求是Hotspot 2.0(HS2.0)相关功能的一部分，用于强制客户端断开连接

29. hostapd_cli vendor

命令格式

hostapd_cli vendor <vendor_id> <subcmd_id> [十六进制数据参数]

参数格式

vendor_id：厂商的OUI(组织唯一标识符)，通常是一个24位的十六进制数(例如Intel为0x001735，Realtek为0x00e04c)
subcmd_id：厂商自定义的子命令ID
十六进制数据：随命令发送的特定二进制负载(Payload)

命令作用

vendor命令是一个用于向底层无线驱动程序发送厂商自定义命令(Vendor-Specific Commands)的高级调试接口。它是hostapd与 Linux 内核nl80211驱动框架之间的一个透传通道，允许开发者在不修改hostapd源码的情况下，直接调用网卡驱动特有的私有功能

30. hostapd_cli enable

hostapd_cli enable命令的作用是启用hostapd配置的无线接入点。通过该命令，可以启用或激活hostapd服务，从而让无线接入点开始广播并为客户端提供连接服务

31. hostapd_cli reload

hostapd_cli reload命令用于重新加载hostapd配置文件，而不需要停止hostapd服务。这允许hostapd应用新的配置而不中断当前的无线服务。此命令通常在修改了hostapd配置文件(如hostapd.conf)后使用，可以让配置生效

32. hostapd_cli disable

hostapd_cli disable命令用于禁用hostapd服务，即关闭无线网络的广播和服务。执行该命令后，AP将不再提供无线网络连接，设备也无法连接到该AP

33. hostapd_cli update_beacon

hostapd_cli update_beacon命令用于更新当前hostapd AP广播的beacon帧。具体来说，该命令强制hostapd重新生成和发送beacon帧，以便更新其广播的信息，通常用于修改无线网络配置后，立即更新AP的广播信息

34.hostapd_cli erp_flush

hostapd_cli erp_flush命令的作用是刷新Extended Rate Physical (ERP)相关的缓存或表项。具体来说，它会清除hostapd中与ERP相关的缓存信息，这些信息可能会影响到无线网络的性能或者接入点的配置

35. hostapd_cli log_level

获取当前的日志等级

36. hostapd_cli pmksa

hostapd_cli pmksa命令主要用于管理PMKSA缓存条目，提供查看、添加和删除缓存条目的功能，帮助hostapd进行高效的设备认证

37. hostapd_cli pmksa_flush

hostapd_cli pmksa_flush命令的作用是清空PMKSA缓存，即删除所有存储的PMKSA(Pairwise Master Key Security Association)条目

38. hostapd_cli set_neighbor

命令格式

hostapd_cli set_neighbor <bssid> <ssid> <nr> [lci] [civic]

参数格式

bssid ：邻居AP的MAC地址(格式如aa:bb:cc:dd:ee:ff)
ssid： 邻居AP的SSID(需用十六进制表示，例如"MyWiFi"→4d7957694669)
nr：Neighbor Report元素的十六进制编码(包含BSSID、频段、信道、能力等)
lci(可选)：Location Configuration Information(LCI)，十六进制格式
civic(可选)：Civic Location，十六进制格式

这个命令用于向邻居数据库中添加一个邻居AP。通过set_neighbor命令，您可以将另一个AP添加到当前AP的邻居列表中，并提供一些额外的信息，如AP的SSID、信道、位置等

39. hostapd_cli remove_neighbor

命令格式

hostapd_cli remove_neighbor <BSSID>

参数格式

BSSID：要删除的邻居AP的MAC地址，格式为aa:bb:cc:dd:ee:ff(支持带冒号或不带冒号，但推荐使用标准冒号格式)

该命令用于从邻居数据库中移除一个邻居AP。使用此命令可以删除一个已经记录的邻居AP，通常用于动态更新邻居列表，或者当AP不再可用时，及时移除不必要的邻居

40. hostapd_cli req_lci

req_lci是一个命令，用于触发LCI(Location Channel Information)测量请求，符合IEEE 802.11v标准。这个命令允许AP向STA请求其位置通道信息(LCI)，这对于进行无线电测量和位置管理至关重要

41. hostapd_cli req_range

请求信号范围测量：req_range允许AP向STA请求其信号范围或网络环境信息，这对于评估客户端与AP之间的连接质量非常有用
增强网络管理与优化：通过收集STA信号质量数据，AP可以优化漫游决策，帮助STA在多个接入点之间选择最佳信号。在大规模无线网络中，req_range命令可以帮助管理员评估网络的覆盖范围和信号强度。
IEEE 802.11k测量支持：802.11k标准定义了多种测量请求和报告类型，而req_range是其中之一。它用于网络质量的动态评估，帮助BSS(基本服务集)中的设备更好地管理无线资源

42. hostapd_cli driver_flags

查询驱动程序的当前标志：driver_flags命令可以用来查看当前无线驱动程序的标志。例如，它可能会显示是否支持某些特性(如WPS、STA、AP模式等)

43. hostapd_cli accept_acl

accept_acl命令用于动态管理接入控制列表(ACL)，即实时控制哪些MAC地址被允许(Accept)或禁止(Deny)连接到热点，该命令的具体用法取决于你想要执行的操作(添加、删除、查看或刷新)。

添加MAC地址到允许列表：

  hostapd_cli accept_acl ADD_ACL <MAC地址>

从允许列表中删除MAC地址：

  hostapd_cli accept_acl DEL_ACL <MAC地址>

显示当前允许列表中的所有MAC：

  hostapd_cli accept_acl SHOW

清空整个允许列表：

  hostapd_cli accept_acl CLEAR

44. hostapd_cli deny_acl

deny_acl命令与accept_acl相对，用于动态管理黑名单(禁止接入列表)。通过此命令，你可以实时禁止特定的MAC地址连接到你的无线热点，或者将已经连接的可疑设备强制断开并列入黑名单，而无需重启hostapd服务

根据 2025 年hostapd的标准控制接口协议，其子命令格式如下：

添加设备到黑名单：

  hostapd_cli deny_acl ADD_ACL <MAC地址>

从黑名单中移除设备：

  hostapd_cli deny_acl DEL_ACL <MAC地址>

查看当前黑名单列表：

  hostapd_cli deny_acl SHOW

清空整个黑名单：

  hostapd_cli deny_acl CLEAR

45. hostapd_cli poll_sta

hostapd_cli poll_sta命令用于轮询指定的客户端设备，并获取该设备的状态信息或进行相关的操作。通常，poll_sta是用来检查某个设备(STA)是否仍然连接到AP并获取其状态信息

46. hostapd_cli req_beacon

触发客户端扫描周围的AP(邻居)并报告扫描结果回AP
用于无线网络漫游优化(如BSS Transition Management)
辅助AP了解STA周边的无线环境(包括信号强度、信道使用等)

47. hostapd_cli reload_wpa_psk

hostapd_cli reload_wpa_psk命令用于重新加载WPA PSK(Pre-shared Key，预共享密钥)配置。它的作用是使Hostapd重新加载或更新与WPA相关的密钥配置。这通常用于在运行时动态更新或修改WPA密钥，而无需重新启动Hostapd服务

参考文档

hostapd-2.9源码

【hostapd_cli 命令全集】-CSDN博客