Skip to content
English下载

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, 路由器上请用透明网关接管局域网流量。

检查方法:

bash
uname -r                                  # 5.17 或更新
stat -fc %T /sys/fs/cgroup                # cgroup2fs
test -r /sys/kernel/btf/vmlinux && echo BTF ok

在容器里,即使是 root,通常也不允许加载 eBPF 程序或挂到 cgroup 上。

配置 ​

toml
[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 时请给配置文件写绝对路径:

bash
specola-core -t --config ~/.config/specola/profiles/my.toml
sudo specola-core --config /home/me/.config/specola/profiles/my.toml

启动成功时日志里会有:

text
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 发送,内核按下面的顺序判断:

  1. 豁免的程序。 Specola Core 自己,以及启动 Core 的 Specola 应用,直接放行。位于其他网络命名空间的套接字 (大多数容器)也直接放行。
  2. DNS。 发往任何服务器 53 端口的 TCP 和 UDP,包括 127.0.0.53 和局域网里的 DNS,都重定向到 Core 的 DNS。 见 DNS。
  3. 本地目标直接放行:0.0.0.0、回环 127/8、私有网段 10/8、172.16/12、192.168/16、链路本地 169.254/16、组播 224/4、255.255.255.255,以及本机自己的地址和子网广播地址(每秒刷新一次)。
  4. 候选条件。 满足下面任意一条,连接就会被接管:
    • 目标在 Fake-IP 网段内;
    • 目标在某条 IP 规则(IP-CIDR、GEOIP 等)的地址范围内;
    • 目标是 DNS 为某个被域名规则命中的域名返回的地址;
    • 程序命中进程规则候选条件(见下文)。
  5. 其余连接按兜底出站处理。兜底出站为 DIRECT 时,连接保留自己的套接字,不会到达 Core,除非设置了 unmatched-traffic = "core"。兜底出站是节点、代理组或 REJECT 时,连接会被接管。
  6. 在 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 个字符时才能 命中。内核仍按可执行文件的完整文件名决定是否接管。

验证 ​

bash
curl -sI https://example.com                   # 被接管时会出现在「连接」页面
sudo bpftool cgroup tree /sys/fs/cgroup         # 列出已挂载的程序

FINAL,DIRECT 且没有规则选中 curl 时,这个请求不会被接管,也不会出现在页面上,这是正常的。Core 停止后, bpftool cgroup tree 里就看不到这些程序了。

想在不改动真实程序的情况下测试进程规则,可以把某个程序复制成规则期望的名字:

bash
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 IPv4ip-version = "ipv6",请改用 ipv4
Linux eBPF inbound setup failed[general] port = 0,请设置端口
Cannot start DNS127.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"