Built-in DNS Service

Custom Upstream DNS Servers

Stash supports configuring multiple DNS servers simultaneously. When making queries, Stash will send concurrent requests to all servers and use the fastest response. Stash supports the following DNS protocols:

• Use the system-provided DNS: system
• DNS over UDP: 8.8.8.8 or udp://8.8.8.8
• DNS over TCP: tcp://8.8.8.8
• DNS over TLS : tls://8.8.8.8:853
• DNS over HTTPS : https://1.1.1.1/dns-query
• DNS over HTTP/3: 'https://1.1.1.1/dns-query#h3=true'
• DNS over QUIC : quic://dns.adguard.com:853

Stash uses the LRU algorithm for local caching of DNS queries. When the local cache expires, Stash continues using the cached result while silently refreshing the record in the background, reducing latency caused by DNS cache expiration.

DNS over HTTP/3

DNS over HTTP/3 carries DoH requests over QUIC. It uses the same URL format as regular DNS over HTTPS; append #h3=true to select HTTP/3. This fragment does not become part of the DNS query path.

dns:
  nameserver:
    - 'https://1.1.1.1/dns-query#h3=true'

The complete address must be quoted; otherwise, YAML treats #h3=true as a comment.

Encrypted DNS bootstrap

default-nameserver can use encrypted DNS to resolve the hostnames of other DNS servers. Except for system, the server address must use an IP.

dns:
  default-nameserver:
    - 'https://1.1.1.1/dns-query#h3=true'

Proxy Server Domain Resolution

proxy-server-nameserver specifies the DNS servers used to resolve proxy server domain names. It uses an independent DNS query path that never follows proxy rules, preventing recursive queries while connecting to a proxy server.

dns:
  proxy-server-nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query

proxy-server-nameserver supports the same DNS protocols as nameserver. When multiple servers are configured, Stash queries them in parallel and uses the first successful response.

Domain-based Custom DNS Service

nameserver-policy allows using specific DNS servers for specified domain names or domain sets. It supports exact domains, wildcard domains, geosite sets in the geosite:<name> form, and rule sets in the rule-set:<name> form.

dns:
  # Use separate DNS servers for specific domain names
  nameserver-policy:
    'www.baidu.com': 114.114.114.114
    '+.internal.crop.com': system
    '*.example.com':
      - https://dns.alidns.com/dns-query
      - https://doh.pub/dns-query
    'geosite:cn,private':
      - 223.5.5.5
      - 119.29.29.29
    'rule-set:company-domains': 10.0.0.53
 
rule-providers:
  company-domains:
    behavior: domain
    url: https://example.com/company-domains.txt

The value of nameserver-policy can be either a single DNS server or an array of DNS servers. When multiple DNS servers are configured, Stash queries them in parallel and uses the first successful response.

A key may list several sets separated by commas: geosite:cn,private is the same as writing the same servers for geosite:cn and geosite:private separately.

When a domain matches multiple policies, precedence is exact domain > wildcard domain > set. If multiple set policies match, Stash uses the first match in configuration order.

Referencing Rule Sets

rule-set:<name> references a rule set declared under rule-providers and matches its domain entries; the domain behavior is recommended. fake-ip-filter accepts geosite: and rule-set: entries as well, so the same domain list can be shared with your routing rules.

Fallback DNS

fallback names a second group of DNS servers, and fallback-filter decides which queries take the fallback answer. A common setup sends domestic domains to a domestic resolver and everything else to a resolver abroad, avoiding polluted or poorly optimized answers from the domestic resolver for foreign domains.

dns:
  nameserver:
    - 223.5.5.5
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
    domain:
      - '+.google.com'
      - '+.youtube.com'

With fallback configured, Stash queries nameserver and fallback at the same time and picks an answer according to fallback-filter:

• Domains listed under domain are queried through fallback only.
• For every other domain, the nameserver answer is checked first: when it is empty, when any resolved address falls into ipcidr, or when geoip is on and an address is outside the country named by geoip-code, the fallback answer is used instead. Otherwise the nameserver answer stands.

geoip-code defaults to CN. Without fallback, fallback-filter has no effect and every query is answered by nameserver.

Fake-IP

By default, Stash answers DNS queries from apps in Fake-IP mode: it returns a virtual address from a reserved range right away, and the real lookup happens only when the connection is established and the rules require it. Related options:

• fake-ip-range: The range the virtual addresses come from, 198.18.0.1/16 by default.
• fake-ip-filter: Domains that bypass Fake-IP and receive the real answer. It accepts wildcard domains as well as geosite: and rule-set: sets.

dns:
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.stun.*.*'
    - '*.n.n.srv.nintendo.net'
    - 'geosite:private'
    - 'rule-set:real-ip-domains'

IPv6 Resolution

When neither option is set, Stash decides whether to resolve and return AAAA records from whether the current network has IPv6 connectivity. Both switches only change behavior when set to false:

• Top-level ipv6: false: Connections Stash makes itself resolve IPv4 only, and DNS queries from apps receive no AAAA records.
• dns.ipv6: false: DNS queries from apps receive no AAAA records, while Stash’s own connections may still use IPv6.

ipv6: false
 
dns:
  ipv6: false

Custom Hosts

# Support wildcard domain names (e.g., *.clash.dev, *.foo.*.example.com)
# Non-wildcard domain names take precedence over wildcard domain names (e.g., foo.example.com > *.example.com > .example.com)
# Note: The effect of +.foo.com is equivalent to .foo.com and foo.com
hosts:
  '*.clash.dev': 127.0.0.1
  '.dev': 127.0.0.1
  'alpha.clash.dev': ::1

DNS Query Follow Rules

By default, Stash sends DNS queries directly without passing through any proxy rules. When the follow-rule option is enabled, Stash will forward DNS queries based on proxy rules.