Linux eBPF
在 Linux 上,增强模式把 eBPF 程序挂到 cgroup v2 的根节点。程序连接套接字或发送 UDP 数据报时,由内核决定 要不要交给 Specola Core。被接管的连接重定向到 127.0.0.1 上的 Core,Core 按规则直连或经代理转发。 不建虚拟网卡,也不改路由和系统 DNS 设置。
进程识别、include-children 和成员固定见进程规则,本页只链接过去,不再重复。
运行要求
- Linux 5.17 或更新版本。
- cgroup v2 挂载在
/sys/fs/cgroup。 - 内核 BTF(
/sys/kernel/btf/vmlinux)。 - Core 以 root 运行。
- 带 eBPF 的 Core 构建(
SPECOLA_ENABLE_LINUX_EBPF,桌面 Linux 默认开启)。OpenWrt 构建没有 eBPF, 路由器上请用透明网关接管局域网流量。
检查方法:
uname -r # 5.17 或更新
stat -fc %T /sys/fs/cgroup # cgroup2fs
test -r /sys/kernel/btf/vmlinux && echo BTF ok在容器里,即使是 root,通常也不允许加载 eBPF 程序或挂到 cgroup 上。
配置
[general]
route-mode = "rule"
port = 7890
protocols = "mixed"
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080
[route]
rules = [
"PROCESS-NAME,git-remote-https,office",
"PROCESS-NAME,cargo,office",
"DOMAIN-SUFFIX,corp.example.com,office",
"IP-CIDR,203.0.113.0/24,office",
"FINAL,DIRECT",
]
[enhanced-mode]
enable = true
backend = "ebpf" # Linux 上的默认值
ip-version = "ipv4"本地端口必须保持开启(port 大于 0):内核把被接管的连接重定向到 127.0.0.1 上的这个端口号。 可以写 protocols = "none",此时这个端口只为 eBPF 服务。
字段
| 字段 | 默认值 | 说明 |
|---|---|---|
[enhanced-mode] ip-version | "ipv4" | 只接管 IPv4。dual 等同于 ipv4;ipv6 会让 Core 拒绝启动 |
[enhanced-mode.ebpf] unmatched-traffic | "direct" | direct:没有被任何规则选中的连接在内核里按兜底出站处理(见下文);core:全部交给 Core |
[enhanced-mode.ebpf] 里只有 unmatched-traffic 这一个字段,写其他字段(比如旧的 process-routing)会报错。 [enhanced-mode.tun] 在 Linux 上不生效,但仍会做校验。
运行
先用普通用户校验,再以 root 启动。用 sudo 时请给配置文件写绝对路径:
specola-core -t --config ~/.config/specola/profiles/my.toml
sudo specola-core --config /home/me/.config/specola/profiles/my.toml启动成功时日志里会有:
Linux IPv4 process proxy started with cgroup eBPF socket redirection (IPv6 bypassed)如果 Core 不是以 root 启动,而启动时加载的配置开启了 eBPF,它会通过桌面认证对话框(polkit)申请一次授权, 然后以 root 身份重新启动自己,见权限。想长期运行请做成 systemd 服务,完整的 unit 文件见 Setting up Specola on Omarchy。
用 Ctrl+C、SIGTERM 或 systemctl stop 停止。Core 退出时 eBPF 程序就会卸下,即使是 kill -9。
一条连接如何判定
每次 TCP 连接、每次 UDP 发送,内核按下面的顺序判断:
- 豁免的程序。 Specola Core 自己,以及启动 Core 的 Specola 应用,直接放行。位于其他网络命名空间的套接字 (大多数容器)也直接放行。
- DNS。 发往任何服务器 53 端口的 TCP 和 UDP,包括
127.0.0.53和局域网里的 DNS,都重定向到 Core 的 DNS。 见 DNS。 - 本地目标直接放行:
0.0.0.0、回环127/8、私有网段10/8、172.16/12、192.168/16、链路本地169.254/16、组播224/4、255.255.255.255,以及本机自己的地址和子网广播地址(每秒刷新一次)。 - 候选条件。 满足下面任意一条,连接就会被接管:
- 目标在 Fake-IP 网段内;
- 目标在某条 IP 规则(
IP-CIDR、GEOIP等)的地址范围内; - 目标是 DNS 为某个被域名规则命中的域名返回的地址;
- 程序命中进程规则候选条件(见下文)。
- 其余连接按兜底出站处理。兜底出站为
DIRECT时,连接保留自己的套接字,不会到达 Core,除非设置了unmatched-traffic = "core"。兜底出站是节点、代理组或REJECT时,连接会被接管。 - 在 Core 里,被接管的连接带着进程信息,按顺序匹配完整的规则列表,然后直连、拒绝,或经选中的节点、代理组转发。
IPv6 永远不会被接管:没有 IPv6 的 hook。这种模式下 [dns] ipv6 被强制关闭(见 DNS),向 Core 查询地址的程序只会拿到 IPv4。
兜底出站是 [route] final-enhanced(需要是已存在的节点或代理组),否则是规则列表里的 FINAL。 route-mode = "global" 时是 global-proxy。route-mode = "direct" 时只接管 Fake-IP 和 DNS 流量 (设置了 unmatched-traffic = "core" 时接管全部)。
这意味着:
- 用
FINAL,DIRECT时,只有规则关心的连接经过 Core,其余连接以内核原生速度运行。 - 兜底出站是节点或代理组时,所有非本地连接都经过 Core。
- 规则改动只影响新连接,已有的 TCP 连接保持最初的判定。
100.64.0.0/10(Tailscale 和运营商级 NAT)不在本地地址列表里。兜底出站是代理时,Tailscale 对端 的流量也会被送去代理。请在规则靠前的位置加上"IP-CIDR,100.64.0.0/10,DIRECT"。
进程候选条件
内核知道每个套接字属于哪个程序,但无法运行完整的规则列表。Core 根据你的进程规则给内核一份候选条件:
PROCESS-NAME和PROCESS-NAME-WILDCARD的模式。内核拿它和程序可执行文件的文件名比较(解析符号链接后的 文件,也就是规则使用的名称,不是最多 15 个字符的comm),忽略 ASCII 大小写。- 加载配置时文件存在的精确
PROCESS-PATH规则,按文件身份和文件名比较。
可执行文件名达到 64 字节或读取不到的程序,一律算作候选。
有些规则无法转换成候选条件。这时所有程序都算候选,所有非本地连接都经过 Core。匹配结果仍然正确,只是吞吐会下降。 其中大部分情况下 Core 会记录 Linux eBPF: complex rule requires conservative capture; Core matches precisely。 以下规则会导致这种情况:
PROCESS-NAME-REGEX、PROCESS-PATH-REGEX、PROCESS-PATH-WILDCARD,以及含*或?的PROCESS-PATH;- 加载时文件不存在的
PROCESS-PATH,或达到 64 字节的名称; - 候选条件超过 64 个;
NOT,以及无法归结为进程名或路径的AND/OR;DST-PORT、NETWORK和各种SRC-*规则;IP-SUFFIX和IP-ASN;- 任何带
include-children的规则。
在意吞吐的话,优先用 PROCESS-NAME 和精确的 PROCESS-PATH,保持 FINAL,DIRECT,避开上面这些规则类型。 另见 Linux eBPF 捕获哪些连接。
unmatched-traffic
unmatched-traffic 只在兜底出站为 DIRECT 时有意义:
| 取值 | 没有被任何候选条件选中的连接 |
|---|---|
direct(默认) | 保留自己的套接字,Core 看不到它 |
core | 被接管;Core 运行规则,没有命中时按 DIRECT 连接 |
想在「连接」页面看到所有连接,或者想让嗅探为自带 DNS 的程序找出域名,可以用 core,代价是吞吐下降。
DNS
除 Core 和 Specola 应用以外,任何程序发往 53 端口的 DNS 查询都由 Core 应答,无论原本发往哪里。 Core 为此监听 127.0.0.1:5353,不改动系统解析器的配置。
[dns] ipv6被强制关闭:AAAA 查询得到空应答,因为 IPv6 不会被接管。[dns.listener]的地址在这种模式下不生效,监听被移到127.0.0.1:5353。[dns] mode = "fake-ip"(默认)时,没有被域名规则决定的域名会得到 Fake-IP,于是它们的连接会被接管,并带着 进程信息参与判断。被域名规则分流的域名得到真实地址还是 Fake-IP,见 DNS;real-ip从不返回 Fake-IP。- DNS over HTTPS 和 DNS over TLS 不走 53 端口,不会被拦截。这类程序不会把域名告诉 Core:请保持嗅探开启, 或用 IP、进程规则匹配。
进程规则从不决定 DNS 应答,见 DNS 与进程规则。
容器
- 有独立网络命名空间的容器(Docker 默认的 bridge 网络、大多数 Podman 配置):完全不会被接管。它们的流量经主机的 NAT 出去,走普通路由表。请让这类容器使用本地端口,或者用主机网络运行。
- 使用主机网络、但有独立 PID 命名空间的容器:会被接管。Core 看不到进程的路径和父进程,只有内核记录的名称,最长 15 个字符。
PROCESS-PATH和include-children对它永远不命中,PROCESS-NAME规则只有在名称不超过 15 个字符时才能 命中。内核仍按可执行文件的完整文件名决定是否接管。
验证
curl -sI https://example.com # 被接管时会出现在「连接」页面
sudo bpftool cgroup tree /sys/fs/cgroup # 列出已挂载的程序FINAL,DIRECT 且没有规则选中 curl 时,这个请求不会被接管,也不会出现在页面上,这是正常的。Core 停止后, bpftool cgroup tree 里就看不到这些程序了。
想在不改动真实程序的情况下测试进程规则,可以把某个程序复制成规则期望的名字:
cp /usr/bin/curl /tmp/cargo && /tmp/cargo -sI https://example.com # 命中 PROCESS-NAME,cargo排错
| 现象 | 原因和解决办法 |
|---|---|
eBPF requires administrator privileges | 以 root 运行 Core(sudo、systemd) |
This Linux build has no enhanced mode | 这个构建没有 eBPF(OpenWrt),请用网关 |
cgroup v2 is not mounted at /sys/fs/cgroup | 系统使用 cgroup v1 或非标准挂载点,请启用统一层级(unified hierarchy) |
loading IPv4 process-proxy eBPF programs ... 或 Operation not permitted | 内核早于 5.17、没有 BTF,或者容器、安全模块阻止了 eBPF |
eBPF process proxy requires IPv4 | ip-version = "ipv6",请改用 ipv4 |
Linux eBPF inbound setup failed | [general] port = 0,请设置端口 |
Cannot start DNS | 127.0.0.1:5353 被其他程序占用(用 ss -lntup 查看) |
| 进程规则从不命中 | 名称和可执行文件的文件名不一致。运行 readlink /proc/<pid>/exe,取最后一段,不要用 comm 或 ps 的输出。见进程规则排错 |
| 连接从未到达 Core | 目标是本机或私有网段、是 IPv6、来自容器网络,或者没有规则选中它而兜底出站为 DIRECT |
| 域名规则从不命中 | 程序用了 DNS over HTTPS/TLS;保持嗅探开启,或改用 IP、进程规则 |
| 所有流量都经过 Core | 兜底出站不是 DIRECT、设置了 unmatched-traffic = "core",或者某条规则导致保守接管(看上面那条日志) |
| 某个程序的代理组成员始终不变 | 这是成员固定 |
| Tailscale 对端无法访问 | 加上 "IP-CIDR,100.64.0.0/10,DIRECT" |
