Skip to content

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.

toml
[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.

PlatformbackendHow it capturesPage
Windowstun (default)a WinTUN virtual adapter; routes send traffic into itTUN
macOStun (default)a utun virtual interface; routes send traffic into itTUN
Linuxebpf (default)eBPF programs on cgroup v2 socket hooks redirect sockets to Core; no virtual interface, no route changesLinux 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:

  • backend must be tun or ebpf. Anything else (wfp, windivert, netfilter, network-extension, ...) is rejected: enhanced-mode.backend must be tun or ebpf.
  • On Linux, backend = "tun" with enable = true is 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 (or on 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 ​

FieldDefaultNotes
enablefalseturn Enhanced Mode on
backendtun on Windows and macOS, ebpf on Linuxsee Backends
ip-version"ipv4"ipv4, ipv6 or dual; see below

ip-version per backend:

ValueTUN (Windows, macOS)eBPF (Linux)
ipv4IPv4 routes only; IPv6 traffic keeps the normal networkIPv4 captured; IPv6 is never captured
dualIPv4 and IPv6 routessame as ipv4
ipv6IPv6 routes only. The IPv4 Fake-IP range is then not routed either, so names that get a Fake-IP stop working. Do not use itCore 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.

PlatformWhat is neededHow
Windowsan elevated Corethe installed Specola service (specola-service, runs as LocalSystem), or Core started as Administrator. wintun.dll must sit next to the Core executable
macOSCore running as rootsudo, or let Core ask: see below
LinuxCore running as rootsudo, 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.1 and never enter TUN.
  • eBPF hands captured TCP and UDP connections to Core through the local port's port number, so [general] port must be greater than 0. With protocols = "none" the port stays open for eBPF but does not accept HTTP or SOCKS5 clients. With port = 0 eBPF 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:

BackendDNS capture
TUN, Windowsan 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, macOSthe 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
eBPFevery 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)
Captureswhat the routes send into the adapterwhat the routes send into the interfacesockets of every process in Core's network namespace
Never capturedSpecola's own outgoing connections; destinations with a more specific route elsewhere (LAN, VPNs, exclude-routes)same as WindowsCore and the Specola app; loopback, private, link-local, multicast, broadcast and local addresses (except DNS); IPv6
Process of TCP connectionssocket table, exactsocket table, exactkernel, exact
Process of UDPbest effortbest effortkernel, exact
Process rules pin group membersnonoyes (pinning)
Specola app exemptnonoyes
IPv6with ip-version = "dual"with ip-version = "dual"never
System changesadapter, routes, NRPT ruleinterface, routes, DNS of the primary servicenone outside the eBPF programs
Privilegeselevated Core (service)rootroot
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-network when it is ended abnormally. See TUN troubleshooting.
  • macOS: the DNS servers of the primary network service stay at 127.0.0.1 after a forced kill. See TUN troubleshooting.
  • Linux: the eBPF programs are detached when the process ends, however it ends.

Troubleshooting ​

Message or symptomCause and fix
Unknown enhanced-mode field: typethe key is backend
enhanced-mode.backend must be tun or ebpfWFP, WinDivert, NetFilter and Network Extension backends do not exist in this build
enhanced-mode.backend=tun is not supported on Linuxremove backend or write ebpf
Enhanced mode requires the TUN backend on Windows / on macOSremove backend or write tun
... requires administrator privilegessee Privileges
Domain rules never match captured trafficthe program uses its own encrypted DNS. Keep the sniffer on, or match it with an IP or process rule
IPv6 sites bypass Specolaexpected with ip-version = "ipv4" and always on eBPF. Keep [dns] ipv6 = false