Local DNS Mapping

Chute supports local-customized DNS mapping. It's equivalent to /etc/hosts, but with more powerful features, including wildcard, alias and assigning DNS server.

[Host]
abc.com = 1.2.3.4
*.dev = 6.7.8.9
foo.com = bar.com
bar.com = server:8.8.8.8

Note: The mapping lines described here are also accepted in a [DNS] section, next to the DNS server options. See DNS Section. The Shadowrocket ssid: form (Per-Network DNS) is the exception: it is recognized in [Host] only, and in [DNS] it is read as a mapping for a name that never occurs.

A mapping may list several addresses, IPv4 and IPv6 mixed: dns.google = 8.8.8.8, 8.8.4.4, 2001:4860:4860::8888. An A question is answered with the IPv4 addresses and an AAAA question with the IPv6 ones. A list that holds anything but addresses is a configuration error. A name mapped to addresses of one family only gets an empty answer (NODATA) to a question for the other family; the upstream servers are not asked. A name can also take two lines, one mapping its IPv4 addresses and one its IPv6 ones. A mapping that a configuration reload or a module adds takes effect at once. An upstream NXDOMAIN answer is not cached for a name covered by a [Host] mapping or alias; the local mapping or alias takes precedence.

Wildcard

You can use * prefix to wildcard all sub-domains. Please note that Chute uses a simple string match. For example, *google.com will match google.com, foo.google.com and bargoogle.com. And *.google.com will not match google.com.

[Host]
*.dev = 6.7.8.9

Alias

It's equivalent to CNAME record.

[Host]
foo.com = bar.com

An A or AAAA lookup for the aliased name is answered with the target's addresses, so the client does not have to follow the alias itself. When the target has no address of the family that was asked for, the answer is empty rather than a record of the other family. Chute resolves the target when the rule is loaded; if it is not resolved yet, the answer is the CNAME record and the target is resolved for the next lookup.

Assigning DNS Server

You can assign a specified DNS server to one or more domains.

[Host]
bar.com = server:8.8.8.8

server: also accepts a DoH URL, so a specified DoH endpoint can be assigned to the domains directly.

[Host]
*.example.com = server:https://doh.example/dns-query

server: accepts a comma-separated list of servers. Every usable entry is kept and they are asked at the same time; the first answer wins. An entry may be an IP address with an optional port (8.8.8.8:5353, [2001:db8::1]:5353), system, syslib (force-syslib is the same) or a DoH URL. An IP address or a DoH URL may end with the #proxy suffix; system and syslib written with it are dropped with a warning, because the system resolver cannot be sent through a policy. A tcp://IP[:port] entry asks that server over DNS over TCP.

[Host]
bar.com = server:8.8.8.8, 8.8.4.4

You can assign system DNS server to one or more domains. Chute will only use system DNS configuration to query these domains.

[Host]
devs = server:system

Since Chute has its own DNS client implementation, some hostnames may fail to resolve. You can use server:syslib to let system handle the lookup.

[Host]
Macbook = server:syslib

Assigning DoH Service

You can assign a specified DoH service to one or more domains.

[Host]
bar.com = doh:cloudflare

By default, A and AAAA questions for hostnames with suffix .local are resolved by the system. Questions of other types — PTR, SRV, TXT — go to the configured upstream servers.

Assigning DoT Service

You can assign a specified DoT (DNS-over-TLS) service to one or more domains.

[Host]
bar.com = dot:dns.google

A dot: entry cannot carry the #proxy suffix.

Assigning DoQ Service

You can assign a specified DoQ (DNS-over-QUIC) service to one or more domains.

[Host]
bar.com = doq:dns.adguard.com

The entry may end with the #proxy suffix, as in bar.com = doq:dns.adguard.com#proxy=HK, to send the query through that policy. The policy name is kept exactly as written.

Assigning DoH3 Service

You can assign a specified DoH3 (DNS-over-HTTP/3) service to one or more domains.

[Host]
bar.com = doh3:https://dns.google/dns-query

Like a DoQ entry, it may end with the #proxy suffix.

Rule Set Keys

The key may be a rule set instead of a domain pattern:

[Host]
RULE-SET:https://example.com/cn-domains.list = server:223.5.5.5
RULE-SET:MyProvider = server:https://doh.pub/dns-query
DOMAIN-SET:https://example.com/ad-hosts.txt = 0.0.0.0

RULE-SET:<source> takes a URL or the name of a rule provider; DOMAIN-SET:<source> takes a URL. Only the domain rules of the set take part — IP and other rule types are ignored. The set is downloaded and refreshed the same way as when a [Rule] line uses it, and every domain it matches gets the value on the right. The built-in SYSTEM and LAN sets cannot be used here.

DNS Script

[Host]
*.corp.example = script:CorpResolver

script:<name> hands the lookup of matching domains to the type=dns script with that name — both for questions apps send and for Chute's own lookups. When the script returns no address, or no enabled dns script has that name, the domain resolves normally.

Per-Network DNS (Shadowrocket)

[Host]
ssid:Home WiFi = server:192.168.1.1

Shadowrocket's ssid:<network name> = server:<servers> is read as an [SSID Setting] DNS override for that Wi-Fi network: while the device is on it, these servers replace the plain resolvers of the main pool. The network name may contain spaces. Only plain resolvers count here — an address with an optional port, system or syslib; a DoH URL, which server: takes elsewhere in [Host], is dropped with a notice.

System Hosts File

[General]
read-etc-hosts = false

On macOS and Android, Chute also reads the system's hosts file, /etc/hosts, and adds its entries to this table ahead of the [Host] lines, so when a name appears in both, the hosts file's address wins. read-etc-hosts in [General] switches this and is on by default; set it to false to leave the file out. Chute iOS and tvOS never read a hosts file.

Combined Usage

All features can be used together. For example:

[Host]
*.dev = foo.com
*.bar.com = server:system
Macbook = server:syslib
*.foo.com = doh:cloudflare
*.local = dot:dns.google
api.internal = doq:dns.adguard.com