Skip to content

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.

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

FieldDefaultNotes
ipv6falseanswer 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:

SetupWho sends queries to Core
Enhanced Mode, TUN on Windowsthe system resolver, through an NRPT rule (see Windows)
Enhanced Mode, TUN on macOSthe system resolver, pointed at 127.0.0.1 (see macOS)
Enhanced Mode, Linux eBPFDNS packets of captured programs (see Linux eBPF)
Router gatewaythe LAN's DNS traffic
listener.enable = truewhatever 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:

  1. AAAA with ipv6 = false: empty answer.
  2. The name is routed. The route mode applies (direct → DIRECT, global → the global proxy). In rule mode the rules are matched with the name only (see what decides a DNS answer), then FINAL (final-enhanced for captured traffic). bypass is 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.
  3. REJECT: REFUSED. (Linux eBPF answers with a Fake-IP instead, so the decision is made when the connection arrives.)
  4. hosts: an entry in [dns].hosts or the system hosts file is answered from there.
  5. Fake-IP, for captured traffic, depending on mode; see Fake-IP.
  6. 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, NETWORK and process rules never match a query. In AND/OR/NOT they count as unknown: AND with an unknown part does not match.
  • Source rules decide only for a query from a LAN device through the router gateway.
  • If nothing decides, FINAL does.

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 toAskedThrough
DIRECTthe system DNS serversdirectly
a proxy or groupnameserver-proxy (or the system DNS servers when it is empty)that proxy
your [[proxy]] server namesthe system DNS serversdirectly
anything, with mode = "real-ip"the system DNS serversdirectly

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: nameserver lines of /etc/resolv.conf, then /run/systemd/resolve/resolv.conf, then the OpenWrt files /tmp/resolv.conf.d/resolv.conf.auto and /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.

FormatProtocolDefault port
8.8.8.8 or udp://8.8.8.8UDP53
tcp://8.8.8.8TCP53
https://dns.example.com/dns-queryDNS over HTTPS443
  • Add :port to 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:

modeNames routed to a proxyNames routed DIRECT
fake-ip (default)Fake-IPreal address (system DNS)
fake-ip-allFake-IPFake-IP; Core resolves the name again when the connection arrives
real-ipreal 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 in hosts.

A standalone listener (without Enhanced Mode or the gateway) never hands out Fake-IPs.

PropertyValue
IPv4 poolfake-ip-range, default 198.18.0.1/16
IPv6 poolfd00::1/18, fixed, only with ipv6 = true
Answer TTL300 seconds
Mappings keptup 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) ​

toml
[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 in dns-namespaces to its virtual DNS server, the address after the TUN adapter address (198.19.0.2 by 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-namespaces limits which names are sent to Core: "." is every name, ".example.com" that domain and its subdomains. It must not be empty while dns-hijack is 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].listener is started only when you enable it, at its address.

macOS (TUN) ​

  • While TUN runs, Core points the system DNS of the active network service at 127.0.0.1 and serves DNS on 127.0.0.1:53, UDP and TCP. It restores the previous servers when TUN stops normally.
  • dns-hijack and dns-namespaces have no effect on macOS.
  • [dns].listener.address is not used; Core always listens on 127.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.address is 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:
NameAnswer
a domain rule sends it DIRECTreal address (Fake-IP with fake-ip-all)
a domain rule sends it to a proxyFake-IP
a domain rule sends it to REJECTFake-IP; the connection is refused when it arrives
no domain rule decides itFake-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. hosts and nameserver-proxy are not used for it.
  • A name routed DIRECT is 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 and hosts: first A, then AAAA. With ipv6 = false that AAAA answer is empty, so an IPv6-only name cannot be reached DIRECT.
  • 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 ​

toml
[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.
  • REJECT comes first: a rejected name gets REFUSED even if it is in hosts.
  • hosts applies to queries Core answers and to Core's own lookups for DIRECT connections. It does not apply to names that the local port passes to a proxy.

Local DNS listener ​

toml
[dns]
listener = { enable = true, address = "127.0.0.1:1053" }
FieldDefaultNotes
enablefalse
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 to route.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, unless fake-ip-range changed.

Troubleshooting ​

SymptomLikely cause
A domain rule never matches in Enhanced Modethe 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 Windowsdns-hijack = false, or the name is outside dns-namespaces
Domain rules work, IP or GeoIP rules do notthe name got a Fake-IP; see IP rules and Fake-IP
dns.fake-ip-range must lie within 198.18.0.0/15pick 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 stopsthe operating system or the application cached a Fake-IP answer. Flush the system DNS cache or restart the application
Some names fail with SERVFAILevery 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 failipv6 = false; on Linux eBPF that is expected
Cannot start DNSthe 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.