How Specola Works
This page follows one connection through Core, from the moment it arrives to the moment its bytes flow. Knowing the order helps when a rule does not do what you expect: each step can only use what the steps before it found out.
program ──► ingress ──► process ──► DNS mapping / sniffing ──► rules ──► group ──► dialer ──► server
(port, TUN, (who (which host name (first (which (DIRECT,
eBPF, opened belongs to this IP) match) member) proxy, chain)
gateway) it)
telemetry: Connections, rule and proxy counters, logs1. Ingress: how a connection arrives
| Ingress | What arrives | Destination known as | Process known |
|---|---|---|---|
Local port ([general] port) | TCP from programs set to use the HTTP or SOCKS5 proxy | the host name the program sent, or an IP | yes, for programs on this computer |
| TUN (Enhanced Mode, Windows and macOS) | TCP and UDP routed into the virtual adapter | an IP (a Fake-IP if Core answered the DNS query) | TCP yes, UDP best effort |
| eBPF (Enhanced Mode, Linux) | TCP and UDP the kernel selects, handed to Core's local port | an IP | yes, recorded by the kernel |
Router gateway (Linux, --gateway) | traffic of LAN devices, redirected with TPROXY | an IP | no; source address, MAC and device name instead |
- The local port listens on
127.0.0.1, or on all IPv4 addresses withallow-lan = true. It serves HTTP (CONNECTand plainhttp://requests) and SOCKS5CONNECT. It carries TCP only. A SOCKS5 client that sends a Fake-IP address is treated as if it had sent the host name behind it. - TUN captures by route: everything routed into the adapter, except what
exclude-routesor a more specific route keeps out. See TUN. - eBPF decides in the kernel, from your rules, which connections reach Core at all. Destinations on private networks and IPv6 are never captured. See Linux eBPF.
- Core's own connections to proxy servers are bound to the physical network interface, so they never loop back into Enhanced Mode.
2. Process attribution
Core finds the program that opened the connection, so process rules can match it:
- Local port: Core asks the operating system which process owns the client socket. Only connections from the same computer have one.
- TUN: Core looks up the owner of each new flow in the system's socket table. Exact for TCP; short-lived UDP sockets can come out unknown.
- eBPF: the kernel records the process when the socket is created.
- Router gateway: LAN devices have no local process. Use
SRC-IP-CIDR,SRC-MACorSRC-DEVICErules.
When the process is unknown, every process rule is skipped. Rules with include-children also ask for the chain of parent processes.
3. DNS: which host name belongs to this address
Enhanced Mode sees IP addresses, but most rules are about host names. Core closes that gap by answering the DNS queries itself and remembering which name each answer belongs to. A DNS module runs when Enhanced Mode is on, when [dns] listener is enabled, or in router gateway mode.
For a query captured by Enhanced Mode, Core decides the route of the name first, then answers:
| Name | Answer |
|---|---|
in [dns] hosts | the configured address |
| a proxy server's own name | real address from the system's DNS servers, sent direct |
routed to REJECT | refused |
routed to a proxy, mode = "fake-ip" (default) | a Fake-IP from fake-ip-range (default 198.18.0.1/16) |
routed to DIRECT, mode = "fake-ip" | real address from the system's DNS servers |
any name, mode = "fake-ip-all" | a Fake-IP |
any name, mode = "real-ip" | real address from the system's DNS servers |
- When a connection later goes to a Fake-IP, Core knows the exact name behind it and matches the rules with that name. A Fake-IP connection that ends up
DIRECTis resolved again by Core. - A real answer for a name that goes through a proxy is fetched through that proxy from
nameserver-proxy. Core remembers the address too, so a later connection to it is matched with the name. - On Linux eBPF, names that no domain or IP rule decides also get Fake-IP answers, so that their connections are captured and can be matched with the process.
- Answers are cached. A reload that changes proxies, groups or rules clears the cache, because cached answers carry route decisions.
DNS queries come from the system resolver, not from the program, so process rules never decide a DNS answer. On the local port, programs usually send the host name themselves and no DNS step is needed. See DNS.
4. Sniffing
For connections captured by Enhanced Mode or the router gateway, Core can read the host name from the first bytes: the Host header of HTTP, or the server name (SNI) of a TLS handshake. It only does this on the ports in http-ports and tls-ports, and skips it when the destination is a Fake-IP, which already names the host. A sniffed name takes part in rule matching. With override-destination = true, the proxy is also asked to connect to the sniffed name instead of the IP (not for DIRECT). The local port is never sniffed. See Sniffer.
5. Rule matching
Core now knows the destination (name and/or IP, port), the network (TCP or UDP), the process if any, and for gateway traffic the source device. It decides in this order:
[route] bypass: a matching name or address goesDIRECT, before anything else. This holds for Enhanced Mode and the gateway, and for the local port in Global and Direct mode. In Rule mode the local port currently does not checkbypass.- Route mode:
directsends everything direct,globalsends everything toglobal-proxy. - Rules (
rulemode): checked in the order written; the first rule that matches wins. A domain rule and a process rule compete only by position. Rules switched off in the app are skipped. FINAL: nothing matched.final-mixedandfinal-enhancedcan give the local port and Enhanced Mode their own final target.
With resolve-unknown-domains = true, a host name that no rule matched is resolved and the rules are tried again with its addresses, so IP and GeoIP rules can match. On the local port this is done for SOCKS5 requests that carry a name, and only while a DNS module runs.
Results of domain-only and IPv4-only lookups are cached (4096 entries each); the cache belongs to the rule table and is replaced with it on reload. See Rules.
6. Group selection
When the target is a proxy group, the group picks a member at connection time:
| Group | Picks |
|---|---|
select | the member chosen in the app (the first one until you choose) |
url-test | the member with the lowest measured delay (the first member before any check); switches only when another is faster by tolerance ms |
fallback | the first member whose last health check passed; the first member when none has |
load-balance | consistent-hashing: the same member for the same host name (or process path); round-robin: the next member |
Health checks run every interval seconds against url; without interval there are none. On Linux eBPF, a process rule that targets a group keeps the member it picked first, see pinned members. See Proxy Groups.
7. Dialing
The chosen outbound connects:
DIRECTconnects to the destination itself. For a Fake-IP destination Core resolves the name first.REJECTcloses the connection.- A proxy connects to its server and asks it to reach the destination. If the proxy has a
dialer-proxy, Core first connects to that proxy (or group member) and reaches the server through it. The chain is built from the inside out, soAwithdialer-proxy = "B"means you →B→A→ destination. See Proxy Chains.
The host passed to the proxy is the original host name when Core has one (from the program, a Fake-IP, or sniffing with override-destination), otherwise the IP.
8. Telemetry
While the connection runs, Core records:
- the connection itself, with ingress, process, matched rule, route, group and proxy, for the Connections page;
- hits and bytes per rule, shown on the Rules page;
- connections, latency and bytes per proxy and per group;
- total traffic for the overview charts;
- log lines, kept in memory and, with
log-file = true, in daily files kept for 7 days.
Reloading a profile
Activating a profile while another one runs reloads Core in place: Core compares the new profile with the running one and changes only what differs. Nothing restarts and the running connections keep going.
| What changed | What happens |
|---|---|
log-level, log-file | applied at once |
route-mode, global-proxy | the new mode applies; a mode picked in the app stays until one of these two changes in the file |
port, protocols, allow-lan | the listener moves; existing connections keep running |
api-listen | the TCP control API moves; the old listener serves about 2 more seconds |
proxies, groups, [route] | new proxy and rule tables replace the old ones; see below |
[dns] | the DNS module is rebuilt, and Enhanced Mode with it |
[sniffer], [enhanced-mode] | Enhanced Mode capture is rebuilt |
When proxies, groups or rules change:
- group choices and health results are kept for the groups and members that still exist;
- proxies whose settings did not change keep running as they are;
- Fake-IP mappings are kept, unless
fake-ip-rangechanged; - the DNS answer cache is cleared and Enhanced Mode recomputes what it captures.
Under Linux eBPF, a change to the listener, DNS, Enhanced Mode or the sniffer rebuilds the whole runtime instead, because eBPF uses the listener and the DNS module directly.
A reload is all or nothing. If a step fails, the steps before it are undone and the previous profile keeps running. A profile that fails to load or validate never touches the running one. The Enhanced Mode switch in the app changes only the running Core; activating the profile again applies the [enhanced-mode] enable written in the file.
See Architecture for how a profile file becomes the running configuration.
