PacketFence 有线 MAC 认证(MAB)端到端测试指南:wired_mac_auth Venom 测试套件全解析
PacketFence 有线 MAC 认证(MAB)端到端测试指南:wired_mac_auth Venom 测试套件全解析
本文以 PacketFence 仓库中 wired_mac_auth 测试套件文档 为核心,系统讲解如何在真实拓扑(PacketFence 服务器 + Cumulus 交换机 + 客户端节点)上,通过 Venom 集成测试框架验证有线 MAC 认证(MAC Authentication Bypass,MAB)的完整链路:从节点注册、连接配置文件(Connection Profile)匹配、RADIUS 认证请求、动态 VLAN 下发,到断开(Disconnect)与节点清理的收尾流程。读者读完本文后,将掌握该测试套件的环境前提、场景步骤、清理(Teardown)流程、关键变量定义,以及底层 node_cleanup 维护任务的源码实现原理,可直接复现或改造这套测试。
一、测试套件定位:用真实 RADIUS 流量验证有线 MAB
wired_mac_auth 是 PacketFence 仓库 t/venom/test_suites/ 下的一个端到端集成测试套件。它不属于单元测试(t/unittest/),而是运行在由 Vagrant 拉起的一整套真实虚拟机上,通过真实网络设备行为验证核心 NAC 功能。
该套件的核心目标正如其文档开篇所写:
Register a node with RADIUS in order to test MAC Authentication on Wired
即在有线场景下,先用 RADIUS 注册一个节点(node),再验证该节点通过 MAC 认证(而非 802.1X EAP 认证)接入网络时,PacketFence 能正确完成"识别 MAC → 匹配角色 → 下发动态 VLAN → 允许访问互联网"的完整流程。
从测试拓扑看,该套件依赖 4 类虚拟机:PacketFence 服务器、作为 RADIUS NAS 的 Cumulus 交换机(switch01)、有线客户端节点(node01)以及无线节点(wireless01)。这与后来引入的 wired_mac_auth_virtualswitch 套件(单台 PF 虚拟机内用 namespace 模式的虚拟交换机模拟)形成对照——前者使用真实 Cumulus NCLU REST API,后者使用模拟的 Cisco 交换机 REST API。
二、环境前提(Requirements)
2.1 全局配置步骤
套件文档明确了两项必须先完成的全局配置(通常由前置的 global_config 套件完成):
- 创建
headless_device角色:这是无头设备(如打印机、传感器等无法交互式认证的终端)使用的角色。在测试变量中,该角色 ID 为headless_device,其 VLAN ID 为 100(见 t/venom/vars/all.yml)。 - 创建交换机与交换机分组,并配置角色映射(role mapping):交换机(switch01,Cumulus VX)必须注册到 PacketFence,并配置"MAC 地址 / 角色 → VLAN"的映射关系,这样认证通过后 PacketFence 才能通过 RADIUS Access-Accept 报文把
Tunnel-Private-Group-Id(目标 VLAN)下发给交换机。
这些步骤由同目录下的 global_config 测试套件负责落地,其相关实现见 t/venom/test_suites/global_config/。
2.2 拓扑与关键测试变量
套件运行所需的全部变量集中在 t/venom/vars/all.yml,与 wired_mac_auth 直接相关的关键变量如下:
| 变量 | 值 | 含义 |
|---|---|---|
node01_ens7_mac_address |
00:03:00:11:11:01 |
node01 的 ens7 网卡 MAC,即被测试的节点身份 |
node01_ens7_mac_address_url_encoded |
00%3A03%3A00%3A11%3A11%3A01 |
上述 MAC 的 URL 编码形式,用于 REST API 路径 |
node_cleanup.delete_window.interval / .unit |
1 / m |
node_cleanup 任务的删除窗口(1 分钟) |
wired_mac_auth.roles.headless_device.id |
headless_device |
测试用角色名 |
wired_mac_auth.roles.headless_device.vlan_id |
100 |
该角色对应的动态 VLAN |
wired_mac_auth.profiles.wired.id |
catch_wired_mac_authentication |
测试用连接配置文件 ID |
wired_mac_auth.profiles.wired.filters.connection_type |
Ethernet-NoEAP |
配置文件匹配的连接类型过滤条件 |
wired_mac_auth.profiles.wired.unreg_on_acct_stop |
disabled |
收到 RADIUS Accounting Stop 时是否注销节点 |
switch01.dot1x_interface.id |
swp12 |
switch01 上启用 MAB 的接口 |
switch01.api.url / user / password |
https://{switch01_mgmt_ip}:8080 / cumulus / CumulusLinux! |
Cumulus NCLU REST API 凭据 |
其中 node_cleanup 的删除窗口在测试中特意被调成 1 分钟,目的是让清理阶段的节点删除测试能在可接受的时间内完成(详见第三节与第五节)。
三、场景步骤(Scenario steps)逐层拆解
场景步骤按序号排列为一组 YAML 文件(00_、02_、05_…),venom-wrapper.sh 会按文件名字母序依次执行目录内所有 *.yml。整个正流程可划分为:基础设施准备 → 实体创建 → 交换机配置触发认证 → 结果验证 四个阶段。
3.1 阶段一:基础设施准备(00–02)
00_enable_node_cleanup_task.yml 通过 WebAdmin API 连续两次 PATCH /api/v1/config/maintenance_task/node_cleanup:
- 将维护任务状态置为
enabled(HTTP 200 断言); - 将
delete_window设置为变量中定义的1m(1 分钟)。
该 API 由 lib/pf/UnifiedApi/Controller/Config/MaintenanceTasks.pm 提供,底层持久化到 pfcron.conf 的 [node_cleanup] 段。
02_restart_pfcron_service.yml 通过自定义测试步骤类型 pf_api_service_restart_async 异步重启 pfcron 服务。文档明确强调这一步的必要性:修改维护任务配置后必须重启 pfcron 才能生效——因为 pfcron 在启动时加载任务调度配置,delete_window 的改变只有在服务重启后才被任务实例读取。
源码印证:
node_cleanup任务的调度实现见 lib/pf/pfcron/task/node_cleanup.pm,其delete_window属性类型为PfInterval(自动从"1m"这类字符串强转为间隔对象),run()方法直接调用pf::node::node_cleanup($self->delete_window, $self->unreg_window, $self->voip, $self->batch, $self->timeout)。任务默认配置见 conf/pfcron.conf.defaults:默认status=disabled、delete_window=0D、schedule=@every 1m、batch=100、timeout=10s。测试正是把默认禁用、0 天的配置改成了启用 + 1 分钟窗口。
3.2 阶段二:实体创建(05–10)
05_create_node01.yml 创建被测节点,分两步:
POST /api/v1/node_categories/search按角色名headless_device查出其category_id;POST /api/v1/nodes创建节点,请求体关键字段:
{
"category_id": "{{.get_category_id_of_role.category_id}}",
"mac": "{{.node01_ens7_mac_address}}",
"notes": "node01 ens7",
"pid": null,
"status": "reg",
"unreg_date": null,
"unregdate": null
}
注意与文档要求的对应关系:MAC 为 node01 的 ens7 网卡地址 00:03:00:11:11:01、角色为 headless_device、不设置 unreg date(unreg_date/unregdate 均为 null)、添加备注(notes: "node01 ens7"),创建成功后断言 HTTP 201。
10_create_connection_profile.yml 创建连接配置文件(POST /api/v1/config/connection_profiles)。该配置的核心是让 PacketFence 识别"有线 MAC 认证"这类流量,关键字段如下:
filter:[{"match": "Ethernet-NoEAP", "type": "connection_type"}]——只有连接类型为Ethernet-NoEAP(有线、无 EAP)的请求才匹配本配置文件;filter_match_style: "all"——所有过滤条件需全部满足;dot1x_recompute_role_from_portal: "enabled"、mac_auth_recompute_role_from_portal: "disabled"——MAC 认证场景不依赖门户重算角色;unreg_on_acct_stop: "disabled"——收到 Accounting Stop 不自动注销(保证节点在测试期间保持注册态);status: "enabled"、root_module: "default_policy"。
这些字段与 conf/profiles.conf.defaults 中的连接配置文件默认项一一对应(如 dot1x_recompute_role_from_portal=enabled、reuse_dot1x_credentials=0 等)。
3.3 阶段三:交换机配置与认证触发(15–20)
该阶段通过 Cumulus NCLU REST API(POST {switch01.api.url}/nclu/v1/rpc,Basic Auth)向 switch01 下发配置:
- 15_enable_mac_auth_dot1x_int.yml:执行
add interface {{.switch01.dot1x_interface.id}} dot1x mab,在接口swp12上启用 MAC 认证旁路(MAB)。这正是文档中"Configure MAC authentication ... on dot1x interface on switch01: will trigger a RADIUS request"的落地——启用 MAB 后,交换机会把该接口上首次出现的源 MAC 封装成 RADIUS Access-Request 发送给 PacketFence。 - 17_enable_dynamic_vlan.yml:执行
add dot1x dynamic-vlan,启用动态 VLAN 下发,使交换机接受 RADIUS Access-Accept 中携带的Tunnel-Private-Group-Id。 - 20_commit_config.yml:执行
commit使 NCLU 配置生效,随后sleep 15秒等待配置稳定。
文档强调此后的等待策略:等待 mab_activation_delay + 20 秒,让交换机发出 RADIUS 请求并由 PacketFence 处理,同时给交换机留出处理应答的时间。(mab_activation_delay 是 PacketFence 在启用 MAB 认证时使用的延迟参数,测试通过 25/35/40 号测试的轮询与重试机制覆盖这段等待。)
3.4 阶段四:结果验证(25–40)
25_check_radius_audit_log.yml 验证 RADIUS 审计日志,分三步:
- 先调用自定义步骤
pfcron_flush_radius_audit_log,把暂存在 Redis 中的审计日志刷入数据库(radius_audit_log表结构见 db/radius_audit_log.sql); POST /api/v1/radius_audit_logs/search按三个条件查询:mac等于00:03:00:11:11:01、auth_status等于Accept、connection_type等于Ethernet-NoEAP,并按created_at DESC取最新一条。这里特意加了retry: 35、delay: 3的轮询机制——RADIUS 请求是异步到达的,需要给足等待时间;GET /api/v1/radius_audit_log/{id}断言 RADIUS 应答内容:radius_reply必须包含Tunnel-Private-Group-Id = "100"(即 headless_device 角色对应的动态 VLAN),且profile等于catch_wired_mac_authentication。
这一步是整套测试的核心断言:它证明 PacketFence 不仅接受了 MAB 认证,还把正确的动态 VLAN 写进了 Access-Accept 应答。
35_check_mac_auth_int_status.yml 通过 NCLU 命令 show dot1x interface {{.switch01.dot1x_interface.id}} json 检查 switch01 上接口状态,断言响应中包含:
MAB(接口启用 MAB 认证方式);AUTHORIZED(客户端已被授权);- headless_device 的 VLAN ID
100(接口被动态 VLAN 100 接管)。
文件注释特意说明"we didn't check MAC address on port to make this testcase reusable"——即不校验端口上的具体 MAC,以便该用例可复用于其他测试套件。
40_check_internet_access.yml 通过自定义步骤 check_internet_access_on_host 在 node01 上验证其能正常访问互联网,作为端到端连通性的最终确认。
四、Teardown 清理流程:如何优雅地还原环境
清理阶段同样按序号文件执行(目录 teardown/,Venom 按字母序自动执行)。与正向流程相反,它承担"注销节点 → 关闭交换机功能 → 删除节点 → 还原维护任务 → 删除配置文件"的职责,确保测试可重复运行、不留脏数据。
4.1 注销节点并规避 Disconnect-NAK(00–02)
00_unreg_node01.yml 通过 PATCH /api/v1/node/{mac} 将节点状态改为 unreg。这一步会触发 PacketFence 向交换机生成 Disconnect 报文(RFC 3576 CoA-Request/Disconnect-Request)。
02_sleep_some_time.yml 执行 sleep 15。文档中的"Wait some time before unconfigure switch01 to avoid a Disconnect-NAK"正是对应这一步——如果注销后立刻撤销交换机上的 MAB 配置,交换机可能还在等待/处理 Disconnect 会话,导致返回 Disconnect-NAK,测试验证逻辑被打乱。
4.2 撤销交换机配置(05–10)
- 05_disable_mac_auth_dot1x_int.yml:
del interface swp12 dot1x mab; - 07_disable_dynamic_vlan.yml:
del dot1x dynamic-vlan; - 10_commit_config.yml:
commit使撤销生效。
4.3 等待删除窗口并执行 node_cleanup(12–20)
12_sleep_delete_windows.yml 执行 sleep {{.node_cleanup.delete_window.interval}}{{.node_cleanup.delete_window.unit}} 10(即 sleep 1m 10,1 分钟加 10 秒),对应文档"Wait delete_windows + 10 seconds before running node_cleanup task"。之所以要多等 10 秒,是确保节点满足"超过 delete_window 未被看到"的删除条件。
15_delete_node01_with_pfcron_node_cleanup.yml 通过 CLI 手动触发维护任务:
/usr/local/pf/bin/pfcmd pfcron node_cleanup
这是文档"Delete node by running pfcron's node_cleanup task"的实际命令。pfcmd pfcron 子命令的说明见 lib/pf/cmd/pf/pfcron.pm。
源码印证:
pf::node::node_cleanup(lib/pf/node.pm)的核心逻辑是:当delete_time ne "0"时,循环调用node_expire_lastseen($delete_time, $batch)找出超过删除窗口未活动的节点,跳过 VoIP 节点(若voip未禁用),然后对每个节点先调用pf::locationlog::locationlog_update_end_mac($mac)结束其位置记录,再调用node_delete($mac)删除节点。整个循环受time_limit约束,防止任务超时失控。删除窗口 1 分钟的设定正是为了让"过期删除"在测试时间预算内可被验证。
20_check_node01_deleted.yml 用 GET /api/v1/node/{mac} 验证节点已被删除,断言 HTTP 404 且返回消息为 Unable to get resource with this identifier——这是 PacketFence REST API 对不存在资源的标准响应。
4.4 还原全局状态(25–30)
- 25_disable_node_cleanup_task.yml:再次
PATCH /api/v1/config/maintenance_task/node_cleanup,把status置为disabled,并把delete_window还原为0D(interval: 0, unit: D),避免测试残留影响后续环境; - 27_restart_pfcron_service.yml:重启
pfcron使配置还原生效; - 30_delete_connection_profile.yml:
DELETE /api/v1/config/connection_profile/catch_wired_mac_authentication删除测试用的连接配置文件。
五、执行方式与套件集成
该套件不是单独运行的,而是被编排进 Ansible 场景 playbook。在 t/venom/scenarios/mac_auth/playbooks/run_tests.yml 中定义了完整的测试序列:
test_suites:
- configurator
- global_config
- wired_mac_auth
- wired_mac_auth/teardown
- wireless_mac_auth
- wireless_mac_auth/teardown
- global_teardown
每个套件通过 venom-wrapper.sh 执行:
{{ venom_dir }}/venom-wrapper.sh {{ venom_dir }}/test_suites/{{ item }}
执行机制方面:t/venom/venom-wrapper.sh 会对传入的目录按字母序收集其中所有 *.yml 文件(find ... -name "*.yml" | sort),再调用 venom run 一并执行;每个套件使用独立的 --output-dir 存放结果(VENOM_COMMON_FLAGS='--output-dir={{ venom_dir }}/results/{{ item }}'),避免多个套件互相覆盖日志与结果。更宏观的测试编排(Vagrant 起虚拟机、Ansible 配置、结果收集与销毁)由 t/venom/test-wrapper.sh 承载。
六、与 virtualswitch 变体的对比
仓库中还存在一个同主题变体套件 wired_mac_auth_virtualswitch,其文档直接列出了与 wired_mac_auth 的差异,便于读者理解本套件在测试体系中的定位:
| 方面 | wired_mac_auth(本文) | wired_mac_auth_virtualswitch |
|---|---|---|
| 所需虚拟机 | PF + switch01 + node01 + wireless01 | 仅 PF 一台 |
| 交换机类型 | Cumulus VX(NCLU REST API) | Cisco 15.5(模拟,REST API) |
| 设备模拟方式 | 真实 node01 虚拟机 | VirtualSwitch API 插拔设备 |
| 附加能力 | 无 | 可叠加 Fingerbank 打印机识别测试 |
两者共享大量变量定义(如 wired_mac_auth_virtualswitch.roles.headless_device.id 引用同一 headless_device 角色,见 t/venom/vars/all.yml),也共享交换机状态检查用例(t/venom/switches/common/check_mac_auth_int_status.yml)。选择哪套取决于 CI 资源:需要真实交换交互选本文套件,追求单机快速回归选 virtualswitch 变体。
七、关键经验与可复用结论
- RADIUS 流程是异步的,验证必须带轮询:
25_check_radius_audit_log.yml的retry: 35+delay: 3模式是处理"交换机发请求 → 服务器应答"时延的标准做法,任何改编该套件的场景都应保留这种轮询而非固定 sleep。 - 维护任务参数与调度解耦,改完必须重启
pfcron:delete_window通过 API 修改后需重启服务才被读取;触发执行则可走pfcmd pfcron node_cleanup手动跑一次,不必等调度周期。 - Teardown 的时序有其物理意义:注销后等待再撤交换机配置(避免 Disconnect-NAK)、删除节点前等
delete_window + 10s(满足过期条件),都是保证断言稳定性的关键,不能省略或合并。 - 节点身份的 URL 编码:REST API 路径中使用
00%3A03%3A00%3A11%3A11%3A01(冒号需编码),这是调用 节点 API 时容易踩坑的细节。
总而言之,wired_mac_auth 是 PacketFence 有线 MAB 功能最完整、最接近生产拓扑的端到端验证样板:它以 45 行测试文档为骨架,辅以 20 个左右的 YAML 用例文件,覆盖了"注册 → 认证 → 授权 → 注销 → 清理"的完整生命周期。无论是排查有线 MAC 认证问题,还是为自定义 NAC 场景编写类似的集成测试,这套测试的步骤划分、断言设计与清理纪律都值得直接参考与复用。