Skip to content

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.

text
 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, logs

1. Ingress: how a connection arrives ​

IngressWhat arrivesDestination known asProcess known
Local port ([general] port)TCP from programs set to use the HTTP or SOCKS5 proxythe host name the program sent, or an IPyes, for programs on this computer
TUN (Enhanced Mode, Windows and macOS)TCP and UDP routed into the virtual adapteran 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 portan IPyes, recorded by the kernel
Router gateway (Linux, --gateway)traffic of LAN devices, redirected with TPROXYan IPno; source address, MAC and device name instead
  • The local port listens on 127.0.0.1, or on all IPv4 addresses with allow-lan = true. It serves HTTP (CONNECT and plain http:// requests) and SOCKS5 CONNECT. 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-routes or 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-MAC or SRC-DEVICE rules.

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:

NameAnswer
in [dns] hoststhe configured address
a proxy server's own namereal address from the system's DNS servers, sent direct
routed to REJECTrefused
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 DIRECT is 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:

  1. [route] bypass: a matching name or address goes DIRECT, 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 check bypass.
  2. Route mode: direct sends everything direct, global sends everything to global-proxy.
  3. Rules (rule mode): 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.
  4. FINAL: nothing matched. final-mixed and final-enhanced can 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:

GroupPicks
selectthe member chosen in the app (the first one until you choose)
url-testthe member with the lowest measured delay (the first member before any check); switches only when another is faster by tolerance ms
fallbackthe first member whose last health check passed; the first member when none has
load-balanceconsistent-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:

  • DIRECT connects to the destination itself. For a Fake-IP destination Core resolves the name first.
  • REJECT closes 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, so A with dialer-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 changedWhat happens
log-level, log-fileapplied at once
route-mode, global-proxythe new mode applies; a mode picked in the app stays until one of these two changes in the file
port, protocols, allow-lanthe listener moves; existing connections keep running
api-listenthe 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-range changed;
  • 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.