singboxer/references/ref-dns.md

# sing-box DNS Reference

## DNS Configuration Structure

```json
{
  "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
```json
{
  "type": "local",
  "tag": "dns-local"
}
```

### `udp` — Plain UDP DNS
```json
{
  "type": "udp",
  "tag": "dns-udp",
  "server": "8.8.8.8",
  "server_port": 53
}
```

### `tcp` — Plain TCP DNS
```json
{
  "type": "tcp",
  "tag": "dns-tcp",
  "server": "8.8.8.8",
  "server_port": 53
}
```

### `tls` — DNS over TLS (DoT)
```json
{
  "type": "tls",
  "tag": "dns-dot",
  "server": "dns.google",
  "server_port": 853
}
```

### `quic` — DNS over QUIC (DoQ)
```json
{
  "type": "quic",
  "tag": "dns-doq",
  "server": "dns.adguard-dns.com",
  "server_port": 853
}
```

### `https` — DNS over HTTPS (DoH)
```json
{
  "type": "https",
  "tag": "dns-doh",
  "server": "dns.google",
  "server_port": 443,
  "path": "/dns-query"
}
```

### `h3` — DNS over HTTP/3
```json
{
  "type": "h3",
  "tag": "dns-h3",
  "server": "dns.google",
  "server_port": 443,
  "path": "/dns-query"
}
```

### `dhcp` — DHCP-provided DNS
```json
{
  "type": "dhcp",
  "tag": "dns-dhcp",
  "interface": "eth0"
}
```

### `fakeip` — Fake IP DNS
```json
{
  "type": "fakeip",
  "tag": "dns-fakeip",
  "inet4_range": "198.18.0.0/15",
  "inet6_range": "fc00::/18"
}
```

### `hosts` — Static hosts file
```json
{
  "type": "hosts",
  "tag": "dns-hosts",
  "path": "/etc/hosts"
}
```

### `rcode` — Return specific response code
```json
{
  "type": "rcode",
  "tag": "dns-block",
  "rcode": "success"
}
```
Rcodes: `success`, `format_error`, `server_failure`, `name_error` (NXDOMAIN), `not_implemented`, `refused`

### `tailscale` — Tailscale MagicDNS
```json
{
  "type": "tailscale",
  "tag": "dns-tailscale"
}
```

### `resolved` — Reference to resolved service
```json
{
  "type": "resolved",
  "tag": "dns-resolved",
  "service_tag": "resolved-service"
}
```

## DNS Server Common Fields

All DNS server types support:
```json
{
  "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:

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

### DNS Rule Actions

#### `route` — Route to DNS server
```json
{
  "action": "route",
  "server": "dns-server-tag",
  "strategy": "prefer_ipv4",
  "disable_cache": false,
  "rewrite_ttl": 0,
  "client_subnet": ""
}
```

#### `route-options` — Modify DNS options
```json
{
  "action": "route-options",
  "disable_cache": true
}
```

#### `reject` — Reject DNS query
```json
{
  "action": "reject"
}
```

#### `predefined` — Return predefined response
```json
{
  "action": "predefined",
  "rcode": "success",
  "answer": [],
  "ns": [],
  "extra": []
}
```

## Common DNS Patterns

### Pattern: Split DNS (domestic + foreign)
```json
{
  "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
```json
{
  "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
```json
{
  "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:
```json
{
  "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
```json
{
  "type": "https",
  "tag": "dns-with-subnet",
  "server": "dns.google",
  "client_subnet": "1.2.3.0/24"
}
```