DNS
Specola needs DNS for one reason: to know which name a connection belongs to, so domain rules can match. On the local HTTP/SOCKS5 port the application sends the name itself. In Enhanced Mode the application resolves the name first and connects to an address, so Core answers its DNS queries and remembers which name each answer belongs to.
Start without [dns]. The defaults work for most setups.
[dns]
ipv6 = false
mode = "fake-ip"
fake-ip-range = "198.18.0.1/16"
nameserver-proxy = ["https://1.1.1.1/dns-query", "8.8.8.8"]
hosts = { "nas.lan" = "192.168.1.10" }
listener = { enable = false, address = "127.0.0.1:1053" }Fields
[dns] accepts exactly these six keys. Any other key fails with Unknown dns field.
| Field | Default | Notes |
|---|---|---|
ipv6 | false | answer AAAA queries. When false, an AAAA query gets an empty answer. Always off with Linux eBPF |
mode | "fake-ip" | fake-ip, fake-ip-all or real-ip; see Fake-IP. Only affects queries from captured traffic |
fake-ip-range | "198.18.0.1/16" | IPv4 block for Fake-IP answers; see the range |
nameserver-proxy | [] | resolvers for names routed through a proxy, queried through that proxy. Empty: the system DNS servers, queried through the proxy |
hosts | {} | fixed answers; inline table |
listener | { enable = false, address = "127.0.0.1:1053" } | a DNS server for other programs; inline table |
hosts and listener must be inline tables. [dns.hosts] or [dns.listener] written as separate tables fail to load.
When Core answers DNS
Core runs its DNS module only when one of these is true:
| Setup | Who sends queries to Core |
|---|---|
| Enhanced Mode, TUN on Windows | the system resolver, through an NRPT rule (see Windows) |
| Enhanced Mode, TUN on macOS | the system resolver, pointed at 127.0.0.1 (see macOS) |
| Enhanced Mode, Linux eBPF | DNS packets of captured programs (see Linux eBPF) |
| Router gateway | the LAN's DNS traffic |
listener.enable = true | whatever program you point at the listener |
Without any of these, Core has no DNS module. The local port still works: names routed through a proxy are resolved by the proxy server, and names routed DIRECT are resolved by the operating system when Core connects.
How a query is answered
Core handles each query in this order:
- AAAA with
ipv6 = false: empty answer. - The name is routed. The route mode applies (
direct→DIRECT,global→ the global proxy). Inrulemode the rules are matched with the name only (see what decides a DNS answer), thenFINAL(final-enhancedfor captured traffic).bypassis not checked here; it applies to the connection. The host names of your[[proxy]]servers skip routing and are always resolved with the system DNS servers. REJECT:REFUSED. (Linux eBPF answers with a Fake-IP instead, so the decision is made when the connection arrives.)hosts: an entry in[dns].hostsor the system hosts file is answered from there.- Fake-IP, for captured traffic, depending on
mode; see Fake-IP. - Forwarded upstream; see Resolvers.
What decides a DNS answer
A DNS query carries only a name. Rules that need more than the name cannot match it:
- Domain rules decide. So do GeoSite rules.
- IP rules (
IP-CIDR,GEOIP, …),DST-PORT,NETWORKand process rules never match a query. InAND/OR/NOTthey count as unknown:ANDwith an unknown part does not match. - Source rules decide only for a query from a LAN device through the router gateway.
- If nothing decides,
FINALdoes.
The connection that follows the answer is routed again with everything it carries, so a process or IP rule can still send it elsewhere. Process rules never decide a DNS answer; see Process Rules.
Resolvers
| Name routed to | Asked | Through |
|---|---|---|
DIRECT | the system DNS servers | directly |
| a proxy or group | nameserver-proxy (or the system DNS servers when it is empty) | that proxy |
your [[proxy]] server names | the system DNS servers | directly |
anything, with mode = "real-ip" | the system DNS servers | directly |
System DNS servers are the servers the operating system used when Core started:
- Windows and macOS: the DNS servers of the network adapter that holds the default route. With TUN on macOS, the servers that were set before Core redirected the system resolver.
- Linux:
nameserverlines of/etc/resolv.conf, then/run/systemd/resolve/resolv.conf, then the OpenWrt files/tmp/resolv.conf.d/resolv.conf.autoand/tmp/resolv.conf.auto. Loopback entries, such as a local stub resolver, are skipped.
nameserver-proxy entries are tried in order. Each attempt waits up to 5 seconds. A timeout, an error, or an error answer other than NXDOMAIN moves on to the next entry. When all fail, the query gets SERVFAIL.
| Format | Protocol | Default port |
|---|---|---|
8.8.8.8 or udp://8.8.8.8 | UDP | 53 |
tcp://8.8.8.8 | TCP | 53 |
https://dns.example.com/dns-query | DNS over HTTPS | 443 |
- Add
:portto change the port; write IPv6 addresses in brackets (udp://[2606:4700::1111]:53). - Other schemes, including
tls://, fail to load. - A host name in an entry (
https://dns.example.com/...) is resolved with the system DNS servers. - A UDP query through a proxy that cannot carry UDP falls back to TCP. A truncated UDP answer is asked again over TCP.
Fake-IP
A Fake-IP is an address from a private pool that Core hands out instead of the real one. When the application connects to it, Core maps it back to the name and gives the name to the proxy. The proxy server resolves the name, so the real address never has to be looked up on this computer.
mode decides which names get a Fake-IP:
mode | Names routed to a proxy | Names routed DIRECT |
|---|---|---|
fake-ip (default) | Fake-IP | real address (system DNS) |
fake-ip-all | Fake-IP | Fake-IP; Core resolves the name again when the connection arrives |
real-ip | real address (system DNS, not through the proxy) | real address (system DNS) |
Only these queries can get a Fake-IP:
- A queries, and AAAA queries when
ipv6 = true; - from captured traffic: TUN, Linux eBPF, LAN clients of the router gateway, and the listener while Enhanced Mode or the gateway runs;
- not for the host names of your
[[proxy]]servers, and not for names inhosts.
A standalone listener (without Enhanced Mode or the gateway) never hands out Fake-IPs.
| Property | Value |
|---|---|
| IPv4 pool | fake-ip-range, default 198.18.0.1/16 |
| IPv6 pool | fd00::1/18, fixed, only with ipv6 = true |
| Answer TTL | 300 seconds |
| Mappings kept | up to 65535 |
real-ip keeps domain rules working: Core remembers which name each real answer belongs to. Use it when IP rules (for example GEOIP,CN,DIRECT) must see real addresses, or when an application cannot handle Fake-IPs. The cost: names routed through a proxy are resolved by your local DNS servers, in plain text, and the proxy connects to whatever address that DNS returned.
IP rules and Fake-IP. A Fake-IP connection carries the name but no usable address, so IP rules do not match it. With mode = "fake-ip", a name that no domain rule decides and whose FINAL is a proxy gets a Fake-IP, and GEOIP,CN,DIRECT never sees its real address. Use GeoSite or domain rules, or real-ip.
The Fake-IP range
fake-ip-range is an IPv4 CIDR with a prefix of /30 or shorter. The first address handed out is the one you write (or the first host address of the block), the last is the one before the broadcast address.
The range must lie inside 198.18.0.0/15, the block reserved for benchmarking (RFC 2544). A profile with any other block fails to load with dns.fake-ip-range must lie within 198.18.0.0/15: private and local destinations pass the Linux eBPF program and the router gateway untouched, and a range there could shadow real hosts. The range must also stay clear of [enhanced-mode.tun] address (default 198.19.0.1/30), or loading fails with dns.fake-ip-range ... overlaps enhanced-mode.tun.address.
DNS in Enhanced Mode
Windows (TUN)
[enhanced-mode.tun]
dns-hijack = true # default
dns-namespaces = ["."] # default: every name- With
dns-hijack = true, Core adds an NRPT rule that sends the names indns-namespacesto its virtual DNS server, the address after the TUN adapter address (198.19.0.2by default). Adapter DNS settings are not edited. The rule is removed when TUN stops, and a rule left by a Core that was killed is removed at the next start. - With
dns-hijack = true, every UDP DNS query (port 53) that enters the TUN adapter is answered by Core. No local port 53 is taken. dns-namespaceslimits which names are sent to Core:"."is every name,".example.com"that domain and its subdomains. It must not be empty whiledns-hijackis on.- With
dns-hijack = false, Core does not answer DNS for Windows. Queries leave as ordinary traffic and domain rules depend on the sniffer. [dns].listeneris started only when you enable it, at itsaddress.
macOS (TUN)
- While TUN runs, Core points the system DNS of the active network service at
127.0.0.1and serves DNS on127.0.0.1:53, UDP and TCP. It restores the previous servers when TUN stops normally. dns-hijackanddns-namespaceshave no effect on macOS.[dns].listener.addressis not used; Core always listens on127.0.0.1:53.
Linux eBPF
- DNS queries (UDP port 53) of captured programs are sent to Core's DNS module. Core also listens on
127.0.0.1:5353;[dns].listener.addressis not used. The system resolver is not changed. - IPv6 is always off: AAAA queries get an empty answer, because eBPF captures IPv4 only.
- With
mode = "fake-ip", eBPF hands out Fake-IPs more widely than TUN so that the connection is captured and can be routed with its process:
| Name | Answer |
|---|---|
a domain rule sends it DIRECT | real address (Fake-IP with fake-ip-all) |
| a domain rule sends it to a proxy | Fake-IP |
a domain rule sends it to REJECT | Fake-IP; the connection is refused when it arrives |
| no domain rule decides it | Fake-IP, whatever FINAL is |
any name, mode = "real-ip" | real address |
See Linux eBPF for what eBPF captures.
Router gateway
DNS queries of LAN clients get the same treatment as captured traffic: Fake-IPs by mode, and source rules (SRC-IP-CIDR, SRC-MAC, SRC-DEVICE) decide per device.
Without Enhanced Mode
On the local HTTP/SOCKS5 port:
- Domain rules match the name the application sends.
- A name routed through a proxy is passed to the proxy and resolved on the proxy server.
hostsandnameserver-proxyare not used for it. - A name routed
DIRECTis resolved by the operating system. When Core's DNS module runs (for example because the listener is on), Core resolves it instead, with the system DNS servers andhosts: first A, then AAAA. Withipv6 = falsethat AAAA answer is empty, so an IPv6-only name cannot be reachedDIRECT. - IP rules see names only with
resolve-unknown-domains.
The listener answers real addresses: names routed to a proxy are resolved with nameserver-proxy through that proxy, DIRECT names with the system DNS servers, REJECT names get REFUSED. Fake-IP needs Enhanced Mode.
IPv6
ipv6 = false (the default) answers every AAAA query with an empty answer, so applications use IPv4. With ipv6 = true, AAAA queries are answered: real addresses, or Fake-IPs from fd00::1/18 where an IPv4 query would get a Fake-IP. Linux eBPF always behaves as false. Check that Enhanced Mode also captures IPv6 before turning it on ([enhanced-mode] ip-version).
Hosts
[dns]
hosts = { "nas.lan" = "192.168.1.10", "dev.example.com" = ["10.0.0.5", "fd00::5"] }- Each key is an exact name. There are no wildcards; case and a trailing dot are ignored.
- Each value is one IP address or a non-empty list of them. An invalid address or a duplicate name fails to load.
- Core also reads the system hosts file (
/etc/hosts, or%SystemRoot%\System32\drivers\etc\hosts). A profile entry replaces the file's entry for the same name. - A hosts answer has a TTL of 60 seconds and is never a Fake-IP. An A query for a name with only IPv6 entries gets an empty answer, and the other way round.
REJECTcomes first: a rejected name getsREFUSEDeven if it is inhosts.hostsapplies to queries Core answers and to Core's own lookups forDIRECTconnections. It does not apply to names that the local port passes to a proxy.
Local DNS listener
[dns]
listener = { enable = true, address = "127.0.0.1:1053" }| Field | Default | Notes |
|---|---|---|
enable | false | |
address | "127.0.0.1:1053" | an IPv4 address, or localhost, and a port. UDP and TCP |
The listener is for programs you point at it by hand. Enhanced Mode does not need it. With TUN on macOS and with Linux eBPF, Core listens on its own fixed address and address is not used. If the DNS module cannot bind its port, the profile fails to start or reload with Cannot start DNS. Binding a port below 1024 needs administrator rights.
Caches and reload
- Answers are cached up to their TTL, at most 4096 entries. Empty answers and failures are cached for 30 seconds.
- Name memory: for every real answer, Core remembers the name for at least 10 minutes, so a later connection to that address is matched by name.
- Fake-IP mappings are leased for 300 seconds, up to 65535 at a time.
When the profile is reloaded in place:
- A change to proxies, groups or rules drops cached answers. Fake-IP mappings stay.
- A change in
[dns], or toroute.resolve-unknown-domains, rebuilds the DNS module, and with it Enhanced Mode capture. On Linux eBPF the whole runtime is rebuilt. Fake-IP mappings stay, unlessfake-ip-rangechanged.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| A domain rule never matches in Enhanced Mode | the application uses its own DNS (DNS over HTTPS, "secure DNS" in browsers), so Core never sees the name. Turn that off, or rely on the sniffer, or match by process or IP |
| Same, on Windows | dns-hijack = false, or the name is outside dns-namespaces |
| Domain rules work, IP or GeoIP rules do not | the name got a Fake-IP; see IP rules and Fake-IP |
dns.fake-ip-range must lie within 198.18.0.0/15 | pick a block inside 198.18.0.0/15, such as the default 198.18.0.1/16; see the range |
198.18.x.x addresses still show up after Specola stops | the operating system or the application cached a Fake-IP answer. Flush the system DNS cache or restart the application |
Some names fail with SERVFAIL | every nameserver-proxy entry failed through the proxy. Check that the proxy reaches the resolver; try tcp:// or https:// if the proxy has no UDP |
| IPv6-only sites fail | ipv6 = false; on Linux eBPF that is expected |
Cannot start DNS | the listener port, or 127.0.0.1:53 on macOS, is used by another program |
Older documents show [dns.upstream], [dns.tun], [dns.nameserver-policy], [dns.fallback-filter], [dns.system-proxy], route-resolution, respect-rules, cache fields, use-hosts, and flat fields such as enable, listen, nameserver, fallback or enhanced-mode. None of them exists; each fails to load with Unknown dns field.
See also Rules, Process Rules, Sniffer, TUN and Linux eBPF.
