Salt iwtools 执行模块实战:用 salt 命令批量管理 Linux 无线网络接口
Salt iwtools 执行模块实战:用 salt 命令批量管理 Linux 无线网络接口
本指南围绕 Salt 开源仓库中的 salt.modules.iwtools 执行模块(Execution Module)展开,介绍如何通过 salt 命令在受管 minion 上扫描无线网络、切换无线接口工作模式、枚举本机无线接口。读者读完本文后,可以掌握 iwtools.scan、iwtools.set_mode、iwtools.list_interfaces 三个函数的完整用法、输出结构与底层调用原理,并能将其纳入自己的无线网络运维状态编排中。
模块定位:基于 wireless-tools 的无线接口管理
iwtools 是 Salt 在 Linux 平台上提供的一组无线网络工具执行模块,源码位于 salt/modules/iwtools.py。它的名字来源于 Linux 下经典的 wireless-tools 软件包——该软件包提供的 iwconfig 与 iwlist 命令行工具,是模块所有能力的底层支撑。
模块公开了三个可被 minion 调用的函数:
| 函数 | 作用 | 典型场景 |
|---|---|---|
scan(iface, style=None) |
扫描指定无线接口附近可连接的网络 | 无线网络勘察、自动选网 |
set_mode(iface, mode) |
设置无线接口的工作模式 | 切换 Managed / Monitor 等模式 |
list_interfaces(style=None) |
列出本机所有无线接口 | 批量巡检前先获取接口清单 |
加载机制:只有安装了 iwconfig 才会被加载
执行模块的加载由 __virtual__() 函数控制(salt/modules/iwtools.py):
def __virtual__():
if salt.utils.path.which("iwconfig"):
return True
return (
False,
"The iwtools execution module cannot be loaded: iwconfig is not installed.",
)
也就是说,只有当 minion 系统 PATH 中能找到 iwconfig 可执行文件时,模块才会注册为 iwtools.* 函数;否则加载器会跳过该模块,并记录提示信息 "The iwtools execution module cannot be loaded: iwconfig is not installed."。这里的可执行文件探测复用了 salt/utils/path.py 的 which() 工具函数,在 Linux 发行版上需要先安装 wireless-tools(Debian/Ubuntu 为 apt install wireless-tools,RHEL/CentOS 为 yum install wireless-tools)。该模块面向 Linux 平台,在无无线网卡的机器上即使加载成功,实际调用也会失败。
扫描无线网络:iwtools.scan
scan 函数对指定无线接口执行扫描,返回结构化字典。命令形式为:
salt minion iwtools.scan wlp3s0 # 返回完整结构化结果
salt minion iwtools.scan wlp3s0 list # 只返回网络 BSSID(Address)列表
执行流程
从 salt/modules/iwtools.py 的源码看,其执行链路为:
- 调用内部辅助函数
_valid_iface()校验接口是否存在于本机接口列表中,非法接口直接抛出SaltInvocationError(来自 salt/exceptions.py); - 通过
__salt__"cmd.run"执行系统命令; - 若输出中出现
Network is down,说明接口处于 down 状态,模块会自动先执行ip link set {iface} up拉起接口,再重新扫描——这是扫描失败时的一次自动恢复尝试; - 逐行解析
iwlist输出,按Cell块切分每个接入点,将Address、ESSID、Channel、Frequency、Quality、Encryption key等信息解析为键值对;其中IE(信息元素)字段会被收集成列表,Address前的引号会被剥离(因为合法 SSID 中也可能包含引号字符,而 iwlist 习惯用引号包裹 SSID); - 返回以 BSSID(Address)为键的嵌套字典;
style="list"时仅返回所有 BSSID 的键列表。
返回结构示例
minion:
----------
00:11:22:33:44:55:
----------
Address: 00:11:22:33:44:55
Channel: 6
ESSID: MyHomeWiFi
Encryption key: on
Frequency: 2.437 GHz
IE:
- IEEE 802.11i/WPA2 Version 1
- ...
Mode: Master
Quality: 48/70
借助该结构,可以进一步用 salt.state 或 reactor 事件做自动化选网,例如在 state 中对扫描结果做条件判断。
设置无线接口模式:iwtools.set_mode
set_mode 用于修改无线接口的工作模式:
salt minion iwtools.set_mode wlp3s0 Managed
salt minion iwtools.set_mode wlp3s0 Monitor
合法的模式取值
源码中通过 valid_modes 元组白名单做了强校验(salt/modules/iwtools.py),仅接受以下七种取值,其余值一律抛出 SaltInvocationError,并提示合法模式列表:
Managed:普通客户端模式(连接 AP 上网)Ad-Hoc:点对点自组网Master:作为无线接入点Repeater:中继模式Secondary:备份接入点Monitor:监听模式(常用于抓包、渗透测试)Auto:自动协商
执行流程
- 校验接口有效性;
- 校验 mode 是否在合法白名单内;
- 调用
__salt__"ip.down"先将接口置为 down——修改无线模式通常要求接口处于关闭状态; - 执行
iwconfig {iface} mode {mode}完成模式切换; - 调用
__salt__"ip.up"重新拉起接口; - 返回设置后的模式字符串。
这里依赖的 ip.down / ip.up 是 Salt 的 ip 执行模块(在 salt/modules/linux_ip.py 与 salt/modules/linux_ip.py 中实现),也就是说 iwtools 内部复用了 Salt 自带的网络接口启停能力,而不是直接拼写系统命令。这套"先 down、改配置、再 up"的模式切换序列,也正是 Linux 下修改无线模式的标准操作流程,模块替你封装好了,避免在批量 minion 上重复手写。
列出无线接口:iwtools.list_interfaces
list_interfaces 用于枚举本机所有具备无线扩展能力的接口:
salt minion iwtools.list_interfaces
salt minion iwtools.list_interfaces list # 只返回接口名列表
解析逻辑
函数执行 iwconfig 并逐行解析(salt/modules/iwtools.py):
- 跳过空行与包含
no wireless extensions的行(这类行属于没有无线扩展的普通网卡); - 顶格的行(不以空格开头)被识别为新接口的开始,之前的接口结果先存入返回字典;
- 每行按
:与=拆分出键值对,如ESSID、Mode、Frequency、Access Point等;ESSID值的引号同样会被剥离; - 无法按键值对解析的碎片文本归入
extra列表,避免丢信息; - 最终返回以接口名为键的字典;
style="list"时只返回接口名列表。
返回结构示例:
minion:
----------
wlp3s0:
----------
Access Point: 00:11:22:33:44:55
ESSID: MyHomeWiFi
Frequency: 2.437 GHz
Mode: Managed
extra:
- ...
底层依赖与调用链小结
iwtools 模块本身不直接做网络编程,而是以"命令封装 + 文本解析"的方式工作,其完整调用链可以归纳为:
- 外部命令依赖:
iwconfig(接口信息与模式设置)、iwlist(无线扫描)、ip(接口启停),三者均为 Linux 无线/网络管理的基础工具; - Salt 内部依赖:
__salt__["cmd.run"]执行外部命令、__salt__["ip.down"/"ip.up"]启停接口、salt.utils.path.which做可执行文件探测、SaltInvocationError做参数异常上报; - 错误恢复逻辑:扫描时若发现接口 down,自动拉起后重试,减少人工介入。
从源码结构看,scan 返回的字典以 BSSID 为主键、list_interfaces 以接口名为主键,二者数据结构都便于在 Jinja 模板或 state 条件判断中直接遍历。若要在批量机器上做无线巡检,常见的组合用法是:先用 iwtools.list_interfaces list 拿到接口清单,再对每个接口执行 iwtools.scan,最后将结果回传到 master 的 job cache 中存档。
使用前提与限制
- 平台限制:模块面向 Linux,且要求安装 wireless-tools;macOS/Windows minion 无法加载该模块;
- 权限要求:
iwconfig、iwlist、ip link set等操作通常需要 root 权限,minion 进程需以 root 或具备相应 capability 的用户运行; - 命令输出依赖:模块解析的是
iwlist/iwconfig的传统文本格式,若系统同时安装了新版iw(nl80211 工具),解析仍以 wireless-tools 输出为准,因此保持 wireless-tools 安装完整是前提; - 校验是强制的:所有函数都会先校验接口是否真实存在,参数不合法时统一抛出
SaltInvocationError,便于在 state 中通过result: false快速定位问题。
该模块自 Salt 2016.3.0 版本起随发行版提供(见 doc/topics/releases/2016.3.0.rst 的模块清单),其 API 文档亦被收录在 doc/ref/modules/all/index.rst 的模块索引中。对无线网络运维感兴趣的同学,可以直接阅读 salt/modules/iwtools.py 的完整实现,或参考 salt/modules/linux_ip.py 理解其依赖的接口启停实现。