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:
uname -r # 5.17 or newer
stat -fc %T /sys/fs/cgroup # cgroup2fs
test -r /sys/kernel/btf/vmlinux && echo BTF okInside containers, loading eBPF programs and attaching them to cgroups is usually blocked, even for root.
Configuration
[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
| Field | Default | Notes |
|---|---|---|
[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:
specola-core -t --config ~/.config/specola/profiles/my.toml
sudo specola-core --config /home/me/.config/specola/profiles/my.tomlA successful start logs:
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:
- 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.
- DNS. TCP and UDP to port 53, to any server, including
127.0.0.53and a LAN resolver, is redirected to Core's DNS. See DNS. - Local destinations are let through:
0.0.0.0, loopback127/8, private10/8,172.16/12,192.168/16, link-local169.254/16, multicast224/4,255.255.255.255, and the computer's own addresses and subnet broadcast addresses (refreshed every second). - 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).
- Everything else follows the final target. When the final target is
DIRECTthe connection keeps its own socket and never reaches Core, unlessunmatched-traffic = "core". When it is a proxy, a group orREJECT, the connection is captured. - 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,DIRECTonly 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-NAMEandPROCESS-NAME-WILDCARDpatterns. The kernel compares them with the file name of the program's executable (the resolved file, the same name rules use, not the 15-charactercomm), ignoring ASCII case.- Exact
PROCESS-PATHrules 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, andPROCESS-PATHwith*or?;- a
PROCESS-PATHfile that does not exist at load time, or a name of 64 bytes or more; - more than 64 candidates;
NOT, andAND/ORthat do not reduce to process names or paths;DST-PORT,NETWORKand theSRC-*rule types;IP-SUFFIXandIP-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:
| Value | A connection no candidate selects |
|---|---|
direct (default) | keeps its own socket; Core never sees it |
core | is 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] ipv6is 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 to127.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-ipnever 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-PATHandinclude-childrennever match it, and aPROCESS-NAMErule only matches when the name fits in 15 characters. The kernel still selects the connection by the executable's full file name.
Verify
curl -sI https://example.com # appears on the Connections page when captured
sudo bpftool cgroup tree /sys/fs/cgroup # lists the attached programsWith 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:
cp /usr/bin/curl /tmp/cargo && /tmp/cargo -sI https://example.com # matches PROCESS-NAME,cargoTroubleshooting
| Symptom | Cause and fix |
|---|---|
eBPF requires administrator privileges | run Core as root (sudo, systemd) |
This Linux build has no enhanced mode | the build has no eBPF (OpenWrt); use the gateway |
cgroup v2 is not mounted at /sys/fs/cgroup | the system uses cgroup v1 or a different mount; enable the unified hierarchy |
loading IPv4 process-proxy eBPF programs ... or Operation not permitted | kernel older than 5.17, no BTF, or a container or security module blocks eBPF |
eBPF process proxy requires IPv4 | ip-version = "ipv6"; use ipv4 |
Linux eBPF inbound setup failed | [general] port = 0; set a port |
Cannot start DNS | something else holds 127.0.0.1:5353 (check with ss -lntup) |
| A process rule never matches | the 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 Core | its 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 matches | the program uses DNS over HTTPS/TLS; keep the sniffer on or use an IP or process rule |
| Everything goes through Core | the 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 program | that is pinning |
| Tailscale peers stop working | add "IP-CIDR,100.64.0.0/10,DIRECT" |
