From 021e0877a3a56de022a13ee3d2821319b2998417 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Sat, 26 Sep 2026 20:10:32 +0800 Subject: [PATCH] Cleanup documentations --- docs/changelog.md | 96 +++++++------------ docs/clients/desktop/features.md | 2 +- docs/configuration/dns/index.md | 2 +- docs/configuration/dns/rule.md | 12 +-- docs/configuration/dns/rule.zh.md | 6 +- docs/configuration/dns/rule_action.md | 12 +-- docs/configuration/dns/rule_action.zh.md | 11 +-- docs/configuration/dns/server/mdns.md | 2 +- docs/configuration/dns/server/mdns.zh.md | 2 +- docs/configuration/dns/server/openconnect.md | 4 +- .../dns/server/openconnect.zh.md | 4 +- docs/configuration/dns/server/openvpn.md | 6 +- docs/configuration/dns/server/openvpn.zh.md | 6 +- docs/configuration/dns/server/tailscale.md | 2 - docs/configuration/dns/server/tailscale.zh.md | 2 - docs/configuration/endpoint/openconnect.md | 42 +++----- docs/configuration/endpoint/openconnect.zh.md | 42 +++----- docs/configuration/endpoint/openvpn-client.md | 64 +++---------- .../endpoint/openvpn-client.zh.md | 47 ++------- docs/configuration/endpoint/openvpn-server.md | 35 ++----- .../endpoint/openvpn-server.zh.md | 31 +++--- docs/configuration/endpoint/tailscale.md | 6 +- docs/configuration/endpoint/tailscale.zh.md | 6 +- docs/configuration/inbound/hysteria2.md | 6 +- docs/configuration/inbound/hysteria2.zh.md | 6 +- docs/configuration/inbound/snell.md | 2 +- docs/configuration/inbound/snell.zh.md | 2 +- docs/configuration/inbound/tun.md | 32 +++---- docs/configuration/inbound/tun.zh.md | 22 ++--- docs/configuration/outbound/bridge.md | 2 - docs/configuration/outbound/bridge.zh.md | 2 - docs/configuration/outbound/hysteria2.md | 8 +- docs/configuration/outbound/hysteria2.zh.md | 8 +- docs/configuration/rule-set/headless-rule.md | 6 +- .../rule-set/headless-rule.zh.md | 3 +- docs/configuration/rule-set/index.md | 4 +- docs/configuration/rule-set/index.zh.md | 3 +- docs/configuration/schema.md | 1 - docs/configuration/schema.zh.md | 1 - docs/configuration/service/api.md | 10 +- docs/configuration/service/api.zh.md | 8 +- docs/configuration/service/hysteria-realm.md | 4 +- .../service/hysteria-realm.zh.md | 4 +- docs/configuration/service/usbip-client.md | 6 -- docs/configuration/service/usbip-client.zh.md | 4 - docs/configuration/service/usbip-server.md | 6 -- docs/configuration/service/usbip-server.zh.md | 4 - .../shared/certificate-provider/acme.zh.md | 2 - docs/configuration/shared/dial.md | 2 +- docs/configuration/shared/dial.zh.md | 2 +- docs/configuration/shared/http-client.md | 3 +- docs/configuration/shared/http-client.zh.md | 3 +- docs/configuration/shared/pre-match.md | 3 +- docs/configuration/shared/pre-match.zh.md | 2 +- docs/configuration/shared/tls.md | 41 +------- docs/configuration/shared/tls.zh.md | 39 +------- docs/deprecated.md | 3 +- docs/deprecated.zh.md | 3 +- docs/installation/build-from-source.md | 6 +- docs/installation/build-from-source.zh.md | 6 +- docs/migration.md | 35 ++----- docs/migration.zh.md | 26 +---- 62 files changed, 211 insertions(+), 561 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 9c7de2cf..b58fc55b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -185,14 +185,11 @@ supplied at runtime through the API service by the graphical clients or the **10**: The new [Hysteria Realm service](/configuration/service/hysteria-realm/) -is a rendezvous service for Hysteria2 NAT traversal. A Hysteria2 server -behind NAT registers its STUN-discovered public addresses on a stable -realm endpoint via the new -[`realm`](/configuration/inbound/hysteria2/#realm) inbound field; -clients query the realm via the new -[`realm`](/configuration/outbound/hysteria2/#realm) outbound field to -learn the server's current addresses and perform UDP hole-punching to -establish a direct QUIC connection. +is a rendezvous service for Hysteria2 NAT traversal. Hysteria2 servers behind +NAT register on the realm via the new +[`realm`](/configuration/inbound/hysteria2/#realm) inbound field, and clients +connect to them through the realm via the new +[`realm`](/configuration/outbound/hysteria2/#realm) outbound field. [`realm.ip_version`](/configuration/outbound/hysteria2/#realmip_version) restricts realm connections to a single IP version, and [`realm.port_mapping`](/configuration/outbound/hysteria2/#realmport_mapping) @@ -247,8 +244,7 @@ See [Migration](/migration/#migrate-address-filter-fields-to-response-matching). referenced rule-sets, now take effect on every DNS rule evaluation, including matches from internal domain resolutions that do not target a specific DNS server (for example a `resolve` route rule action without -`server` set). In earlier versions they were silently ignored in that -path. Combining these fields with any of the legacy DNS fields deprecated +`server` set). Combining these fields with any of the legacy DNS fields deprecated in **12** in the same DNS configuration is no longer supported and is rejected at startup. See [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules). @@ -278,8 +274,7 @@ file option. A per-query field is also available on DNS rule actions and the `resolve` route rule action. -This deprecates the `independent_cache` DNS option (the DNS cache now -always keys by transport) and the `store_rdrc` cache file option +This deprecates the `independent_cache` DNS option and the `store_rdrc` cache file option (replaced by `store_dns`); both will be removed in sing-box 1.16.0. See [Migration](/migration/#migrate-independent-dns-cache). @@ -295,9 +290,8 @@ and a `timeout` field on The new [mDNS DNS server](/configuration/dns/server/mdns/) sends queries via multicast on the local network. The default -[local DNS server](/configuration/dns/server/local/) also routes queries for -`*.local.` and IPv4/IPv6 link-local reverse zones via mDNS on non-Apple -platforms (and via the system resolver on Apple), and the new +[local DNS server](/configuration/dns/server/local/) also resolves +`*.local.` and IPv4/IPv6 link-local reverse zones, and the new [`neighbor_domain`](/configuration/dns/server/local/#neighbor_domain) option answers single-label hosts from the [neighbor resolver](/configuration/shared/neighbor/). @@ -331,8 +325,7 @@ The default `hijack` mode now sets the platform's native interface DNS (`systemd-resolved` on Linux, per-interface DNS on Windows and Apple) and installs platform-level DNS hijacking (an `iproute2` rule on Linux, nftables DNAT when `auto_redirect` is enabled, WFP filters on Windows when -`strict_route` is enabled). Earlier versions did not touch the interface -DNS or the platform firewall. +`strict_route` is enabled). **20**: @@ -345,9 +338,7 @@ TUN and TProxy inbounds and the WireGuard endpoint. **21**: -For UDP connections, the first packet is available in pre-match, so protocol -sniffing runs on it directly and rule matching continues with the sniffed -metadata. +The `sniff` action now works in pre-match for UDP connections. See [Pre-match](/configuration/shared/pre-match/#sniff). @@ -364,8 +355,8 @@ previously inlined in each component. [`route.default_http_client`](/configuration/route/#default_http_client) selects the default client for remote rule-sets. The legacy fallback (use the default outbound when `http_clients` is empty altogether) is -preserved with a deprecation warning and will be removed in sing-box -1.16.0, together with the legacy `download_detour` remote rule-set option. +deprecated and will be removed in sing-box 1.16.0, together with the legacy +`download_detour` remote rule-set option. **23**: @@ -419,7 +410,7 @@ through Schannel via SSPI on Windows build 17763 or later. The new `apple` value for outbound TLS `engine` routes the TLS handshake through `Network.framework`, and the new `apple` [HTTP client `engine`](/configuration/shared/http-client/#engine) routes HTTP -requests through `NSURLSession`. The default remains `go`. +requests through `NSURLSession`. **28**: @@ -448,8 +439,7 @@ The rule-set [`tag`](/configuration/rule-set/#tag) field now accepts a list of tags to define multiple rule-sets sharing other options at once, with the `{tag}` placeholder in `path` or `url` replaced by each tag. The new [`initial_path`](/configuration/rule-set/#initial_path) option provides -initial content for remote rule-sets so startup is not blocked by the initial -download. +initial content for remote rule-sets. **31**: @@ -696,9 +686,7 @@ split-DNS resolvers and, when enabled, general pushed resolvers. The [OpenConnect Client](/configuration/endpoint/openconnect/) endpoint can now submit Fortinet host check results using the new [`fortinet_host_check`](/configuration/endpoint/openconnect/#fortinet_host_check) -option. This behavior is modeled after openfortivpn and is not an OpenConnect -feature. sing-box only submits explicitly configured values when requested by -the Fortinet server and does not collect system information automatically. +option. #### 1.14.0-alpha.48 @@ -1040,15 +1028,11 @@ The `control_http_client` field on **1**: The new [Hysteria Realm service](/configuration/service/hysteria-realm/) -is a rendezvous service for Hysteria2 NAT traversal. A Hysteria2 server -behind NAT registers its STUN-discovered public addresses on a stable -realm endpoint via the new -[`realm`](/configuration/inbound/hysteria2/#realm) inbound field; -clients query the realm via the new -[`realm`](/configuration/outbound/hysteria2/#realm) outbound field to -learn the server's current addresses and perform UDP hole-punching to -establish a direct QUIC connection. Once hole-punching succeeds, all -proxy traffic flows directly between client and server. +is a rendezvous service for Hysteria2 NAT traversal. Hysteria2 servers behind +NAT register on the realm via the new +[`realm`](/configuration/inbound/hysteria2/#realm) inbound field, and clients +connect to them through the realm via the new +[`realm`](/configuration/outbound/hysteria2/#realm) outbound field. #### 1.14.0-alpha.21 @@ -1068,19 +1052,14 @@ The default `hijack` mode now sets the platform's native interface DNS (`systemd-resolved` on Linux, per-interface DNS on Windows and Apple) and installs platform-level DNS hijacking (an `iproute2` rule on Linux, nftables DNAT when `auto_redirect` is enabled, WFP filters on Windows when -`strict_route` is enabled). Earlier versions did not touch the interface -DNS or the platform firewall. +`strict_route` is enabled). **2**: The new [mDNS DNS server](/configuration/dns/server/mdns/) sends queries via multicast on the local network. The default -[local DNS server](/configuration/dns/server/local/) also routes queries for -`*.local.` and IPv4/IPv6 link-local reverse zones via mDNS on non-Apple -platforms (and via the system resolver on Apple), so an explicit `mdns` -server is only needed to reference it from -[`preferred_by`](/configuration/dns/rule/#preferred_by) or to use it -standalone. +[local DNS server](/configuration/dns/server/local/) also resolves +`*.local.` and IPv4/IPv6 link-local reverse zones. **3**: @@ -1193,20 +1172,13 @@ HTTP/2 and QUIC parameters). Components that make outbound HTTP requests DERP `verify_client_url`, and the Tailscale `control_http_client` — now accept an inline HTTP client object or the tag of an `http_clients` entry, replacing the dial and TLS fields previously inlined in each -component. When the field is omitted, ACME, Cloudflare Origin CA, DERP -and Tailscale dial direct (their existing default). +component. -Remote rule-sets are the only HTTP-using component whose default for an -omitted `http_client` has historically resolved to the default outbound, -not to direct, and a typical configuration contains many of them. To -avoid repeating the same `http_client` block in every rule-set, [`route.default_http_client`](/configuration/route/#default_http_client) -selects a default rule-set client by tag and is the only field that -consults it. If `default_http_client` is empty and `http_clients` is -non-empty, the first entry is used automatically. The legacy fallback -(use the default outbound when `http_clients` is empty altogether) is -preserved with a deprecation warning and will be removed in sing-box -1.16.0, together with the legacy `download_detour` remote rule-set +selects the default HTTP client for remote rule-sets; if empty, the first +`http_clients` entry is used. The legacy fallback (use the default outbound +when `http_clients` is empty altogether) is deprecated and will be removed in +sing-box 1.16.0, together with the legacy `download_detour` remote rule-set option and the legacy dialer fields on Tailscale endpoints. **2**: @@ -1220,9 +1192,7 @@ places: the TLS handshake through `Network.framework` for direct TCP TLS client connections. -The default remains `go`. Both engines come with additional CGO and -framework memory overhead and platform restrictions documented on each -field. +Both engines have platform restrictions documented on each field. **3**: @@ -1280,8 +1250,7 @@ file option. A per-query field is also available on DNS rule actions and the `resolve` route rule action. -This deprecates the `independent_cache` DNS option (the DNS cache now -always keys by transport) and the `store_rdrc` cache file option +This deprecates the `independent_cache` DNS option and the `store_rdrc` cache file option (replaced by `store_dns`); both will be removed in sing-box 1.16.0. See [Migration](/migration/#migrate-independent-dns-cache). @@ -1320,8 +1289,7 @@ See [Migration](/migration/#migrate-address-filter-fields-to-response-matching). referenced rule-sets, now take effect on every DNS rule evaluation, including matches from internal domain resolutions that do not target a specific DNS server (for example a `resolve` route rule action without -`server` set). In earlier versions they were silently ignored in that -path. Combining these fields with any of the legacy DNS fields deprecated +`server` set). Combining these fields with any of the legacy DNS fields deprecated in **1** in the same DNS configuration is no longer supported and is rejected at startup. See [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules). diff --git a/docs/clients/desktop/features.md b/docs/clients/desktop/features.md index bb399a03..f9ecc580 100644 --- a/docs/clients/desktop/features.md +++ b/docs/clients/desktop/features.md @@ -2,7 +2,7 @@ #### Service -SFW runs sing-box as a system service, so no administrator elevation is required for daily use. +SFW runs sing-box as a system service. ### Chore diff --git a/docs/configuration/dns/index.md b/docs/configuration/dns/index.md index 19a183ac..9351604a 100644 --- a/docs/configuration/dns/index.md +++ b/docs/configuration/dns/index.md @@ -77,7 +77,7 @@ Conflict with `optimistic`. !!! failure "Deprecated in sing-box 1.14.0" - `independent_cache` is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-independent-dns-cache). + `independent_cache` is deprecated and will be removed in sing-box 1.16.0, check [Migration](/migration/#migrate-independent-dns-cache). Make each DNS server's cache independent for special purposes. If enabled, will slightly degrade performance. diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md index ab5ca0f3..7a82f188 100644 --- a/docs/configuration/dns/rule.md +++ b/docs/configuration/dns/rule.md @@ -262,10 +262,8 @@ Tags of [Inbound](/configuration/inbound/). This field now also applies when a DNS rule is matched from an internal domain resolution that does not target a specific DNS server, such as a [`resolve`](../../route/rule_action/#resolve) route rule action without a - `server` set. In earlier versions, only DNS queries received from a - client evaluated this field. See - [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules) - for the full list. + `server` set. See + [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules). Setting this field makes the DNS rule incompatible in the same DNS configuration with Legacy Address Filter Fields in DNS rules, the Legacy @@ -285,10 +283,8 @@ Not limited if empty. This field now also applies when a DNS rule is matched from an internal domain resolution that does not target a specific DNS server, such as a [`resolve`](../../route/rule_action/#resolve) route rule action without a - `server` set. In earlier versions, only DNS queries received from a - client evaluated this field. See - [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules) - for the full list. + `server` set. See + [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules). Setting this field makes the DNS rule incompatible in the same DNS configuration with Legacy Address Filter Fields in DNS rules, the Legacy diff --git a/docs/configuration/dns/rule.zh.md b/docs/configuration/dns/rule.zh.md index a72101f6..572f9d68 100644 --- a/docs/configuration/dns/rule.zh.md +++ b/docs/configuration/dns/rule.zh.md @@ -260,8 +260,7 @@ icon: material/alert-decagram !!! quote "sing-box 1.14.0 中的更改" 此字段现在也会在 DNS 规则被未指定具体 DNS 服务器的内部域名解析匹配时生效， - 例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。 - 此前只有来自客户端的 DNS 查询才会评估此字段。完整列表参阅 + 例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。参阅 [迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。 在 DNS 规则中设置此字段后，该 DNS 规则在同一 DNS 配置中不能与 @@ -279,8 +278,7 @@ icon: material/alert-decagram !!! quote "sing-box 1.14.0 中的更改" 此字段现在也会在 DNS 规则被未指定具体 DNS 服务器的内部域名解析匹配时生效， - 例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。 - 此前只有来自客户端的 DNS 查询才会评估此字段。完整列表参阅 + 例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。参阅 [迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。 在 DNS 规则中设置此字段后，该 DNS 规则在同一 DNS 配置中不能与 diff --git a/docs/configuration/dns/rule_action.md b/docs/configuration/dns/rule_action.md index 0476588d..28f829bb 100644 --- a/docs/configuration/dns/rule_action.md +++ b/docs/configuration/dns/rule_action.md @@ -55,7 +55,7 @@ immediately; the remaining queries are canceled. Rules without `race` still take effect strictly in listed order: while a preceding race rule is not yet judged, the action of any other matched rule is held until none of the race rules -matched. The result may therefore depend on server speed only among race rules. +matched. ### route @@ -92,8 +92,7 @@ By default, no query is sent in parallel with pending race rules: a matched `rou holds its query until none of the race rules matched. When `speculative` is enabled, the query is sent as soon as the rule matches, in parallel with -the pending race rules, and may be wasted: its response is still used only after none of the -race rules matched. +the pending race rules; its response is used only after none of the race rules matched. #### strategy @@ -170,8 +169,7 @@ Unlike `route`, it does **not** terminate rule evaluation. Only allowed on top-level DNS rules (not inside logical sub-rules). Rules that use [`match_response`](/configuration/dns/rule/#match_response) or Response Match Fields -require a preceding top-level rule with `evaluate` action. A rule's own `evaluate` action -does not satisfy this requirement, because matching happens before the action runs. +require a preceding top-level rule with `evaluate` action. #### server @@ -196,7 +194,7 @@ By default, no query is sent in parallel with pending race rules: a matched `eva holds its query, and rule matching stops there, until none of the race rules matched. When `speculative` is enabled, the query is sent as soon as the rule matches, in parallel with -the pending race rules, and may be wasted: rule matching continues without waiting for them. +the pending race rules, and rule matching continues without waiting for them. #### disable_cache @@ -248,8 +246,6 @@ Conflict with `client_subnet`. `respond` terminates rule evaluation and returns the evaluated response from a preceding [`evaluate`](/configuration/dns/rule_action/#evaluate) action. -This action does not send a new DNS query. - Only allowed after a preceding top-level `evaluate` rule. If the action is reached without an evaluated response at runtime, the request fails with an error instead of falling through to later rules. ### route-options diff --git a/docs/configuration/dns/rule_action.zh.md b/docs/configuration/dns/rule_action.zh.md index e01a6e2c..86d77ea0 100644 --- a/docs/configuration/dns/rule_action.zh.md +++ b/docs/configuration/dns/rule_action.zh.md @@ -48,7 +48,7 @@ icon: material/new-box 启用 `race` 的规则成为竞态规则，不再保持这一顺序：其引用的响应尚未到达时，规则匹配会越过它继续进行，因此竞态规则的匹配相互并行、也与后续规则并行。每条竞态规则在其引用的响应可用时被判定，首个匹配的竞态规则立即终止规则评估，其余查询将被取消。 -未启用 `race` 的规则仍严格按顺序生效：只要前面还有未判定的竞态规则，其他已匹配规则的动作就被扣住，直到所有竞态规则均未匹配。因此只有竞态规则之间的结果取决于服务器速度。 +未启用 `race` 的规则仍严格按顺序生效：只要前面还有未判定的竞态规则，其他已匹配规则的动作就被扣住，直到所有竞态规则均未匹配。 ### route @@ -83,7 +83,7 @@ icon: material/new-box 默认情况下，查询决不与未判定的竞态规则并行发出：已匹配的 `route` 动作扣住其查询，直到所有竞态规则均未匹配后才发送。 -启用 `speculative` 后，查询成为投机查询：在规则匹配时立即发出、与未判定的竞态规则并行，且可能被浪费；其响应仍仅在所有竞态规则均未匹配后才被使用。 +启用 `speculative` 后，查询在规则匹配时立即发出、与未判定的竞态规则并行；其响应仅在所有竞态规则均未匹配后才被使用。 #### strategy @@ -158,8 +158,7 @@ icon: material/new-box 仅允许在顶层 DNS 规则中使用（不可在逻辑子规则内部使用）。 使用 [`match_response`](/zh/configuration/dns/rule/#match_response) 或响应匹配字段的规则， -需要位于更早的顶层 `evaluate` 规则之后。规则自身的 `evaluate` 动作不能满足这个条件， -因为匹配发生在动作执行之前。 +需要位于更早的顶层 `evaluate` 规则之后。 #### server @@ -182,7 +181,7 @@ icon: material/new-box 默认情况下，查询决不与未判定的竞态规则并行发出：已匹配的 `evaluate` 动作扣住其查询，规则匹配在此处停止，直到所有竞态规则均未匹配。 -启用 `speculative` 后，查询成为投机查询：在规则匹配时立即发出、与未判定的竞态规则并行，且可能被浪费；规则匹配继续进行而不等待竞态规则。 +启用 `speculative` 后，查询在规则匹配时立即发出、与未判定的竞态规则并行，规则匹配继续进行而不等待竞态规则。 #### disable_cache @@ -234,8 +233,6 @@ icon: material/new-box `respond` 会终止规则评估，并直接返回前序 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作保存的已评估的响应。 -此动作不会发起新的 DNS 查询。 - 只能用于前面已有顶层 `evaluate` 规则的场景。如果运行时命中该动作时没有已评估的响应，则请求会直接返回错误，而不是继续匹配后续规则。 ### route-options diff --git a/docs/configuration/dns/server/mdns.md b/docs/configuration/dns/server/mdns.md index d42e0715..4b2fedaa 100644 --- a/docs/configuration/dns/server/mdns.md +++ b/docs/configuration/dns/server/mdns.md @@ -27,7 +27,7 @@ icon: material/new-box !!! info "" - You usually do not need an explicit `mdns` server in addition to a [Local](./local/) server: the local server already routes queries for `*.local.` and IPv4/IPv6 link-local reverse zones via mDNS on non-Apple platforms and via the system resolver on Apple platforms. Add an explicit `mdns` server only when you want to reference it from [`preferred_by`](../rule/#preferred_by) or use it standalone. + `*.local.` and IPv4/IPv6 link-local reverse zones are also resolved by the [Local](./local/) server. ### Fields diff --git a/docs/configuration/dns/server/mdns.zh.md b/docs/configuration/dns/server/mdns.zh.md index 3af3763e..ac0297ac 100644 --- a/docs/configuration/dns/server/mdns.zh.md +++ b/docs/configuration/dns/server/mdns.zh.md @@ -27,7 +27,7 @@ icon: material/new-box !!! info "" - 通常不需要在 [Local](./local/) 服务器之外再添加显式的 `mdns` 服务器：本地服务器已经会在非 Apple 平台通过 mDNS、在 Apple 平台通过系统解析器来回答 `*.local.` 与 IPv4/IPv6 链路本地反向区域的查询。仅当需要从 [`preferred_by`](../rule/#preferred_by) 引用，或独立使用时，才需要显式添加 `mdns` 服务器。 + [Local](./local/) 服务器也会解析 `*.local.` 与 IPv4/IPv6 链路本地反向区域。 ### 字段 diff --git a/docs/configuration/dns/server/openconnect.md b/docs/configuration/dns/server/openconnect.md index 0ba053be..4252616e 100644 --- a/docs/configuration/dns/server/openconnect.md +++ b/docs/configuration/dns/server/openconnect.md @@ -33,9 +33,7 @@ icon: material/new-box The tag of the [OpenConnect Endpoint](/configuration/endpoint/openconnect). -DNS queries are sent to the resolvers pushed by the VPN server through the OpenConnect endpoint. Pushed split-DNS rules use their dedicated resolvers, while pushed split-DNS and search-domain suffixes use the general pushed resolvers. The most specific matching suffix takes precedence. - -Pushed DNS settings are not installed into the operating system. +DNS queries are sent to the resolvers pushed by the VPN server through the OpenConnect endpoint. #### accept_default_resolvers diff --git a/docs/configuration/dns/server/openconnect.zh.md b/docs/configuration/dns/server/openconnect.zh.md index af812851..175581db 100644 --- a/docs/configuration/dns/server/openconnect.zh.md +++ b/docs/configuration/dns/server/openconnect.zh.md @@ -33,9 +33,7 @@ icon: material/new-box [OpenConnect 端点](/zh/configuration/endpoint/openconnect) 的标签。 -DNS 查询会通过 OpenConnect 端点发送到 VPN 服务器推送的解析器。推送的分流 DNS 规则使用各自的专用解析器，推送的分流 DNS 和搜索域后缀则使用通用推送解析器。匹配时优先使用最具体的后缀。 - -推送的 DNS 设置不会安装到操作系统中。 +DNS 查询会通过 OpenConnect 端点发送到 VPN 服务器推送的解析器。 #### accept_default_resolvers diff --git a/docs/configuration/dns/server/openvpn.md b/docs/configuration/dns/server/openvpn.md index d11a4573..71f25fc0 100644 --- a/docs/configuration/dns/server/openvpn.md +++ b/docs/configuration/dns/server/openvpn.md @@ -33,11 +33,9 @@ icon: material/new-box The tag of the [OpenVPN Client Endpoint](/configuration/endpoint/openvpn-client). -DNS queries are sent through the endpoint to resolvers pushed by the OpenVPN server. Modern OpenVPN `dns server` options support plain DNS, DNS over TLS, DNS over HTTPS, custom ports, SNI, and `resolve-domains`. Only the server group with the lowest priority number is active. Legacy `dhcp-option DNS`/`DNS6` and `DOMAIN-ROUTE` are used when no modern server group is present. +DNS queries are sent through the endpoint to resolvers pushed by the OpenVPN server. -A modern server group overrides legacy DHCP DNS resolver and domain options. A standalone modern `dns search-domains` option does not remove legacy resolvers. Required DNSSEC validation (`dnssec yes`) is rejected because this transport does not provide DNSSEC validation. - -Pushed DNS settings are not installed into the operating system. +Both modern `dns` options and legacy `dhcp-option DNS`/`DNS6` and `DOMAIN-ROUTE` options are supported. `dnssec yes` is not supported. #### accept_default_resolvers diff --git a/docs/configuration/dns/server/openvpn.zh.md b/docs/configuration/dns/server/openvpn.zh.md index 29d1d668..b537bf04 100644 --- a/docs/configuration/dns/server/openvpn.zh.md +++ b/docs/configuration/dns/server/openvpn.zh.md @@ -33,11 +33,9 @@ icon: material/new-box [OpenVPN 客户端端点](/zh/configuration/endpoint/openvpn-client) 的标签。 -DNS 查询会通过该端点发送到 OpenVPN 服务器推送的解析器。现代 OpenVPN `dns server` 选项支持普通 DNS、DNS over TLS、DNS over HTTPS、自定义端口、SNI 和 `resolve-domains`。只有优先级数字最低的服务器组会生效。没有现代服务器组时，使用传统的 `dhcp-option DNS`/`DNS6` 和 `DOMAIN-ROUTE`。 +DNS 查询会通过该端点发送到 OpenVPN 服务器推送的解析器。 -现代服务器组会覆盖传统 DHCP DNS 解析器及相关域选项。只有现代 `dns search-domains` 而没有现代服务器组时，不会移除传统解析器。由于此传输不提供 DNSSEC 验证，需要强制验证的 `dnssec yes` 会被拒绝。 - -推送的 DNS 设置不会安装到操作系统中。 +支持现代 `dns` 选项，以及传统的 `dhcp-option DNS`/`DNS6` 和 `DOMAIN-ROUTE` 选项。不支持 `dnssec yes`。 #### accept_default_resolvers diff --git a/docs/configuration/dns/server/tailscale.md b/docs/configuration/dns/server/tailscale.md index d28a11c6..35d22f83 100644 --- a/docs/configuration/dns/server/tailscale.md +++ b/docs/configuration/dns/server/tailscale.md @@ -49,8 +49,6 @@ if not enabled, `NXDOMAIN` will be returned for non-Tailscale domain queries. When enabled, single-label queries (e.g. `my-device`) are retried against each Tailscale search domain until one resolves. -Default resolvers are not consulted for single-label queries regardless of `accept_default_resolvers`. - ### Examples === "MagicDNS only" diff --git a/docs/configuration/dns/server/tailscale.zh.md b/docs/configuration/dns/server/tailscale.zh.md index 40fae69c..d1b33c93 100644 --- a/docs/configuration/dns/server/tailscale.zh.md +++ b/docs/configuration/dns/server/tailscale.zh.md @@ -49,8 +49,6 @@ icon: material/new-box 启用后，单标签查询（例如 `my-device`）将依次附加 Tailscale 搜索域进行重试，直到其中一个解析成功。 -对于单标签查询，无论 `accept_default_resolvers` 是否启用，都不会使用默认 DNS 解析器。 - ### 示例 === "仅 MagicDNS" diff --git a/docs/configuration/endpoint/openconnect.md b/docs/configuration/endpoint/openconnect.md index 8afb65ba..ef8e3c34 100644 --- a/docs/configuration/endpoint/openconnect.md +++ b/docs/configuration/endpoint/openconnect.md @@ -198,7 +198,7 @@ For `totp` and `hotp`, this can be a Base32 secret, a `base32:`-prefixed secret, For `stoken`, this is the encoded RSA SecurID CTF token content. -For `oidc`, this is the access token value. It is sent only after the VPN server requests HTTP Bearer authentication. +For `oidc`, this is the access token value. Conflict with `token.secret_path`. @@ -244,7 +244,7 @@ The default is flavor-specific. AnyConnect, Network Connect, Pulse, and F5 use ` Client version reported separately from `user_agent` when supported by the selected flavor. -`v9.21` is used by default. Currently used by AnyConnect XML authentication. +`v9.21` is used by default. ### local_hostname @@ -254,7 +254,7 @@ The system hostname is used by default, or `localhost` if it is unavailable. ### mobile -AnyConnect mobile client identity. When configured, all three fields are required and are reported during XML authentication and tunnel establishment. +AnyConnect mobile client identity. When configured, all three fields are required. ### mobile.platform_version @@ -348,11 +348,9 @@ Conflict with `tncc.certificates.certificate`. ### fortinet_host_check -Fortinet hostcheck result override. +Fortinet hostcheck result override, submitted when requested by the server. -Hostcheck is disabled by default. It is enabled only when `fortinet_host_check.hostcheck` is non-empty. No operating system, security product, or network interface information is collected automatically. - -When enabled and a successful Fortinet login response requests hostcheck, both configured values are submitted to the server before the VPN session is used. The values are sent unchanged as `application/x-www-form-urlencoded` fields. +Disabled if `fortinet_host_check.hostcheck` is empty. Some Fortinet servers only request hostcheck from recognized FortiClient user agents. Configure `user_agent` when required by the server policy. @@ -362,13 +360,11 @@ Fortinet hostcheck result string. The conventional format is `,`, for example `0100,10.0.19042`. `security-status` contains four `0` or `1` characters representing, in order, third-party firewall, third-party antivirus, FortiClient firewall, and FortiClient antivirus. -An empty value disables Fortinet hostcheck, even if `fortinet_host_check.check_virtual_desktop` is configured. - ### fortinet_host_check.check_virtual_desktop Fortinet virtual desktop check result string. -FortiClient conventionally sends colon-separated MAC addresses joined by `|`, for example `74:78:27:4d:81:93|84:1b:77:3a:95:84`. An empty value is submitted as an empty field when hostcheck is enabled. +FortiClient conventionally sends colon-separated MAC addresses joined by `|`, for example `74:78:27:4d:81:93|84:1b:77:3a:95:84`. ### no_udp @@ -386,8 +382,6 @@ Disable AnyConnect compression negotiation. By default, stateless `oc-lz4` and `lzs` compression is negotiated for CSTP and DTLS when supported by the server. -Compression can weaken traffic confidentiality when an attacker can influence plaintext sent through the VPN tunnel. - Conflict with `compression_mode` set to `all`. ### compression_mode @@ -397,9 +391,7 @@ AnyConnect compression mode, one of: - `stateless`: Advertise stateless `oc-lz4` and `lzs` compression. - `all`: Additionally advertise stateful `deflate` compression for CSTP. -`stateless` is used by default. DTLS always uses stateless compression, including when `all` is selected. - -Stateful compression has additional traffic confidentiality risks and should only be enabled when required by the VPN server. +`stateless` is used by default. ### ipv6_disabled @@ -417,19 +409,15 @@ Disable AnyConnect XML POST authentication and start authentication with the leg Disable external browser authentication such as SSO and SAML for AnyConnect, GlobalProtect, and Fortinet. -When enabled, external authentication is not advertised for AnyConnect or GlobalProtect, and any unexpected external authentication request, including Fortinet SAML, is rejected. - ### password_authentication_disabled Abort AnyConnect authentication if the server returns a non-success authentication form, matching OpenConnect `--no-passwd` behavior. -This does not affect the other flavors or a session supplied by `cookie`. - ### tcp_keep_alive_enabled Enable TCP keep alive for direct VPN server connections. -Disabled by default to match OpenConnect. Setting `tcp_keep_alive` or `tcp_keep_alive_interval` also enables it without requiring this field. When enabled without either duration, the operating system TCP keep alive timing is retained. +Setting `tcp_keep_alive` or `tcp_keep_alive_interval` also enables it. When enabled without either duration, the operating system defaults are used. Conflict with `disable_tcp_keep_alive`. @@ -437,13 +425,11 @@ Conflict with `disable_tcp_keep_alive`. Require forward-secret TLS cipher suites for TLS 1.2 and earlier. -Disabled by default for compatibility with VPN servers that require RSA key exchange. This does not enable deprecated cipher suites; see `allow_insecure_crypto` for legacy crypto support. - ### mtu Preferred tunnel MTU. -The negotiated MTU is limited to this value for all flavors. For AnyConnect, this value is also sent to the server. GlobalProtect, F5, and Fortinet remove their protocol overhead before using it as the tunnel MTU. +The negotiated MTU is limited to this value. Non-zero values below `576` are treated as `576`. The maximum value is `65535`. @@ -465,7 +451,7 @@ Positive values below `2s` are treated as `2s`. The value must not be negative. ### reconnect_timeout -Maximum accumulated backoff time after failed reconnect attempts. The first reconnect attempt starts immediately, and this timeout does not cancel an attempt already in progress. +Maximum accumulated backoff time after failed reconnect attempts. `300s` is used by default. @@ -483,13 +469,13 @@ The value must not be negative. Inbound and outbound packet queue length between the VPN transport and the tunnel interface. -`32` is used by default. A full queue applies backpressure until its consumer makes room; queued packets are not discarded. +`32` is used by default. ### allow_insecure_crypto Enable weak TLS and DTLS cipher suites and TLS 1.0 compatibility required by legacy VPN servers. -Disabled by default; TLS versions below 1.2 are otherwise rejected. This option does not disable server certificate verification. +Disabled by default; TLS versions below 1.2 are otherwise rejected. ### tls @@ -499,7 +485,7 @@ OpenConnect TLS configuration. Disable verification of the VPN server certificate and hostname. -Disabled by default. Enabling this permits an active attacker to impersonate the VPN server. Prefer `tls.certificate_authority` or `tls.peer_fingerprint` when possible. +Disabled by default. Prefer `tls.certificate_authority` or `tls.peer_fingerprint` when possible. ### tls.server_name @@ -648,4 +634,4 @@ Use `Tools` > `Endpoints` in the sing-box dashboard or any sing-box graphical cl ## DNS -Pushed DNS settings are not installed into the operating system. Configure an [OpenConnect DNS server](/configuration/dns/server/openconnect/) to use them through sing-box. +Configure an [OpenConnect DNS server](/configuration/dns/server/openconnect/) to use the pushed DNS settings. diff --git a/docs/configuration/endpoint/openconnect.zh.md b/docs/configuration/endpoint/openconnect.zh.md index 904a4041..eab4f2e3 100644 --- a/docs/configuration/endpoint/openconnect.zh.md +++ b/docs/configuration/endpoint/openconnect.zh.md @@ -198,7 +198,7 @@ Token 模式，可选值为： 对于 `stoken`，这是编码后的 RSA SecurID CTF token 内容。 -对于 `oidc`，这是 access token 值。仅在 VPN 服务器请求 HTTP Bearer 认证后发送。 +对于 `oidc`，这是 access token 值。 与 `token.secret_path` 冲突。 @@ -244,7 +244,7 @@ Token 模式，可选值为： 所选 flavor 支持时，与 `user_agent` 分开报告的客户端版本。 -默认使用 `v9.21`。当前用于 AnyConnect XML 认证。 +默认使用 `v9.21`。 ### local_hostname @@ -254,7 +254,7 @@ Token 模式，可选值为： ### mobile -AnyConnect 移动客户端身份。配置时三个字段均为必填，并会在 XML 认证和隧道建立阶段报告。 +AnyConnect 移动客户端身份。配置时三个字段均为必填。 ### mobile.platform_version @@ -348,11 +348,9 @@ PEM 格式的 TNCC 机器证书路径。 ### fortinet_host_check -Fortinet hostcheck 结果覆盖选项。 +Fortinet hostcheck 结果覆盖选项，在服务器要求时提交。 -默认禁用 hostcheck。仅当 `fortinet_host_check.hostcheck` 非空时启用。不会自动收集操作系统、安全产品或网络接口信息。 - -启用后，如果成功的 Fortinet 登录响应要求 hostcheck，将在使用 VPN 会话前向服务器提交两个配置值。这些值不经修改，作为 `application/x-www-form-urlencoded` 字段发送。 +`fortinet_host_check.hostcheck` 为空时禁用。 部分 Fortinet 服务器只会要求可识别的 FortiClient User-Agent 执行 hostcheck。服务器策略有要求时请配置 `user_agent`。 @@ -362,13 +360,11 @@ Fortinet hostcheck 结果字符串。 通常格式为 `,`，例如 `0100,10.0.19042`。`security-status` 包含四个 `0` 或 `1` 字符，依次表示第三方防火墙、第三方杀毒软件、FortiClient 防火墙和 FortiClient 杀毒软件。 -空值会禁用 Fortinet hostcheck，即使配置了 `fortinet_host_check.check_virtual_desktop`。 - ### fortinet_host_check.check_virtual_desktop Fortinet virtual desktop 检查结果字符串。 -FortiClient 通常发送以冒号分隔的 MAC 地址，多个地址使用 `|` 连接，例如 `74:78:27:4d:81:93|84:1b:77:3a:95:84`。启用 hostcheck 时，空值会作为空字段提交。 +FortiClient 通常发送以冒号分隔的 MAC 地址，多个地址使用 `|` 连接，例如 `74:78:27:4d:81:93|84:1b:77:3a:95:84`。 ### no_udp @@ -386,8 +382,6 @@ FortiClient 通常发送以冒号分隔的 MAC 地址，多个地址使用 `|` 默认情况下，当服务器支持时，CSTP 和 DTLS 会协商无状态 `oc-lz4` 和 `lzs` 压缩。 -当攻击者能够影响通过 VPN 隧道发送的明文时，压缩可能削弱流量机密性。 - 与设置为 `all` 的 `compression_mode` 冲突。 ### compression_mode @@ -397,9 +391,7 @@ AnyConnect 压缩模式，可选值为： - `stateless`：声明支持无状态 `oc-lz4` 和 `lzs` 压缩。 - `all`：额外声明支持 CSTP 有状态 `deflate` 压缩。 -默认使用 `stateless`。即使选择 `all`，DTLS 也始终使用无状态压缩。 - -有状态压缩存在额外的流量机密性风险，仅应在 VPN 服务器需要时启用。 +默认使用 `stateless`。 ### ipv6_disabled @@ -417,19 +409,15 @@ AnyConnect 压缩模式，可选值为： 禁用 AnyConnect、GlobalProtect 和 Fortinet 的 SSO、SAML 等外部浏览器认证。 -启用时不会为 AnyConnect 或 GlobalProtect 向服务器声明外部认证支持，并会拒绝任何意外收到的外部认证请求，包括 Fortinet SAML。 - ### password_authentication_disabled 如果服务器返回非成功的认证表单，则中止 AnyConnect 认证，与 OpenConnect `--no-passwd` 行为一致。 -此选项不影响其他 flavor，也不影响由 `cookie` 提供的会话。 - ### tcp_keep_alive_enabled 为直接 VPN 服务器连接启用 TCP keep alive。 -默认禁用以匹配 OpenConnect。设置 `tcp_keep_alive` 或 `tcp_keep_alive_interval` 也会启用，无需同时设置此字段。启用但未设置这两个时间值时，保留操作系统的 TCP keep alive 时间设置。 +设置 `tcp_keep_alive` 或 `tcp_keep_alive_interval` 也会启用。启用但未设置这两个时间值时，使用操作系统默认值。 与 `disable_tcp_keep_alive` 冲突。 @@ -437,13 +425,11 @@ AnyConnect 压缩模式，可选值为： 要求 TLS 1.2 及更早版本使用具有前向保密性的 TLS 密码套件。 -默认禁用，以兼容需要 RSA 密钥交换的 VPN 服务器。此选项不会启用已弃用的密码套件；旧版加密支持参阅 `allow_insecure_crypto`。 - ### mtu 首选隧道 MTU。 -所有 flavor 协商的 MTU 都不会超过此值。对于 AnyConnect，此值还会发送给服务器。GlobalProtect、F5 和 Fortinet 会先扣除各自的协议开销，再将结果作为隧道 MTU。 +协商的 MTU 不超过此值。 非零值小于 `576` 时按 `576` 处理。最大值为 `65535`。 @@ -465,7 +451,7 @@ AnyConnect 压缩模式，可选值为： ### reconnect_timeout -重连尝试失败后允许累计使用的最大退避时间。断线后的第一次重连会立即开始，且此超时不会取消已经进行中的尝试。 +重连尝试失败后允许累计使用的最大退避时间。 默认使用 `300s`。 @@ -483,13 +469,13 @@ AnyConnect 压缩模式，可选值为： VPN transport 与隧道接口之间的入站和出站数据包队列长度。 -默认使用 `32`。队列已满时会施加反压并等待消费者腾出空间，不会丢弃已排队的数据包。 +默认使用 `32`。 ### allow_insecure_crypto 启用旧版 VPN 服务器所需的弱 TLS 和 DTLS 密码套件及 TLS 1.0 兼容性。 -默认禁用；未启用时会拒绝低于 TLS 1.2 的版本。此选项不会禁用服务器证书验证。 +默认禁用；未启用时会拒绝低于 TLS 1.2 的版本。 ### tls @@ -499,7 +485,7 @@ OpenConnect TLS 配置。 禁用 VPN 服务器证书和主机名验证。 -默认禁用。启用后，主动攻击者可以冒充 VPN 服务器。应尽可能使用 `tls.certificate_authority` 或 `tls.peer_fingerprint`。 +默认禁用。应尽可能使用 `tls.certificate_authority` 或 `tls.peer_fingerprint`。 ### tls.server_name @@ -648,4 +634,4 @@ MCA 证书和私钥必须同时设置或同时为空。 ## DNS -推送的 DNS 设置不会安装到操作系统中。配置 [OpenConnect DNS 服务器](/zh/configuration/dns/server/openconnect/) 以通过 sing-box 使用这些设置。 +配置 [OpenConnect DNS 服务器](/zh/configuration/dns/server/openconnect/) 以使用推送的 DNS 设置。 diff --git a/docs/configuration/endpoint/openvpn-client.md b/docs/configuration/endpoint/openvpn-client.md index d35a35f7..7501beba 100644 --- a/docs/configuration/endpoint/openvpn-client.md +++ b/docs/configuration/endpoint/openvpn-client.md @@ -120,9 +120,7 @@ OpenVPN session mode, one of `tls` or `static_key`. `tls` is used by default. `static_key` is a deprecated OpenVPN mode without a TLS control channel or -forward secrecy. It is retained as an explicit compatibility option for -immutable enterprise VPN servers. It does not use `tls`, username/password -authentication, pull options, or TLS renegotiation options. +forward secrecy. ### server @@ -264,7 +262,7 @@ OpenVPN control channel TLS configuration. Expected server certificate name. -Certificate name verification is disabled if empty. The certificate chain or fingerprint and server certificate usage are still verified. +Certificate name verification is disabled if empty. ### tls.server_name_type @@ -322,14 +320,10 @@ Allowed SHA-256 fingerprints of the server leaf certificate. Each fingerprint must be 64 lowercase hexadecimal characters without separators. -When a trusted CA is also configured, both the certificate chain and fingerprint are verified. Without a trusted CA, the fingerprint, certificate validity period, configured name, and certificate usage are verified, but the certificate chain is not. - ### tls.crl_path Path to a PEM or DER certificate revocation list used to reject revoked server certificates. -The CRL signature and validity period are verified against the trusted certificate chain. - Disabled by default. ### tls.remote_certificate_ku @@ -371,7 +365,7 @@ keys for compatibility with immutable peers. Use it only when the peer cannot be upgraded. `legacy` accepts SHA-1 but rejects MD5 signatures; `preferred` requires stronger signatures and keys. -When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. Explicit `tls.cipher` and `tls.groups` values are not restricted by the profile. +When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. ### tls.ns_certificate_type @@ -397,7 +391,7 @@ The value cannot be lower than `tls.version_min`. Colon-separated OpenSSL cipher suite names allowed for TLS 1.2 and earlier. -The default TLS cipher suites are used when empty. TLS 1.3 cipher suites are not controlled by this field. +The default TLS cipher suites are used when empty. ### tls.groups @@ -441,13 +435,11 @@ Only available when `tls.control_wrap.type` is `tls_auth`. The key is used bidir Data-channel cipher used in `static_key` mode. -The upstream static-key default `BF-CBC` is used when empty. `BF-CBC` is a -legacy cipher with a 64-bit block size; configure the cipher required by the -server explicitly whenever possible. Static-key ciphers include `BF-CBC`, +The upstream static-key default `BF-CBC` is used when empty. Static-key ciphers include `BF-CBC`, `CAST5-CBC`, `DES-CBC`, `DES-EDE-CBC`, `DES-EDE3-CBC`, the AES-CBC, ARIA-CBC, and Camellia-CBC families, `SEED-CBC`, `SM4-CBC`, and `NONE`. -Only available in `static_key` mode. `NONE` provides no confidentiality. +Only available in `static_key` mode. ### data_ciphers @@ -460,8 +452,7 @@ Only available in TLS mode. The AES-GCM family includes `AES-192-GCM`. Retained ciphers include the CBC, CFB, and OFB forms of AES, ARIA, Camellia, DES, Blowfish, and CAST5, the CBC, CFB, and OFB forms of SEED and SM4, and `NONE`. CFB and OFB are available only -in TLS mode. Legacy ciphers provide weaker or no confidentiality and are not -enabled by default. +in TLS mode. ### data_ciphers_fallback @@ -477,15 +468,10 @@ OpenVPN data channel authentication digest. `SHA1` is used by default. It only applies to non-AEAD data ciphers and `tls_auth`. -Legacy digests including `MD5` and `RIPEMD160` remain available when explicitly -configured for compatibility. - ### mss_fix Maximum OpenVPN UDP packet size used to clamp the MSS of TCP connections sent through the tunnel. -This prevents TCP packets from exceeding the path MTU after OpenVPN encapsulation. - When empty, the upstream OpenVPN default is used: `fragment` when configured, otherwise `1492` for the default tunnel MTU or the configured tunnel MTU. @@ -515,8 +501,6 @@ Conflict with TCP transport. UDP data-channel replay window size. `64` is used by default. The maximum is `65536`. -TCP always requires strictly consecutive packet IDs. - ### replay_window_time UDP data-channel replay window duration. `15s` is used by default and the maximum is `10m`. @@ -529,21 +513,17 @@ OpenVPN `compress` framing mode, one of `none`, `no`, `lz4`, `lz4-v2`, `stub`, ` Disabled by default. -Compression can weaken traffic confidentiality. Prefer `stub` or `stub-v2` only when framing compatibility is required. - ### compression_lzo OpenVPN `comp-lzo` mode, one of `none`, `no`, `yes`, `adaptive`, `asym`, `disabled`, or `off`. Disabled by default. -Compression can weaken traffic confidentiality. Enable it only when required by the server. - ### allow_compression Policy for compression pushed by the server, one of `no`, `asym`, or `yes`. -`no` is used by default and permits only compression stub framing. `asym` accepts compressed packets from the server but does not compress outgoing packets. For OpenVPN 2.7 compatibility, `yes` is accepted as a legacy alias for `asym`; the client never sends compressed packets. +`no` is used by default and permits only compression stub framing. `asym` accepts compressed packets from the server but does not compress outgoing packets. `yes` is a legacy alias for `asym`. Conflict with non-stub compression enabled by `compression` or `compression_lzo` when set to `no`. @@ -552,8 +532,6 @@ Conflict with non-stub compression enabled by `compression` or `compression_lzo` Ignore routes, DNS and DHCP settings, route metrics, `redirect-gateway`, `redirect-private`, `block-ipv6`, and `block-outside-dns` pushed by the server. -Interface configuration, topology, tunnel MTU, `route-gateway`, and locally configured routes are still used. - Disabled by default. ### pull_filters @@ -584,53 +562,38 @@ IPv4 and IPv6 prefixes preferred by sing-box routing for this OpenVPN endpoint. These routes are used in addition to routes accepted from the server. -They do not install operating-system routes. Select the endpoint through -sing-box route rules or its preferred-route behavior. - ### route_gateway IPv4 gateway for routes through the OpenVPN endpoint. When empty, the VPN gateway received from the server is used. -The value is retained for OpenVPN configuration compatibility; endpoint route -preference is prefix-based and does not install a system gateway route. - ### route_metric Default metric for routes through the OpenVPN endpoint. The platform default is used when `0`. -The value is retained for OpenVPN configuration compatibility and does not -install a system route. - ### redirect_gateway Prefer the OpenVPN endpoint for all IPv4 destinations in sing-box routing. Disabled by default. -This does not install an operating-system default route. - ### redirect_gateway_flags OpenVPN `redirect-gateway` flags. `!ipv4` disables IPv4 preference, `def1` represents it with two `/1` -prefixes, and `ipv6` also prefers the upstream-specific IPv6 prefixes. The -OpenVPN control connection always uses its configured outbound dialer rather -than endpoint routes, so `local` and `autolocal` require no system-route -exception. `bypass-dhcp` and `bypass-dns` are not applicable because sing-box -does not install pushed DHCP or DNS settings into the operating system. -`block-local` is unsupported because the endpoint has no cross-platform source -for the physical default gateway needed to preserve the gateway exception. +prefixes, and `ipv6` also prefers the upstream-specific IPv6 prefixes. +`local`, `autolocal`, `bypass-dhcp` and `bypass-dns` have no effect. +`block-local` is not supported. Empty by default. ### redirect_private -Accept `redirect_gateway_flags` without adding a default-route preference. Routes pushed or configured separately still affect the endpoint's preferred addresses, but no operating-system routes are installed. +Accept `redirect_gateway_flags` without adding a default-route preference. Disabled by default. @@ -707,9 +670,6 @@ Use a system interface. Requires privilege and cannot conflict with existing system interfaces. -The endpoint configures interface addresses and MTU but does not install -operating-system routes or DNS settings. - If disabled, sing-box uses the internal network stack. ### name diff --git a/docs/configuration/endpoint/openvpn-client.zh.md b/docs/configuration/endpoint/openvpn-client.zh.md index 1ee072de..fd7fdb13 100644 --- a/docs/configuration/endpoint/openvpn-client.zh.md +++ b/docs/configuration/endpoint/openvpn-client.zh.md @@ -120,8 +120,6 @@ OpenVPN 会话模式，可选值为 `tls` 或 `static_key`。 默认使用 `tls`。 `static_key` 是已弃用的 OpenVPN 模式，不使用 TLS 控制通道且不提供前向保密。 -为兼容无法修改的企业 VPN 服务器，此模式仍作为显式兼容选项保留。该模式不使用 -`tls`、用户名/密码认证、拉取选项或 TLS 重协商选项。 ### server @@ -261,7 +259,7 @@ OpenVPN 控制通道 TLS 配置。 预期的服务器证书名称。 -为空时禁用证书名称验证，但仍会验证证书链或 fingerprint 与服务器证书用途。 +为空时禁用证书名称验证。 ### tls.server_name_type @@ -319,14 +317,10 @@ OpenVPN 控制通道 TLS 配置。 每个 fingerprint 必须是不带分隔符的 64 字符小写十六进制字符串。 -同时配置受信任 CA 时，会同时验证证书链和 fingerprint。未配置受信任 CA 时，会验证 fingerprint、证书有效期、配置的名称和证书用途，但不验证证书链。 - ### tls.crl_path 用于拒绝已吊销服务器证书的 PEM 或 DER CRL 文件路径。 -根据受信任证书链验证 CRL 签名和有效期。 - 默认禁用。 ### tls.remote_certificate_ku @@ -365,7 +359,7 @@ OpenVPN 控制通道 TLS 配置。 `insecure` 为兼容不可变对端而接受使用 MD5 或 SHA-1 签名的证书链和较小的旧密钥，仅应在对端无法升级时使用。`legacy` 接受 SHA-1 但拒绝 MD5 签名；`preferred` 要求更强的签名和密钥。 -选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。该 profile 不限制显式配置的 `tls.cipher` 和 `tls.groups`。 +选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。 ### tls.ns_certificate_type @@ -391,7 +385,7 @@ OpenVPN 控制通道 TLS 配置。 TLS 1.2 及更低版本允许的 OpenSSL cipher suite 名称，以冒号分隔。 -为空时使用默认 TLS cipher suite。该字段不控制 TLS 1.3 cipher suite。 +为空时使用默认 TLS cipher suite。 ### tls.groups @@ -435,12 +429,11 @@ OpenVPN 控制通道封装。 `static_key` 模式使用的数据通道 cipher。 -为空时使用上游静态密钥模式的默认值 `BF-CBC`。`BF-CBC` 是采用 64 位 block size -的旧 cipher；应尽可能显式配置服务器要求的 cipher。静态密钥 cipher 包括 +为空时使用上游静态密钥模式的默认值 `BF-CBC`。静态密钥 cipher 包括 `BF-CBC`、`CAST5-CBC`、`DES-CBC`、`DES-EDE-CBC`、`DES-EDE3-CBC`、 AES-CBC、ARIA-CBC、Camellia-CBC 系列，以及 `SEED-CBC`、`SM4-CBC` 和 `NONE`。 -仅在 `static_key` 模式下可用。`NONE` 不提供机密性。 +仅在 `static_key` 模式下可用。 ### data_ciphers @@ -450,7 +443,7 @@ AES-CBC、ARIA-CBC、Camellia-CBC 系列，以及 `SEED-CBC`、`SM4-CBC` 和 `NO 默认使用 `AES-256-GCM`、`AES-128-GCM` 和 `CHACHA20-POLY1305`。 -AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。旧 cipher 只能提供较弱的机密性或完全不加密，因此默认不启用。 +AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。 ### data_ciphers_fallback @@ -466,14 +459,10 @@ OpenVPN 数据通道认证摘要。 默认使用 `SHA1`，仅应用于非 AEAD 数据 cipher 和 `tls_auth`。 -为兼容既有服务器，显式配置时仍可使用 `MD5` 和 `RIPEMD160` 等旧摘要。 - ### mss_fix OpenVPN UDP packet 的最大大小，用于限制通过隧道发送的 TCP 连接 MSS。 -这可以避免 TCP packet 在 OpenVPN 封装后超过 path MTU。 - 为空时使用上游 OpenVPN 默认值：配置了 `fragment` 时使用其值；否则默认 tunnel MTU 使用 `1492`，自定义 tunnel MTU 使用该 MTU。 ### mss_fix_disabled @@ -502,8 +491,6 @@ OpenVPN UDP packet 的最大大小，用于限制通过隧道发送的 TCP 连 UDP 数据通道重放窗口大小。默认使用 `64`，最大值为 `65536`。 -TCP 始终要求数据包 ID 严格连续。 - ### replay_window_time UDP 数据通道重放窗口时长。默认使用 `15s`，最大值为 `10m`。 @@ -516,21 +503,17 @@ OpenVPN `compress` framing 模式，可选值为 `none`、`no`、`lz4`、`lz4-v2 默认禁用。 -Compression 可能削弱流量机密性。仅在需要 framing 兼容性时使用 `stub` 或 `stub-v2`。 - ### compression_lzo OpenVPN `comp-lzo` 模式，可选值为 `none`、`no`、`yes`、`adaptive`、`asym`、`disabled` 或 `off`。 默认禁用。 -Compression 可能削弱流量机密性。仅在服务器要求时启用。 - ### allow_compression 服务器推送的 compression 策略，可选值为 `no`、`asym` 或 `yes`。 -默认使用 `no`，仅允许 compression stub framing。`asym` 接受来自服务器的 compressed packet，但不压缩出站 packet。为兼容 OpenVPN 2.7，`yes` 作为 `asym` 的旧别名接受；客户端绝不会发送 compressed packet。 +默认使用 `no`，仅允许 compression stub framing。`asym` 接受来自服务器的 compressed packet，但不压缩出站 packet。`yes` 是 `asym` 的旧别名。 当设为 `no` 时，与通过 `compression` 或 `compression_lzo` 启用的非 stub compression 冲突。 @@ -539,8 +522,6 @@ Compression 可能削弱流量机密性。仅在服务器要求时启用。 忽略服务器推送的 route、DNS 和 DHCP 设置、route metric、`redirect-gateway`、 `redirect-private`、`block-ipv6` 和 `block-outside-dns`。 -仍会使用接口配置、topology、tunnel MTU、`route-gateway` 和本地配置的 route。 - 默认禁用。 ### pull_filters @@ -571,43 +552,35 @@ sing-box 路由优先选择此 OpenVPN endpoint 的 IPv4 和 IPv6 前缀。 这些 route 会与从服务器接受的 route 一起使用。 -它们不会安装操作系统路由。请通过 sing-box 路由规则或 endpoint 的首选路由行为选择此 endpoint。 - ### route_gateway 通过 OpenVPN endpoint 路由的 IPv4 gateway。 为空时使用从服务器接收的 VPN gateway。 -该值仅为兼容 OpenVPN 配置而保留；endpoint 的路由偏好只按前缀判断，不会安装系统 gateway 路由。 - ### route_metric 通过 OpenVPN endpoint 路由的默认 metric。 设为 `0` 时使用平台默认值。 -该值仅为兼容 OpenVPN 配置而保留，不会安装系统路由。 - ### redirect_gateway 在 sing-box 路由中对所有 IPv4 目的地优先选择 OpenVPN endpoint。 默认禁用。 -这不会安装操作系统默认路由。 - ### redirect_gateway_flags OpenVPN `redirect-gateway` flag。 -`!ipv4` 禁用 IPv4 偏好，`def1` 使用两个 `/1` 前缀表示，`ipv6` 还会优先选择上游特定的 IPv6 前缀。OpenVPN 控制连接始终使用其配置的出站拨号器，不经过 endpoint 路由，因此 `local` 和 `autolocal` 不需要系统路由例外。由于 sing-box 不会把推送的 DHCP 或 DNS 设置安装到操作系统，`bypass-dhcp` 和 `bypass-dns` 不适用。`block-local` 不受支持，因为 endpoint 没有可跨平台获取物理默认网关的来源，无法保留网关例外。 +`!ipv4` 禁用 IPv4 偏好，`def1` 使用两个 `/1` 前缀表示，`ipv6` 还会优先选择上游特定的 IPv6 前缀。`local`、`autolocal`、`bypass-dhcp` 和 `bypass-dns` 无效果。不支持 `block-local`。 默认为空。 ### redirect_private -接受 `redirect_gateway_flags`，但不添加默认路由偏好。单独推送或配置的路由仍会影响 endpoint 的首选地址，但不会安装操作系统路由。 +接受 `redirect_gateway_flags`，但不添加默认路由偏好。 默认禁用。 @@ -683,8 +656,6 @@ Notification 之间间隔一秒。设为 `0` 时禁用。 需要权限，且不能与现有系统接口冲突。 -endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。 - 禁用时，sing-box 使用内部网络栈。 ### name diff --git a/docs/configuration/endpoint/openvpn-server.md b/docs/configuration/endpoint/openvpn-server.md index 37802ba8..3b4d82a7 100644 --- a/docs/configuration/endpoint/openvpn-server.md +++ b/docs/configuration/endpoint/openvpn-server.md @@ -111,9 +111,6 @@ Use system interface. Requires privilege and cannot conflict with existing system interfaces. -The endpoint configures interface addresses and MTU but does not install -operating-system routes or DNS settings. - If disabled, sing-box uses the internal network stack. ### name @@ -135,8 +132,6 @@ OpenVPN session mode, one of `tls` or `static_key`. `tls` is used by default. `static_key` serves one peer without a TLS control channel or forward secrecy. -It is retained as an explicit compatibility option for immutable deployments. -It does not use `tls`, `users`, push options, or TLS renegotiation options. ### network @@ -145,15 +140,13 @@ OpenVPN transport network, one of `udp` or `tcp`. `udp` will be used by default. Only one transport network is served per endpoint; to serve both TCP and UDP, -configure two endpoints with separate `address` subnets, -matching upstream OpenVPN which requires two server processes. +configure two endpoints with separate `address` subnets. ### remote Fixed remote peer address for a UDP `static_key` server. -Required with `remote_port` in UDP `static_key` mode. TCP servers accept the -single peer from the listening socket and do not use this field. +Required with `remote_port` in UDP `static_key` mode. ### remote_port @@ -165,9 +158,9 @@ Required with `remote` in UDP `static_key` mode. Maximum number of established and pending TLS client sessions. -`1024` is used by default. The value must be smaller than `16777216`, the size of the OpenVPN peer-id space. +`1024` is used by default. The maximum value is `16777215`. -`static_key` mode supports one peer, so this value must be `0` or `1`. +Must be `0` or `1` in `static_key` mode. ### address @@ -317,8 +310,6 @@ If set to `optional`, a client certificate is verified when provided, but client If set to `none`, client certificates are not requested. -This field does not replace `users`; when `users` is set, username/password authentication is still required. - ### tls.client_name Expected client certificate name. Disabled when empty. @@ -360,7 +351,7 @@ keys for compatibility with immutable peers. Use it only when the peer cannot be upgraded. `legacy` accepts SHA-1 but rejects MD5 signatures; `preferred` requires stronger signatures and keys. -When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. Explicit `tls.cipher` and `tls.groups` values are not restricted by the profile. +When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. ### tls.ns_certificate_type @@ -378,7 +369,7 @@ Maximum TLS version. The maximum supported version is used by default. Colon-separated OpenSSL cipher suite names allowed for TLS 1.2 and earlier. -The default TLS cipher suites are used when empty. TLS 1.3 cipher suites are not controlled by this field. +The default TLS cipher suites are used when empty. ### tls.groups @@ -443,7 +434,7 @@ The upstream static-key default `BF-CBC` is used when empty. Supported static-key ciphers are the AES-CBC, ARIA-CBC, Camellia-CBC, DES-CBC, Blowfish-CBC, CAST5-CBC families, `SEED-CBC`, `SM4-CBC`, and `NONE`. -Only available in `static_key` mode. `NONE` provides no confidentiality. +Only available in `static_key` mode. ### data_ciphers @@ -454,8 +445,7 @@ Allowed OpenVPN data channel ciphers. The AES-GCM family includes `AES-192-GCM`. Retained ciphers include the CBC, CFB, and OFB forms of AES, ARIA, Camellia, DES, Blowfish, and CAST5, the CBC, CFB, and OFB forms of SEED and SM4, and `NONE`. CFB and OFB are available only -in TLS mode. Legacy ciphers provide weaker or no confidentiality and are not -enabled by default. +in TLS mode. Only available in TLS mode. @@ -473,10 +463,7 @@ Only available in TLS mode. OpenVPN data channel authentication digest. -`SHA1` will be used by default, matching the upstream default; it only applies to non-AEAD data ciphers and `tls_auth`. - -Legacy digests including `MD5` and `RIPEMD160` remain available when explicitly -configured for compatibility. +`SHA1` will be used by default. It only applies to non-AEAD data ciphers and `tls_auth`. ### mss_fix @@ -492,7 +479,7 @@ Calculation mode for an explicit `mss_fix`, one of `mtu` or `fixed`. Requires `m ### replay_window -UDP data-channel replay window size. `64` is used by default; TCP packet IDs remain strictly consecutive. +UDP data-channel replay window size. `64` is used by default. ### replay_window_time @@ -582,8 +569,6 @@ Time without receiving a packet after which the server closes the client session This value applies to the server. Use `push.ping_restart` to configure clients. -The server timeout should be longer than the client timeout so the client can reconnect before the server discards its session. - The value must use whole seconds. Disabled by default. diff --git a/docs/configuration/endpoint/openvpn-server.zh.md b/docs/configuration/endpoint/openvpn-server.zh.md index 2ebdbce1..4738e202 100644 --- a/docs/configuration/endpoint/openvpn-server.zh.md +++ b/docs/configuration/endpoint/openvpn-server.zh.md @@ -111,8 +111,6 @@ 需要特权且不能与已有系统接口冲突。 -endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。 - 如果禁用，sing-box 将使用内部网络栈。 ### name @@ -133,7 +131,7 @@ OpenVPN 会话模式，`tls` 或 `static_key` 之一。 默认使用 `tls`。 -`static_key` 在没有 TLS 控制信道和前向保密的情况下服务一个对端，仅作为不可变部署的显式兼容选项保留。该模式不使用 `tls`、`users`、推送选项或 TLS 重协商选项。 +`static_key` 在没有 TLS 控制信道和前向保密的情况下服务一个对端。 ### network @@ -142,14 +140,13 @@ OpenVPN 传输网络，`udp` 或 `tcp` 之一。 默认使用 `udp`。 每个端点仅服务一种传输网络；如需同时服务 TCP 与 UDP， -需要配置两个端点并使用互不重叠的 `address` 子网， -与上游 OpenVPN 需要两个服务进程一致。 +需要配置两个端点并使用互不重叠的 `address` 子网。 ### remote UDP `static_key` 服务器的固定远端地址。 -在 UDP `static_key` 模式下与 `remote_port` 一起必填。TCP 服务器从监听套接字接受单个对端，不使用此字段。 +在 UDP `static_key` 模式下与 `remote_port` 一起必填。 ### remote_port @@ -161,9 +158,9 @@ UDP `static_key` 服务器的固定远端端口。 已建立与握手中的 TLS 客户端会话的最大数量。 -默认使用 `1024`。该值必须小于 OpenVPN peer-id 空间的大小 `16777216`。 +默认使用 `1024`。最大值为 `16777215`。 -`static_key` 模式仅支持一个对端，因此此值必须为 `0` 或 `1`。 +在 `static_key` 模式下必须为 `0` 或 `1`。 ### address @@ -311,8 +308,6 @@ OpenVPN 客户端证书策略，`require`、`optional` 或 `none` 之一。 设为 `none` 时，不请求客户端证书。 -该字段不替代 `users`；设置 `users` 后仍然要求用户名/密码认证。 - ### tls.client_name 期望的客户端证书名称。为空时禁用。 @@ -351,7 +346,7 @@ OpenVPN `remote-cert-ku` 格式的客户端证书 Key Usage mask。 `insecure` 为兼容不可变对端而接受使用 MD5 或 SHA-1 签名的证书链和较小的旧密钥，仅应在对端无法升级时使用。`legacy` 接受 SHA-1 但拒绝 MD5 签名；`preferred` 要求更强的签名和密钥。 -选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。该 profile 不限制显式配置的 `tls.cipher` 和 `tls.groups`。 +选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。 ### tls.ns_certificate_type @@ -369,7 +364,7 @@ OpenVPN `remote-cert-ku` 格式的客户端证书 Key Usage mask。 TLS 1.2 及更低版本允许的 OpenSSL cipher suite 名称，以冒号分隔。 -为空时使用默认 TLS cipher suite。该字段不控制 TLS 1.3 cipher suite。 +为空时使用默认 TLS cipher suite。 ### tls.groups @@ -431,7 +426,7 @@ OpenVPN `tls-auth` 密钥方向，`server` 或 `client` 之一。 为空时使用上游静态密钥模式的默认值 `BF-CBC`。支持 AES-CBC、ARIA-CBC、Camellia-CBC、DES-CBC、Blowfish-CBC、CAST5-CBC 系列，以及 `SEED-CBC`、`SM4-CBC` 和 `NONE`。 -仅在 `static_key` 模式下可用。`NONE` 不提供机密性。 +仅在 `static_key` 模式下可用。 ### data_ciphers @@ -439,7 +434,7 @@ OpenVPN `tls-auth` 密钥方向，`server` 或 `client` 之一。 默认使用 `AES-256-GCM`、`AES-128-GCM` 和 `CHACHA20-POLY1305`。 -AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。旧 cipher 只能提供较弱的机密性或完全不加密，因此默认不启用。 +AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。 仅在 TLS 模式下可用。 @@ -457,9 +452,7 @@ AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Cam OpenVPN 数据信道认证摘要。 -默认使用 `SHA1`，与上游默认值一致；仅对非 AEAD 数据信道加密方式和 `tls_auth` 生效。 - -为兼容既有客户端，显式配置时仍可使用 `MD5` 和 `RIPEMD160` 等旧摘要。 +默认使用 `SHA1`，仅对非 AEAD 数据信道加密方式和 `tls_auth` 生效。 ### mss_fix @@ -475,7 +468,7 @@ OpenVPN 数据信道认证摘要。 ### replay_window -UDP 数据通道重放窗口大小。默认使用 `64`；TCP 数据包 ID 始终严格连续。 +UDP 数据通道重放窗口大小。默认使用 `64`。 ### replay_window_time @@ -565,8 +558,6 @@ IPv4 和 IPv6 前缀可以混用。 该值应用于服务器。使用 `push.ping_restart` 配置客户端。 -服务器超时应长于客户端超时，以便客户端在服务器丢弃其会话前重新连接。 - 该值必须使用整秒。 默认禁用。 diff --git a/docs/configuration/endpoint/tailscale.md b/docs/configuration/endpoint/tailscale.md index 00d40154..a66dcd19 100644 --- a/docs/configuration/endpoint/tailscale.md +++ b/docs/configuration/endpoint/tailscale.md @@ -177,9 +177,9 @@ Run a Tailscale SSH server on tailnet port 22. Access is controlled by the SSH ACL in the Tailscale admin console, which maps each connection to a local user. How that user is resolved, and which users are allowed, depends on the platform: -- **Linux** and **macOS**: the user is resolved from the system user database. Switching to a user other than the one sing-box runs as requires running as root; without root, sessions are limited to the current user. -- **Windows**: in the command line client, sessions run as the sing-box process identity; the mapped user is not impersonated, so a session mapped to a different local account is refused. In the graphical client, there is no such restriction. -- **Android**: the user is resolved by the app rather than the system user database. `root` is the superuser (UID 0) and `shell` is the ADB shell user (UID 2000); every other name is resolved as the package name of an installed application, running as that application's UID with its data directory as the home directory, so the target application must be installed. `termux` is a shortcut for `com.termux`, and `sing-box` for the app's own package name; when Termux is installed, the `root` and `termux` users load the Termux environment. Running as the sing-box application itself requires no root, while any other user requires granted root access; without root, sessions are limited to the sing-box user. +- **Linux** and **macOS**: switching to a user other than the one sing-box runs as requires running as root. +- **Windows**: in the command line client, sessions mapped to a local account other than the one sing-box runs as are refused. In the graphical client, there is no such restriction. +- **Android**: `root` is the superuser (UID 0) and `shell` is the ADB shell user (UID 2000); every other name is resolved as the package name of an installed application, running as that application's UID with its data directory as the home directory. `termux` is a shortcut for `com.termux`, and `sing-box` for the app's own package name; when Termux is installed, the `root` and `termux` users load the Termux environment. Running as the sing-box application itself requires no root, while any other user requires granted root access. - **macOS**: the SSH server is only available in the standalone version and requires the Helper Service; the App Store version is not supported. - **iOS**: the SSH server is only available in the jailbreak build; the App Store and TestFlight versions are not supported. - **tvOS**: not yet supported. diff --git a/docs/configuration/endpoint/tailscale.zh.md b/docs/configuration/endpoint/tailscale.zh.md index adda6425..887f279c 100644 --- a/docs/configuration/endpoint/tailscale.zh.md +++ b/docs/configuration/endpoint/tailscale.zh.md @@ -176,9 +176,9 @@ UDP NAT 过期时间。 访问控制由 Tailscale 管理控制台中的 SSH ACL 决定，它将每个连接映射到一个本地用户。该用户如何解析、以及允许哪些用户，取决于平台： -- **Linux** 和 **macOS**：从系统用户数据库解析用户。要切换到 sing-box 运行身份以外的用户需要以 root 运行；非 root 时，会话仅限于当前用户。 -- **Windows**：在命令行客户端中，会话以 sing-box 进程的身份运行；映射的用户不会被模拟，因此映射到其他本地账户的会话将被拒绝。在图形客户端中没有此限制。 -- **Android**：用户由应用解析，而非系统用户数据库。`root` 即超级用户（UID 0），`shell` 为 ADB shell 用户（UID 2000）；其他名称均作为已安装应用的包名解析，以该应用的 UID 运行，并使用其数据目录作为主目录，因此目标应用必须已安装。`termux` 是 `com.termux` 的快捷方式，`sing-box` 是应用自身包名的快捷方式；当 Termux 已安装时，`root` 和 `termux` 用户将加载 Termux 环境。以 sing-box 应用自身身份运行无需 root，其他用户则需要已授予的 root 权限；非 root 时，会话仅限于 sing-box 用户。 +- **Linux** 和 **macOS**：要切换到 sing-box 运行身份以外的用户需要以 root 运行。 +- **Windows**：在命令行客户端中，映射到 sing-box 运行身份以外的本地账户的会话将被拒绝。在图形客户端中没有此限制。 +- **Android**：`root` 即超级用户（UID 0），`shell` 为 ADB shell 用户（UID 2000）；其他名称均作为已安装应用的包名解析，以该应用的 UID 运行，并使用其数据目录作为主目录。`termux` 是 `com.termux` 的快捷方式，`sing-box` 是应用自身包名的快捷方式；当 Termux 已安装时，`root` 和 `termux` 用户将加载 Termux 环境。以 sing-box 应用自身身份运行无需 root，其他用户则需要已授予的 root 权限。 - **macOS**：SSH 服务器仅在独立版本中可用，且需要辅助服务；App Store 版本不支持。 - **iOS**：SSH 服务器仅在越狱版本中可用；App Store 和 TestFlight 版本不支持。 - **tvOS**：暂不支持。 diff --git a/docs/configuration/inbound/hysteria2.md b/docs/configuration/inbound/hysteria2.md index 7b5b07a0..4919217d 100644 --- a/docs/configuration/inbound/hysteria2.md +++ b/docs/configuration/inbound/hysteria2.md @@ -203,8 +203,6 @@ Enable debug information logging for Hysteria Brutal CC. Register this inbound to a Hysteria Realm rendezvous service to enable NAT traversal. -The inbound discovers its public addresses via STUN, registers them on the realm, and uses UDP hole-punching to accept incoming clients without a publicly reachable listen address. - See [Hysteria Realm](/configuration/service/hysteria-realm/) for the rendezvous service. #### realm.server_url @@ -255,7 +253,7 @@ The `listen` address must be compatible with the selected version. Maintain a UDP port mapping on the local gateway via UPnP or NAT-PMP. -The mapping is established before STUN discovery and improves hole-punching reliability behind gateways that support it; failures are non-fatal. +Improves hole-punching reliability behind gateways that support it. Requires IPv4: conflicts with `"ip_version": 6`. @@ -271,7 +269,7 @@ Timeout for gateway discovery and mapping operations. #### realm.port_mapping.lifetime -Lease lifetime of the mapping; it is renewed at half the lifetime. +Lease lifetime of the mapping. `10m` is used by default. diff --git a/docs/configuration/inbound/hysteria2.zh.md b/docs/configuration/inbound/hysteria2.zh.md index daf83b6f..9fc136df 100644 --- a/docs/configuration/inbound/hysteria2.zh.md +++ b/docs/configuration/inbound/hysteria2.zh.md @@ -200,8 +200,6 @@ BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。 将此入站注册到 Hysteria Realm 会合服务，以启用 NAT 穿透。 -入站通过 STUN 发现自己的公网地址并注册到 realm，借助 UDP 打洞接受客户端连接，无需可公网直达的监听地址。 - 会合服务参阅 [Hysteria Realm](/zh/configuration/service/hysteria-realm/)。 #### realm.server_url @@ -252,7 +250,7 @@ Realm 上的槽位标识符。 通过 UPnP 或 NAT-PMP 在本地网关上维护 UDP 端口映射。 -映射在 STUN 发现之前建立，可在支持的网关后提升打洞成功率；失败不影响正常流程。 +可在支持的网关后提升打洞成功率。 需要 IPv4：与 `"ip_version": 6` 冲突。 @@ -268,7 +266,7 @@ Realm 上的槽位标识符。 #### realm.port_mapping.lifetime -映射的租约时长；每过一半时长续期一次。 +映射的租约时长。 默认使用 `10m`。 diff --git a/docs/configuration/inbound/snell.md b/docs/configuration/inbound/snell.md index 9fb6fe97..e7451052 100644 --- a/docs/configuration/inbound/snell.md +++ b/docs/configuration/inbound/snell.md @@ -77,7 +77,7 @@ The pre-shared key. Snell users. When set, the server runs in multi-user mode: each entry has a `name` (optional, used in -logs) and a `userkey` (the user's key). The top-level `psk` remains the server key. +logs) and a `userkey` (the user's key). #### obfs_mode diff --git a/docs/configuration/inbound/snell.zh.md b/docs/configuration/inbound/snell.zh.md index f0051c8f..605b06cb 100644 --- a/docs/configuration/inbound/snell.zh.md +++ b/docs/configuration/inbound/snell.zh.md @@ -77,7 +77,7 @@ Snell 协议版本，`5` `6` 之一。 Snell 用户。 设置后，服务器运行于多用户模式：每一项包含 `name`（可选，用于日志）和 `userkey` -（用户密钥）。顶层的 `psk` 仍作为服务器密钥。 +（用户密钥）。 #### obfs_mode diff --git a/docs/configuration/inbound/tun.md b/docs/configuration/inbound/tun.md index ec8829ea..33653755 100644 --- a/docs/configuration/inbound/tun.md +++ b/docs/configuration/inbound/tun.md @@ -259,21 +259,16 @@ How DNS is handled on the TUN interface. `hijack` adds the following on top of `native`: -*On Linux*: only DNS sent to non-local destinations can be intercepted. -Traffic destined to addresses on the host's own interfaces (such as -`127.0.0.53` or the host's LAN-side IP) is delivered through the kernel -`local` routing table before any user rule applies, and `OUTPUT` NAT cannot -redirect packets going through `lo`. +*On Linux*: DNS sent to addresses on the host's own interfaces (such as +`127.0.0.53` or the host's LAN-side IP) is not hijacked. -- Without `auto_redirect`, an `iproute2` rule makes port 53 skip the `main` - table's specific-route lookup, forcing DNS that would otherwise be - delivered through a directly-attached subnet through the TUN. Destination - addresses are not rewritten. -- With `auto_redirect`, an nftables rule DNATs port 53 traffic directly to +- Without `auto_redirect`, port 53 traffic to directly-attached subnets is + also routed through the TUN. +- With `auto_redirect`, port 53 traffic is redirected to [`dns_address`](#dns_address). -*On Windows with [`strict_route`](#strict_route)*: a WFP filter blocks port -53 traffic going through interfaces other than the TUN. +*On Windows with [`strict_route`](#strict_route)*: port 53 traffic going +through interfaces other than the TUN is blocked. #### dns_address @@ -281,15 +276,12 @@ redirect packets going through `lo`. List of DNS server addresses used by [`dns_mode`](#dns_mode). -When unset, sing-box derives one address per family by taking the next IP after -the first IPv4/IPv6 entry in [`address`](#address). Connections toward those -derived addresses are additionally hijacked into the sing-box DNS module, -equivalent to a [`hijack-dns`](/configuration/route/rule_action/#hijack-dns) -route action; this preserves the behaviour from before this option was added. +When unset, the next address after the first IPv4 and IPv6 entry in +[`address`](#address) is used, and connections to it are handled as a +[`hijack-dns`](/configuration/route/rule_action/#hijack-dns) route action. -When set, this auto-hijack is not applied; configure an explicit -[`hijack-dns`](/configuration/route/rule_action/#hijack-dns) route rule if the -behaviour is still required. +When set, configure a [`hijack-dns`](/configuration/route/rule_action/#hijack-dns) +route rule to handle DNS traffic to these addresses. #### gso diff --git a/docs/configuration/inbound/tun.zh.md b/docs/configuration/inbound/tun.zh.md index 726d34e8..2bbe1a50 100644 --- a/docs/configuration/inbound/tun.zh.md +++ b/docs/configuration/inbound/tun.zh.md @@ -263,17 +263,13 @@ TUN 接口上 DNS 的处理方式。 `hijack` 在 `native` 之上额外执行： -*Linux*：只能劫持发往非本机地址的 DNS。发往本机接口地址（如 `127.0.0.53` -或本机 LAN 接口 IP）的流量由内核 `local` 路由表在所有用户规则之前直接交付， -`OUTPUT` 链 NAT 也无法对走 `lo` 的包生效。 +*Linux*：发往本机接口地址（如 `127.0.0.53` 或本机 LAN 接口 IP）的 DNS 不会被劫持。 -- 未启用 `auto_redirect` 时：通过 `iproute2` 规则让 53 端口跳过 `main` 表的 - 具体路由查找，把本来会经直连子网直接送达的 DNS 改走 TUN —— 不重写目的地址。 -- 启用 `auto_redirect` 时：通过 nftables 规则将 53 端口流量直接 DNAT 至 +- 未启用 `auto_redirect` 时：发往直连子网的 53 端口流量也会经由 TUN 路由。 +- 启用 `auto_redirect` 时：53 端口流量被重定向至 [`dns_address`](#dns_address)。 -*Windows 启用 [`strict_route`](#strict_route) 时*：通过 WFP 过滤器阻止经由非 -TUN 接口的 53 端口流量。 +*Windows 启用 [`strict_route`](#strict_route) 时*：阻止经由非 TUN 接口的 53 端口流量。 #### dns_address @@ -281,13 +277,11 @@ TUN 接口的 53 端口流量。 [`dns_mode`](#dns_mode) 使用的 DNS 服务器地址列表。 -未设置时，sing-box 会按地址族在 [`address`](#address) 的第一个 IPv4/IPv6 -条目后面取下一个 IP 作为 DNS 服务器地址，并将流向这些推导地址的连接额外劫持到 -sing-box DNS 模块，等价于一条 -[`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) 路由动作；这与此选项加入之前的行为一致。 +未设置时，使用 [`address`](#address) 中第一个 IPv4 和 IPv6 条目的下一个地址， +发往该地址的连接按 [`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) 路由动作处理。 -设置后，将不再自动劫持；如仍需此行为，请显式配置 -[`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) 路由规则。 +设置后，请配置 [`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) +路由规则以处理发往这些地址的 DNS 流量。 #### gso diff --git a/docs/configuration/outbound/bridge.md b/docs/configuration/outbound/bridge.md index aa93aa04..201afd58 100644 --- a/docs/configuration/outbound/bridge.md +++ b/docs/configuration/outbound/bridge.md @@ -48,8 +48,6 @@ Interface name for forwarded traffic to egress. The default interface will be used by default. -Forwarded traffic will be dropped while the interface is unavailable. - #### bridge_name Custom bridge TUN interface name prefix, `bridge` is used by default. diff --git a/docs/configuration/outbound/bridge.zh.md b/docs/configuration/outbound/bridge.zh.md index 25c8b44f..ec97accf 100644 --- a/docs/configuration/outbound/bridge.zh.md +++ b/docs/configuration/outbound/bridge.zh.md @@ -43,8 +43,6 @@ icon: material/new-box 默认使用默认接口。 -接口不可用期间，转发流量将被丢弃。 - #### bridge_name 自定义 bridge TUN 接口名前缀，默认使用 `bridge`。 diff --git a/docs/configuration/outbound/hysteria2.md b/docs/configuration/outbound/hysteria2.md index 70c3c277..799a90f6 100644 --- a/docs/configuration/outbound/hysteria2.md +++ b/docs/configuration/outbound/hysteria2.md @@ -197,7 +197,7 @@ maximums. !!! warning "" Chrome does not declare support for Ed25519, so a server using an Ed25519 certificate will fail the - handshake. Use an ECDSA or RSA certificate instead; certificates issued by ACME are unaffected. + handshake. Use an ECDSA or RSA certificate instead. #### realm @@ -205,8 +205,6 @@ maximums. Connect to a Hysteria2 server through a Hysteria Realm rendezvous service. -The outbound queries the realm for the server's current public addresses, performs UDP hole-punching, and proceeds with the normal QUIC handshake. - Conflicts with `server`, `server_port` and `server_ports`. The TLS SNI defaults to the host portion of `server_url`. Set `tls.server_name` to match the certificate the Hysteria2 server presents. @@ -247,7 +245,7 @@ Restrict realm connections (STUN, hole punching, and the resulting QUIC path) to Maintain a UDP port mapping on the local gateway via UPnP or NAT-PMP. -The mapping is established before STUN discovery and improves hole-punching reliability behind gateways that support it; failures are non-fatal. +Improves hole-punching reliability behind gateways that support it. Requires IPv4: conflicts with `"ip_version": 6`. @@ -263,7 +261,7 @@ Timeout for gateway discovery and mapping operations. #### realm.port_mapping.lifetime -Lease lifetime of the mapping; it is renewed at half the lifetime. +Lease lifetime of the mapping. `10m` is used by default. diff --git a/docs/configuration/outbound/hysteria2.zh.md b/docs/configuration/outbound/hysteria2.zh.md index 042f5e75..f6be0012 100644 --- a/docs/configuration/outbound/hysteria2.zh.md +++ b/docs/configuration/outbound/hysteria2.zh.md @@ -193,7 +193,7 @@ BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。 !!! warning "" Chrome 不声明支持 Ed25519，因此使用 Ed25519 证书的服务端将无法完成握手。 - 请改用 ECDSA 或 RSA 证书；由 ACME 签发的证书不受影响。 + 请改用 ECDSA 或 RSA 证书。 #### realm @@ -201,8 +201,6 @@ BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。 通过 Hysteria Realm 会合服务连接 Hysteria2 服务器。 -出站从 realm 查询服务器当前的公网地址，执行 UDP 打洞，然后进行常规的 QUIC 握手。 - 与 `server`、`server_port` 和 `server_ports` 冲突。 TLS SNI 默认使用 `server_url` 中的主机名。需设置 `tls.server_name` 以匹配 Hysteria2 服务器证书覆盖的名字。 @@ -243,7 +241,7 @@ Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配 通过 UPnP 或 NAT-PMP 在本地网关上维护 UDP 端口映射。 -映射在 STUN 发现之前建立，可在支持的网关后提升打洞成功率；失败不影响正常流程。 +可在支持的网关后提升打洞成功率。 需要 IPv4：与 `"ip_version": 6` 冲突。 @@ -259,7 +257,7 @@ Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配 #### realm.port_mapping.lifetime -映射的租约时长；每过一半时长续期一次。 +映射的租约时长。 默认使用 `10m`。 diff --git a/docs/configuration/rule-set/headless-rule.md b/docs/configuration/rule-set/headless-rule.md index 81a5e9a0..a2218361 100644 --- a/docs/configuration/rule-set/headless-rule.md +++ b/docs/configuration/rule-set/headless-rule.md @@ -137,10 +137,8 @@ icon: material/new-box When a DNS rule references this rule-set, this field now also applies when the DNS rule is matched from an internal domain resolution that - does not target a specific DNS server. In earlier versions, only DNS - queries received from a client evaluated this field. See - [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules) - for the full list. + does not target a specific DNS server. See + [Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules). When a DNS rule references a rule-set containing this field, the DNS rule is incompatible in the same DNS configuration with Legacy Address diff --git a/docs/configuration/rule-set/headless-rule.zh.md b/docs/configuration/rule-set/headless-rule.zh.md index ad78ffe4..a3e00dd0 100644 --- a/docs/configuration/rule-set/headless-rule.zh.md +++ b/docs/configuration/rule-set/headless-rule.zh.md @@ -136,8 +136,7 @@ icon: material/new-box !!! quote "sing-box 1.14.0 中的更改" 当 DNS 规则引用此规则集时，此字段现在也会在 DNS 规则被未指定具体 - DNS 服务器的内部域名解析匹配时生效。此前只有来自客户端的 DNS 查询 - 才会评估此字段。完整列表参阅 + DNS 服务器的内部域名解析匹配时生效。参阅 [迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。 当 DNS 规则引用了包含此字段的规则集时，该 DNS 规则在同一 DNS 配置中 diff --git a/docs/configuration/rule-set/index.md b/docs/configuration/rule-set/index.md index 1d4ca942..42b35c82 100644 --- a/docs/configuration/rule-set/index.md +++ b/docs/configuration/rule-set/index.md @@ -129,9 +129,7 @@ Download URL of rule-set. File path of the initial rule-set content. -Read once at startup when no cached rule-set is available, so startup is not -blocked by the initial download. The rule-set is still updated in the background -immediately after startup. +Used at startup when no cached rule-set is available. #### http_client diff --git a/docs/configuration/rule-set/index.zh.md b/docs/configuration/rule-set/index.zh.md index 69cedf1a..f4ccb044 100644 --- a/docs/configuration/rule-set/index.zh.md +++ b/docs/configuration/rule-set/index.zh.md @@ -128,8 +128,7 @@ 规则集初始内容的文件路径。 -仅在启动时没有可用的规则集缓存时读取一次，使启动不被初始下载阻塞。 -启动后规则集仍会立即在后台更新。 +在启动时没有可用的规则集缓存时使用。 #### http_client diff --git a/docs/configuration/schema.md b/docs/configuration/schema.md index 210e2bf5..95920525 100644 --- a/docs/configuration/schema.md +++ b/docs/configuration/schema.md @@ -22,7 +22,6 @@ Compatible editors can use it for completion and validation. #### $schema The schema URI used by compatible editors. -This field does not affect sing-box runtime behavior. The schema published with this documentation is available at [sing-box.sagernet.org/schema.json](https://sing-box.sagernet.org/schema.json). diff --git a/docs/configuration/schema.zh.md b/docs/configuration/schema.zh.md index 26c85264..7c289f9f 100644 --- a/docs/configuration/schema.zh.md +++ b/docs/configuration/schema.zh.md @@ -22,7 +22,6 @@ sing-box 为配置文件提供 JSON Schema Draft 2020-12。 #### $schema 兼容编辑器使用的 Schema URI。 -该字段不影响 sing-box 的运行行为。 随本文档发布的 Schema 位于 [sing-box.sagernet.org/schema.json](https://sing-box.sagernet.org/schema.json)。 diff --git a/docs/configuration/service/api.md b/docs/configuration/service/api.md index b7712050..a2797d40 100644 --- a/docs/configuration/service/api.md +++ b/docs/configuration/service/api.md @@ -12,9 +12,7 @@ It can be accessed by the [sing-box graphical clients](/clients/) for iOS, macOS Android (via the Remote Control feature), or the [sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard). -The server also accepts [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) requests, -including the WebSocket transport of [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web) -for bidirectional streaming methods. +The server also accepts [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) requests. ### Structure @@ -80,9 +78,7 @@ Directory the dashboard files are stored in. `dashboard` in the working directory will be used by default. -If the directory is empty, the dashboard is downloaded and an `.etag` file is stored inside -it to skip unchanged updates. A non-empty directory without an `.etag` file is served as-is -and never updated automatically. +If the directory contains files not downloaded by sing-box, they are served as-is. ##### download_url @@ -96,8 +92,6 @@ HTTP client used to download the dashboard. See [HTTP Client Fields](/configuration/shared/http-client/) for details. -Not used when the dashboard directory contains user-provided files. - ##### update_interval Update interval of the dashboard. diff --git a/docs/configuration/service/api.zh.md b/docs/configuration/service/api.zh.md index 5b51ef3e..6d03131b 100644 --- a/docs/configuration/service/api.zh.md +++ b/docs/configuration/service/api.zh.md @@ -10,8 +10,7 @@ sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gR 它可以由 iOS、macOS 和 Android 上的 [sing-box 图形客户端](/zh/clients/)（通过 Remote Control 功能）或 [sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard) 访问。 -服务器同时接受 [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) 请求, -包括用于双向流方法的 [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web) WebSocket 传输。 +服务器同时接受 [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) 请求。 ### 结构 @@ -76,8 +75,7 @@ API 密钥。 默认使用工作目录下的 `dashboard`。 -如果目录为空，将下载仪表板，并在其中存放 `.etag` 文件以跳过未变更的更新。 -非空且不含 `.etag` 文件的目录将按原样提供，且不会自动更新。 +如果目录中包含非 sing-box 下载的文件，将按原样提供。 ##### download_url @@ -91,8 +89,6 @@ API 密钥。 参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/)。 -当仪表板目录包含用户提供的文件时不使用。 - ##### update_interval 仪表板的更新间隔。 diff --git a/docs/configuration/service/hysteria-realm.md b/docs/configuration/service/hysteria-realm.md index 0fe01f1e..a56861f9 100644 --- a/docs/configuration/service/hysteria-realm.md +++ b/docs/configuration/service/hysteria-realm.md @@ -8,9 +8,7 @@ icon: material/new-box Hysteria Realm is a rendezvous service for Hysteria2 NAT traversal. -A Hysteria2 server behind NAT registers its STUN-discovered public addresses to a stable realm endpoint; clients query the realm to learn the server's current addresses and perform UDP hole-punching to establish a direct QUIC connection. - -The realm only carries control-plane signaling. Once hole-punching succeeds, all proxy traffic flows directly between client and server. +Hysteria2 servers behind NAT register on the realm via the [`realm`](/configuration/inbound/hysteria2/#realm) inbound field, and clients connect to them through the realm via the [`realm`](/configuration/outbound/hysteria2/#realm) outbound field. ### Structure diff --git a/docs/configuration/service/hysteria-realm.zh.md b/docs/configuration/service/hysteria-realm.zh.md index c01d744b..4eb6cca7 100644 --- a/docs/configuration/service/hysteria-realm.zh.md +++ b/docs/configuration/service/hysteria-realm.zh.md @@ -8,9 +8,7 @@ icon: material/new-box Hysteria Realm 是用于 Hysteria2 NAT 穿透的会合服务。 -位于 NAT 后面的 Hysteria2 服务器将其通过 STUN 发现的公网地址注册到一个稳定的 realm 端点；客户端从 realm 查询服务器当前的地址并执行 UDP 打洞，以建立直连的 QUIC 连接。 - -Realm 只承载控制信令。打洞成功后，所有代理流量在客户端和服务器之间直连传输。 +位于 NAT 后面的 Hysteria2 服务器通过 [`realm`](/zh/configuration/inbound/hysteria2/#realm) 入站字段注册到 realm，客户端通过 [`realm`](/zh/configuration/outbound/hysteria2/#realm) 出站字段经由 realm 连接到这些服务器。 ### 结构 diff --git a/docs/configuration/service/usbip-client.md b/docs/configuration/service/usbip-client.md index 3c7c99eb..0838321a 100644 --- a/docs/configuration/service/usbip-client.md +++ b/docs/configuration/service/usbip-client.md @@ -27,12 +27,6 @@ The server must be a sing-box (or sing-usbip) server. } ``` -!!! info "Difference from the official USB/IP protocol" - - sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional - set of protocols to support enhancements such as hotplug, while remaining interoperable with - the standard USB/IP protocol. - ### Dial Fields See [Dial Fields](/configuration/shared/dial/) for details. diff --git a/docs/configuration/service/usbip-client.zh.md b/docs/configuration/service/usbip-client.zh.md index 853ac575..78acc74f 100644 --- a/docs/configuration/service/usbip-client.zh.md +++ b/docs/configuration/service/usbip-client.zh.md @@ -26,10 +26,6 @@ USB/IP Client 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导入由 [U } ``` -!!! info "与官方 USB/IP 协议的区别" - - sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。 - ### 拨号字段 参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。 diff --git a/docs/configuration/service/usbip-server.md b/docs/configuration/service/usbip-server.md index 6f972202..526171fd 100644 --- a/docs/configuration/service/usbip-server.md +++ b/docs/configuration/service/usbip-server.md @@ -26,12 +26,6 @@ requires disabling System Integrity Protection). Not available on iOS. } ``` -!!! info "Difference from the official USB/IP protocol" - - sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional - set of protocols to support enhancements such as hotplug, while remaining interoperable with - the standard USB/IP protocol. - ### Listen Fields See [Listen Fields](/configuration/shared/listen/) for details. diff --git a/docs/configuration/service/usbip-server.zh.md b/docs/configuration/service/usbip-server.zh.md index 52e5bbb7..d35ac675 100644 --- a/docs/configuration/service/usbip-server.zh.md +++ b/docs/configuration/service/usbip-server.zh.md @@ -23,10 +23,6 @@ USB/IP Server 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导出本地 } ``` -!!! info "与官方 USB/IP 协议的区别" - - sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。 - ### 监听字段 参阅 [监听字段](/zh/configuration/shared/listen/) 了解详情。 diff --git a/docs/configuration/shared/certificate-provider/acme.zh.md b/docs/configuration/shared/certificate-provider/acme.zh.md index e01986d5..251cfece 100644 --- a/docs/configuration/shared/certificate-provider/acme.zh.md +++ b/docs/configuration/shared/certificate-provider/acme.zh.md @@ -153,5 +153,3 @@ ACME DNS01 质询字段。如果配置，将禁用其他质询方法。 用于所有提供者 HTTP 请求的 HTTP 客户端。 参阅 [HTTP 客户端字段](/zh/configuration/shared/http-client/) 了解详情。 - -所有提供者 HTTP 请求将使用此出站。 diff --git a/docs/configuration/shared/dial.md b/docs/configuration/shared/dial.md index 83f867cb..bd38726c 100644 --- a/docs/configuration/shared/dial.md +++ b/docs/configuration/shared/dial.md @@ -120,7 +120,7 @@ Reuse listener address. Set network namespace, name or path. Since sing-box 1.14.0, the tag of a [network namespace](/configuration/network-namespace/) can also be used. -Referencing an `unshare` network namespace should be avoided, since its only route out is the tun interface managed by sing-box itself. +Referencing an `unshare` network namespace should be avoided. #### connect_timeout diff --git a/docs/configuration/shared/dial.zh.md b/docs/configuration/shared/dial.zh.md index 3067c9d4..3325069d 100644 --- a/docs/configuration/shared/dial.zh.md +++ b/docs/configuration/shared/dial.zh.md @@ -120,7 +120,7 @@ icon: material/new-box 设置网络命名空间，名称或路径。 自 sing-box 1.14.0 起，也可以使用[网络命名空间](/zh/configuration/network-namespace/)的标签。 -应避免引用 `unshare` 类型的网络命名空间，因为其唯一出口是由 sing-box 自身管理的 tun 接口。 +应避免引用 `unshare` 类型的网络命名空间。 #### connect_timeout diff --git a/docs/configuration/shared/http-client.md b/docs/configuration/shared/http-client.md index a0aa9d23..dfa986b8 100644 --- a/docs/configuration/shared/http-client.md +++ b/docs/configuration/shared/http-client.md @@ -42,8 +42,7 @@ Values: !!! warning "" - Experimental only: due to the high memory overhead of both CGO and Network.framework, - do not use in hot paths on iOS and tvOS. + Experimental only: do not use in hot paths on iOS and tvOS. Supported fields: diff --git a/docs/configuration/shared/http-client.zh.md b/docs/configuration/shared/http-client.zh.md index 5c05968a..7b28d4c3 100644 --- a/docs/configuration/shared/http-client.zh.md +++ b/docs/configuration/shared/http-client.zh.md @@ -42,8 +42,7 @@ icon: material/new-box !!! warning "" - 仅供实验用途：由于 CGO 和 Network.framework 占用的内存都很多， - 不应在 iOS 和 tvOS 的热路径中使用。 + 仅供实验用途：不应在 iOS 和 tvOS 的热路径中使用。 支持的字段： diff --git a/docs/configuration/shared/pre-match.md b/docs/configuration/shared/pre-match.md index f88f7676..95d54819 100644 --- a/docs/configuration/shared/pre-match.md +++ b/docs/configuration/shared/pre-match.md @@ -58,8 +58,7 @@ See [route](/configuration/route/rule_action/#route) for details. !!! question "Since sing-box 1.14.0" -For UDP connections, the first packet is available in pre-match, -so protocol sniffing runs on it directly and rule matching continues with the sniffed metadata. +For UDP connections, sniffing runs on the first packet and rule matching continues with the sniffed metadata. When sniffers require more data (like a fragmented QUIC Client Hello), pre-match stops at that rule. diff --git a/docs/configuration/shared/pre-match.zh.md b/docs/configuration/shared/pre-match.zh.md index 9e41d239..a3274494 100644 --- a/docs/configuration/shared/pre-match.zh.md +++ b/docs/configuration/shared/pre-match.zh.md @@ -52,7 +52,7 @@ FakeIP 目标需要在预匹配中先执行 `resolve` 动作，否则连接将 !!! question "自 sing-box 1.14.0 起" -对于 UDP 连接，首个数据包在预匹配中可用，因此协议探测将直接在其上运行，随后规则匹配将携带探测结果继续。 +对于 UDP 连接，协议探测在首个数据包上运行，随后规则匹配将携带探测结果继续。 当探测器需要更多数据时（如分片的 QUIC Client Hello），预匹配将在该规则处停止。 diff --git a/docs/configuration/shared/tls.md b/docs/configuration/shared/tls.md index 0b3adc15..984c6cfe 100644 --- a/docs/configuration/shared/tls.md +++ b/docs/configuration/shared/tls.md @@ -237,33 +237,10 @@ Unsupported fields: !!! note "" - TLS 1.3 is only negotiated on Windows 11 or Windows Server 2022 and newer. On older Windows versions, Schannel caps the connection at TLS 1.2 even when `max_version` is `1.3`. + TLS 1.3 is only negotiated on Windows 11 or Windows Server 2022 and newer. The default version range is TLS 1.2 to TLS 1.3, matching the `go` engine. -Supported fields: - -* `server_name` -* `insecure` -* `alpn` -* `min_version` -* `max_version` -* `certificate` / `certificate_path` -* `certificate_public_key_sha256` -* `handshake_timeout` - -Unsupported fields: - -* `disable_sni` -* `cipher_suites` -* `curve_preferences` -* `client_certificate` / `client_certificate_path` / `client_key` / `client_key_path` -* `fragment` / `record_fragment` -* `kernel_tx` / `kernel_rx` -* `ech` -* `utls` -* `reality` - #### disable_sni ==Client only== @@ -686,16 +663,8 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls. Inject a forged TLS ClientHello carrying a whitelisted SNI before the real one, to fool SNI-filtering middleboxes that permit specific hostnames. -The forged segment is a copy of the real ClientHello with only the SNI value -replaced by the value of this field, so TLS fingerprinting cannot distinguish -it from the real one. The receiving server drops the forged segment -(see `spoof_method`) while the middlebox treats it as a legitimate session. - -Requires raw-socket access (`CAP_NET_RAW` on Linux, root on macOS); -on Linux, `CAP_NET_ADMIN` is additionally required because the send sequence -number is read via `TCP_REPAIR`. -On Windows, Administrator is required to install the embedded WinDivert kernel -driver on first use. Windows on ARM64 is not supported. +Requires `CAP_NET_RAW` and `CAP_NET_ADMIN` on Linux, root on macOS, and +Administrator on Windows. Windows on ARM64 is not supported. #### spoof_method @@ -710,8 +679,8 @@ How the forged segment is rejected by the real server. | `wrong-sequence` (default) | The forged segment's TCP sequence number is placed before the server's receive window. | | `wrong-checksum` | The forged segment's TCP checksum is deliberately invalid. | | `wrong-ack` | The forged segment's TCP acknowledgment number is placed before the server's send window. | -| `wrong-md5` | The forged segment carries a TCP-MD5 signature option, which the server rejects since no MD5 key is negotiated. | -| `wrong-timestamp` | The forged segment carries a backdated TCP timestamp, which the server rejects as a PAWS replay. Linux/Windows only; not supported on macOS. | +| `wrong-md5` | The forged segment carries a TCP-MD5 signature option. | +| `wrong-timestamp` | The forged segment carries a backdated TCP timestamp. Linux/Windows only; not supported on macOS. | ### ACME Fields diff --git a/docs/configuration/shared/tls.zh.md b/docs/configuration/shared/tls.zh.md index 9a86eb34..0db72f43 100644 --- a/docs/configuration/shared/tls.zh.md +++ b/docs/configuration/shared/tls.zh.md @@ -237,32 +237,9 @@ TLS 版本值： !!! note "" - TLS 1.3 仅在 Windows 11 或 Windows Server 2022 及后续版本上协商。在更早的 Windows 版本上，即使 `max_version` 设为 `1.3`，Schannel 也会把连接上限固定在 TLS 1.2。 + TLS 1.3 仅在 Windows 11 或 Windows Server 2022 及后续版本上协商。 -默认版本范围为 TLS 1.2 到 TLS 1.3，与 `go` 引擎一致。证书验证在 Go 侧基于 Schannel 返回的证书链执行，默认使用系统证书存储。当设置了 `certificate` 或 `certificate_path` 时，这些根证书会替代系统存储。 - -支持的字段： - -* `server_name` -* `insecure` -* `alpn` -* `min_version` -* `max_version` -* `certificate` / `certificate_path` -* `certificate_public_key_sha256` -* `handshake_timeout` - -不支持的字段： - -* `disable_sni` -* `cipher_suites` -* `curve_preferences` -* `client_certificate` / `client_certificate_path` / `client_key` / `client_key_path` -* `fragment` / `record_fragment` -* `kernel_tx` / `kernel_rx` -* `ech` -* `utls` -* `reality` +默认版本范围为 TLS 1.2 到 TLS 1.3，与 `go` 引擎一致。 #### disable_sni @@ -682,13 +659,7 @@ ECH 配置路径，PEM 格式。 在真实 ClientHello 之前注入一个伪造的、携带白名单 SNI 的 TLS ClientHello， 以欺骗基于 SNI 过滤的中间盒放行连接。 -伪造报文是真实 ClientHello 的副本，仅将 SNI 值替换为本字段的值， -因此 TLS 指纹无法区分伪造与真实报文。真实服务器会丢弃伪造报文（见 `spoof_method`）， -而中间盒将该连接视为合法会话。 - -需要原始套接字权限（Linux 上需 `CAP_NET_RAW`，macOS 上需 root）； -在 Linux 上还需 `CAP_NET_ADMIN`，因为需要通过 `TCP_REPAIR` 读取发送序列号。 -Windows 上首次使用时需要 Administrator 以安装内嵌的 WinDivert 内核驱动， +Linux 上需要 `CAP_NET_RAW` 和 `CAP_NET_ADMIN`，macOS 上需要 root，Windows 上需要 Administrator。 不支持 Windows ARM64。 #### spoof_method @@ -704,8 +675,8 @@ Windows 上首次使用时需要 Administrator 以安装内嵌的 WinDivert 内 | `wrong-sequence`（默认） | 伪造报文的 TCP 序列号位于服务器接收窗口之前。 | | `wrong-checksum` | 伪造报文的 TCP 校验和被故意设为无效。 | | `wrong-ack` | 伪造报文的 TCP 确认号位于服务器发送窗口之前。 | -| `wrong-md5` | 伪造报文携带 TCP-MD5 签名选项，未协商 MD5 密钥的服务器将拒绝。 | -| `wrong-timestamp` | 伪造报文携带回退的 TCP 时间戳，服务器按 PAWS 规则视为重放并拒绝。仅支持 Linux/Windows，不支持 macOS。 | +| `wrong-md5` | 伪造报文携带 TCP-MD5 签名选项。 | +| `wrong-timestamp` | 伪造报文携带回退的 TCP 时间戳。仅支持 Linux/Windows，不支持 macOS。 | ### ACME 字段 diff --git a/docs/deprecated.md b/docs/deprecated.md index 8e8498ae..96470afd 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -43,8 +43,7 @@ Old fields will be removed in sing-box 1.16.0. #### `independent_cache` DNS option -`independent_cache` DNS option is deprecated. -The DNS cache now always keys by transport, making this option unnecessary, +`independent_cache` DNS option is deprecated, check [Migration](../migration/#migrate-independent-dns-cache). Old fields will be removed in sing-box 1.16.0. diff --git a/docs/deprecated.zh.md b/docs/deprecated.zh.md index 887139bb..2b96258c 100644 --- a/docs/deprecated.zh.md +++ b/docs/deprecated.zh.md @@ -43,8 +43,7 @@ TLS 中的内联 ACME 选项（`tls.acme`）已废弃， #### `independent_cache` DNS 选项 -`independent_cache` DNS 选项已废弃。 -DNS 缓存现在始终按传输分离，使此选项不再需要， +`independent_cache` DNS 选项已废弃， 参阅[迁移指南](/zh/migration/#迁移-independent-dns-cache)。 旧字段将在 sing-box 1.16.0 中被移除。 diff --git a/docs/installation/build-from-source.md b/docs/installation/build-from-source.md index ea799863..413b7726 100644 --- a/docs/installation/build-from-source.md +++ b/docs/installation/build-from-source.md @@ -62,8 +62,8 @@ go build -tags "tag_a tag_b" ./cmd/sing-box | `with_ocm` | :material-check: | Build with OpenAI Codex Multiplexer service support. | | `with_naive_outbound` | :material-check: | Build with NaiveProxy outbound support, see [NaiveProxy outbound](/configuration/outbound/naive/). | | `with_cloudflared` | :material-check: | Build with Cloudflare Tunnel inbound support, see [Cloudflared inbound](/configuration/inbound/cloudflared/). | -| `badlinkname` | :material-check: | Enable `go:linkname` access to internal standard library functions. Required because the Go standard library does not expose many low-level APIs needed by this project, and reimplementing them externally is impractical. Used for kTLS (kernel TLS offload) and raw TLS record manipulation. | -| `tfogo_checklinkname0` | :material-check: | Companion to `badlinkname`. Go 1.23+ enforces `go:linkname` restrictions via the linker; this tag signals the build uses `-checklinkname=0` to bypass that enforcement. | +| `badlinkname` | :material-check: | Enable `go:linkname` access to internal standard library functions. | +| `tfogo_checklinkname0` | :material-check: | Indicates the build uses the `-checklinkname=0` linker flag. Required together with `badlinkname`. | It is not recommended to change the default build tag list unless you really know what you are adding. @@ -73,7 +73,7 @@ The required linker flags for official builds are maintained in `release/LDFLAGS | Flag | Description | |-------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-checklinkname=0` | Go 1.23+ linker rejects unauthorized `go:linkname` usage. This flag disables the check, required together with the `badlinkname` build tag. | +| `-checklinkname=0` | Required together with the `badlinkname` build tag. | ## :material-package-variant: For Downstream Packagers diff --git a/docs/installation/build-from-source.zh.md b/docs/installation/build-from-source.zh.md index cfd8ac76..c99a714c 100644 --- a/docs/installation/build-from-source.zh.md +++ b/docs/installation/build-from-source.zh.md @@ -66,8 +66,8 @@ go build -tags "tag_a tag_b" ./cmd/sing-box | `with_ocm` | :material-check: | 构建 OpenAI Codex Multiplexer 服务支持。 | | `with_naive_outbound` | :material-check: | 构建 NaiveProxy 出站支持，参阅 [NaiveProxy 出站](/zh/configuration/outbound/naive/)。 | | `with_cloudflared` | :material-check: | 构建 Cloudflare Tunnel 入站支持，参阅 [Cloudflared 入站](/zh/configuration/inbound/cloudflared/)。 | -| `badlinkname` | :material-check: | 启用 `go:linkname` 以访问标准库内部函数。Go 标准库未提供本项目需要的许多底层 API，且在外部重新实现不切实际。用于 kTLS（内核 TLS 卸载）和原始 TLS 记录操作。 | -| `tfogo_checklinkname0` | :material-check: | `badlinkname` 的伴随标记。Go 1.23+ 链接器强制限制 `go:linkname` 使用；此标记表示构建使用 `-checklinkname=0` 以绕过该限制。 | +| `badlinkname` | :material-check: | 启用 `go:linkname` 以访问标准库内部函数。 | +| `tfogo_checklinkname0` | :material-check: | 表示构建使用 `-checklinkname=0` 链接器标志，需要与 `badlinkname` 一起使用。 | 除非您确实知道您正在启用什么，否则不建议更改默认构建标签列表。 @@ -77,7 +77,7 @@ go build -tags "tag_a tag_b" ./cmd/sing-box | 标志 | 说明 | |-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `-checklinkname=0` | Go 1.23+ 链接器拒绝未授权的 `go:linkname` 使用。此标志禁用该检查，需要与 `badlinkname` 构建标记一起使用。 | +| `-checklinkname=0` | 需要与 `badlinkname` 构建标记一起使用。 | ## :material-package-variant: 下游打包者 diff --git a/docs/migration.md b/docs/migration.md index 8a78869f..7e718943 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -107,7 +107,8 @@ See [ACME](/configuration/shared/certificate-provider/acme/) for fields newly ad Legacy Address Filter Fields (`ip_cidr`, `ip_is_private` without `match_response`) in DNS rules are deprecated, along with the Legacy `rule_set_ip_cidr_accept_empty` DNS rule item. A DNS rule that references a rule-set containing only `ip_cidr` items (for example, a GeoIP rule-set) without `match_response` is also rejected -at startup when legacy DNS mode is disabled. +at startup when DNS rules use features added in sing-box 1.14.0, such as `evaluate`, `match_response` +or `ip_version`. In sing-box 1.14.0, use the [`evaluate`](/configuration/dns/rule_action/#evaluate) action to fetch a DNS response, then match against it explicitly with `match_response`. @@ -164,8 +165,7 @@ to fetch a DNS response, then match against it explicitly with `match_response`. ### Migrate independent DNS cache -The DNS cache now always keys by transport name, making `independent_cache` unnecessary. -Simply remove the field. +`independent_cache` is deprecated, remove the field. !!! info "References" @@ -232,31 +232,10 @@ In sing-box 1.14.0, the behavior of [`query_type`](/configuration/rule-set/headless-rule/#query_type) in referenced rule-sets, changes in two ways. -First, these fields now take effect on every DNS rule evaluation. In earlier -versions they were evaluated only for DNS queries received from a client -(for example, from a DNS inbound or intercepted by `tun`), and were silently -ignored when a DNS rule was matched from an internal domain resolution that -did not target a specific DNS server. Such internal resolutions include: - -- The [`resolve`](/configuration/route/rule_action/#resolve) route rule - action without a `server` set. -- ICMP traffic routed to a domain destination through a `direct` outbound. -- A [WireGuard](/configuration/endpoint/wireguard/) or - [Tailscale](/configuration/endpoint/tailscale/) endpoint used as an - outbound, when resolving its own destination address. -- A [SOCKS4](/configuration/outbound/socks/) outbound, which must resolve - the destination locally because the protocol has no in-protocol domain - support. -- The [DERP](/configuration/service/derp/) `bootstrap-dns` endpoint and the - [`resolved`](/configuration/service/resolved/) service (when resolving a - hostname or an SRV target). - -Resolutions that target a specific DNS server — via -[`domain_resolver`](/configuration/shared/dial/#domain_resolver) on a dial -field, [`default_domain_resolver`](/configuration/route/#default_domain_resolver) -in route options, or an explicit `server` on a DNS rule action or the -`resolve` route rule action — do not go through DNS rule matching and are -unaffected. +First, these fields now also take effect when a DNS rule is matched from an +internal domain resolution that does not target a specific DNS server, such as +the [`resolve`](/configuration/route/rule_action/#resolve) route rule action +without a `server` set. Second, setting `ip_version` or `query_type` in a DNS rule, or referencing a rule-set containing `query_type`, is no longer compatible in the same DNS diff --git a/docs/migration.zh.md b/docs/migration.zh.md index a710b17c..198f600b 100644 --- a/docs/migration.zh.md +++ b/docs/migration.zh.md @@ -104,7 +104,8 @@ sing-box 1.14.0 新增字段参阅 [ACME](/zh/configuration/shared/certificate-p ### 迁移地址筛选字段到响应匹配 旧版地址筛选字段（不使用 `match_response` 的 `ip_cidr`、`ip_is_private`）已废弃， -旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项也已废弃。当旧版 DNS 模式被禁用时， +旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项也已废弃。当 DNS 规则使用了 sing-box 1.14.0 +新增的功能（例如 `evaluate`、`match_response` 或 `ip_version`）时， 引用仅包含 `ip_cidr` 项的规则集（例如 GeoIP 规则集）且未设置 `match_response` 的 DNS 规则 也将在启动时被拒绝。 @@ -163,8 +164,7 @@ sing-box 1.14.0 新增字段参阅 [ACME](/zh/configuration/shared/certificate-p ### 迁移 independent DNS cache -DNS 缓存现在始终按传输名称分离，使 `independent_cache` 不再需要。 -直接移除该字段即可。 +`independent_cache` 已废弃，直接移除该字段即可。 !!! info "参考" @@ -231,24 +231,8 @@ DNS 缓存现在始终按传输名称分离，使 `independent_cache` 不再需 [`query_type`](/zh/configuration/rule-set/headless-rule/#query_type)， 行为有两项更改。 -其一，这些字段现在对每一次 DNS 规则评估都会生效。此前它们仅对来自客户端的 DNS 查询 -（例如来自 DNS 入站或被 `tun` 截获的查询）生效，当 DNS 规则被未指定具体 DNS 服务器的 -内部域名解析匹配时，会被静默忽略。此类内部解析包括： - -- 未设置 `server` 的 [`resolve`](/zh/configuration/route/rule_action/#resolve) 路由规则动作。 -- 通过 `direct` 出站路由到域名目标的 ICMP 流量。 -- 作为出站使用的 [WireGuard](/zh/configuration/endpoint/wireguard/) 或 - [Tailscale](/zh/configuration/endpoint/tailscale/) 端点在解析自身目标地址时。 -- [SOCKS4](/zh/configuration/outbound/socks/) 出站，因为协议本身不支持域名， - 必须在本地解析目标。 -- [DERP](/zh/configuration/service/derp/) 的 `bootstrap-dns` 端点，以及 - [`resolved`](/zh/configuration/service/resolved/) 服务在解析主机名或 SRV 目标时。 - -通过拨号字段中的 -[`domain_resolver`](/zh/configuration/shared/dial/#domain_resolver)、 -路由选项中的 [`default_domain_resolver`](/zh/configuration/route/#default_domain_resolver)， -或 DNS 规则动作与 `resolve` 路由规则动作上显式的 `server` 指定具体 DNS 服务器的 -解析，不会经过 DNS 规则匹配，不受此次更改影响。 +其一，当 DNS 规则被未指定具体 DNS 服务器的内部域名解析匹配时，这些字段现在也会生效， +例如未设置 `server` 的 [`resolve`](/zh/configuration/route/rule_action/#resolve) 路由规则动作。 其二，设置了 `ip_version` 或 `query_type` 的 DNS 规则，或引用了包含 `query_type` 的 规则集的 DNS 规则，在同一 DNS 配置中不再能与旧版地址筛选字段 (DNS 规则)、旧版