Salt iwtools 执行模块实战:用 salt 命令批量管理 Linux 无线网络接口

原创2026-09-22 16:54:111,955 阅读
文章标签:后端运维配置管理工作流自动化

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 的源码看,其执行链路为:

  1. 调用内部辅助函数 _valid_iface() 校验接口是否存在于本机接口列表中,非法接口直接抛出 SaltInvocationError(来自 salt/exceptions.py);
  2. 通过 __salt__"cmd.run" 执行系统命令;
  3. 若输出中出现 Network is down,说明接口处于 down 状态,模块会自动先执行 ip link set {iface} up 拉起接口,再重新扫描——这是扫描失败时的一次自动恢复尝试;
  4. 逐行解析 iwlist 输出,按 Cell 块切分每个接入点,将 Address、ESSID、Channel、Frequency、Quality、Encryption key 等信息解析为键值对;其中 IE(信息元素)字段会被收集成列表,Address 前的引号会被剥离(因为合法 SSID 中也可能包含引号字符,而 iwlist 习惯用引号包裹 SSID);
  5. 返回以 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:自动协商

执行流程

  1. 校验接口有效性;
  2. 校验 mode 是否在合法白名单内;
  3. 调用 __salt__"ip.down" 先将接口置为 down——修改无线模式通常要求接口处于关闭状态;
  4. 执行 iwconfig {iface} mode {mode} 完成模式切换;
  5. 调用 __salt__"ip.up" 重新拉起接口;
  6. 返回设置后的模式字符串。

这里依赖的 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 理解其依赖的接口启停实现。

登录后查看全文
salt