timamsk/sing-box
1
0
Fork 0
mirror of https://github.com/SagerNet/sing-box.git synced 2026-04-13 20:28:32 +10:00
Code Issues Packages Projects Releases Wiki Activity

documentation: Refactor DNS

Browse Source
This commit is contained in:
世界
2025-01-25 20:35:10 +08:00
parent 549daf9d41
commit a0a41ff2bb
24 changed files with 1710 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/configuration/dns/fakeip.md
View File

@@ -1,3 +1,11 @@
---
icon: material/delete-clock
---
!!! failure "Deprecated in sing-box 1.12.0"
Legacy fake-ip configuration is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-servers).
### Structure
```json

8
docs/configuration/dns/fakeip.zh.md
View File

@@ -1,3 +1,11 @@
---
icon: material/delete-clock
---
!!! failure "已在 sing-box 1.12.0 废弃"
旧的 fake-ip 配置已废弃且将在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/migration/#migrate-to-new-dns-servers)。
### 结构
```json

2
docs/configuration/dns/index.md
View File

@@ -49,8 +49,6 @@ Default domain strategy for resolving the domain names.
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
Take no effect if `server.strategy` is set.
#### disable_cache
Disable dns cache.

2
docs/configuration/dns/index.zh.md
View File

@@ -48,8 +48,6 @@ icon: material/new-box
可选值: `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
如果设置了 `server.strategy`，则不生效。
#### disable_cache
禁用 DNS 缓存。

11
docs/configuration/dns/rule_action.md
View File

@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [strategy](#strategy)
!!! question "Since sing-box 1.11.0"
### route
@@ -10,6 +14,7 @@ icon: material/new-box
{
"action": "route", // default
"server": "",
"strategy": "",
"disable_cache": false,
"rewrite_ttl": 0,
"client_subnet": null
@@ -24,6 +29,12 @@ icon: material/new-box
Tag of target server.
#### strategy
Set domain strategy for this query.
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
#### disable_cache
Disable cache and save cache in this query.

14
docs/configuration/dns/rule_action.zh.md
View File

@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [strategy](#strategy)
!!! question "自 sing-box 1.11.0 起"
### route
@@ -10,8 +14,8 @@ icon: material/new-box
{
"action": "route", // 默认
"server": "",
// 兼容性
"strategy": "",
"disable_cache": false,
"rewrite_ttl": 0,
"client_subnet": null
@@ -26,6 +30,12 @@ icon: material/new-box
目标 DNS 服务器的标签。
#### strategy
为此查询设置域名策略。
可选项：`prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
#### disable_cache
在此查询中禁用缓存。

38
docs/configuration/dns/server/dhcp.md Normal file
View File

@@ -0,0 +1,38 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# DHCP
### Structure
```json
{
"dns": {
"servers": [
{
"type": "dhcp",
"tag": "",
"interface": "",
// Dial Fields
}
]
}
}
```
### Fields
#### interface
Interface name to listen on.
Tge default interface will be used by default.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

35
docs/configuration/dns/server/fakeip.md Normal file
View File

@@ -0,0 +1,35 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# Fake IP
### Structure
```json
{
"dns": {
"servers": [
{
"type": "fakeip",
"tag": "",
"inet4_range": "198.18.0.0/15",
"inet6_range": "fc00::/18"
}
]
}
}
```
### Fields
#### inet4_range
IPv4 address range for FakeIP.
#### inet6_address
IPv6 address range for FakeIP.

71
docs/configuration/dns/server/http3.md Normal file
View File

@@ -0,0 +1,71 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# DNS over HTTP3 (DoH3)
### Structure
```json
{
"dns": {
"servers": [
{
"type": "h3",
"tag": "",
"server": "",
"server_port": 443,
"path": "",
"headers": {},
"tls": {},
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy H3 server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`853` will be used by default.
#### path
The path of the DNS server.
`/dns-query` will be used by default.
#### headers
Additional headers to be sent to the DNS server.
#### tls
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

71
docs/configuration/dns/server/https.md Normal file
View File

@@ -0,0 +1,71 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# DNS over HTTPS (DoH)
### Structure
```json
{
"dns": {
"servers": [
{
"type": "https",
"tag": "",
"server": "",
"server_port": 443,
"path": "",
"headers": {},
"tls": {},
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy HTTPS server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`853` will be used by default.
#### path
The path of the DNS server.
`/dns-query` will be used by default.
#### headers
Additional headers to be sent to the DNS server.
#### tls
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

46
docs/configuration/dns/server/index.md Normal file
View File

@@ -0,0 +1,46 @@
---
icon: material/alert-decagram
---
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [type](#type)
# DNS Server
### Structure
```json
{
"dns": {
"servers": [
{
"type": "",
"tag": ""
}
]
}
}
```
#### type
The type of the DNS server.
| Type | Format |
|-----------------|-----------------------------------------------------|
| empty (default) | [Legacy](/configuration/dns/server/legacy/) |
| `tcp` | [TCP](/configuration/dns/server/tcp/) |
| `udp` | [UDP](/configuration/dns/server/udp/) |
| `tls` | [TLS](/configuration/dns/server/tls/) |
| `https` | [HTTPS](/configuration/dns/server/https/) |
| `quic` | [QUIC](/configuration/dns/server/quic/) |
| `h3` | [HTTP/3](/configuration/dns/server/http3/) |
| `predefined` | [Predefined](/configuration/dns/server/predefined/) |
| `dhcp` | [DHCP](/configuration/dns/server/dhcp/) |
| `fakeip` | [Fake IP](/configuration/dns/server/fakeip/) |
#### tag
The tag of the DNS server.

8
docs/configuration/dns/server.md → docs/configuration/dns/server/legacy.md
View File

@@ -1,3 +1,11 @@
---
icon: material/delete-clock
---
!!! failure "Deprecated in sing-box 1.12.0"
Legacy DNS servers is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-servers).
!!! quote "Changes in sing-box 1.9.0"
:material-plus: [client_subnet](#client_subnet)

8
docs/configuration/dns/server.zh.md → docs/configuration/dns/server/legacy.zh.md
View File

@@ -1,3 +1,11 @@
---
icon: material/delete-clock
---
!!! failure "Deprecated in sing-box 1.12.0"
旧的 DNS 服务器配置已废弃且将在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/migration/#migrate-to-new-dns-servers)。
!!! quote "sing-box 1.9.0 中的更改"
:material-plus: [client_subnet](#client_subnet)

33
docs/configuration/dns/server/local.md Normal file
View File

@@ -0,0 +1,33 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# Local
### Structure
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "",
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy local server"
* The old legacy local server only handles IP requests; the new one handles all types of requests and supports concurrent for IP requests.
* The old local server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

93
docs/configuration/dns/server/predefined.md Normal file
View File

@@ -0,0 +1,93 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# Predefined
### Structure
```json
{
"dns": {
"servers": [
{
"type": "predefined",
"tag": "",
"responses": []
}
]
}
}
```
### Fields
#### responses
==Required==
List of [Response](#response-structure).
### Response Structure
```json
{
"query": [],
"query_type": [],
"rcode": "",
"answer": [],
"ns": [],
"extra": []
}
```
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item
### Response Fields
#### query
List of domain name to match.
#### query_type
List of query type to match.
#### rcode
The response code.
| Value | Value in the legacy rcode server | Description |
|------------|----------------------------------|-----------------|
| `NOERROR` | `success` | Ok |
| `FORMERR` | `format_error` | Bad request |
| `SERVFAIL` | `server_failure` | Server failure |
| `NXDOMAIN` | `name_error` | Not found |
| `NOTIMP` | `not_implemented` | Not implemented |
| `REFUSED` | `refused` | Refused |
`NOERROR` will be used by default.
#### answer
List of text DNS record to respond as answers.
Examples:
| Record Type | Example |
|-------------|-------------------------------|
| `A` | `localhost. IN A 127.0.0.1` |
| `AAAA` | `localhost. IN AAAA ::1` |
| `TXT` | `localhost. IN TXT \"Hello\"` |
#### ns
List of text DNS record to respond as name servers.
#### extra
List of text DNS record to respond as extra records.

58
docs/configuration/dns/server/quic.md Normal file
View File

@@ -0,0 +1,58 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# DNS over QUIC (DoQ)
### Structure
```json
{
"dns": {
"servers": [
{
"type": "quic",
"tag": "",
"server": "",
"server_port": 853,
"tls": {},
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy QUIC server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`853` will be used by default.
#### tls
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

52
docs/configuration/dns/server/tcp.md Normal file
View File

@@ -0,0 +1,52 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# TCP
### Structure
```json
{
"dns": {
"servers": [
{
"type": "tcp",
"tag": "",
"server": "",
"server_port": 53,
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy TCP server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`53` will be used by default.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

58
docs/configuration/dns/server/tls.md Normal file
View File

@@ -0,0 +1,58 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# DNS over TLS (DoT)
### Structure
```json
{
"dns": {
"servers": [
{
"type": "tls",
"tag": "",
"server": "",
"server_port": 853,
"tls": {},
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy TLS server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`853` will be used by default.
#### tls
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.

52
docs/configuration/dns/server/udp.md Normal file
View File

@@ -0,0 +1,52 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.12.0"
# TCP
### Structure
```json
{
"dns": {
"servers": [
{
"type": "udp",
"tag": "",
"server": "",
"server_port": 53,
// Dial Fields
}
]
}
}
```
!!! info "Difference from legacy UDP server"
* The old server uses default outbound by default unless detour is specified; the new one uses dialer just like outbound, which is equivalent to using an empty direct outbound by default.
* The old server uses `address_resolver` and `address_strategy` to resolve the domain name in the server; the new one uses `domain_resolver` and `domain_strategy` in [Dial Fields](/configuration/shared/dial/) instead.
### Fields
#### server
==Required==
The address of the DNS server.
If domain name is used, `domain_resolver` must also be set to resolve IP address.
#### server_port
The port of the DNS server.
`53` will be used by default.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.