From da90b0212ca8bcc9c834fae85006c5ebeb428a0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Tue, 12 Nov 2024 22:57:15 +0800 Subject: [PATCH] documentation: Add parallel network dialing --- docs/configuration/route/index.md | 45 +++++++++++++++-- docs/configuration/route/index.zh.md | 30 ++++++++++- docs/configuration/route/rule_action.md | 29 +++++++++-- docs/configuration/route/rule_action.zh.md | 29 +++++++++-- docs/configuration/shared/dial.md | 59 ++++++++++++++++++---- docs/configuration/shared/dial.zh.md | 59 +++++++++++++++++----- 6 files changed, 215 insertions(+), 36 deletions(-) diff --git a/docs/configuration/route/index.md b/docs/configuration/route/index.md index 507cb140..2b035eb4 100644 --- a/docs/configuration/route/index.md +++ b/docs/configuration/route/index.md @@ -1,5 +1,14 @@ +--- +icon: material/new-box +--- + # Route +!!! quote "Changes in sing-box 1.11.0" + + :material-plus: [default_network_strategy](#default_network_strategy) + :material-alert: [default_fallback_delay](#default_fallback_delay) + !!! quote "Changes in sing-box 1.8.0" :material-plus: [rule_set](#rule_set) @@ -18,16 +27,18 @@ "final": "", "auto_detect_interface": false, "override_android_vpn": false, - "default_interface": "en0", - "default_mark": 233 + "default_interface": "", + "default_mark": 0, + "default_network_strategy": "", + "default_fallback_delay": "" } } ``` ### Fields -| Key | Format | -|-----------|----------------------| +| Key | Format | +|-----------|-----------------------| | `geoip` | [GeoIP](./geoip/) | | `geosite` | [Geosite](./geosite/) | @@ -81,4 +92,28 @@ Takes no effect if `auto_detect_interface` is set. Set routing mark by default. -Takes no effect if `outbound.routing_mark` is set. \ No newline at end of file +Takes no effect if `outbound.routing_mark` is set. + +#### default_network_strategy + +!!! quote "" + + Only supported in graphical clients on Android and iOS with `auto_detect_interface` enabled. + +Strategy for selecting network interfaces. + +Takes no effect if `outbound.bind_interface`, `outbound.inet4_bind_address` or `outbound.inet6_bind_address` is set. + +Can be overrides by `outbound.network_strategy`. + +Conflicts with `default_interface`. + +See [Dial Fields](/configuration/shared/dial/#network_strategy) for available values. + +#### default_fallback_delay + +!!! quote "" + + Only supported in graphical clients on Android and iOS with `auto_detect_interface` enabled and `network_strategy` set. + +See [Dial Fields](/configuration/shared/dial/#fallback_delay) for details. \ No newline at end of file diff --git a/docs/configuration/route/index.zh.md b/docs/configuration/route/index.zh.md index 68d4f66d..b00237c4 100644 --- a/docs/configuration/route/index.zh.md +++ b/docs/configuration/route/index.zh.md @@ -18,8 +18,10 @@ "final": "", "auto_detect_interface": false, "override_android_vpn": false, - "default_interface": "en0", - "default_mark": 233 + "default_interface": "", + "default_mark": 0, + "default_network_strategy": "", + "default_fallback_delay": "" } } ``` @@ -82,3 +84,27 @@ 默认为出站连接设置路由标记。 如果设置了 `outbound.routing_mark` 设置，则不生效。 + +#### network_strategy + +!!! quote "" + + 仅在 Android 与 Apple 平台图形客户端中支持，并且需要 `auto_detect_interface`。 + +选择网络接口的策略。 + +当 `outbound.bind_interface`, `outbound.inet4_bind_address` 或 `outbound.inet6_bind_address` 已设置时不生效。 + +可以被 `outbound.network_strategy` 覆盖。 + +与 `default_interface` 冲突。 + +可用值请参阅 [拨号字段](/configuration/shared/dial/#network_strategy)。 + +#### fallback_delay + +!!! quote "" + + 仅在 Android 与 Apple 平台图形客户端中支持，并且需要 `auto_detect_interface` 且 `network_strategy` 已设置。 + +详情请参阅 [拨号字段](/configuration/shared/dial/#fallback_delay)。 diff --git a/docs/configuration/route/rule_action.md b/docs/configuration/route/rule_action.md index 7804f586..5e9cfbc2 100644 --- a/docs/configuration/route/rule_action.md +++ b/docs/configuration/route/rule_action.md @@ -2,10 +2,6 @@ icon: material/new-box --- -# Rule Action - -!!! question "Since sing-box 1.11.0" - ## Final actions ### route @@ -14,6 +10,8 @@ icon: material/new-box { "action": "route", // default "outbound": "", + "network_strategy": "", + "fallback_delay": "", "udp_disable_domain_unmapping": false, "udp_connect": false } @@ -27,6 +25,27 @@ icon: material/new-box Tag of target outbound. +#### network_strategy + +!!! quote "" + + Only supported in graphical clients on Android and iOS with `auto_detect_interface` enabled. + +Strategy for selecting network interfaces. + +Only take effect if outbound is direct without `outbound.bind_interface`, +`outbound.inet4_bind_address` and `outbound.inet6_bind_address` set. + +See [Dial Fields](/configuration/shared/dial/#network_strategy) for available values. + +#### fallback_delay + +!!! quote "" + + Only supported in graphical clients on Android and iOS with `auto_detect_interface` enabled and `network_strategy` set. + +See [Dial Fields](/configuration/shared/dial/#fallback_delay) for details. + #### udp_disable_domain_unmapping If enabled, for UDP proxy requests addressed to a domain, @@ -44,6 +63,8 @@ If enabled, attempts to connect UDP connection to the destination instead of lis ```json { "action": "route-options", + "network_strategy": "", + "fallback_delay": "", "udp_disable_domain_unmapping": false, "udp_connect": false } diff --git a/docs/configuration/route/rule_action.zh.md b/docs/configuration/route/rule_action.zh.md index 103a04bd..52965fd2 100644 --- a/docs/configuration/route/rule_action.zh.md +++ b/docs/configuration/route/rule_action.zh.md @@ -2,10 +2,6 @@ icon: material/new-box --- -# 规则动作 - -!!! question "自 sing-box 1.11.0 起" - ## 最终动作 ### route @@ -14,6 +10,8 @@ icon: material/new-box { "action": "route", // 默认 "outbound": "", + "network_strategy": "", + "fallback_delay": "", "udp_disable_domain_unmapping": false, "udp_connect": false } @@ -27,6 +25,27 @@ icon: material/new-box 目标出站的标签。 +#### network_strategy + +!!! quote "" + + 仅在 Android 与 Apple 平台图形客户端中支持，并且需要 `auto_detect_interface`。 + +选择网络接口的策略。 + +仅当出站为 `direct` 且 `outbound.bind_interface`, `outbound.inet4_bind_address` +且 `outbound.inet6_bind_address` 未设置时生效。 + +可用值参阅 [拨号字段](/configuration/shared/dial/#network_strategy)。 + +#### fallback_delay + +!!! quote "" + + 仅在 Android 与 Apple 平台图形客户端中支持，并且需要 `auto_detect_interface` 且 `network_strategy` 已设置。 + +详情参阅 [拨号字段](/configuration/shared/dial/#fallback_delay)。 + #### udp_disable_domain_unmapping 如果启用，对于地址为域的 UDP 代理请求，将在响应中发送原始包地址而不是映射的域。 @@ -42,6 +61,8 @@ icon: material/new-box ```json { "action": "route-options", + "network_strategy": "", + "fallback_delay": "", "udp_disable_domain_unmapping": false, "udp_connect": false } diff --git a/docs/configuration/shared/dial.md b/docs/configuration/shared/dial.md index 8139c751..e67bf616 100644 --- a/docs/configuration/shared/dial.md +++ b/docs/configuration/shared/dial.md @@ -1,3 +1,12 @@ +--- +icon: material/new-box +--- + +!!! quote "Changes in sing-box 1.11.0" + + :material-plus: [network_strategy](#network_strategy) + :material-alert: [fallback_delay](#fallback_delay) + ### Structure ```json @@ -13,20 +22,19 @@ "tcp_multi_path": false, "udp_fragment": false, "domain_strategy": "prefer_ipv6", + "network_strategy": "default", "fallback_delay": "300ms" } ``` ### Fields -| Field | Available Context | -|------------------------------------------------------------------------------------------------------------------------------------------|-------------------| -| `bind_interface` /`*bind_address` /`routing_mark` /`reuse_addr` / `tcp_fast_open` / `tcp_multi_path` / `udp_fragment` /`connect_timeout` | `detour` not set | - #### detour The tag of the upstream outbound. +If enabled, all other fields will be ignored. + #### bind_interface The network interface to bind to. @@ -78,7 +86,7 @@ Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". #### domain_strategy -One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`. +Available values: `prefer_ipv4`, `prefer_ipv6`, `ipv4_only`, `ipv6_only`. If set, the requested domain name will be resolved to IP before connect. @@ -87,11 +95,44 @@ If set, the requested domain name will be resolved to IP before connect. | `direct` | Domain in request | Take `inbound.domain_strategy` if not set | | others | Domain in server address | / | +#### network_strategy + +!!! question "Since sing-box 1.11.0" + +!!! quote "" + + Only supported in graphical clients on Android and iOS with `auto_detect_interface` enabled. + +Strategy for selecting network interfaces. + +Available values: + +- `default` (default): Connect to the default interface. +- `fallback`: Try all other interfaces when timeout. +- `hybrid`: Connect to all interfaces concurrently and choose the fastest one. +- `wifi`: Prioritize WIFI, but try all other interfaces when unavailable or timeout. +- `cellular`: Prioritize Cellular, but try all other interfaces when unavailable or timeout. +- `ethernet`: Prioritize Ethernet, but try all other interfaces when unavailable or timeout. +- `wifi_only`: Connect to WIFI only. +- `cellular_only`: Connect to Cellular only. +- `ethernet_only`: Connect to Ethernet only. + +For fallback strategies, when preferred interfaces fails or times out, +it will enter a 15s fast fallback state (upgraded to `hybrid`), +and exit immediately if recovers. + +Conflicts with `bind_interface`, `inet4_bind_address` and `inet6_bind_address`. + #### fallback_delay The length of time to wait before spawning a RFC 6555 Fast Fallback connection. -That is, is the amount of time to wait for connection to succeed before assuming -that IPv4/IPv6 is misconfigured and falling back to other type of addresses. -If zero, a default delay of 300ms is used. -Only take effect when `domain_strategy` is set. \ No newline at end of file +For `domain_strategy`, is the amount of time to wait for connection to succeed before assuming +that IPv4/IPv6 is misconfigured and falling back to other type of addresses. + +For `network_strategy`, is the amount of time to wait for connection to succeed before falling +back to other interfaces. + +Only take effect when `domain_strategy` or `network_strategy` is set. + +`300ms` is used by default. diff --git a/docs/configuration/shared/dial.zh.md b/docs/configuration/shared/dial.zh.md index ccb61c7a..4e20f106 100644 --- a/docs/configuration/shared/dial.zh.md +++ b/docs/configuration/shared/dial.zh.md @@ -1,3 +1,12 @@ +--- +icon: material/new-box +--- + +!!! quote "sing-box 1.11.0 中的更改" + + :material-plus: [network_strategy](#network_strategy) + :material-alert: [fallback_delay](#fallback_delay) + ### 结构 ```json @@ -13,17 +22,13 @@ "tcp_multi_path": false, "udp_fragment": false, "domain_strategy": "prefer_ipv6", + "network_strategy": "", "fallback_delay": "300ms" } ``` ### 字段 -| 字段 | 可用上下文 | -|------------------------------------------------------------------------------------------------------------------------------------------|--------------| -| `bind_interface` /`*bind_address` /`routing_mark` /`reuse_addr` / `tcp_fast_open` / `tcp_mutli_path` / `udp_fragment` /`connect_timeout` | `detour` 未设置 | - - #### detour 上游出站的标签。 @@ -83,15 +88,45 @@ 如果设置，域名将在请求发出之前解析为 IP。 -| 出站 | 受影响的域名 | 默认回退值 | -|----------|--------------------------|-------------------------------------------| -| `direct` | 请求中的域名 | `inbound.domain_strategy` | -| others | 服务器地址中的域名 | / | +| 出站 | 受影响的域名 | 默认回退值 | +|----------|-----------|---------------------------| +| `direct` | 请求中的域名 | `inbound.domain_strategy` | +| others | 服务器地址中的域名 | / | + +#### network_strategy + +!!! question "自 sing-box 1.11.0 起" + +!!! quote "" + + 仅在 Android 与 iOS 平台图形客户端中支持。 + +用于选择网络接口的策略。 + +可用值： + +- `default` (默认): 连接到默认接口， +- `fallback`: 如果超时，尝试所有剩余接口。 +- `hybrid`: 同时尝试所有接口，选择最快的一个。 +- `wifi`: 优先使用 WIFI，但在不可用或超时时尝试所有其他接口。 +- `cellular`: 优先使用蜂窝数据，但在不可用或超时时尝试所有其他接口。 +- `ethernet`: 优先使用以太网，但在不可用或超时时尝试所有其他接口。 +- `wifi_only`: 仅连接到 WIFI。 +- `cellular_only`: 仅连接到蜂窝数据。 +- `ethernet_only`: 仅连接到以太网。 + +对于回退策略, 当优先使用的接口发生故障或超时时， 将进入 15 秒的快速回退状态（升级为 `hybrid`）， 且恢复后立即退出。 + +与 `bind_interface`, `bind_inet4_address` 和 `bind_inet6_address` 冲突。 #### fallback_delay 在生成 RFC 6555 快速回退连接之前等待的时间长度。 -也就是说，是在假设之前等待 IPv6 成功的时间量如果设置了 "prefer_ipv4"，则 IPv6 配置错误并回退到 IPv4。 -如果为零，则使用 300 毫秒的默认延迟。 -仅当 `domain_strategy` 为 `prefer_ipv4` 或 `prefer_ipv6` 时生效。 +对于 `domain_strategy`，是在假设之前等待 IPv6 成功的时间量如果设置了 "prefer_ipv4"，则 IPv6 配置错误并回退到 IPv4。 + +对于 `network_strategy`，对于 `network_strategy`，是在回退到其他接口之前等待连接成功的时间。 + +仅当 `domain_strategy` 或 `network_strategy` 已设置时生效。 + +默认使用 `300ms`。