DNS Overview
Surge uses its own DNS client for all outgoing requests and for rule evaluation. It may behave differently from the DNS client of your operating system, and it is tuned for performance and reliability rather than strict RFC resolver semantics.
Surge's DNS subsystem has two roles:
- The internal DNS client resolves domains for connections that Surge itself establishes and for rules that need an IP address (such as
IP-CIDRandGEOIP). Its behavior is described on this page. - A DNS responder for the virtual network interface: when Enhanced Mode or the iOS VPN tunnel is active, DNS queries from the system and other devices are answered by Surge directly, normally with fake IP addresses. See Advanced DNS Topics.
To customize the upstream servers used by the internal client, see DNS Servers and Encrypted DNS. To override results for specific domains, see Local DNS Mapping.
Concurrent Querying
Surge queries all configured DNS servers simultaneously to improve performance, similar to dnsmasq with the --all-servers parameter. The first valid answer wins. Surge iOS and Surge Dashboard show which server responded first.
While no answer has arrived, Surge resends the query to all servers 1, 2 and 4 seconds after the first query. If there is still no answer 5 seconds after the first query, the lookup fails with a DNS error, and a connection waiting for it fails right away instead of at the connection timeout iOS 6.0.0+ Mac 6.12.0+.
The first resend comes quickly because a lost UDP packet is the most common reason for a missing answer; the longer gaps afterwards give a slow server time to answer without flooding it. Earlier versions resend up to 5 times, and a lookup without any answer can take about 11 seconds to fail.
Queries to encrypted DNS servers use a reliable transport, so they are sent again on this schedule only after the previous attempt failed with an error. The 5-second limit applies to them too.
A and AAAA Queries
When IPv6 is enabled (ipv6 = true in [General]) and the current network has IPv6 connectivity, Surge sends both A and AAAA questions in parallel and waits for both answers before completing the lookup. If only one record type has been answered by the first resend (1 second after the first query), Surge completes the lookup with the partial result.
If 5 consecutive lookups receive an A answer while the AAAA answer times out, Surge concludes that the upstream servers never return AAAA answers on the current network and stops sending AAAA questions. A log event is raised when this happens. AAAA querying resumes after a network change or a DNS cache flush.
Empty Answers
An answer without records (NOERROR with an empty answer section, or NXDOMAIN) is a valid answer, and it is treated like any other: the first answer for each record type wins, and Surge does not wait for the other servers. If the lookup ends without any address, it fails with an empty DNS answer error. This keeps lookups fast for the many names that legitimately have no record of a type, such as the AAAA record of an IPv4-only domain.
Answers with other response codes, such as SERVFAIL or REFUSED, are ignored: Surge keeps waiting for the other servers and resends the query as described above.
As a consequence, if one of the configured servers sometimes returns empty answers for names that do exist, lookups may fail whenever it answers first. Remove such a server from the list, or assign specific domains to reliable servers with a server: item in Local DNS Mapping.
Caching
Results are cached according to the TTL of the returned records (the smallest TTL in the record set determines the expiry).
Surge uses optimistic caching: when a cached entry has expired, it is still returned to the caller immediately, while a refresh query runs in the background. This removes DNS latency from repeated connections at the cost of occasionally using a slightly stale address.
The cache holds up to 200 entries on iOS and 2000 entries on macOS, with least-recently-used eviction. The cache is flushed automatically on network changes, and can be flushed manually from the UI, the CLI, or the HTTP API. Identical in-flight lookups are coalesced into a single query.
Special Hostnames
- Simple hostnames (names without a dot, such as
nas): Surge appends the system's first search domain (nas→nas.example.lan) and forwards the query to the system DNS servers. - Names ending with
.local: resolved through the system resolver library by default, so mDNS/Bonjour names keep working. See Local DNS Mapping for related options. - Fully qualified names with a trailing dot (
example.com.): the trailing dot is stripped and search-domain rewriting is suppressed. - IP literals: returned as-is without any lookup.