mit-pshenov/pktgate
GitHub: mit-pshenov/pktgate
基于 eBPF/XDP 的高性能数据包过滤器，通过 JSON 配置实现多层流水线规则和原子热重载，支持 IPv4/IPv6 双栈。
Stars: 0 | Forks: 0
# pktgate — eBPF/XDP 数据包过滤器
具有 JSON 驱动流水线配置的高性能数据包过滤器。
使用 XDP 实现快速路径丢弃/重定向，使用 TC ingress 实现镜像/DSCP 重写。
## 功能特性
- **L2 MAC 过滤** — 基于哈希的允许列表
- **L3 IPv4/IPv6 子网过滤** — 带有每条规则操作的 LPM trie
- **L4 TCP/UDP 端口过滤** — 协议 + 端口匹配
- **操作类型**：allow（允许）、drop（丢弃）、redirect（重定向到 VRF）、mirror（镜像/克隆）、tag（标记 DSCP）、rate-limit（限速）、userspace（用户空间 AF_XDP）
- **AF_XDP 用户空间快速路径** — 通过 `bpf_redirect_map` 实现向用户空间的零拷贝数据包交付
- **无中断配置重载** — 具有原子代次交换的双缓冲 map
- **热重载** — inotify + SIGHUP，防抖动，故障安全（错误不影响活动流水线）
- **IPv6 双栈** — 独立的 LPM trie，扩展头解析，分片检测
- **Prometheus 指标** — 带有每个计数器标签的 `/metrics` 端点
- **Systemd 集成** — 具有权限限制的加固服务单元
## 架构
```
NIC → [XDP entry] → tail_call → [L2 MAC] → [L3 IP/LPM] → [L4 port]
│
┌────────────┼────────────┐
↓ ↓ ↓
XDP_PASS XDP_REDIRECT XDP_DROP
↓ (AF_XDP)
[TC ingress:
mirror + DSCP]
```
- **数据平面**：5 个 BPF 程序（4 个 XDP + 1 个 TC），尾调用链，通过 `data_meta` 传递元数据
- **控制平面**：C++23，libbpf skeleton API，双缓冲 map
- **层间零 map 查找** — 通过 XDP `data_meta` 区域传递数据包元数据
完整设计文档请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。
## 构建
### 依赖项
```
apt install -y clang-19 llvm-19 libbpf-dev bpftool \
linux-headers-$(uname -r) libelf-dev zlib1g-dev \
nlohmann-json3-dev
```
### 编译
```
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```
### 选项
| CMake 选项 | 描述 |
|---|---|
| `-DBPF_DEBUG=ON` | 在 BPF 程序中启用 `bpf_printk` 跟踪 |
| `-DCOVERAGE=ON` | 启用 gcov/lcov 代码覆盖率 |
| `-DSANITIZER=asan\|tsan\|ubsan` | 使用 sanitizer 构建 |
| `-DFUZZ=ON` | 构建 libFuzzer 模糊测试目标 |
## 使用
```
# 直接运行
sudo ./build/pktgate_ctl [--json] [--debug] [--metrics-port 9090] [--afxdp-queues N] config.json
# Systemd
sudo systemctl start pktgate
sudo systemctl reload pktgate # SIGHUP → hot reload
kill -USR1 $(pidof pktgate_ctl) # dump stats to journal
```
## 配置
JSON 配置定义了对象（MAC、子网、端口组）和一个分层流水线：
```
{
"device_info": { "interface": "eth0", "capacity": "10Gbps" },
"objects": {
"subnets": { "trusted": "100.64.0.0/16" },
"subnets6": { "trusted_v6": "2001:db8:cafe::/48" },
"mac_groups": { "routers": ["00:11:22:33:44:55"] },
"port_groups": { "web": [80, 443] }
},
"pipeline": {
"layer_2": [{ "rule_id": 10, "match": {"src_mac": "object:routers"}, "action": "allow", "next_layer": "layer_3" }],
"layer_3": [
{ "rule_id": 100, "match": {"src_ip": "object:trusted"}, "action": "allow", "next_layer": "layer_4" },
{ "rule_id": 101, "match": {"src_ip6": "object6:trusted_v6"}, "action": "allow", "next_layer": "layer_4" }
],
"layer_4": [{ "rule_id": 1000, "match": {"protocol": "TCP", "dst_port": "object:web"}, "action": "allow" }]
},
"default_behavior": "drop",
"afxdp": {
"enabled": true,
"queues": 4,
"zero_copy": false,
"frame_size": 4096,
"num_frames": 4096
}
}
```
`afxdp` 部分启用 AF_XDP 用户空间快速路径。带有 `"action": "userspace"` 的规则将匹配的数据包重定向到 AF_XDP 套接字，而不是内核协议栈。如果没有绑定套接字，则回退到 `XDP_PASS`。
有关包含所有操作类型的完整示例，请参阅 [sample2.json](sample2.json)。
## 指标
使用 `--metrics-port 9090` 时，Prometheus 指标将在 `http://host:9090/metrics` 提供：
```
pktgate_packets_total
pktgate_drop_total{layer="l3",reason="rule"}
pktgate_pass_total{layer="l4"}
pktgate_action_total{action="mirror"}
pktgate_action_total{action="userspace"}
pktgate_tc_total{action="tag"}
```
Grafana 仪表板位于 `grafana/`。
## 测试
500+ 个测试点：19 个 ctest 目标 + 104 个功能测试 + 3 个模糊测试工具。
完整的测试计划、注意事项和发布前检查清单请参阅 [TEST_PLAN.md](TEST_PLAN.md)。
```
# C++ 单元测试 (13 targets)
ctest --test-dir build -L unit --output-on-failure
# C++ 集成测试 (4 targets)
ctest --test-dir build -L integration --output-on-failure
# BPF data plane 测试 (需要 root)
sudo ctest --test-dir build -L bpf
# 功能测试 — 通过 veth namespaces 的 real XDP traffic (需要 root)
pip install pytest scapy
sudo bash functional_tests/run.sh
# Fuzz testing (libFuzzer, 需要 clang-17+; 也支持 GCC standalone)
CC=clang-18 CXX=clang++-18 cmake -B build -DFUZZ=ON
cmake --build build --target fuzz_config_parser fuzz_net_types fuzz_roundtrip
./build/fuzz_config_parser fuzz/corpus_config -max_total_time=300
```
## 性能
BPF_PROG_TEST_RUN 基准测试（100 万数据包）：
| 路径 | ns/pkt | Mpps |
|---|---|---|
| L2 MAC drop | 76 | ~13.2 |
| L4 TCP:80 allow | 90 | ~11.1 |
| 完整流水线 (L3 LPM + L4) | 165 | ~6.1 |
## 许可证
GPL-2.0
标签：4层负载均衡, AF_XDP, AGPLv3 许可证, Bash脚本, C++23, DDoS防御, DEF CON 演示, Docker镜像, DSCP标记, Google搜索, IPv6双栈, libbpf, Linux内核, Linux网络栈, LPM路由查找, Prometheus监控, TC流量控制, VRF隔离, XDP, 云原生网络, 内核旁路, 原子配置重载, 客户端加密, 数据包过滤, 数据面开发, 流量镜像, 深度包检测, 热加载配置, 网络分流器, 网络安全, 网络安全分析, 网络性能监控, 网络流量控制, 自定义请求头, 配置错误, 防火墙, 隐私保护, 零拷贝, 高性能网络