DNS Server

You can use this option to override system's DNS settings. Chute supports DNS server, DoH (DNS-over-HTTPS), DoT (DNS-over-TLS), DoQ (DNS-over-QUIC), and DoH3 (DNS-over-HTTP/3) services.

[General]
dns-server = 8.8.8.8, 8.8.4.4
doh = cloudflare, google, 1111
dot = dns.google, cloudflare-dns.com
doq = dns.adguard.com
doh3 = https://dns.google/dns-query

You can use keyword system to append additional DNS servers to system's setting. (Duplicate servers will be ignored)

You can use keyword syslib to get DNS result with system built-in API. On macOS the pool-level syslib is skipped while the TUN interface is active, since the system resolver then points back at Chute; server:syslib in [Host] and the .local path still use it.

[General]
dns-server = system, syslib, 8.8.8.8, 8.8.4.4

An entry may carry a port — 192.0.2.53:5353, or [2001:db8::1]:5353 for IPv6. Host names are not accepted in dns-server; use DoH, DoT, DoQ or DoH3 for a resolver known by name. Those may be written right here as well, with their scheme — https://, tls://, quic:// or h3:// — and join doh, dot, doq or doh3, as in encrypted-dns-server.

Currently, there are 5 built-in DoH services. The identifiers are lowercase and case-sensitive:

• cloudflare (Cloudflare)
• google (Google)
• 1111 (1.1.1.1)
• securedns (SecureDNS)
• dnssb (DNS.SB)

You can also config your personal DoH service. For example, if you using https://dns.nextdns.io/xxxxxx as your NextDNS DoH endpoint, you can config like this:

[General]
doh = google, dns.nextdns.io/xxxxxx

An invalid DoH entry is reported as a configuration error and the doh line is rejected.

For compatibility with Surge configurations, the spellings doh-server and doh-service are accepted as aliases of doh.

DNS-over-TLS (DoT) Service

You can configure DoT services to encrypt DNS queries over TLS.

[General]
dot = dns.google, cloudflare-dns.com

Each DoT service entry should be a domain name that supports DNS-over-TLS. Chute will connect to the hostname on port 853 by default; an entry may also be written as host:port or host:port:peer-name (use [IPv6]:port for IPv6 addresses) to override the port and the TLS peer name.

If the DoT hostname cannot be resolved or is unreachable, it will be silently skipped.

You can mix DoT, DoH, DoQ, DoH3, and traditional DNS servers in the same configuration:

[General]
dns-server = system, 8.8.8.8
doh = cloudflare
dot = dns.google
doq = dns.adguard.com
doh3 = https://dns.google/dns-query

DNS-over-QUIC (DoQ) Service

You can configure DoQ servers to encrypt DNS queries over QUIC.

[General]
doq = dns.adguard.com

Each DoQ entry should be a domain name or IP address that supports DNS-over-QUIC. Port 853 is used by default; an entry may also be written as host:port or host:port:peer-name (use [IPv6]:port for IPv6 addresses) to override the port and the TLS peer name. Chute uses QUIC transport for DNS queries, which offers reduced latency compared to TCP-based DNS encryption.

Multiple DoQ servers can be specified, separated by commas:

[General]
doq = dns.adguard.com, dns.nextdns.io

If a DoQ server is unreachable, it will be silently skipped.

DNS-over-HTTP/3 (DoH3) Service

You can configure DoH3 services for DNS-over-HTTPS using HTTP/3 (QUIC) transport.

[General]
doh3 = https://dns.google/dns-query

Each DoH3 entry should be a full HTTPS URL to a DNS resolver that supports HTTP/3. Multiple DoH3 servers can be specified, separated by commas:

[General]
doh3 = https://dns.google/dns-query, https://cloudflare-dns.com/dns-query

DoH3 combines the privacy of DNS-over-HTTPS with the performance benefits of QUIC transport. If a DoH3 server does not support HTTP/3 or is unreachable, it will be silently skipped.

DNS over TCP

[General]
dns-server = tcp://8.8.8.8, tcp://[2001:4860:4860::8888]:53

A resolver written as tcp://IP[:port] is asked over TCP (RFC 7766) instead of UDP; the port defaults to 53. Use it on a network that drops or tampers with DNS over UDP. It is accepted wherever a plain resolver is: in dns-server, the dedicated pools, the dns-server= of an SSID Suspend entry and a [Host] server: list. Like a plain resolver, it takes an IP address only — not a host name, system or syslib. The per-server options, such as #disable-qtype=, apply as usual. With #proxy the query goes through that policy, over TCP as every proxied plain query does. encrypted-dns-server does not take it.

Dedicated DNS Pools

Besides the main pool above, three optional pools serve particular names:

[General]
direct-dns-server = 223.5.5.5, https://doh.pub/dns-query, system
proxy-dns-server = 1.1.1.1, tls://dns.google
fallback-dns-server = 8.8.8.8

direct-dns-server

Resolves domains whose rule verdict is DIRECT: the lookups Chute makes when it dials a direct connection, and an app's question when that question reaches Chute's resolver — one sent to Chute's DNS listening port, a name listed in always-real-ip, or a record type other than A and AAAA. Under TUN, apps' A and AAAA questions do not reach it: the fake IP layer answers them directly, whatever the rules say. Only domain rules are consulted, so a question from an app for a domain no domain rule matches — one whose verdict depends on an IP rule such as IP-CIDR or GEOIP — follows FINAL: this pool when FINAL is DIRECT, the main pool when it is a proxy. Chute's own lookup for such a domain uses the main pool, because the connection is not bound to DIRECT yet. When the key is not set, the main pool answers everything.

proxy-dns-server

Resolves the host names of your proxy servers. When the key is not set, they use the main pool.

fallback-dns-server

Asked once when the main pool returns no answer at all, just before the lookup fails. Like the other DNS keys it may be written in [General] or in [DNS], and only once.

Entries in these pools may mix transports: ip[:port], [v6][:port], system, syslib, a DoH URL (https://…), tls://host[:port] for DoT, quic://host[:port] for DoQ and h3://… for DoH3. Plain, DoH, DoT, DoQ and DoH3 entries may end with the #proxy suffix; system#proxy and syslib#proxy are skipped with a warning. When direct-dns-server or proxy-dns-server returns no answer, the query is retried on the main pool. Each key may appear only once. A tcp://IP[:port] entry is asked over DNS over TCP.

For compatibility with Shadowrocket, dns-direct-system = true is read as direct-dns-server = system and saved in that form. Likewise dns-fallback-system = true appends system to fallback-dns-server; when the profile declares fallback-dns-server as well, the two are merged into one pool.

Encrypted DNS Options

encrypted-dns-server

encrypted-dns-server = https://dns.google/dns-query, tls://dns.google, quic://dns.adguard.com, h3://cloudflare-dns.com/dns-query

Surge's single list for encrypted resolvers. Each entry joins doh, dot, doq or doh3 according to its scheme (https://, tls://, quic://, h3://); tcp:// and other schemes are ignored with a notice. For DNS over TCP, write tcp:// in dns-server or a dedicated pool instead — see DNS over TCP.

encrypted-dns-follow-outbound-mode (Default: false)

encrypted-dns-follow-outbound-mode = true

Makes the connections to DoH, DoT, DoQ and DoH3 upstreams follow the outbound mode and the rules like any other request: direct in Direct mode, the selected policy in Global mode, and in Rule mode the policy of the matching rule — PROTOCOL,DOH, PROTOCOL,DOT, PROTOCOL,DOQ and PROTOCOL,DOH3 match them. An upstream whose verdict is REJECT is skipped. DoQ and DoH3 speak QUIC, so their connection goes through the chosen policy's UDP relay; when that policy — for a group, its current pick — carries no UDP, udp-policy-not-supported-behaviour decides: REJECT, the default, skips the upstream, and DIRECT asks it directly.

encrypted-dns-skip-cert-verification (Default: false)

encrypted-dns-skip-cert-verification = true

Do not verify the certificates of DoH, DoT, DoQ and DoH3 upstreams — for a resolver with a self-signed certificate. It also removes the protection against an impersonated resolver.

Sending a Query Through a Policy

[General]
dns-server = 1.1.1.1#proxy, 8.8.8.8#proxy=HK
doh = https://dns.google/dns-query#proxy=Proxy%20Group
doq = dns.adguard.com#proxy=HK

An entry of dns-server, doh, dot, doq, doh3 or one of the dedicated pools may end with #proxy or #proxy=<policy>: the query then goes through that policy instead of directly. #proxy alone uses the policy selected for Global mode or, when there is none, the policy of the FINAL rule; #proxy=<name> names a policy or group, with spaces written as %20. A plain DNS entry switches to DNS over TCP, since not every policy can relay UDP. A DoQ or DoH3 entry keeps QUIC, and its connection goes through the policy's UDP relay: when the policy — for a group, its current pick — carries no UDP, that upstream is skipped with a warning, never asked directly. A policy that does not exist, or resolves to REJECT, skips the upstream. Lookups of a proxy server's own host name never use a proxied upstream.

Per-server Options

[General]
dns-server = 1.1.1.1#disable-ipv6, 8.8.8.8#disable-qtype=65
doh = https://dns.google/dns-query#h3=true, https://10.0.0.1/dns-query#skip-cert-verify=true

The same # fragment carries options that apply to that one server. Several are joined with &, and =true may be left off:

• h3=true — ask a DoH server over HTTP/3 instead of HTTP/2.
• skip-cert-verify=true — do not verify this one upstream's certificate. For that server it removes the protection against an impersonated resolver, exactly as the global encrypted-dns-skip-cert-verification does for all of them.
• disable-ipv4=true / disable-ipv6=true — never ask this server for A / AAAA records.
• disable-qtype=65 — never ask it for that record type. disable-qtype-65 means the same, and a comma list disables several at once: 8.8.8.8#disable-qtype=65,64 is one entry with both types off. The split into entries knows about the # fragment, so a comma outside one still separates servers — 8.8.8.8#proxy, 1.1.1.1 is two of them.

A server a question type is disabled for is skipped before the query goes out, so it costs no attempt and no timeout; when every server in the pool refuses the type, the lookup fails instead of waiting for answers nobody sent.

HTTPS and SVCB Questions

allow-dns-svcb = true

Off by default: apps' HTTPS (type 65) and SVCB (type 64) questions are answered with an empty NOERROR response instead of being forwarded, because the address hints in those records would let an app connect around fake IP and the rules. Set it to true to forward them. The switch covers the questions apps send through TUN as well, both to Chute's own DNS address and to a resolver hijack-dns takes over. Chute's own ECH lookups are not affected.