PacketFence Configurator 端到端集成测试全解析:基于 Venom 测试套件掌握首次引导配置流程

原创2026-10-13 13:15:231,932 阅读
文章标签:网络安全认证鉴权身份认证网络后端前端

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 记录了三个关键设计决策,对理解套件行为至关重要:

  1. 只配置 VLAN enforcement 场景:尽管可以配置 inline 接口,但套件刻意只做 VLAN 强制接入,inline 场景由专门的 configurator_inline_l2 套件覆盖;
  2. 无 Authorization 头:Configurator 处于 token-less 状态(尚未完成配置),因此所有 API 调用都不带认证头;
  3. 自包含:该套件必须能独立完成一切验证,且几乎不引用公共目录(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 将这一思路落为三步:

  1. 通过 ip -o link show | egrep -v '^1:' | grep '^{{.configurator.interfaces.dhcp_listener.index}}:' | awk -F ': ' '{print $2;}' 按索引解析出真实网卡名(如 eth1);
  2. 调用 PATCH /api/v1/configurator/config/interface/<iface>,body 为 {"ipaddress": ..., "netmask": ..., "type": "dhcp-listener"},把接口类型标记为 dhcp-listener;
  3. 依次 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 演示了“密钥从密码库安全取用”的典型模式:

  1. 执行 psonoci secret get <secret_id> password,把输出的 Fingerbank API key 存为变量;
  2. 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"
}
  1. 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 顺序执行:

  1. 重启 packetfence-config:configurator/system_service/packetfence-config/restart(POST),通过自定义 executor pf_api_system_service_restart_async 以 {"async": "true"} 发起异步重启并轮询任务(见 t/venom/lib/pf_api_system_service_restart_async.yml);
  2. 重启 pfqueue 双后端:pfqueue-backend 与 pfqueue-go 各异步重启一次;
  3. 更新 systemd:POST /api/v1/configurator/service/pf/update_systemd,断言 "Updated systemd for pf",因管理员 API 后端恢复期可能返回 502,故 retry: 12;
  4. 重启 haproxy-admin:configurator/service/haproxy-admin/restart;
  5. 重启 pfperl-api:无可用 API,直接通过 systemctl_service_restart 重启 packetfence-pfperl-api,以应用自定义步骤的改动;
  6. 等待 API 就绪:GET /api/v1/system/summary 轮询至返回 200/401/403(此时带上了登录 token);
  7. 启动 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

三组收尾验证

  1. Configurator 已禁用:见上节 401 断言,确保默认页面不再指向配置向导;
  2. 服务全部运行: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.service active、重启次数 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 已应用;
  3. 管理员账号: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 为模板,按“网络 → 数据库 → 外部依赖 → 服务编排 → 收尾验证”的骨架组织用例。

登录后查看全文
packetfence