documentation: Outbound domain resolver

SagerNet · Jan 29, 2025 · 355b8d1 · 355b8d1
1 parent 413d223
commit 355b8d1
Show file tree

Hide file tree

Showing 14 changed files with 294 additions and 38 deletions.
diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md
@@ -1,7 +1,11 @@
 ---
-icon: material/new-box
+icon: material/alert-decagram
 ---
 
+!!! quote "Changes in sing-box 1.12.0"
+
+    :material-delete-clock: [outbound](#outbound)
+
 !!! quote "Changes in sing-box 1.11.0"
 
     :material-plus: [action](#action)  
@@ -395,6 +399,10 @@ Invert match result.
 
 #### outbound
 
+!!! failure "Deprecated in sing-box 1.12.0"
+
+    `outbound` rule items are deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-outbound-dns-rule-items-to-dial-fields). 
+
 Match outbound.
 
 `any` can be used as a value to match any outbound.

diff --git a/docs/configuration/dns/rule.zh.md b/docs/configuration/dns/rule.zh.md
@@ -1,7 +1,11 @@
 ---
-icon: material/new-box
+icon: material/alert-decagram
 ---
 
+!!! quote "sing-box 1.12.0 中的更改"
+
+    :material-delete-clock: [outbound](#outbound)
+
 !!! quote "sing-box 1.11.0 中的更改"
 
     :material-plus: [action](#action)  
@@ -395,6 +399,10 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
 
 #### outbound
 
+!!! failure "已在 sing-box 1.12.0 废弃"
+
+    `outbound` 规则项已废弃且将在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/migration/#migrate-outbound-dns-rule-items-to-dial-fields)。
+
 匹配出站。
 
 `any` 可作为值用于匹配任意出站。

diff --git a/docs/configuration/route/geoip.md b/docs/configuration/route/geoip.md
@@ -1,10 +1,10 @@
 ---
-icon: material/delete-clock
+icon: material/note-remove
 ---
 
-!!! failure "Deprecated in sing-box 1.8.0"
+!!! failure "Removed in sing-box 1.12.0"
 
-    GeoIP is deprecated and will be removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geoip-to-rule-sets).
+    GeoIP is deprecated in sing-box 1.8.0 and removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geoip-to-rule-sets).
 
 ### Structure
 

diff --git a/docs/configuration/route/geoip.zh.md b/docs/configuration/route/geoip.zh.md
@@ -1,10 +1,10 @@
 ---
-icon: material/delete-clock
+icon: material/note-remove
 ---
 
-!!! failure "已在 sing-box 1.8.0 废弃"
+!!! failure "已在 sing-box 1.12.0 中被移除"
 
-    GeoIP 已废弃且将在 sing-box 1.12.0 中被移除，参阅 [迁移指南](/zh/migration/#geoip)。
+    GeoIP 已在 sing-box 1.8.0 废弃且在 sing-box 1.12.0 中被移除，参阅 [迁移指南](/zh/migration/#geoip)。
 
 ### 结构
 

diff --git a/docs/configuration/route/geosite.md b/docs/configuration/route/geosite.md
@@ -1,10 +1,10 @@
 ---
-icon: material/delete-clock
+icon: material/note-remove
 ---
 
-!!! failure "Deprecated in sing-box 1.8.0"
+!!! failure "Removed in sing-box 1.12.0"
 
-    Geosite is deprecated and will be removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geosite-to-rule-sets).
+    Geosite is deprecated in sing-box 1.8.0 and removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geosite-to-rule-sets).
 
 ### Structure
 

diff --git a/docs/configuration/route/geosite.zh.md b/docs/configuration/route/geosite.zh.md
@@ -1,10 +1,10 @@
 ---
-icon: material/delete-clock
+icon: material/note-remove
 ---
 
-!!! failure "已在 sing-box 1.8.0 废弃"
+!!! failure "已在 sing-box 1.12.0 中被移除"
 
-    Geosite 已废弃且将在 sing-box 1.12.0 中被移除，参阅 [迁移指南](/zh/migration/#geosite)。
+    Geosite 已在 sing-box 1.8.0 废弃且在 sing-box 1.12.0 中被移除，参阅 [迁移指南](/zh/migration/#geosite)。
 
 ### 结构
 

diff --git a/docs/configuration/route/index.md b/docs/configuration/route/index.md
@@ -1,9 +1,15 @@
 ---
-icon: material/new-box
+icon: material/alert-decagram
 ---
 
 # Route
 
+!!! quote "Changes in sing-box 1.12.0"
+
+    :material-plus: [default_domain_resolver](#default_domain_resolver)  
+    :material-note-remove: [geoip](#geoip)  
+    :material-note-remove: [geosite](#geosite)
+
 !!! quote "Changes in sing-box 1.11.0"
 
     :material-plus: [default_network_strategy](#default_network_strategy)  
@@ -22,19 +28,23 @@ icon: material/new-box
 ```json
 {
   "route": {
-    "geoip": {},
-    "geosite": {},
     "rules": [],
     "rule_set": [],
     "final": "",
     "auto_detect_interface": false,
     "override_android_vpn": false,
     "default_interface": "",
     "default_mark": 0,
+    "default_domain_resolver": "", // or {}
     "default_network_strategy": "",
     "default_network_type": [],
     "default_fallback_network_type": [],
-    "default_fallback_delay": ""
+    "default_fallback_delay": "",
+
+    // Removed
+
+    "geoip": {},
+    "geosite": {}
   }
 }
 ```
@@ -97,6 +107,14 @@ Set routing mark by default.
 
 Takes no effect if `outbound.routing_mark` is set.
 
+#### default_domain_resolver
+
+!!! question "Since sing-box 1.12.0"
+
+See [Dial Fields](/configuration/shared/dial/#domain_resolver) for details.
+
+Can be overrides by `outbound.domain_resolver`.
+
 #### default_network_strategy
 
 !!! question "Since sing-box 1.11.0"

diff --git a/docs/configuration/route/index.zh.md b/docs/configuration/route/index.zh.md
@@ -1,9 +1,15 @@
 ---
-icon: material/new-box
+icon: material/alert-decagram
 ---
 
 # 路由
 
+!!! quote "sing-box 1.12.0 中的更改"
+
+    :material-plus: [default_domain_resolver](#default_domain_resolver)  
+    :material-note-remove: [geoip](#geoip)  
+    :material-note-remove: [geosite](#geosite)
+
 !!! quote "sing-box 1.11.0 中的更改"
 
     :material-plus: [network_strategy](#network_strategy)  
@@ -100,6 +106,14 @@ icon: material/new-box
 
 如果设置了 `outbound.routing_mark` 设置，则不生效。
 
+#### default_domain_resolver
+
+!!! question "自 sing-box 1.12.0 起"
+
+详情参阅 [拨号字段](/configuration/shared/dial/#domain_resolver)。
+
+可以被 `outbound.domain_resolver` 覆盖。
+
 #### network_strategy
 
 !!! question "自 sing-box 1.11.0 起"

diff --git a/docs/configuration/shared/dial.md b/docs/configuration/shared/dial.md
@@ -2,6 +2,11 @@
 icon: material/new-box
 ---
 
+!!! quote "Changes in sing-box 1.12.0"
+
+    :material-plus: [domain_resolver](#domain_resolver)  
+    :material-delete-clock: [domain_strategy](#domain_strategy)
+
 !!! quote "Changes in sing-box 1.11.0"
 
     :material-plus: [network_strategy](#network_strategy)  
@@ -23,11 +28,14 @@ icon: material/new-box
   "tcp_fast_open": false,
   "tcp_multi_path": false,
   "udp_fragment": false,
-  "domain_strategy": "prefer_ipv6",
+  "domain_resolver": "", // or {}
   "network_strategy": "default",
   "network_type": [],
   "fallback_network_type": [],
-  "fallback_delay": "300ms"
+  "fallback_delay": "300ms",
+
+  // Deprecated
+  "domain_strategy": "prefer_ipv6"
 }
 ```
 
@@ -92,16 +100,22 @@ decimal numbers, each with optional fraction and a unit suffix,
 such as "300ms", "-1.5h" or "2h45m".
 Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
 
-#### domain_strategy
+#### domain_resolver
 
-Available values: `prefer_ipv4`, `prefer_ipv6`, `ipv4_only`, `ipv6_only`.
+!!! warning ""
 
-If set, the requested domain name will be resolved to IP before connect.
+    `outbound` DNS rule items are deprecated and will be removed in sing-box 1.14.0, so this item will be required for outbound/endpoints using domain name in server address since sing-box 1.14.0.
 
-| Outbound | Effected domains         | Fallback Value                            |
-|----------|--------------------------|-------------------------------------------|
-| `direct` | Domain in request        | Take `inbound.domain_strategy` if not set | 
-| others   | Domain in server address | /                                         |
+Set domain resolver to use for resolving domain names.
+
+This option uses the same format as the [route DNS rule action](/configuration/dns/rule_action/#route) without the `action` field.
+
+Setting this option directly to a string is equivalent to setting `server` of this options.
+
+| Outbound/Endpoints | Effected domains         |
+|--------------------|--------------------------|
+| `direct`           | Domain in request        | 
+| others             | Domain in server address |
 
 #### network_strategy
 
@@ -171,3 +185,19 @@ back to other interfaces.
 Only take effect when `domain_strategy` or `network_strategy` is set.
 
 `300ms` is used by default.
+
+#### domain_strategy
+
+!!! failure "Deprecated in sing-box 1.12.0"
+
+    `domain_strategy` is merged to [domain_resolver](#domain_resolver) in sing-box 1.12.0.
+
+Available values: `prefer_ipv4`, `prefer_ipv6`, `ipv4_only`, `ipv6_only`.
+
+If set, the requested domain name will be resolved to IP before connect.
+
+| Outbound | Effected domains         | Fallback Value                            |
+|----------|--------------------------|-------------------------------------------|
+| `direct` | Domain in request        | Take `inbound.domain_strategy` if not set | 
+| others   | Domain in server address | /                                         |
+
diff --git a/docs/configuration/shared/dial.zh.md b/docs/configuration/shared/dial.zh.md
@@ -2,6 +2,11 @@
 icon: material/new-box
 ---
 
+!!! quote "sing-box 1.12.0 中的更改"
+
+    :material-plus: [domain_resolver](#domain_resolver)  
+    :material-delete-clock: [domain_strategy](#domain_strategy)
+
 !!! quote "sing-box 1.11.0 中的更改"
 
     :material-plus: [network_strategy](#network_strategy)  
@@ -23,11 +28,15 @@ icon: material/new-box
   "tcp_fast_open": false,
   "tcp_multi_path": false,
   "udp_fragment": false,
-  "domain_strategy": "prefer_ipv6",
+  "domain_resolver": "", // 或 {}
   "network_strategy": "",
   "network_type": [],
   "fallback_network_type": [],
-  "fallback_delay": "300ms"
+  "fallback_delay": "300ms",
+
+  // 废弃的
+
+  "domain_strategy": "prefer_ipv6"
 }
 ```
 
@@ -90,16 +99,22 @@ icon: material/new-box
 持续时间字符串是一个可能有符号的序列十进制数，每个都有可选的分数和单位后缀， 例如 "300ms"、"-1.5h" 或 "2h45m"。
 有效时间单位为 "ns"、"us"（或 "µs"）、"ms"、"s"、"m"、"h"。
 
-#### domain_strategy
+#### domain_resolver
 
-可选值：`prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
+!!! warning ""
 
-如果设置，域名将在请求发出之前解析为 IP。
+    `outbound` DNS 规则项已弃用，且将在 sing-box 1.14.0 中被移除。因此，从 sing-box 1.14.0 版本开始，所有在服务器地址中使用域名的出站/端点均需配置此项。
 
-| 出站       | 受影响的域名    | 默认回退值                     |
-|----------|-----------|---------------------------|
-| `direct` | 请求中的域名    | `inbound.domain_strategy` | 
-| others   | 服务器地址中的域名 | /                         |
+用于设置解析域名的域名解析器。
+
+此选项的格式与 [路由 DNS 规则动作](/configuration/dns/rule_action/#route) 相同，但不包含 `action` 字段。  
+
+若直接将此选项设置为字符串，则等同于设置该选项的 `server` 字段。
+
+| 出站/端点       | 受影响的域名                |
+|----------------|---------------------------|
+| `direct`       | 请求中的域名                | 
+| 其他类型        | 服务器地址中的域名           |
 
 #### network_strategy
 
@@ -160,3 +175,14 @@ icon: material/new-box
 仅当 `domain_strategy` 或 `network_strategy` 已设置时生效。
 
 默认使用 `300ms`。
+
+#### domain_strategy
+
+可选值：`prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
+
+如果设置，域名将在请求发出之前解析为 IP。
+
+| 出站       | 受影响的域名    | 默认回退值                     |
+|----------|-----------|---------------------------|
+| `direct` | 请求中的域名    | `inbound.domain_strategy` | 
+| others   | 服务器地址中的域名 | /                         |
diff --git a/docs/deprecated.md b/docs/deprecated.md
@@ -13,6 +13,12 @@ check [Migration](../migration/#migrate-to-new-dns-servers).
 
 Compatibility for old formats will be removed in sing-box 1.14.0.
 
+#### `outbound` DNS rule item
+
+Legacy `outbound` DNS rules are deprecated
+and can be replaced by dial fields,
+check [Migration](../migration/#migrate-outbound-dns-rule-items-to-dial-fields).
+
 ## 1.11.0
 
 #### Legacy special outbounds

diff --git a/docs/deprecated.zh.md b/docs/deprecated.zh.md
@@ -11,6 +11,12 @@ DNS 服务器已重构，
 
 对旧格式的兼容性将在 sing-box 1.14.0 中被移除。
 
+#### `outbound` DNS 规则项
+
+旧的 `outbound` DNS 规则已废弃，
+且可被拨号字段代替，
+参阅 [迁移指南](/migration/#migrate-outbound-dns-rule-items-to-dial-fields).
+
 ## 1.11.0
 
 #### 旧的特殊出站
@@ -27,7 +33,7 @@ DNS 服务器已重构，
 
 旧字段将在 sing-box 1.13.0 中被移除。
 
-####  direct 出站中的目标地址覆盖字段
+#### direct 出站中的目标地址覆盖字段
 
 direct 出站中的目标地址覆盖字段（`override_address` / `override_port`）已废弃且可以通过规则动作替代，
 参阅 [迁移指南](/migration/#migrate-destination-override-fields-to-route-options)。