Enhanced Mode
The local HTTP/SOCKS5 port only sees programs that are configured to use it. Enhanced Mode captures the connections of every program on the computer and routes them with the same [route].rules.
[enhanced-mode]
enable = true
# backend is optional: tun on Windows and macOS, ebpf on Linux
ip-version = "ipv4"Make the profile work through the local port first (Direct, then Global, then Rule; see Quick Start), then turn Enhanced Mode on.
Backends
Each platform has exactly one working backend. Leave backend out and Specola picks it.
| Platform | backend | How it captures | Page |
|---|---|---|---|
| Windows | tun (default) | a WinTUN virtual adapter; routes send traffic into it | TUN |
| macOS | tun (default) | a utun virtual interface; routes send traffic into it | TUN |
| Linux | ebpf (default) | eBPF programs on cgroup v2 socket hooks redirect sockets to Core; no virtual interface, no route changes | Linux eBPF |
Both backends know which program opened a connection. TUN looks the owner up in the system's socket table; eBPF records it in the kernel when the socket is created. See which connections carry a process.
What the configuration accepts:
backendmust betunorebpf. Anything else (wfp,windivert,netfilter,network-extension, ...) is rejected:enhanced-mode.backend must be tun or ebpf.- On Linux,
backend = "tun"withenable = trueis rejected:enhanced-mode.backend=tun is not supported on Linux; use ebpf or disable enhanced mode. - On Windows and macOS,
backend = "ebpf"passes validation, but Core refuses to start Enhanced Mode:Enhanced mode requires the TUN backend on Windows(oron macOS). - Linux builds without eBPF (OpenWrt) have no Enhanced Mode:
This Linux build has no enhanced mode; capture LAN traffic with the transparent gateway (--gateway).
Fields
| Field | Default | Notes |
|---|---|---|
enable | false | turn Enhanced Mode on |
backend | tun on Windows and macOS, ebpf on Linux | see Backends |
ip-version | "ipv4" | ipv4, ipv6 or dual; see below |
ip-version per backend:
| Value | TUN (Windows, macOS) | eBPF (Linux) |
|---|---|---|
ipv4 | IPv4 routes only; IPv6 traffic keeps the normal network | IPv4 captured; IPv6 is never captured |
dual | IPv4 and IPv6 routes | same as ipv4 |
ipv6 | IPv6 routes only. The IPv4 Fake-IP range is then not routed either, so names that get a Fake-IP stop working. Do not use it | Core refuses to start: eBPF process proxy requires IPv4; set enhanced-mode.ip-version to ipv4 |
Stay with ipv4 unless you have a reason. Keep [dns] ipv6 = false so programs get IPv4 answers.
Backend tables: [enhanced-mode.tun] on TUN, [enhanced-mode.ebpf] on Linux eBPF. A profile may contain both; only the one for the selected backend has an effect. [enhanced-mode.tun] is still validated on Linux. Any other key under [enhanced-mode], including the old type, is rejected with Unknown enhanced-mode field.
Privileges
Enhanced Mode needs administrator rights. Ordinary proxy mode through the local port does not.
| Platform | What is needed | How |
|---|---|---|
| Windows | an elevated Core | the installed Specola service (specola-service, runs as LocalSystem), or Core started as Administrator. wintun.dll must sit next to the Core executable |
| macOS | Core running as root | sudo, or let Core ask: see below |
| Linux | Core running as root | sudo, a systemd service, or let Core ask: see below |
On macOS and Linux, when the profile Core starts with enables Enhanced Mode and Core is not root, Core asks for authorization once and restarts itself as root: an administrator dialog on macOS, the desktop authentication dialog (polkit, pkexec) on Linux. If you decline, Core exits. Switching to such a profile while Core is already running does not ask; it fails with a message such as TUN requires administrator privileges. Restart specola-core with sudo, or enable TUN in the startup profile and restart Core to request authorization.
How it works with the rest of Specola
Local port. The local HTTP/SOCKS5 port keeps working next to Enhanced Mode.
- TUN does not need the local port. Connections to it come from
127.0.0.1and never enter TUN. - eBPF hands captured TCP and UDP connections to Core through the local port's port number, so
[general] portmust be greater than 0. Withprotocols = "none"the port stays open for eBPF but does not accept HTTP or SOCKS5 clients. Withport = 0eBPF fails to start (Linux eBPF inbound setup failed).
DNS. Domain rules need to know which name a captured connection is for. Enhanced Mode answers the computer's DNS queries itself and gives out Fake-IP addresses (from [dns] fake-ip-range) for names a rule sends through a proxy; a connection to a Fake-IP is routed by its name. How the queries reach Core differs:
| Backend | DNS capture |
|---|---|
| TUN, Windows | an NRPT rule sends the system resolver to Core's virtual DNS address; every UDP query to port 53 that enters the adapter is answered by Core. dns-hijack = false turns both off |
| TUN, macOS | the DNS servers of the primary network service are set to 127.0.0.1 and restored when TUN stops; Core listens on 127.0.0.1:53 |
| eBPF | every TCP and UDP query to port 53, to any server, is redirected to Core (listening on 127.0.0.1:5353); the system DNS settings are not changed |
See DNS for how answers are chosen, and the backend pages for the details.
Sniffer. For captured TCP connections Core can read the HTTP Host header or the TLS SNI and use the name for domain rules, even when the program resolved it on its own (for example with DNS over HTTPS). It is on by default and applies only to Enhanced Mode and the router gateway, never to the local port. Connections to a Fake-IP are not sniffed: their name is already known. See Sniffer.
Final target. Captured connections that no rule matches go to [route] final-enhanced when it names an existing proxy or group, otherwise to the rule list's FINAL. See Rules.
Process rules work with both backends, with differences in UDP, pinning and which programs are exempt. See Process Rules.
Hot reload
Activating the profile again applies changes without restarting Core:
- Turning Enhanced Mode on or off, or changing anything under
[enhanced-mode]or[sniffer], stops and restarts only the capture (the TUN adapter or the eBPF programs). DNS is rebuilt too when[dns]changed or when the DNS mode changes, for example when Enhanced Mode is turned on or off. - Rule, proxy and group changes keep the capture running. On eBPF, the set of connections the kernel sends to Core is recalculated in place.
- Linux eBPF: a change to the local port,
[dns],[enhanced-mode]or[sniffer]rebuilds the whole runtime, because eBPF shares the local port and the DNS module. Expect open connections to drop.
If the new capture fails to start, the previous configuration is restored. A profile that does not validate leaves the running one untouched.
Platform comparison
| Windows (TUN) | macOS (TUN) | Linux (eBPF) | |
|---|---|---|---|
| Captures | what the routes send into the adapter | what the routes send into the interface | sockets of every process in Core's network namespace |
| Never captured | Specola's own outgoing connections; destinations with a more specific route elsewhere (LAN, VPNs, exclude-routes) | same as Windows | Core and the Specola app; loopback, private, link-local, multicast, broadcast and local addresses (except DNS); IPv6 |
| Process of TCP connections | socket table, exact | socket table, exact | kernel, exact |
| Process of UDP | best effort | best effort | kernel, exact |
| Process rules pin group members | no | no | yes (pinning) |
| Specola app exempt | no | no | yes |
| IPv6 | with ip-version = "dual" | with ip-version = "dual" | never |
| System changes | adapter, routes, NRPT rule | interface, routes, DNS of the primary service | none outside the eBPF programs |
| Privileges | elevated Core (service) | root | root |
| Main settings | [enhanced-mode.tun] | [enhanced-mode.tun] (fewer keys apply) | [enhanced-mode.ebpf] |
Stopping safely
Stop Core normally (quit the app, Ctrl+C, stop the service, systemctl stop) so it can undo its changes. Do not use kill -9 or end the process in Task Manager.
- Windows: the adapter and its routes disappear with the process; only the NRPT DNS rule can stay. Core removes a leftover rule every time it starts, and the service runs
specola-service.exe --reset-networkwhen it is ended abnormally. See TUN troubleshooting. - macOS: the DNS servers of the primary network service stay at
127.0.0.1after a forced kill. See TUN troubleshooting. - Linux: the eBPF programs are detached when the process ends, however it ends.
Troubleshooting
| Message or symptom | Cause and fix |
|---|---|
Unknown enhanced-mode field: type | the key is backend |
enhanced-mode.backend must be tun or ebpf | WFP, WinDivert, NetFilter and Network Extension backends do not exist in this build |
enhanced-mode.backend=tun is not supported on Linux | remove backend or write ebpf |
Enhanced mode requires the TUN backend on Windows / on macOS | remove backend or write tun |
... requires administrator privileges | see Privileges |
| Domain rules never match captured traffic | the program uses its own encrypted DNS. Keep the sniffer on, or match it with an IP or process rule |
| IPv6 sites bypass Specola | expected with ip-version = "ipv4" and always on eBPF. Keep [dns] ipv6 = false |
