DNS — sing-box
DNS-движок sing-box — это список типизированных серверов плюс структурированная цепочка правил. Каждый сервер имеет type, выбирающий его транспорт (UDP, TLS, HTTPS, файл hosts, пул fake-ip, полученный по DHCP, systemd-resolved, встроенный Tailscale). Правила используют тот же набор полей сопоставления, что и правила маршрутизации, но с действиями, специфичными для DNS.
Параметры верхнего уровня
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
servers | []DNSServerOptions | [] | [DNSServerOptions] | Список DNS-серверов. Каждая запись имеет `type` (local, udp, tls, https, h3, dhcp, fakeip, hosts, resolved, tailscale) и соответствующий набор параметров. |
rules | []DNSRule | [] | [DNSRule] | Правила маршрутизации на уровне DNS. Той же формы, что правила маршрутизации, но с набором действий, специфичных для DNS. |
final | string | (unset) | <server tag> | DNS-сервер по умолчанию, когда ни одно правило не совпало. При пустом значении используется первый сервер из `servers[]`. |
reverse_mapping | bool | false | true | false | Вести обратное отображение (IP → домен), чтобы правила могли сопоставляться с исходным доменом после того, как соединение разрешило назначение в IP. |
Исходный код: option/dns.go:21-27 · зафиксировано на v1.13.15 (3708fa1)
Плюс встроенные DNSClientOptions:
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
strategy | DomainStrategy | (prefer_ipv4) | prefer_ipv4 | prefer_ipv6 | ipv4_only | ipv6_only | Предпочтение семейства адресов по умолчанию. |
disable_cache | bool | false | true | false | Отключить кэш ответов в памяти. |
disable_expire | bool | false | true | false | Не вытеснять кэшированные записи по TTL — хранить их бессрочно. |
independent_cache | bool | false | true | false | Использовать отдельный кэш на каждый тег сервера (вместо одного глобального кэша). |
cache_capacity | uint32 | (unbounded) | <int> | Максимум кэшированных записей. 0 снимает ограничение. |
client_subnet | *badoption.Prefixable | (unset) | <CIDR> | ECS (EDNS Client Subnet), объявляемый в исходящих запросах. |
Исходный код: option/dns.go:105-112 · зафиксировано на v1.13.15 (3708fa1)
Типы серверов
Каждая запись в servers[] имеет поле type. Соответствующие поля:
type: "local"
Разрешение через резолвер ОС (удобно на macOS/iOS, где системный резолвер — авторитетный путь). Добавляет prefer_go для перехода на Go-резолвер без CGO.
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
prefer_go | bool | false | true | false | Использовать net.Resolver из Go (без CGO) вместо нативного резолвера платформы. Полезно на системах, где нативный резолвер сломан или ограничен по частоте запросов. |
Исходный код: option/dns.go:376-379 · зафиксировано на v1.13.15 (3708fa1)
type: "udp" и type: "tcp" — RemoteDNSServerOptions
{ "type": "udp", "tag": "local-udp", "server": "8.8.8.8", "server_port": 53 }| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
server | string | (required) | <host> | Имя хоста или IP сервера. |
server_port | uint16 | 53 (udp/tcp), 853 (tls), 443 (https/h3) | <port> | Порт сервера. |
Исходный код: option/dns.go:332-335 · зафиксировано на v1.13.15 (3708fa1)
type: "tls" — DNS-over-TLS
Те же поля, что у udp/tcp, плюс стандартный блок tls:.
type: "https" и type: "h3" — DNS-over-HTTPS / -H3
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
path | string | /dns-query | /<path> | Путь конечной точки DoH. |
method | string | POST | POST | GET | HTTP-метод для DoH-запросов. |
headers | badoption.HTTPHeader | {} | {<header>: <value>} | Дополнительные HTTP-заголовки. |
Исходный код: option/dns.go:394-399 · зафиксировано на v1.13.15 (3708fa1)
type: "hosts" — локальный файл hosts
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
path | badoption.Listable[string] | [/etc/hosts] | [<file path>] | Список путей hosts-файлов для объединения. |
predefined | *badjson.TypedMap[string, badoption.Listable[netip.Addr]] | {} | {<domain>: [<IP>]} | Встроенная таблица hosts. Приоритет выше, чем у `path`. |
Исходный код: option/dns.go:363-366 · зафиксировано на v1.13.15 (3708fa1)
type: "fakeip"
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
inet4_range | *badoption.Prefix | (required for v4) | <CIDR> | IPv4 CIDR, выделяемый под поддельные IP. |
inet6_range | *badoption.Prefix | (required for v6) | <CIDR> | IPv6 CIDR, выделяемый под поддельные IP. |
Исходный код: option/dns.go:401-404 · зафиксировано на v1.13.15 (3708fa1)
type: "dhcp"
| Поле | Тип | По умолчанию | Допустимые значения | Описание |
|---|---|---|---|---|
interface | string | (auto) | <interface> | Интерфейс, чьи полученные по DHCP резолверы используются. |
Исходный код: option/dns.go:406-409 · зафиксировано на v1.13.15 (3708fa1)
Прочие типы
type: "resolved"— читать серверы имён systemd-resolved, привязанные к сетевым интерфейсам (только Linux).type: "tailscale"— использовать резолвер MagicDNS демона Tailscale.type: "predefined"— возвращать жёстко заданный набор ответов.type: "rcode"— возвращать фиксированный RCODE (NOERROR / NXDOMAIN / SERVFAIL и т. д.).
Правила DNS
Правила DNS используют ту же полиморфную форму _Rule, что и правила маршрутизации (type: "default" или type: "logical"), и тот же набор из 43 ключей сопоставления в RawDefaultDNSRule. Различия — на уровне действий:
| DNS-действие | Значение |
|---|---|
route (по умолчанию) | Отправить запрос в server: "<tag>". Необязательные поля: strategy, disable_cache, rewrite_ttl, client_subnet. |
route-options | Применить параметры DNS-маршрута к последующим совпадениям правил. |
reject | Отклонить запрос. С method: "default" (NXDOMAIN) или method: "drop" (без ответа). |
predefined | Вернуть жёстко заданный ответ (набор записей или RCODE). |
Примеры
Разделение на два сервера — внутренние домены через локальный DoH, всё остальное через DoH Cloudflare:
{
"dns": {
"servers": [
{ "type": "https", "tag": "local",
"server": "doh.pub", "path": "/dns-query" },
{ "type": "https", "tag": "remote",
"server": "cloudflare-dns.com", "path": "/dns-query",
"detour": "proxy" },
{ "type": "fakeip", "tag": "fakeip",
"inet4_range": "198.18.0.0/15",
"inet6_range": "fc00::/18" }
],
"rules": [
{ "rule_set": ["geosite-cn"], "server": "local" },
{ "outbound": "any", "server": "remote" }
],
"final": "remote",
"strategy": "prefer_ipv4"
}
}Блокировка рекламы через DNS:
{
"dns": {
"servers": [
{ "type": "https", "tag": "main",
"server": "cloudflare-dns.com" }
],
"rules": [
{
"domain_keyword": ["ads", "doubleclick", "googlesyndication"],
"action": "reject",
"method": "default"
}
],
"final": "main"
}
}Примечания
- Устаревший параметр верхнего уровня
fakeip: {...}объявлен устаревшим — вместо него используйте запись сервераtype: "fakeip". sing-box автоматически мигрирует старые конфигурации при загрузке, но выводит предупреждение об устаревании. reverse_mapping: trueпозволяет последующим правилам маршрутизации сопоставляться с доменным именем даже после того, как сниффинг разрешил его в IP. Необходимо при использовании fake-ip вместе со сложными доменными правилами.independent_cache: trueполезен, когда есть серверы, легитимно возвращающие разные ответы для одного и того же домена (split-horizon-резолверы).- Правила DNS и правила маршрутизации разделяют один и тот же словарь ключей сопоставления, но работают в разное время: правила DNS выполняются на запросе к резолверу; правила маршрутизации — на итоговом соединении.
type: "resolved"читает данные через D-Bus APIsystemd-resolved— работает только на Linux-системах, где resolved действительно является запущенным резолвером.
Сравнение с другими ядрами
- Xray-core использует плоский блок
dns:, гдеservers[]содержит URL-строки (или объекты NameServerConfig) — поляtypeнет, транспорт определяется схемой URL. См. DNS — Xray-core. - mihomo имеет блок
dns:из 25 полей с отдельными спискамиnameserver/fallbackи отображениемnameserver-policy. См. DNS — mihomo.
Исходный код: option/dns.go:21-409 · v1.13.15 (3708fa1)