documentation: Add rule action

SagerNet · Nov 7, 2024 · b169074 · b169074
1 parent 348cb1c
commit b169074
Show file tree

Hide file tree

Showing 22 changed files with 1,076 additions and 43 deletions.
diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md
@@ -2,6 +2,14 @@
 icon: material/new-box
 ---
 
+!!! quote "Changes in sing-box 1.11.0"
+
+    :material-plus: [action](#action)  
+    :material-alert: [server](#server)  
+    :material-alert: [disable_cache](#disable_cache)  
+    :material-alert: [rewrite_ttl](#rewrite_ttl)  
+    :material-alert: [client_subnet](#client_subnet)
+
 !!! quote "Changes in sing-box 1.10.0"
 
     :material-delete-clock: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source)  
@@ -14,7 +22,7 @@ icon: material/new-box
     :material-plus: [geoip](#geoip)  
     :material-plus: [ip_cidr](#ip_cidr)  
     :material-plus: [ip_is_private](#ip_is_private)  
-    :material-plus: [client_subnet](#client_subnet)
+    :material-plus: [client_subnet](#client_subnet)  
     :material-plus: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source)
 
 !!! quote "Changes in sing-box 1.8.0"
@@ -135,19 +143,15 @@ icon: material/new-box
         "outbound": [
           "direct"
         ],
-        "server": "local",
-        "disable_cache": false,
-        "rewrite_ttl": 100,
-        "client_subnet": "127.0.0.1/24"
+        "action": "route",
+        "server": "local"
       },
       {
         "type": "logical",
         "mode": "and",
         "rules": [],
-        "server": "local",
-        "disable_cache": false,
-        "rewrite_ttl": 100,
-        "client_subnet": "127.0.0.1/24"
+        "action": "route",
+        "server": "local"
       }
     ]
   }
@@ -354,29 +358,35 @@ Match outbound.
 
 `any` can be used as a value to match any outbound.
 
-#### server
+#### action
 
 ==Required==
 
-Tag of the target dns server.
+See [DNS Rule Actions](../rule_action/) for details.
+
+#### server
+
+!!! failure "Deprecated in sing-box 1.11.0"
+
+    Moved to [DNS Rule Action](../rule_action#route).
 
 #### disable_cache
 
-Disable cache and save cache in this query.
+!!! failure "Deprecated in sing-box 1.11.0"
 
-#### rewrite_ttl
+    Moved to [DNS Rule Action](../rule_action#route).
 
-Rewrite TTL in DNS responses.
+#### rewrite_ttl
 
-#### client_subnet
+!!! failure "Deprecated in sing-box 1.11.0"
 
-!!! question "Since sing-box 1.9.0"
+    Moved to [DNS Rule Action](../rule_action#route).
 
-Append a `edns0-subnet` OPT extra record with the specified IP prefix to every query by default.
+#### client_subnet
 
-If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
+!!! failure "Deprecated in sing-box 1.11.0"
 
-Will overrides `dns.client_subnet` and `servers.[].client_subnet`.
+    Moved to [DNS Rule Action](../rule_action#route).
 
 ### Address Filter Fields
 

diff --git a/docs/configuration/dns/rule.zh.md b/docs/configuration/dns/rule.zh.md
@@ -14,7 +14,7 @@ icon: material/new-box
     :material-plus: [geoip](#geoip)  
     :material-plus: [ip_cidr](#ip_cidr)  
     :material-plus: [ip_is_private](#ip_is_private)  
-    :material-plus: [client_subnet](#client_subnet)
+    :material-plus: [client_subnet](#client_subnet)  
     :material-plus: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source)
 
 !!! quote "sing-box 1.8.0 中的更改"

diff --git a/docs/configuration/dns/rule_action.md b/docs/configuration/dns/rule_action.md
@@ -0,0 +1,85 @@
+---
+icon: material/new-box
+---
+
+# DNS Rule Action
+
+!!! question "Since sing-box 1.11.0"
+
+### route
+
+```json
+{
+  "action": "route",  // default
+  "server": "",
+
+  // for compatibility
+  "disable_cache": false,
+  "rewrite_ttl": 0,
+  "client_subnet": null
+}
+```
+
+`route` inherits the classic rule behavior of routing DNS requests to the specified server.
+
+#### server
+
+==Required==
+
+Tag of target server.
+
+#### disable_cache/rewrite_ttl/client_subnet
+
+!!! failure "Deprecated in sing-box 1.11.0"
+
+    Legacy route options is deprecated and will be removed in sing-box 1.12.0, check [Migration](/migration/#migrate-legacy-dns-route-options-to-rule-actions).
+
+### route-options
+
+```json
+{
+  "action": "route-options",
+  "disable_cache": false,
+  "rewrite_ttl": null,
+  "client_subnet": null
+}
+```
+
+#### disable_cache
+
+Disable cache and save cache in this query.
+
+#### rewrite_ttl
+
+Rewrite TTL in DNS responses.
+
+#### client_subnet
+
+Append a `edns0-subnet` OPT extra record with the specified IP prefix to every query by default.
+
+If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
+
+Will overrides `dns.client_subnet` and `servers.[].client_subnet`.
+
+### reject
+
+```json
+{
+  "action": "reject",
+  "method": "default", // default
+  "no_drop": false
+}
+```
+
+`reject` reject DNS requests.
+
+#### method
+
+- `default`: Reply with NXDOMAIN.
+- `drop`: Drop the request.
+
+#### no_drop
+
+If not enabled, `method` will be temporarily overwritten to `drop` after 50 triggers in 30s.
+
+Not available when `method` is set to drop.
diff --git a/docs/configuration/dns/rule_action.zh.md b/docs/configuration/dns/rule_action.zh.md
@@ -0,0 +1,86 @@
+---
+icon: material/new-box
+---
+
+# DNS 规则动作
+
+!!! question "自 sing-box 1.11.0 起"
+
+### route
+
+```json
+{
+  "action": "route",  // 默认
+  "server": "",
+
+  // 兼容性
+  "disable_cache": false,
+  "rewrite_ttl": 0,
+  "client_subnet": null
+}
+```
+
+`route` 继承了将 DNS 请求 路由到指定服务器的经典规则动作。
+
+#### server
+
+==必填==
+
+目标 DNS 服务器的标签。
+
+#### disable_cache/rewrite_ttl/client_subnet
+
+!!! failure "自 sing-box 1.11.0 起"
+
+    旧的路由选项已弃用，且将在 sing-box 1.12.0 中移除，参阅 [迁移指南](/migration/#migrate-legacy-dns-route-options-to-rule-actions).
+
+### route-options
+
+```json
+{
+  "action": "route-options",
+  "disable_cache": false,
+  "rewrite_ttl": null,
+  "client_subnet": null
+}
+```
+
+
+#### disable_cache
+
+在此查询中禁用缓存。
+
+#### rewrite_ttl
+
+重写 DNS 回应中的 TTL。
+
+#### client_subnet
+
+默认情况下，将带有指定 IP 前缀的 `edns0-subnet` OPT 附加记录附加到每个查询。
+
+如果值是 IP 地址而不是前缀，则会自动附加 `/32` 或 `/128`。
+
+将覆盖 `dns.client_subnet` 与 `servers.[].client_subnet`。
+
+### reject
+
+```json
+{
+  "action": "reject",
+  "method": "default", // default
+  "no_drop": false
+}
+```
+
+`reject` 拒绝 DNS 请求。
+
+#### method
+
+- `default`: 返回 NXDOMAIN。
+- `drop`: 丢弃请求。
+
+#### no_drop
+
+如果未启用，则 30 秒内触发 50 次后，`method` 将被暂时覆盖为 `drop`。
+
+当 `method` 设为 `drop` 时不可用。
diff --git a/docs/configuration/outbound/block.md b/docs/configuration/outbound/block.md
@@ -1,8 +1,14 @@
-`block` outbound closes all incoming requests.
+---
+icon: material/delete-clock
+---
+
+!!! failure "Deprecated in sing-box 1.11.0"
+
+    Legacy special outbounds are deprecated and will be removed in sing-box 1.13.0, check [Migration](/migration/#migrate-legacy-special-outbounds-to-rule-actions). 
 
 ### Structure
 
-```json
+```json F
 {
   "type": "block",
   "tag": "block"

diff --git a/docs/configuration/outbound/block.zh.md b/docs/configuration/outbound/block.zh.md
@@ -1,3 +1,11 @@
+---
+icon: material/delete-clock
+---
+
+!!! failure "已在 sing-box 1.11.0 废弃"
+
+    旧的特殊出站已被弃用，且将在 sing-box 1.13.0 中被移除，参阅 [迁移指南](/migration/#migrate-legacy-special-outbounds-to-rule-actions). 
+
 `block` 出站关闭所有传入请求。
 
 ### 结构
@@ -11,4 +19,4 @@
 
 ### 字段
 
-无字段。
+无字段。
diff --git a/docs/configuration/outbound/dns.md b/docs/configuration/outbound/dns.md
@@ -1,3 +1,11 @@
+---
+icon: material/delete-clock
+---
+
+!!! failure "Deprecated in sing-box 1.11.0"
+
+    Legacy special outbounds are deprecated and will be removed in sing-box 1.13.0, check [Migration](/migration/#migrate-legacy-special-outbounds-to-rule-actions).
+
 `dns` outbound is a internal DNS server.
 
 ### Structure

diff --git a/docs/configuration/outbound/dns.zh.md b/docs/configuration/outbound/dns.zh.md
@@ -1,3 +1,11 @@
+---
+icon: material/delete-clock
+---
+
+!!! failure "已在 sing-box 1.11.0 废弃"
+
+    旧的特殊出站已被弃用，且将在 sing-box 1.13.0 中被移除, 参阅 [迁移指南](/migration/#migrate-legacy-special-outbounds-to-rule-actions). 
+
 `dns` 出站是一个内部 DNS 服务器。
 
 ### 结构

diff --git a/docs/configuration/route/rule.md b/docs/configuration/route/rule.md
@@ -1,7 +1,12 @@
 ---
-icon: material/alert-decagram
+icon: material/new-box
 ---
 
+!!! quote "Changes in sing-box 1.11.0"
+
+    :material-plus: [action](#action)  
+    :material-alert: [outbound](#outbound)
+
 !!! quote "Changes in sing-box 1.10.0"
 
     :material-plus: [client](#client)  
@@ -129,13 +134,15 @@ icon: material/alert-decagram
         "rule_set_ipcidr_match_source": false,
         "rule_set_ip_cidr_match_source": false,
         "invert": false,
+        "action": "route",
         "outbound": "direct"
       },
       {
         "type": "logical",
         "mode": "and",
         "rules": [],
         "invert": false,
+        "action": "route",
         "outbound": "direct"
       }
     ]
@@ -357,11 +364,17 @@ Make `ip_cidr` in rule-sets match the source IP.
 
 Invert match result.
 
-#### outbound
+#### action
 
 ==Required==
 
-Tag of the target outbound.
+See [Rule Actions](../rule_action/) for details.
+
+#### outbound
+
+!!! failure "Deprecated in sing-box 1.11.0"
+
+    Moved to [Rule Action](../rule_action#route).
 
 ### Logical Fields