PacketFence Configurator 端到端集成测试全解析:基于 Venom 测试套件掌握首次引导配置流程
PacketFence Configurator 端到端集成测试全解析:基于 Venom 测试套件掌握首次引导配置流程
本指南以 PacketFence 仓库中的 t/venom/test_suites/configurator/TESTSUITE.md 及其配套 Venom YAML 测试用例为蓝本,完整剖析 Configurator(首次引导配置向导)的端到端集成测试流程:从多网卡网络规划、MariaDB 数据库初始化、Fingerbank API 对接,到服务启动与 Configurator 禁用收尾。读完本文,你将掌握 PacketFence 的 API 级配置编排顺序、Venom 测试用例的编写套路,以及这些步骤背后对应的服务与配置落地位置,可直接复用于自定义部署脚本或测试场景扩展。
测试套件全景:位置、前置条件与设计动机
套件文件布局
configurator 是 PacketFence 在 Vagrant + Ansible 环境下运行的第一套端到端测试,位于 t/venom/test_suites/configurator,由 TESTSUITE.md 与 9 个按数字前缀排序的 Venom YAML 用例组成:
| 文件 | 对应阶段 | 作用 |
|---|---|---|
| 00_configure_dhcp_listener_interface.yml | 可选步骤 | 配置 dhcp-listener(互联网接口)并启动 dhclient 守护 |
| 10_run_configurator_step1.yml | Step 1 | 配置管理、注册、隔离接口及 DNS |
| 20_run_configurator_step2.yml | Step 2 | MariaDB 初始化、告警、常规设置、管理员账号 |
| 30_run_configurator_step3.yml | Step 3 | Fingerbank API key 配置与验证 |
| 40_run_custom_step.yml | 自定义步骤 | 调整 API 超时、进程数与 pfqueue 工作线程 |
| 41_run_configreload_hard.yml | 自定义步骤 | 执行 pfcmd configreload hard |
| 50_run_configurator_step4.yml | Step 4 | 重启服务、更新 systemd、禁用 Configurator |
| 60_check_configurator_disabled.yml | 验证 | 确认 Configurator 已关闭 |
| 70_check_admin_account.yml | 验证 | 用管理员账号登录 Web 管理界面 |
| 80_check_iptables_services.yml | 验证 | 校验 IPv4 iptables 服务与规则 |
| 82_check_ip6tables_services.yml | 验证 | 校验 IPv6 ip6tables 服务与规则 |
前置环境要求
TESTSUITE.md 明确列出该套件运行的硬件前提,全部由 Vagrant + Ansible 预置完成:
- 第一块网卡:由虚拟化平台分配动态 IP(作为 Vagrant 管理通道),默认网关走该接口;
- 第二块网卡:由 Vagrant 分配静态 IP(作为 PacketFence 管理接口);
- 主机名:依据 Ansible inventory 设置;
- 操作系统:已更新到最新版本,且已安装最新 PacketFence 软件包;
- iptables:已针对 Vagrant 与 MailHog 调整;
- 环境变量:用于密钥与单元测试的 secrets 已设置;
- 工具链:Venom、psonoci 与 MailHog 已安装。
其中 psonoci(Psono 的 CLI 客户端)用于从密码管理库中取出 Fingerbank API key,MailHog 则作为本地 SMTP 测试服务器接收配置期间发送的告警邮件。从 t/venom/install-venom.sh 可见 Venom 的安装方式(make -C t/venom install 即调用该脚本,默认安装 v1.0.1 到 /usr/bin/venom)。
套件的设计原则
TESTSUITE.md 的 Additional notes 记录了三个关键设计决策,对理解套件行为至关重要:
- 只配置 VLAN enforcement 场景:尽管可以配置 inline 接口,但套件刻意只做 VLAN 强制接入,inline 场景由专门的
configurator_inline_l2套件覆盖; - 无
Authorization头:Configurator 处于 token-less 状态(尚未完成配置),因此所有 API 调用都不带认证头; - 自包含:该套件必须能独立完成一切验证,且几乎不引用公共目录(
t/venom/lib),因为所有 API 调用都是 Configurator 特有、后续套件不会再用的。
可选步骤:dhcp-listener 接口的“双 IP”技巧
在 vagrant-libvirt 环境下,Configurator 会把接口从动态(DHCP)切换为静态,导致 DHCP 租约到期后 Vagrant 因依赖该租约而无法再访问服务器。TESTSUITE.md 给出的解决思路是:只对该接口以守护进程方式启动 dhclient,并让其不修改 /etc/resolv.conf,这样 PacketFence 服务器将同时拥有静态与动态两个 IP。
00_configure_dhcp_listener_interface.yml 将这一思路落为三步:
- 通过
ip -o link show | egrep -v '^1:' | grep '^{{.configurator.interfaces.dhcp_listener.index}}:' | awk -F ': ' '{print $2;}'按索引解析出真实网卡名(如 eth1); - 调用
PATCH /api/v1/configurator/config/interface/<iface>,body 为{"ipaddress": ..., "netmask": ..., "type": "dhcp-listener"},把接口类型标记为 dhcp-listener; - 依次
POST .../interface/<iface>/down与/up将接口切到静态,再写入/etc/dhcp/dhclient-enter-hooks(内容为make_resolv_conf() { :; })并执行/usr/sbin/dhclient -nw <iface>维持动态租约。
值得注意的两点工程细节:其一,PATCH 用例带有 retry: 5, delay: 10,注释说明“冷启动后首次 Configurator API 调用时,haproxy-admin → pfperl-api 后端可能尚未就绪而返回 504,重试可使首次调用自愈(PATCH 幂等)”;其二,/down 与 /up 还会断言响应体 result.bodyjson.message 分别为 "Interface xxx disabled" 与 "Interface xxx enabled",用后端返回消息反向确认状态切换成功。
Step 1:四接口 + DNS 的网络拓扑落地
接口配置参数
10_run_configurator_step1.yml 先以 GET /api/v1/configurator/config/interfaces 轮询(retry: 30, delay: 10)等待 API 预热,然后为每个接口做一次“解析网卡名 → PATCH 配置”:
| 接口 | 网卡索引 | type 取值 | 关键附加参数 |
|---|---|---|---|
| 管理接口 mgmt | 3 | management |
additional_listening_daemons: ["portal"] |
| 注册接口 reg | 4 | vlan-registration |
dhcpd_enabled: enabled |
| 隔离接口 iso | 5 | vlan-isolation |
dhcpd_enabled: enabled |
对应变量在 t/venom/vars/all.yml 中定义:configurator.interfaces.mgmt.index: 3、configurator.interfaces.reg.index: 4、configurator.interfaces.iso.index: 5,管理接口 IP 取自 pfserver_mgmt_ip,注册/隔离接口的 dhcpd_enabled 均为 enabled。
TESTSUITE.md 补充了三条例外说明:
- PacketFence 会把每个动态接口转为静态,第一块网卡的静态 IP 在 libvirt 下不会引发问题;
- 注册与隔离网络的 IP 不能是
.1,因为虚拟化平台已占用该地址; - 当前不修改主机名,因为 Configurator 结束时修改主机名需要重启。
另外,针对 Debian Vagrant box 中“无 IP 的接口默认是 down”的问题,用例在执行 PATCH 前先用 ip link set dev <iface> up 把注册/隔离接口拉起(bounce_registration_int / bounce_isolation_int),最后通过 systemctl restart NetworkManager | true 让 EL(RHEL 系)正确应用 IP(Debian 未装 NetworkManager,| true 保证命令不失败)。
DNS 服务器配置
DNS 通过 PUT /api/v1/configurator/config/system/dns_servers 写入,body 为 {"dns_servers": ["{{.configurator.dns.primary_ip}}", "{{.configurator.dns.secondary_ip}}"]}。按 t/venom/vars/all.yml 的取值,主 DNS 是公共 DNS 8.8.8.8,次 DNS 是未来 AD 域控制器 IP(ad_mgmt_ip),为后续 802.1X/AD 认证场景预留解析能力。
Step 2:MariaDB 数据库初始化全流程
20_run_configurator_step2.yml 是整套件 API 调用最密集的阶段,对应 TESTSUITE.md Step 2 的完整清单,按依赖顺序可分成五组。
启动与连通性检查
POST /api/v1/configurator/system_service/packetfence-mariadb/start 启动 MariaDB 服务,断言返回消息为 "Service has been started";随后 POST /api/v1/configurator/config/base/database/test 传入 root 用户名做连通性测试,断言 "Successfully connected to the database mysql with user root"。
安全化与建库建用户
POST .../config/base/database/secure_installation:传入{"username": "root", "password": "<root密码>"}为 root 设置密码,完成“安全安装”;POST .../config/base/database/create:传入数据库名与 root 凭据,创建 pf 数据库并加载 schema,断言"Created database and loaded the schema";POST .../config/base/database/assign:传入 root 凭据与 pf 用户名/密码,为 pf 用户授权并调整配置,断言"Granted rights to user and adjusted the configuration";PATCH .../config/base/database:最后把db/user/pass/root_username/root_pass写入 PacketFence 配置,断言"Settings updated"。
测试用凭据定义在 t/venom/vars/all.yml:root 密码 ebjiatKeygId、pf 用户密码 AkuddIgTatzu、库名 pf。这些 API 与 PacketFence 的数据库 schema 文件(如 db/pf-schema-15.2.sql 一系)共同完成从空 MariaDB 到可用 pf 库的转变。
保存 root 凭据到 ~/.my.cnf
为让后续单元测试免密码运行,用例直接写入 ~/.my.cnf:
[client]
user = root
password = <root密码>
告警配置与测试邮件
PATCH /api/v1/configurator/config/base/alerting 配置告警邮箱,body 完整覆盖 SMTP 参数:
{
"emailaddr": "mailhog@example.lan",
"fromaddr": "packetfence@example.lan",
"smtp_encryption": "none",
"smtp_port": "<smtp_port>",
"smtp_verifyssl": "enabled",
"smtpserver": "<smtp_server>",
"test_emailaddr": "mailhog@example.lan"
}
随后 POST /api/v1/configurator/config/bases/test_smtp 用相同参数发送测试邮件,并断言返回 200。TESTSUITE.md 用复选框 [ ] Validate mail received by MailHog 标记人工/后续验证点(用例中留有 # FIXME: MailHog API call 注释,表示当前未自动断言收件箱),套件 Teardown 阶段会清理 MailHog 收件箱。SMTP 服务器与端口变量(smtp_server、smtp_port)由环境注入,指向 MailHog。
常规设置、重启与管理员账号
PATCH .../config/base/general:写入domain(example.lan)、timezone、hostname(pf),与 t/venom/vars/all.yml 中configurator.domain/hostname/timezone对应;POST .../system_service/packetfence-mariadb/restart:重启 MariaDB 使时区变更生效;POST /api/v1/configurator/user/admin/password:创建管理员账号。用例注释明确指出:“schema 中 admin 已无默认密码行,因此用 POST 创建而非 PATCH 更新”,body 为:
{
"password": "secret",
"pid": "admin",
"access_level": "ALL",
"valid_from": "1970-01-01 00:00:00",
"expiration": "2038-01-01 00:00:00"
}
TESTSUITE.md 的 Step 2 备注补充:tracking-config 默认已启用,故不修改任何配置,相应 API 调用也不在套件中测试。
Step 3:Fingerbank API key 的获取与验证
30_run_configurator_step3.yml 演示了“密钥从密码库安全取用”的典型模式:
- 执行
psonoci secret get <secret_id> password,把输出的 Fingerbank API key 存为变量; PATCH /api/v1/configurator/config/fingerbank_setting/upstream写入 upstream 设置,body 为:
{
"api_key": "<从 psonoci 取出的 key>",
"db_path": "/api/v2/download/db",
"host": "api.fingerbank.org",
"id": "upstream",
"port": "443",
"sqlite_db_retention": "2",
"use_https": "enabled"
}
GET /api/v1/configurator/fingerbank/account_info回读账户邮箱并断言等于预期值——TESTSUITE.md中解释:这一步确认 API 已被正确访问(需要 Internet 才能查询 Fingerbank API)。
该用例带 retry: 3, delay: 5,对上游 API 的网络波动做容错。Fingerbank 是 PacketFence 设备指纹识别能力的上游数据源,API key 的配置质量直接影响后续 BYOD/设备画像类场景的测试。
自定义步骤:为后续套件调优运行时参数
TESTSUITE.md 的 “Custom step before starting services” 注明这些操作“当然也可以在 step 4 期间完成”,其目的是为后续所有测试套件准备更友好的运行环境:
- 调大 API token 超时:
PATCH /api/v1/configurator/config/base/advanced写入api_inactivity_timeout: {"interval": 12, "unit": "h"}(见 40_run_custom_step.yml),避免长时间测试中 token 中途失效; - 降低 fork 进程数:
pffilter_processes: 1、pfperl_api_processes: 8,减少资源占用; - 追加 pfqueue 工作线程:向
/usr/local/pf/conf/pfqueue.conf追加[pfqueue] workers=8(pfserver_conf_dir来自 t/venom/vars/all.yml); - 执行硬重载:
{{.pfserver_pfcmd}} configreload hard(即/usr/local/pf/bin/pfcmd configreload hard),把对配置文件(含直接追加的 pfqueue.conf)的修改强制生效——这正是 41_run_configreload_hard.yml 的全部内容; - 日志级别调为 debug:便于集成测试失败时做事后排查。
Step 4:服务编排与 Configurator 关闭
服务重启与 systemd 更新
50_run_configurator_step4.yml 按 TESTSUITE.md 顺序执行:
- 重启 packetfence-config:
configurator/system_service/packetfence-config/restart(POST),通过自定义 executorpf_api_system_service_restart_async以{"async": "true"}发起异步重启并轮询任务(见 t/venom/lib/pf_api_system_service_restart_async.yml); - 重启 pfqueue 双后端:
pfqueue-backend与pfqueue-go各异步重启一次; - 更新 systemd:
POST /api/v1/configurator/service/pf/update_systemd,断言"Updated systemd for pf",因管理员 API 后端恢复期可能返回 502,故retry: 12; - 重启 haproxy-admin:
configurator/service/haproxy-admin/restart; - 重启 pfperl-api:无可用 API,直接通过
systemctl_service_restart重启packetfence-pfperl-api,以应用自定义步骤的改动; - 等待 API 就绪:
GET /api/v1/system/summary轮询至返回 200/401/403(此时带上了登录 token); - 启动 pf 全部服务:executor
pf_api_service_pf_start_async(见 t/venom/lib/pf_api_service_pf_start_async.yml)异步启动pf服务,并轮询radiusd-auth直到alive = 1——注释说明 radiusd-auth 依赖众多,是最后就绪的关键服务之一。
禁用 Configurator
60_check_configurator_disabled.yml 执行收尾的 PATCH:
{
"configurator": "disabled"
}
随后 GET /api/v1/configurator/config/interfaces 必须返回 401 且消息包含 "The configurator is turned off"。
这一行为的底层实现在 lib/pf/UnifiedApi/Controller/Configurator.pm 的 allowed 方法中:当 $Config{advanced}{configurator} 未启用时,直接 render_error(401, "The configurator is turned off")——测试断言与实现文案完全一致。同一控制器还揭示了 Configurator API 的代理架构:proxy_api_frontend 会把 /api/v1/configurator/ 路径改写为 /api/v1/ 并转发到 https://localhost:9999(api-frontend),且通过 add_token 为无 Authorization 头的请求自动注入内部服务 token,这正是 TESTSUITE.md 中“无 Authorization 头”设计能成立的原因。路由挂载见 lib/pf/UnifiedApi.pm 的 setup_api_v1_configurator_routes(/config 下聚合 interfaces、system、bases、fingerbank_settings 等子路由)。
此外,go/api-frontend/aaa/paths.go 的 publicPaths 明确包含 apiPrefix + "/configurator/",即 api-frontend 层把 /api/v1/configurator/ 视为公开路径(配置完成前无需认证),从 Go 网关层面印证了 Configurator 的 token-less 设计。
验证阶段与 Teardown
三组收尾验证
- Configurator 已禁用:见上节 401 断言,确保默认页面不再指向配置向导;
- 服务全部运行:80_check_iptables_services.yml 用
systemctl is-active packetfence-iptables.service断言 IPv4 服务 active,并用iptables -L INPUT -n | grep "dpt:22"确认管理接口存在 SSH 规则;82_check_ip6tables_services.yml 则断言packetfence-ip6tables.serviceactive、重启次数NRestarts不大于 10(防止 restart loop)、生成规则文件/usr/local/pf/var/conf/ip6tables_generated_rules.conf非空,并在 haproxy-portal active 时校验/usr/local/pf/var/conf/ip6tables/haproxy_portal_rules.json含 dport 80/443 且内核ip6tables -L INPUT -n已应用; - 管理员账号:70_check_admin_account.yml 用默认管理员
admin/secret(pfserver_default_admin_user/pfserver_admin_password)POST /api/v1/login,断言 200,证明 Step 2 创建的账号可正常登录。
Teardown
TESTSUITE.md 的 Teardown 只有一步:清空 MailHog 收件箱,为后续套件(如 captive_portal)的邮件类断言提供干净起点。
如何在 CI 中运行该套件
Make 目标
t/venom/Makefile 为 configurator 提供了两条常用目标:
configurator_el8:
make PF_VM_NAMES=pfel8$(DEV_ENV) SCENARIOS_TO_RUN=configurator $(MAKE_TARGET)
configurator_deb12:
make PF_VM_NAMES=pfdeb12$(DEV_ENV) SCENARIOS_TO_RUN=configurator $(MAKE_TARGET)
以及从零安装的“pristine”变体(configurator_el8_pristine / configurator_deb12_pristine)。DEV_ENV 在 CI 下为 dev、本地为 localdev;MAKE_TARGET 在 CI 下为 run(含 VM 构建),本地可用 run_tests 只跑测试。运行链为 make → t/venom/test-wrapper.sh run → ansible 起 VM + site.yml 预置 → run_tests 执行 scenario。
Scenario 编排
t/venom/scenarios/configurator/playbooks/run_tests.yml 是所有 configurator 相关 CI 任务的统一入口:以 - hosts: pfservers 对每个 VM 执行 venom-wrapper.sh {{ venom_dir }}/test_suites/configurator,并通过 VENOM_COMMON_FLAGS: --output-dir={{ venom_dir }}/results/{{ item }} 为每个套件单独存放结果(注释指出这是为了规避 Venom “逐套件运行时旧日志/结果被覆盖”的问题)。
venom-wrapper.sh 则负责把目录参数展开为按字母序排列的 YAML 文件列表,并透传 VENOM_COMMON_FLAGS / VENOM_EXIT_FLAGS 调用 venom run——这就是 00_、10_、20_ 等数字前缀必须存在的原因,它决定了阶段执行的先后顺序。执行入口约定为:套件文件安装在 VM 内的 /usr/local/pf/t/venom/test_suites(见 t/venom/vars/all.yml 的 venom_dir / test_suites_dir),且各 API 均指向 https://{{.pfserver_mgmt_ip}}:1443(pfserver_webadmin_url)。
总结:从测试套件反推 Configurator 的行为契约
通过本套件可以归纳出 PacketFence Configurator 的行为契约,这些约定对二次开发或脚本化部署同样适用:
- 接口配置:
type取值覆盖dhcp-listener、management、vlan-registration、vlan-isolation(inline 由专门套件覆盖);注册/隔离接口通常开启dhcpd_enabled; - 数据库初始化:secure_installation → create(建库 + 载入 schema)→ assign(授权 pf 用户)→ PATCH database(写配置)的次序不可颠倒;
- 告警邮件:alerting 配置与
test_smtp发送解耦,可独立验证 SMTP 通路; - 管理员创建:schema 中 admin 无默认密码行,需 POST 而非 PATCH;
- 安全边界:
configurator: disabled后所有/api/v1/configurator/*请求返回 401("The configurator is turned off"),网关层将 configurator 路径列为公开路径以支持无 token 引导; - 幂等与容错:绝大多数写操作(PATCH/PUT)幂等,配合
retry/delay可自愈冷启动期 502/504 等瞬时故障。
掌握这套流程后,无论是复现一次完整的环境初始化,还是为 PacketFence 编写新的端到端测试,都可以直接以 t/venom/test_suites/configurator 为模板,按“网络 → 数据库 → 外部依赖 → 服务编排 → 收尾验证”的骨架组织用例。