Skip to content

Linux eBPF ​

On Linux, Enhanced Mode attaches eBPF programs to the root cgroup v2. When a program connects a socket or sends a UDP datagram, the kernel decides whether to hand it to Specola Core. Captured connections are redirected to Core on 127.0.0.1; Core applies your rules and connects direct or through a proxy. There is no virtual interface, and routes and system DNS settings are not changed.

Process attribution, include-children and member pinning are covered on Process Rules; this page links there instead of repeating it.

Requirements ​

  • Linux 5.17 or newer.
  • cgroup v2 mounted at /sys/fs/cgroup.
  • Kernel BTF (/sys/kernel/btf/vmlinux).
  • Core running as root.
  • A Core built with eBPF (SPECOLA_ENABLE_LINUX_EBPF, on by default for desktop Linux). OpenWrt builds have no eBPF; routers capture LAN traffic with the transparent gateway instead.

Check:

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

Inside containers, loading eBPF programs and attaching them to cgroups is usually blocked, even for root.

Configuration ​

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"     # the default on Linux
ip-version = "ipv4"

The local port must stay enabled (port greater than 0): the kernel redirects captured connections to that port number on 127.0.0.1. protocols = "none" is allowed; the port then serves only eBPF.

Fields ​

FieldDefaultNotes
[enhanced-mode] ip-version"ipv4"only IPv4 is captured. dual behaves like ipv4; ipv6 makes Core refuse to start
[enhanced-mode.ebpf] unmatched-traffic"direct"direct: connections no rule selects follow the final target in the kernel (see below); core: send them all to Core

unmatched-traffic is the only key in [enhanced-mode.ebpf]; any other key, such as the old process-routing, is rejected. [enhanced-mode.tun] has no effect on Linux, but it is still validated.

Run ​

Validate as your normal user, then start as root. Give an absolute path to the profile when you use sudo:

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

A successful start logs:

text
Linux IPv4 process proxy started with cgroup eBPF socket redirection (IPv6 bypassed)

If Core is started without root and its startup profile enables eBPF, it asks once for authorization with the desktop dialog (polkit) and restarts itself as root; see Privileges. For a permanent setup run Core as a systemd service; see Setting up Specola on Omarchy for a complete unit file.

Stop with Ctrl+C, SIGTERM or systemctl stop. The eBPF programs are detached when Core exits, even after kill -9.

How a connection is decided ​

For every TCP connect and every UDP send, in the kernel, in this order:

  1. Exempt programs. Specola Core itself, and the Specola app that started Core, are let through. Sockets in another network namespace (most containers) are let through.
  2. DNS. TCP and UDP to port 53, to any server, including 127.0.0.53 and a LAN resolver, is redirected to Core's DNS. See DNS.
  3. Local destinations are let through: 0.0.0.0, loopback 127/8, private 10/8, 172.16/12, 192.168/16, link-local 169.254/16, multicast 224/4, 255.255.255.255, and the computer's own addresses and subnet broadcast addresses (refreshed every second).
  4. Candidates. The connection is captured if any of these hold:
    • the destination is in the Fake-IP range;
    • the destination is in an IP range of an IP rule (IP-CIDR, GEOIP, ...);
    • the destination is an address DNS returned for a name that a domain rule matches;
    • the program is a process-rule candidate (below).
  5. Everything else follows the final target. When the final target is DIRECT the connection keeps its own socket and never reaches Core, unless unmatched-traffic = "core". When it is a proxy, a group or REJECT, the connection is captured.
  6. In Core, a captured connection is matched against the full rule list in order, with its process, and goes direct, is rejected, or connects through the chosen proxy or group.

IPv6 is never captured: there are no IPv6 hooks. With [dns] ipv6 forced off in this mode (see DNS), programs that ask Core for addresses get IPv4 only.

The final target is [route] final-enhanced when it names an existing proxy or group, otherwise the rule list's FINAL. In route-mode = "global" it is global-proxy. In route-mode = "direct" only Fake-IP and DNS traffic is captured (everything, with unmatched-traffic = "core").

What this means:

  • With FINAL,DIRECT only connections your rules care about pass through Core. Everything else runs at full kernel speed.
  • With a proxy or group as the final target, every non-local connection passes through Core.
  • Rule changes take effect on new connections. Existing TCP connections keep their first decision.
  • 100.64.0.0/10 (Tailscale and carrier-grade NAT) is not in the local list. With a proxy as the final target, Tailscale peers are sent to the proxy too. Add "IP-CIDR,100.64.0.0/10,DIRECT" near the top of your rules.

Process candidates ​

The kernel knows the program of each socket but cannot run the full rule list. Core gives it a list of candidates built from your process rules:

  • PROCESS-NAME and PROCESS-NAME-WILDCARD patterns. The kernel compares them with the file name of the program's executable (the resolved file, the same name rules use, not the 15-character comm), ignoring ASCII case.
  • Exact PROCESS-PATH rules whose file exists when the profile loads, by the file's identity and by its file name.

A program whose executable name is 64 bytes or longer, or cannot be read, counts as a candidate.

Some rules cannot be expressed as candidates. Then every program becomes a candidate and every non-local connection goes through Core. Matching stays correct; throughput drops. For most of them Core logs Linux eBPF: complex rule requires conservative capture; Core matches precisely. This happens with:

  • PROCESS-NAME-REGEX, PROCESS-PATH-REGEX, PROCESS-PATH-WILDCARD, and PROCESS-PATH with * or ?;
  • a PROCESS-PATH file that does not exist at load time, or a name of 64 bytes or more;
  • more than 64 candidates;
  • NOT, and AND/OR that do not reduce to process names or paths;
  • DST-PORT, NETWORK and the SRC-* rule types;
  • IP-SUFFIX and IP-ASN;
  • any rule with include-children.

If throughput matters, prefer PROCESS-NAME and exact PROCESS-PATH, keep FINAL,DIRECT, and avoid the rule types above. See also what Linux eBPF captures.

unmatched-traffic ​

unmatched-traffic only matters when the final target is DIRECT:

ValueA connection no candidate selects
direct (default)keeps its own socket; Core never sees it
coreis captured; Core runs the rules and, with no match, connects it DIRECT

Use core to see every connection on the Connections page or to let the sniffer find names for programs that use their own DNS. It costs throughput.

DNS ​

Every DNS query on port 53 from any program except Core and the Specola app is answered by Core, wherever it was going. Core listens on 127.0.0.1:5353 for this; the system resolver configuration is not touched.

  • [dns] ipv6 is forced off: AAAA queries get an empty answer, because IPv6 is not captured.
  • A [dns.listener] address has no effect in this mode; the listener is moved to 127.0.0.1:5353.
  • With [dns] mode = "fake-ip" (the default), names that no domain rule decides get a Fake-IP, so their connections are captured and decided with their process. Names a domain rule routes get a real or a Fake-IP answer as described on DNS; real-ip never gives out Fake-IPs.
  • DNS over HTTPS and DNS over TLS are not port 53 and are not intercepted. Such programs never show Core the name: keep the sniffer on, or match them with an IP or process rule.

Process rules never decide a DNS answer; see DNS and process rules.

Containers ​

  • Own network namespace (Docker's default bridge, most Podman setups): not captured at all. Their traffic leaves through the host's NAT and follows the normal routing table. Route such containers through the local port, or run them with the host network.
  • Host network, own PID namespace: captured. Core cannot see the process's path or parents, only the kernel name, cut to 15 characters. PROCESS-PATH and include-children never match it, and a PROCESS-NAME rule only matches when the name fits in 15 characters. The kernel still selects the connection by the executable's full file name.

Verify ​

bash
curl -sI https://example.com                   # appears on the Connections page when captured
sudo bpftool cgroup tree /sys/fs/cgroup         # lists the attached programs

With FINAL,DIRECT and no rule selecting curl, the request is not captured and does not appear; that is expected. After Core stops, the programs are gone from bpftool cgroup tree.

To test a process rule without changing a real program, copy a binary under the name the rule expects:

bash
cp /usr/bin/curl /tmp/cargo && /tmp/cargo -sI https://example.com   # matches PROCESS-NAME,cargo

Troubleshooting ​

SymptomCause and fix
eBPF requires administrator privilegesrun Core as root (sudo, systemd)
This Linux build has no enhanced modethe build has no eBPF (OpenWrt); use the gateway
cgroup v2 is not mounted at /sys/fs/cgroupthe system uses cgroup v1 or a different mount; enable the unified hierarchy
loading IPv4 process-proxy eBPF programs ... or Operation not permittedkernel older than 5.17, no BTF, or a container or security module blocks eBPF
eBPF process proxy requires IPv4ip-version = "ipv6"; use ipv4
Linux eBPF inbound setup failed[general] port = 0; set a port
Cannot start DNSsomething else holds 127.0.0.1:5353 (check with ss -lntup)
A process rule never matchesthe name differs from the executable's file name. Run readlink /proc/<pid>/exe and use its last component, not comm or ps output. See Process Rules
A connection never reaches Coreits destination is local or private, it is IPv6, it comes from a container network, or nothing selects it and the final target is DIRECT
A domain rule never matchesthe program uses DNS over HTTPS/TLS; keep the sniffer on or use an IP or process rule
Everything goes through Corethe final target is not DIRECT, unmatched-traffic = "core", or a rule forces conservative capture (look for the log line above)
A group never changes member for a programthat is pinning
Tailscale peers stop workingadd "IP-CIDR,100.64.0.0/10,DIRECT"