Skip to content

TUN ​

On Windows and macOS, Enhanced Mode creates a virtual network interface (TUN) and adds routes that send traffic into it. Core reads the packets, applies your rules and connects direct or through a proxy. On Linux use eBPF; backend = "tun" is rejected there.

toml
[enhanced-mode]
enable = true
backend = "tun"      # the default on Windows and macOS

[enhanced-mode.tun]
exclude-routes = ["192.168.0.0/16"]

Every field has a default; [enhanced-mode.tun] can be left out.

Fields ​

FieldDefaultWindowsmacOSNotes
auto-routetrueyesyesroute all traffic into TUN: 0.0.0.0/1 and 128.0.0.0/1, plus ::/1 and 8000::/1 when ip-version includes IPv6
routes[]yesyesextra CIDRs routed into TUN, in addition to auto-route
exclude-routes[]yesyesCIDRs removed from auto-route and routes; they keep the route the system already had
address"198.19.0.1/30"yesnoadapter address; the next address (198.19.0.2) is Core's virtual DNS server. IPv4, prefix 8 to 30. macOS always uses 10.0.0.1/24
dns-hijacktrueyesnosend the system resolver to Core. macOS always takes over system DNS while TUN runs
dns-namespaces["."]yesnoname suffixes the system resolver sends to Core: "." for every name, or suffixes such as ".example.com". Must not be empty while dns-hijack is on

Validation, on every platform:

  • An invalid CIDR in routes or exclude-routes is rejected with the field name: Invalid enhanced-mode.tun.routes entry: ....
  • address must leave room for the DNS address inside the subnet; 198.19.0.1/31 or a network address is rejected.
  • A dns-namespaces entry must be "." or start with a dot.
  • Any other key is rejected, including stack, auto-detect-interface and extra-routes.

CIDRs of a family that ip-version does not enable are ignored: with the default ipv4, IPv6 entries in routes do nothing.

What goes into TUN ​

The routes Core installs are, in order:

  1. The Fake-IP range, [dns] fake-ip-range (default 198.18.0.1/16), and the IPv6 Fake-IP range when [dns] ipv6 = true. These are always routed; exclude-routes does not remove them.
  2. With auto-route = true, the four half-ranges above. They are more specific than the default route, so the default route itself is left alone.
  3. Every CIDR in routes.

exclude-routes is subtracted from 2 and 3: 0.0.0.0/1 minus 10.0.0.0/8 becomes several smaller routes that skip 10.0.0.0/8. Nothing is installed on the physical interface.

With auto-route = false, only the Fake-IP range and routes enter TUN. That is enough for domain rules: names a rule sends through a proxy get a Fake-IP, and Fake-IP traffic always reaches Core.

What bypasses TUN ​

  • Specola's own connections. Core binds its outgoing sockets to the physical interface, so connections to proxy servers and its own DNS queries never loop back into TUN. You do not need to exclude proxy servers.
  • Destinations with a more specific route elsewhere: your LAN subnet, a VPN's routes (Tailscale's 100.64.0.0/10, corporate VPNs), and everything in exclude-routes.
  • Loopback (127.0.0.1, ::1), and with it the local HTTP/SOCKS5 port.
  • IPv6, when ip-version = "ipv4" (the default).
  • Programs that bind their sockets to a specific interface.

Inside TUN, multicast and broadcast packets are dropped. ICMP echo (ping) is answered by Core itself after 1 to 10 ms, so ping always succeeds for any address routed into TUN and does not test reachability.

DNS on Windows ​

With dns-hijack = true (the default):

  • Core installs a Name Resolution Policy Table (NRPT) rule that sends the names in dns-namespaces to Core's virtual DNS address (198.19.0.2 by default). The adapter's own DNS server is set to the same address, and the adapter gets the lowest interface metric.
  • Every UDP query to port 53 that enters the adapter is answered by Core, whatever server it was addressed to. Queries to a LAN resolver do not enter the adapter.
  • Core does not bind port 53; queries arrive through the adapter. [dns.listener] is separate and only opens when you enable it.

dns-namespaces narrows only what the system resolver sends to Core. A program that asks a public DNS server directly still gets its answer from Core when that server is routed into TUN.

A longer, more specific NRPT rule wins, so "." never overrides the suffix rules that Tailscale or a corporate VPN install. When another catch-all rule exists (a VPN's DNS override), Core logs another NRPT catch-all rule is active and the winner is undefined. If Group Policy defines NRPT rules, Core writes its rule into the Group Policy store, because Windows then ignores the local one.

With dns-hijack = false, nothing is redirected and Core does not answer queries inside TUN. DNS goes to your own servers, programs get real addresses, and domain rules work only through the sniffer (TCP to HTTP and TLS ports).

DNS on macOS ​

While TUN runs, Core sets the DNS servers of the primary network service (for example Wi-Fi) to 127.0.0.1 and answers on 127.0.0.1:53, whatever dns-hijack says. It forwards to the servers the service had (manual servers, or the DHCP servers from scutil --dns), or to 8.8.8.8 if it finds none. When TUN stops normally, the previous setting is restored, including "automatic".

  • Port 53 on 127.0.0.1 must be free, or DNS fails to start.
  • dns-namespaces has no effect. Programs that query another DNS server themselves are routed like any other UDP traffic, not answered by Core.
  • A [dns.listener] address is replaced by 127.0.0.1:53 while TUN runs.

Fake-IP and routing ​

A connection to a Fake-IP is routed by its name. If a rule sends it DIRECT (for example a process rule), Core resolves the name again and connects to the real address. Other connections are routed by their address, and by the name the sniffer finds for HTTP and TLS. See DNS.

Process rules on TUN ​

TUN captures by route, not by program: every connection that enters TUN is matched with its process.

  • Core looks the owner up in the system's socket table. TCP is exact. UDP is best effort: a socket that sends to many destinations or closes at once can come out unknown, and then process rules are skipped for it.
  • Process rules do not pin group members: every connection asks the group.
  • The Specola app is not exempt: its connections enter TUN and are routed like any other program. Core's own connections never enter TUN.
  • include-children follows the parent chain; on macOS also the responsible app.

Details: Process Rules.

IPv6 ​

ip-version = "dual" adds the IPv6 half-ranges. Core's own outgoing connections leave over IPv4 on the physical interface, so in this build IPv6 destinations sent DIRECT fail and proxy servers need an IPv4 address. ip-version = "ipv6" drops the IPv4 Fake-IP route as well and breaks Fake-IP names; do not use it. Keep ip-version = "ipv4" and [dns] ipv6 = false unless you have tested otherwise.

Privileges and setup ​

Windows. Core must be elevated. The installed Specola service (specola-service, LocalSystem) always is; the app talks to it without a prompt. A Core started by hand must run as Administrator. wintun.dll ships next to the Core executable. Without elevation Core reports TUN needs administrator privileges. Use the installed Specola service, or start Core as administrator.

macOS. Core must run as root. Start it with sudo, or enable TUN in the profile Core starts with: Core then asks for administrator authorization once and restarts itself as root. Switching to a TUN profile while Core runs without root only shows an error. See Privileges.

Core changes routes and DNS while TUN runs and undoes them when it stops normally. Quit the app or stop Core normally; do not force-kill it.

Troubleshooting ​

SymptomCause and fix
TUN needs administrator privileges (Windows)use the Specola service or an Administrator prompt
TUN requires administrator privileges (macOS)start Core with sudo, or enable TUN in the startup profile and restart Core
wintun.dll cannot be loadedreinstall; wintun.dll must be next to the Core executable
No DNS at all after Core was killed (Windows)a leftover NRPT rule. Start Core again (it removes the rule), or run specola-service.exe --reset-network as Administrator
No DNS at all after Core was killed (macOS)the primary service still points at 127.0.0.1. Run networksetup -setdnsservers Wi-Fi Empty (use your service name). Starting TUN again does not fix it: Core would save 127.0.0.1 as the setting to restore
Cannot start DNS (macOS)something else listens on port 53
LAN devices, printers or a NAS unreachablethey are outside your on-link subnet; add their range to exclude-routes
A VPN stops workingadd its ranges to exclude-routes
Trouble on a 10.0.0.0/24 network (macOS)macOS TUN always uses 10.0.0.1/24, which overlaps that LAN; use another LAN range
Domain rules never matchdns-hijack = false on Windows, or the program uses its own encrypted DNS; keep the sniffer on
A process rule misses UDP trafficUDP attribution is best effort on TUN; add a domain or IP rule
Ping succeeds but nothing connectsCore answers ping itself; test with a real connection