DNS configuration

A server, WireGuard listener, or TUN entry can select an inline resolver or a named dns_group. Omitted dns uses the native system resolver; see native DNS freshness for its cache behavior. Use Fake DNS only when synthetic address mapping is needed.

Complete example: dns_tuning.yaml. Its proxy addresses and credentials need deployment-specific values.

- dns_group: secure-dns
  dns_servers:
    - url: tls://1.1.1.1
      server_name: cloudflare-dns.com
      timeout_secs: 5

- address: "127.0.0.1:1080"
  protocol: {type: socks}
  dns: {servers: secure-dns}

dns.servers and a group’s dns_servers each accept one server or a list. dns.server and dns_server are singular aliases. A plain string is either a named group reference or a resolver URL. Resolver URLs support system, udp://, tcp://, tls:// (DNS-over-TLS), https:// (DNS-over-HTTPS), and h3:// (DNS-over-HTTP/3). Default ports are 53, 53, 853, 443, and 443, respectively. A URL object accepts these options:

Field	Default	Meaning
url	Required	Resolver endpoint or system
server_name	URL hostname	TLS name override for TLS/HTTPS/H3
bootstrap_url	System resolver	IP-literal DNS URL, system, or named DNS group for resolving endpoint/proxy hostnames
client_chain	Direct	Proxy chain(s) used to reach this DNS upstream
ip_strategy	ipv4_then_ipv6	Address-family query order
timeout_secs	5	Whole lookup timeout; 0 disables it
connect_timeout_secs	5	Connection setup timeout
attempts	1	Query retry attempts
native_cache_secs	0	System-only application memoization window; see native DNS

ip_strategy also accepts ipv4_only, ipv6_only, ipv4_and_ipv6, and ipv6_then_ipv4. Option objects reject unknown fields. A non-system upstream cannot set native_cache_secs, even to zero. bootstrap_url must not itself contain a hostname; named groups may be used for multi-step bootstrap, but cycles are rejected.

TCP, TLS, and HTTPS upstreams can use proxy chains. UDP and H3 upstreams are direct-only, except a direct chain can set an interface binding; system does not support a client chain. WireGuard-routed DNS requires a literal upstream IP and no bootstrap_url. See remote rule sources for their stricter startup-bootstrap rules.