singboxer/references/ref-dns.md

sing-box DNS Reference

DNS Configuration Structure

{
  "dns": {
    "servers": [],
    "rules": [],
    "final": "dns-default",
    "strategy": "",
    "disable_cache": false,
    "disable_expire": false,
    "independent_cache": false,
    "cache_capacity": 0,
    "reverse_mapping": false,
    "client_subnet": ""
  }
}

DNS Server Types (13)

local — System DNS resolver

{
  "type": "local",
  "tag": "dns-local"
}

udp — Plain UDP DNS

{
  "type": "udp",
  "tag": "dns-udp",
  "server": "8.8.8.8",
  "server_port": 53
}

tcp — Plain TCP DNS

{
  "type": "tcp",
  "tag": "dns-tcp",
  "server": "8.8.8.8",
  "server_port": 53
}

tls — DNS over TLS (DoT)

{
  "type": "tls",
  "tag": "dns-dot",
  "server": "dns.google",
  "server_port": 853
}

quic — DNS over QUIC (DoQ)

{
  "type": "quic",
  "tag": "dns-doq",
  "server": "dns.adguard-dns.com",
  "server_port": 853
}

https — DNS over HTTPS (DoH)

{
  "type": "https",
  "tag": "dns-doh",
  "server": "dns.google",
  "server_port": 443,
  "path": "/dns-query"
}

h3 — DNS over HTTP/3

{
  "type": "h3",
  "tag": "dns-h3",
  "server": "dns.google",
  "server_port": 443,
  "path": "/dns-query"
}

dhcp — DHCP-provided DNS

{
  "type": "dhcp",
  "tag": "dns-dhcp",
  "interface": "eth0"
}

fakeip — Fake IP DNS

{
  "type": "fakeip",
  "tag": "dns-fakeip",
  "inet4_range": "198.18.0.0/15",
  "inet6_range": "fc00::/18"
}

hosts — Static hosts file

{
  "type": "hosts",
  "tag": "dns-hosts",
  "path": "/etc/hosts"
}

rcode — Return specific response code

{
  "type": "rcode",
  "tag": "dns-block",
  "rcode": "success"
}

Rcodes: success, format_error, server_failure, name_error (NXDOMAIN), not_implemented, refused

tailscale — Tailscale MagicDNS

{
  "type": "tailscale",
  "tag": "dns-tailscale"
}

resolved — Reference to resolved service

{
  "type": "resolved",
  "tag": "dns-resolved",
  "service_tag": "resolved-service"
}

DNS Server Common Fields

All DNS server types support:

{
  "type": "...",
  "tag": "unique-tag",
  "detour": "outbound-tag",
  "domain_resolver": {
    "server": "bootstrap-dns-tag",
    "strategy": "prefer_ipv4"
  },
  "strategy": "prefer_ipv4",
  "disable_cache": false,
  "disable_expire": false,
  "independent_cache": false,
  "cache_capacity": 0,
  "rewrite_ttl": 0,
  "client_subnet": ""
}

• detour: Outbound used for DNS transport connection (e.g., send DoH queries through proxy)
• domain_resolver: Bootstrap DNS for resolving the DNS server's own domain name
• strategy: prefer_ipv4, prefer_ipv6, ipv4_only, ipv6_only
• client_subnet: EDNS Client Subnet for geo-aware responses

DNS Rules

DNS rules route queries to specific DNS servers. Same match criteria as route rules plus:

{
  "dns": {
    "rules": [
      {
        "query_type": ["A", "AAAA"],
        "domain_suffix": [".cn"],
        "action": "route",
        "server": "dns-cn"
      }
    ]
  }
}

DNS Rule Actions

route — Route to DNS server

{
  "action": "route",
  "server": "dns-server-tag",
  "strategy": "prefer_ipv4",
  "disable_cache": false,
  "rewrite_ttl": 0,
  "client_subnet": ""
}

route-options — Modify DNS options

{
  "action": "route-options",
  "disable_cache": true
}

reject — Reject DNS query

{
  "action": "reject"
}

predefined — Return predefined response

{
  "action": "predefined",
  "rcode": "success",
  "answer": [],
  "ns": [],
  "extra": []
}

Common DNS Patterns

Pattern: Split DNS (domestic + foreign)

{
  "dns": {
    "servers": [
      {
        "type": "https",
        "tag": "dns-google",
        "server": "dns.google",
        "server_port": 443,
        "path": "/dns-query",
        "detour": "proxy"
      },
      {
        "type": "https",
        "tag": "dns-alidns",
        "server": "dns.alidns.com",
        "server_port": 443,
        "path": "/dns-query",
        "detour": "direct"
      },
      {
        "type": "udp",
        "tag": "dns-bootstrap",
        "server": "223.5.5.5"
      }
    ],
    "rules": [
      {
        "rule_set": ["geosite-cn"],
        "action": "route",
        "server": "dns-alidns"
      }
    ],
    "final": "dns-google"
  }
}

Pattern: FakeIP for TUN

{
  "dns": {
    "servers": [
      {
        "type": "https",
        "tag": "dns-remote",
        "server": "dns.google",
        "path": "/dns-query",
        "detour": "proxy"
      },
      {
        "type": "fakeip",
        "tag": "dns-fakeip",
        "inet4_range": "198.18.0.0/15",
        "inet6_range": "fc00::/18"
      },
      {
        "type": "udp",
        "tag": "dns-local",
        "server": "223.5.5.5"
      }
    ],
    "rules": [
      {
        "rule_set": ["geosite-cn"],
        "action": "route",
        "server": "dns-local"
      },
      {
        "query_type": ["A", "AAAA"],
        "action": "route",
        "server": "dns-fakeip"
      }
    ],
    "final": "dns-remote"
  }
}

Pattern: Ad-blocking DNS

{
  "dns": {
    "rules": [
      {
        "rule_set": ["adblock-domains"],
        "action": "predefined",
        "rcode": "name_error"
      }
    ]
  }
}

Pattern: DNS Bootstrap Chain

When a DoH server needs DNS to resolve its own hostname:

{
  "servers": [
    {
      "type": "https",
      "tag": "dns-secure",
      "server": "dns.google",
      "domain_resolver": {
        "server": "dns-bootstrap",
        "strategy": "ipv4_only"
      }
    },
    {
      "type": "udp",
      "tag": "dns-bootstrap",
      "server": "8.8.8.8"
    }
  ]
}

Pattern: EDNS Client Subnet

{
  "type": "https",
  "tag": "dns-with-subnet",
  "server": "dns.google",
  "client_subnet": "1.2.3.0/24"
}