读懂FanchmWrt用户态守护进程fwxd:UBUS与Netlink通信架构完整剖析
读懂FanchmWrt用户态守护进程fwxd:UBUS与Netlink通信架构完整剖析
FanchmWrt 是一款基于 OpenWrt 的开源企业级路由器系统,其中的 fwxd 是防火墙子系统 fwx 的核心用户态守护进程:它通过 UBUS 对外提供 API 服务,通过 Netlink 与内核模块交换应用特征和流量数据。本文将带你从零读懂 fwxd 的双通道通信架构、事件循环与周边协作机制,帮助你快速掌握 OpenWrt 守护进程开发的典型范式。
一、fwxd 是什么:三层架构中的"大脑"
FanchmWrt 的防火墙能力由三部分协作完成,理解整体分层是读懂 fwxd 的前提:
| 组件 | 类型 | 职责 |
|---|---|---|
fwx |
内核模块 | 在数据面做流量识别、应用过滤(AppFilter)、MAC 过滤 |
fwxd |
用户态守护进程(C 语言) | API 服务、设备/流量统计管理、应用特征加载、日志归档 |
rule_manager |
Lua 脚本 | 每 10 秒轮询 UCI 配置,把过滤规则同步到内核 |
fwxd 的源码位于 package/fcm/fwxd/src/,入口程序是 main.c,编译依赖在 fwxd/Makefile 中声明:libubox、libubus、libjson-c、libsqlite3 等。
💡 一个典型的 OpenWrt 守护进程设计:数据面在内核(快),控制面在用户态(灵活),两者之间用 Netlink 对话。fwxd 正是这一范式的完整实现。
二、生命周期:从启动到事件循环
启动流程
fwxd 由 procd 托管,启动脚本 fwx.init 会先 modprobe fwx 加载内核模块,然后分别拉起 fwxd 与 rule_manager 两个实例,并配置了 respawn 60 5 5 的自动重启策略——进程异常退出后会自动拉起,保证服务可用性。
主程序 main() 的初始化顺序清晰明了:
- 解析命令行参数:支持
--debug-mode/-d开启调试模式 - 注册信号:
SIGUSR1触发应用特征文件升级,SIGUSR2切换日志级别(ERROR→WARN→INFO→DEBUG 循环) - 加载持久化数据:从 SQLite 和 /tmp 备份文件恢复设备列表、流量统计
- 连接 UBUS:
fwx_ubus_init()失败则直接退出 - 启动 check 线程:独立 pthread 执行网络连通性检查
- 进入
uloop_run():交给 libubox 的事件循环,主线程从此只负责调度
秒级定时器:守护进程的"心跳"
fwx_timeout_handler() 每秒被触发一次,是一个精心编排的周期任务表:
| 周期 | 任务 |
|---|---|
| 2 秒 | 采集接口流量速率 |
| 5 秒 | 在线会话统计 tick |
| 10 秒 | 更新客户端列表、清理过期访问记录 |
| 20 秒 | 日归档检查、刷新 LAN IP/Mask 到 /proc、导出客户端列表 |
| 60 秒 | 保存全部设备日汇总 |
| 300 秒 | 全局流量备份落盘 |
| 600 秒 | 全部客户端备份落盘 |
| 首次循环 | 建立 Netlink 连接,成功后接管内核事件上报 |
这种"一个循环 + 计数器取模"的写法避免了创建大量定时器,是嵌入式环境下控制复杂度的常见技巧。
三、通信通道一:UBUS——对外的"REST 网关"
为什么选 UBUS
OpenWrt 生态中,UBUS 是用户态进程间通信的事实标准:rpcd 把它桥接成 HTTP API,Web 管理界面(LUCI)直接调用它。fwxd 选择注册为 UBUS 对象,等于自动获得了"API 网关"能力,无需自己写 HTTP 服务。
对象注册:一个对象、两个方法
fwx_ubus_init() 先连接 /var/run/ubus/ubus.sock(失败则回退 /var/run/ubus.sock),随后注册名为 fwx 的对象,只提供两个方法:
struct ubus_object fwx_object = {
.name = "fwx",
.methods = fwx_object_methods, // "common" 与 "debug"
};
关键在于 common 是一个"万能分发口"。调用方只需发起一次 UBUS 调用:
ubus call fwx common '{"api": "get_dashboard_common", "data": {...}}'
ubus_handle_common() 的处理流程:
- 解析 JSON 请求,取出
api字段 - 对涉及版权的接口先做
CopyRight请求校验 - 在约百条 API 的静态分发表
fwx_api_node_list<a href="https://link.gitcode.com/i/8f45c1794213e4034f004db72ddc0517" target="_blank">]中线性查找(见 [fwx_ubus.c#L8661-L8761) - 调用对应 handler,handler 返回
json_object*,统一封装为{code: 2000, data: ...}(成功码 2000 / 失败码 4000 定义于 fwx.h#L17-L18) - 部分"写操作"成功后还会通过
fwx_agent把变更转发到 LAN 侧子节点,实现主从协同
API 能力一览
分发表按 GET/POST 分类,覆盖面非常广,按功能可归纳为五类:
- 📊 看板与统计:
get_dashboard_common、get_hourly_top_apps、get_global_traffic_stats、get_daily_top_users - 🛡️ 过滤规则:
add_filter_rule/add_mac_filter_rule/ 各类白名单增删改 - 👨👩👧 家长控制:
get_parental_control_detail、get_user_stat、get_user_daily_summary - 📡 系统配置:
set_firewall、set_work_mode、set_wireless_radio_info - 🧩 应用特征:
get_feature_info、start_feature_online_update、set_custom_feature
设计心得:与其给每个功能注册一个 UBUS method,不如"一个 method + 内部分发表"。新增接口只改数组,不改注册代码,扩展成本极低。
四、通信通道二:Netlink——与内核的"数据管道"
建立连接:预留协议号 29
fwx_netlink_init() 创建了专用的 Netlink 套接字:
socket(AF_NETLINK, SOCK_RAW, FWX_NETLINK_ID /* 29 */);
bind() → nl_pid = 999
协议号 29 落在 Netlink 用户保留段(29-35,即 NETLINK_USERSOCK),不会与系统协议冲突;常量集中定义在 fwx_netlink.h。连接采用惰性建立 + 自动重连策略——由秒级定时器负责(main.c#L388-L396),只要 fd 无效就重试,保证内核模块晚加载、重加载的场景都能恢复通信。
消息格式:Magic 校验 + JSON 负载
fwxd 在标准 nlmsghdr 之外加了一层自定义头 fwx_nl_msg_hdr,以魔术数 0xa0b0c0d0 校验消息真伪,载荷是明文 JSON,可读性极好:
┌─────────────┬─────────────┬──────────────────────────┐
│ nlmsghdr │ magic + len │ JSON 负载(≤1024 字节) │
└─────────────┴─────────────┴──────────────────────────┘
上行:内核 → 用户态(每 60 秒一次流量心跳)
fwx_netlink_handler() 处理内核上报,典型报文包含:
| 字段 | 含义 |
|---|---|
mac / ip / ipv6 |
设备身份(MAC 是全局主键) |
active |
该设备当前是否活跃 |
up_flow / down_flow |
本轮流量(KB 为单位) |
visit_info[] |
应用访问记录:appid + latest_action |
收到报文后,fwxd 按 MAC 查找(不存在则新建)客户端节点,然后完成四件事:更新在线会话状态、累加逐小时流量(含全局曲线)、记录应用访问时长、刷新当日汇总。这就是 Web 界面上"今日流量图"和"应用排行"的数据源头。
下行:用户态 → 内核(应用特征装载)
fwxd 把应用识别的特征文件(/etc/fwxd/feature.bin,加密存储,运行时解密)逐行推入内核,协议定义在 fwx_netlink.h#L20-L27:
CLEAN_FEATURE—— 先清空内核旧特征ADD_FEATURE—— 逐行下发特征(每行 ≤800 字节,自定义特征一并追加)FEATURE_LOAD_DONE—— 通知加载完成,内核正式启用
完整逻辑见 fwx_load_feature_to_kernel()。特征在线升级成功后,SIGUSR1 信号处理函数会置位 g_feature_update,由事件循环在下一轮触发整套重载——升级与加载解耦,避免在信号处理中做重活。
五、全景协作图:三条数据流如何交汇
Web管理界面 / CLI
│ ① ubus call fwx common (JSON)
▼
┌─────────────────────────────── fwxd ────────────────────────────────┐
│ UBUS 对象 "fwx" uloop 事件循环 客户端/流量数据库 │
│ common 分发 → API handler (1s 定时器/重连) (内存+SQLite) │
│ │ │ │
│ │ 读统计结果 │ ② recvmsg (60s 内核上报) │
│ └──────────┬───────────────────┤ │
│ ▼ │ ③ ADD_FEATURE 下行 │
└──────────────────┼───────────────────┼────────────────────────────┘
│ ▼
│ ┌──────────────┐
│ │ fwx 内核模块 │◄── ④ UCI 规则同步
└────────────┴──────────────┘ (rule_manager)
- ① 控制面:Web 请求 →
ubus→ API handler → JSON 响应 - ② 数据面汇报:内核每 60 秒把各设备的流量与应用访问推给 fwxd 记账
- ③ 规则/特征下发:fwxd 把应用特征装载进内核识别引擎
- ④ 旁路:rule_manager.lua 独立轮询 UCI,把 AppFilter/MAC 过滤等规则翻译成内核指令(fwxd 成功建立 Netlink 后会停掉旧版同名进程,二者已合并)
三股数据流最终都汇聚到同一个内存中的"客户端节点表",再通过 UBUS API 输出给前端——收口于 UBUS,源头在内核,这就是 fwxd 架构的核心思想。
六、给新手的 5 个可复用经验
- uloop 一体化事件循环:UBUS 套接字(
ubus_add_uloop)、Netlink fd(ULOOP_READ)、定时器统一挂进 libubox 的 uloop,单线程非阻塞,无需自己写 select - 万能分发 method:
common+ 静态分发表,一个 UBUS 方法覆盖上百个 API - 惰性初始化 + 自动重连:Netlink 不抢跑,放在定时器里兜底重试
- 自定义头 + Magic 数:在通用 Netlink 上叠加 JSON 载荷,调试友好、演进自由
- 信号只做"置位":SIGUSR1/2 只改标志位,实际重活在事件循环中执行,线程安全
七、源码索引
| 模块 | 文件 |
|---|---|
| 程序入口与定时任务 | package/fcm/fwxd/src/main.c |
| UBUS 注册与 API 分发 | package/fcm/fwxd/src/fwx_ubus.c |
| Netlink 收发实现 | package/fcm/fwxd/src/fwx_netlink.c |
| Netlink 协议定义 | package/fcm/fwxd/src/fwx_netlink.h |
| 日志与 API 码常量 | package/fcm/fwxd/src/fwx.h |
| 服务启动脚本 | package/fcm/fwxd/files/fwx.init |
| 规则同步脚本 | package/fcm/fwxd/files/rule_manager.lua |
| 构建定义 | package/fcm/fwxd/Makefile |
总结:fwxd 用 UBUS 打通了"界面 ↔ 服务"的控制面,用 Netlink 打通了"服务 ↔ 内核"的数据面,再用一个 uloop 事件循环把所有异步事件编织在一起。读懂它,你就掌握了 OpenWrt 上开发高性能用户态守护进程的完整地图。
