From e09a94bb9e3a1ade434f1630c1cf439a0a6fcdf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Fri, 1 Dec 2023 13:24:18 +0800 Subject: [PATCH] Update documentation --- docs/configuration/dns/rule.md | 44 +++- docs/configuration/dns/rule.zh.md | 44 +++- docs/configuration/experimental/cache-file.md | 34 +++ docs/configuration/experimental/clash-api.md | 121 ++++++++++ docs/configuration/experimental/index.md | 145 ++---------- docs/configuration/experimental/index.zh.md | 137 ------------ docs/configuration/experimental/v2ray-api.md | 50 +++++ docs/configuration/route/geoip.md | 8 + docs/configuration/route/geoip.zh.md | 33 --- docs/configuration/route/geosite.md | 8 + docs/configuration/route/geosite.zh.md | 33 --- docs/configuration/route/index.md | 30 ++- docs/configuration/route/index.zh.md | 25 ++- docs/configuration/route/rule.md | 68 +++++- docs/configuration/route/rule.zh.md | 66 +++++- docs/configuration/rule-set/headless-rule.md | 207 ++++++++++++++++++ docs/configuration/rule-set/index.md | 97 ++++++++ docs/configuration/rule-set/source-format.md | 34 +++ docs/manual/proxy/client.md | 184 ++++++++++++++++ docs/migration.md | 195 +++++++++++++++++ mkdocs.yml | 28 ++- 21 files changed, 1230 insertions(+), 361 deletions(-) create mode 100644 docs/configuration/experimental/cache-file.md create mode 100644 docs/configuration/experimental/clash-api.md delete mode 100644 docs/configuration/experimental/index.zh.md create mode 100644 docs/configuration/experimental/v2ray-api.md delete mode 100644 docs/configuration/route/geoip.zh.md delete mode 100644 docs/configuration/route/geosite.zh.md create mode 100644 docs/configuration/rule-set/headless-rule.md create mode 100644 docs/configuration/rule-set/index.md create mode 100644 docs/configuration/rule-set/source-format.md create mode 100644 docs/migration.md diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md index 297a2968..68cc32cf 100644 --- a/docs/configuration/dns/rule.md +++ b/docs/configuration/dns/rule.md @@ -1,3 +1,14 @@ +--- +icon: material/alert-decagram +--- + +!!! quote "Changes in sing-box 1.8.0" + + :material-plus: [rule_set](#rule_set) + :material-plus: [source_ip_is_private](#source_ip_is_private) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### Structure ```json @@ -46,6 +57,7 @@ "10.0.0.0/24", "192.168.0.1" ], + "source_ip_is_private": false, "source_port": [ 12345 ], @@ -85,6 +97,10 @@ "wifi_bssid": [ "00:00:00:00:00:00" ], + "rule_set": [ + "geoip-cn", + "geosite-cn" + ], "invert": false, "outbound": [ "direct" @@ -118,10 +134,12 @@ The default rule uses the following matching logic: (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite`) && (`port` || `port_range`) && - (`source_geoip` || `source_ip_cidr`) && + (`source_geoip` || `source_ip_cidr` ｜｜ `source_ip_is_private`) && (`source_port` || `source_port_range`) && `other fields` + Additionally, included rule sets can be considered merged rather than as a single rule sub-item. + #### inbound Tags of [Inbound](/configuration/inbound/). @@ -166,15 +184,29 @@ Match domain using regular expression. #### geosite +!!! failure "Deprecated in sing-box 1.8.0" + + Geosite is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geosite-to-rule-sets). + Match geosite. #### source_geoip +!!! failure "Deprecated in sing-box 1.8.0" + + GeoIP is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geoip-to-rule-sets). + Match source geoip. #### source_ip_cidr -Match source ip cidr. +Match source IP CIDR. + +#### source_ip_is_private + +!!! question "Since sing-box 1.8.0" + +Match non-public source IP. #### source_port @@ -250,6 +282,12 @@ Match WiFi SSID. Match WiFi BSSID. +#### rule_set + +!!! question "Since sing-box 1.8.0" + +Match [Rule Set](/configuration/route/#rule_set). + #### invert Invert match result. @@ -286,4 +324,4 @@ Rewrite TTL in DNS responses. #### rules -Included default rules. \ No newline at end of file +Included rules. \ No newline at end of file diff --git a/docs/configuration/dns/rule.zh.md b/docs/configuration/dns/rule.zh.md index 9cb4e89d..e6c407dc 100644 --- a/docs/configuration/dns/rule.zh.md +++ b/docs/configuration/dns/rule.zh.md @@ -1,3 +1,14 @@ +--- +icon: material/alert-decagram +--- + +!!! quote "sing-box 1.8.0 中的更改" + + :material-plus: [rule_set](#rule_set) + :material-plus: [source_ip_is_private](#source_ip_is_private) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### 结构 ```json @@ -45,6 +56,7 @@ "source_ip_cidr": [ "10.0.0.0/24" ], + "source_ip_is_private": false, "source_port": [ 12345 ], @@ -84,6 +96,10 @@ "wifi_bssid": [ "00:00:00:00:00:00" ], + "rule_set": [ + "geoip-cn", + "geosite-cn" + ], "invert": false, "outbound": [ "direct" @@ -115,10 +131,12 @@ 默认规则使用以下匹配逻辑: (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite`) && (`port` || `port_range`) && - (`source_geoip` || `source_ip_cidr`) && + (`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) && (`source_port` || `source_port_range`) && `other fields` + 另外，引用的规则集可视为被合并，而不是作为一个单独的规则子项。 + #### inbound [入站](/zh/configuration/inbound/) 标签. @@ -163,16 +181,30 @@ DNS 查询类型。值可以为整数或者类型名称字符串。 #### geosite -匹配 GeoSite。 +!!! failure "已在 sing-box 1.8.0 废弃" + + Geosite 已废弃且可能在不久的将来移除，参阅 [迁移指南](/migration/#migrate-geosite-to-rule-sets)。 + +匹配 Geosite。 #### source_geoip +!!! failure "已在 sing-box 1.8.0 废弃" + + GeoIp 已废弃且可能在不久的将来移除，参阅 [迁移指南](/migration/#migrate-geoip-to-rule-sets)。 + 匹配源 GeoIP。 #### source_ip_cidr 匹配源 IP CIDR。 +#### source_ip_is_private + +!!! question "自 sing-box 1.8.0 起" + +匹配非公开源 IP。 + #### source_port 匹配源端口。 @@ -245,6 +277,12 @@ DNS 查询类型。值可以为整数或者类型名称字符串。 匹配 WiFi BSSID。 +#### rule_set + +!!! question "自 sing-box 1.8.0 起" + +匹配[规则集](/zh/configuration/route/#rule_set)。 + #### invert 反选匹配结果。 @@ -281,4 +319,4 @@ DNS 查询类型。值可以为整数或者类型名称字符串。 #### rules -包括的默认规则。 \ No newline at end of file +包括的规则。 \ No newline at end of file diff --git a/docs/configuration/experimental/cache-file.md b/docs/configuration/experimental/cache-file.md new file mode 100644 index 00000000..66e30ef9 --- /dev/null +++ b/docs/configuration/experimental/cache-file.md @@ -0,0 +1,34 @@ +--- +icon: material/new-box +--- + +!!! question "Since sing-box 1.8.0" + +### Structure + +```json +{ + "enabled": true, + "path": "", + "cache_id": "", + "store_fakeip": false +} +``` + +### Fields + +#### enabled + +Enable cache file. + +#### path + +Path to the cache file. + +`cache.db` will be used if empty. + +#### cache_id + +Identifier in cache file. + +If not empty, configuration specified data will use a separate store keyed by it. diff --git a/docs/configuration/experimental/clash-api.md b/docs/configuration/experimental/clash-api.md new file mode 100644 index 00000000..a06fe154 --- /dev/null +++ b/docs/configuration/experimental/clash-api.md @@ -0,0 +1,121 @@ +--- +icon: material/alert-decagram +--- + +!!! quote "Changes in sing-box 1.8.0" + + :material-delete-alert: [store_mode](#store_mode) + :material-delete-alert: [store_selected](#store_selected) + :material-delete-alert: [store_fakeip](#store_fakeip) + :material-delete-alert: [cache_file](#cache_file) + :material-delete-alert: [cache_id](#cache_id) + + +!!! quote "" + + Clash API is not included by default, see [Installation](./#installation). + +### Structure + +```json +{ + "external_controller": "127.0.0.1:9090", + "external_ui": "", + "external_ui_download_url": "", + "external_ui_download_detour": "", + "secret": "", + "default_mode": "", + + // Deprecated + + "store_mode": false, + "store_selected": false, + "store_fakeip": false, + "cache_file": "", + "cache_id": "" +} +``` + +### Fields + +#### external_controller + +RESTful web API listening address. Clash API will be disabled if empty. + +#### external_ui + +A relative path to the configuration directory or an absolute path to a +directory in which you put some static web resource. sing-box will then +serve it at `http://{{external-controller}}/ui`. + + + +#### external_ui_download_url + +ZIP download URL for the external UI, will be used if the specified `external_ui` directory is empty. + +`https://github.com/MetaCubeX/Yacd-meta/archive/gh-pages.zip` will be used if empty. + +#### external_ui_download_detour + +The tag of the outbound to download the external UI. + +Default outbound will be used if empty. + +#### secret + +Secret for the RESTful API (optional) +Authenticate by spedifying HTTP header `Authorization: Bearer ${secret}` +ALWAYS set a secret if RESTful API is listening on 0.0.0.0 + +#### default_mode + +Default mode in clash, `Rule` will be used if empty. + +This setting has no direct effect, but can be used in routing and DNS rules via the `clash_mode` rule item. + +#### store_mode + +!!! failure "Deprecated in sing-box 1.8.0" + + `store_mode` is deprecated in Clash API and enabled by default if `cache_file.enabled`. + +Store Clash mode in cache file. + +#### store_selected + +!!! failure "Deprecated in sing-box 1.8.0" + + `store_selected` is deprecated in Clash API and enabled by default if `cache_file.enabled`. + +!!! note "" + + The tag must be set for target outbounds. + +Store selected outbound for the `Selector` outbound in cache file. + +#### store_fakeip + +!!! failure "Deprecated in sing-box 1.8.0" + + `store_selected` is deprecated in Clash API and migrated to `cache_file.store_fakeip`. + +Store fakeip in cache file. + +#### cache_file + +!!! failure "Deprecated in sing-box 1.8.0" + + `cache_file` is deprecated in Clash API and migrated to `cache_file.enabled` and `cache_file.path`. + +Cache file path, `cache.db` will be used if empty. + +#### cache_id + +!!! failure "Deprecated in sing-box 1.8.0" + + `cache_id` is deprecated in Clash API and migrated to `cache_file.cache_id`. + +Identifier in cache file. + +If not empty, configuration specified data will use a separate store keyed by it. \ No newline at end of file diff --git a/docs/configuration/experimental/index.md b/docs/configuration/experimental/index.md index 308e851c..4ddcc41a 100644 --- a/docs/configuration/experimental/index.md +++ b/docs/configuration/experimental/index.md @@ -1,139 +1,30 @@ +--- +icon: material/alert-decagram +--- + # Experimental +!!! quote "Changes in sing-box 1.8.0" + + :material-plus: [cache_file](#cache_file) + :material-alert-decagram: [clash_api](#clash_api) + ### Structure ```json { "experimental": { - "clash_api": { - "external_controller": "127.0.0.1:9090", - "external_ui": "", - "external_ui_download_url": "", - "external_ui_download_detour": "", - "secret": "", - "default_mode": "", - "store_mode": false, - "store_selected": false, - "store_fakeip": false, - "cache_file": "", - "cache_id": "" - }, - "v2ray_api": { - "listen": "127.0.0.1:8080", - "stats": { - "enabled": true, - "inbounds": [ - "socks-in" - ], - "outbounds": [ - "proxy", - "direct" - ], - "users": [ - "sekai" - ] - } - } + "cache_file": {}, + "clash_api": {}, + "v2ray_api": {} } } ``` -!!! note "" +### Fields - Traffic statistics and connection management can degrade performance. - -### Clash API Fields - -!!! quote "" - - Clash API is not included by default, see [Installation](./#installation). - -#### external_controller - -RESTful web API listening address. Clash API will be disabled if empty. - -#### external_ui - -A relative path to the configuration directory or an absolute path to a -directory in which you put some static web resource. sing-box will then -serve it at `http://{{external-controller}}/ui`. - -#### external_ui_download_url - -ZIP download URL for the external UI, will be used if the specified `external_ui` directory is empty. - -`https://github.com/MetaCubeX/Yacd-meta/archive/gh-pages.zip` will be used if empty. - -#### external_ui_download_detour - -The tag of the outbound to download the external UI. - -Default outbound will be used if empty. - -#### secret - -Secret for the RESTful API (optional) -Authenticate by spedifying HTTP header `Authorization: Bearer ${secret}` -ALWAYS set a secret if RESTful API is listening on 0.0.0.0 - -#### default_mode - -Default mode in clash, `Rule` will be used if empty. - -This setting has no direct effect, but can be used in routing and DNS rules via the `clash_mode` rule item. - -#### store_mode - -Store Clash mode in cache file. - -#### store_selected - -!!! note "" - - The tag must be set for target outbounds. - -Store selected outbound for the `Selector` outbound in cache file. - -#### store_fakeip - -Store fakeip in cache file. - -#### cache_file - -Cache file path, `cache.db` will be used if empty. - -#### cache_id - -Cache ID. - -If not empty, `store_selected` will use a separate store keyed by it. - -### V2Ray API Fields - -!!! quote "" - - V2Ray API is not included by default, see [Installation](./#installation). - -#### listen - -gRPC API listening address. V2Ray API will be disabled if empty. - -#### stats - -Traffic statistics service settings. - -#### stats.enabled - -Enable statistics service. - -#### stats.inbounds - -Inbound list to count traffic. - -#### stats.outbounds - -Outbound list to count traffic. - -#### stats.users - -User list to count traffic. \ No newline at end of file +| Key | Format | +|--------------|----------------------------| +| `cache_file` | [Cache File](./cache-file/) | +| `clash_api` | [Clash API](./clash-api/) | +| `v2ray_api` | [V2Ray API](./v2ray-api/) | \ No newline at end of file diff --git a/docs/configuration/experimental/index.zh.md b/docs/configuration/experimental/index.zh.md deleted file mode 100644 index 88a95852..00000000 --- a/docs/configuration/experimental/index.zh.md +++ /dev/null @@ -1,137 +0,0 @@ -# 实验性 - -### 结构 - -```json -{ - "experimental": { - "clash_api": { - "external_controller": "127.0.0.1:9090", - "external_ui": "", - "external_ui_download_url": "", - "external_ui_download_detour": "", - "secret": "", - "default_mode": "", - "store_mode": false, - "store_selected": false, - "store_fakeip": false, - "cache_file": "", - "cache_id": "" - }, - "v2ray_api": { - "listen": "127.0.0.1:8080", - "stats": { - "enabled": true, - "inbounds": [ - "socks-in" - ], - "outbounds": [ - "proxy", - "direct" - ], - "users": [ - "sekai" - ] - } - } - } -} -``` - -!!! note "" - - 流量统计和连接管理会降低性能。 - -### Clash API 字段 - -!!! quote "" - - 默认安装不包含 Clash API，参阅 [安装](/zh/#_2)。 - -#### external_controller - -RESTful web API 监听地址。如果为空，则禁用 Clash API。 - -#### external_ui - -到静态网页资源目录的相对路径或绝对路径。sing-box 会在 `http://{{external-controller}}/ui` 下提供它。 - -#### external_ui_download_url - -静态网页资源的 ZIP 下载 URL，如果指定的 `external_ui` 目录为空，将使用。 - -默认使用 `https://github.com/MetaCubeX/Yacd-meta/archive/gh-pages.zip`。 - -#### external_ui_download_detour - -用于下载静态网页资源的出站的标签。 - -如果为空，将使用默认出站。 - -#### secret - -RESTful API 的密钥（可选） -通过指定 HTTP 标头 `Authorization: Bearer ${secret}` 进行身份验证 -如果 RESTful API 正在监听 0.0.0.0，请始终设置一个密钥。 - -#### default_mode - -Clash 中的默认模式，默认使用 `Rule`。 - -此设置没有直接影响，但可以通过 `clash_mode` 规则项在路由和 DNS 规则中使用。 - -#### store_mode - -将 Clash 模式存储在缓存文件中。 - -#### store_selected - -!!! note "" - - 必须为目标出站设置标签。 - -将 `Selector` 中出站的选定的目标出站存储在缓存文件中。 - -#### store_fakeip - -将 fakeip 存储在缓存文件中。 - -#### cache_file - -缓存文件路径，默认使用`cache.db`。 - -#### cache_id - -缓存 ID。 - -如果不为空，`store_selected` 将会使用以此为键的独立存储。 - -### V2Ray API 字段 - -!!! quote "" - - 默认安装不包含 V2Ray API，参阅 [安装](/zh/#_2)。 - -#### listen - -gRPC API 监听地址。如果为空，则禁用 V2Ray API。 - -#### stats - -流量统计服务设置。 - -#### stats.enabled - -启用统计服务。 - -#### stats.inbounds - -统计流量的入站列表。 - -#### stats.outbounds - -统计流量的出站列表。 - -#### stats.users - -统计流量的用户列表。 \ No newline at end of file diff --git a/docs/configuration/experimental/v2ray-api.md b/docs/configuration/experimental/v2ray-api.md new file mode 100644 index 00000000..39888424 --- /dev/null +++ b/docs/configuration/experimental/v2ray-api.md @@ -0,0 +1,50 @@ +### Structure + +!!! quote "" + + V2Ray API is not included by default, see [Installation](./#installation). + +```json +{ + "listen": "127.0.0.1:8080", + "stats": { + "enabled": true, + "inbounds": [ + "socks-in" + ], + "outbounds": [ + "proxy", + "direct" + ], + "users": [ + "sekai" + ] + } +} +``` + +### Fields + +#### listen + +gRPC API listening address. V2Ray API will be disabled if empty. + +#### stats + +Traffic statistics service settings. + +#### stats.enabled + +Enable statistics service. + +#### stats.inbounds + +Inbound list to count traffic. + +#### stats.outbounds + +Outbound list to count traffic. + +#### stats.users + +User list to count traffic. \ No newline at end of file diff --git a/docs/configuration/route/geoip.md b/docs/configuration/route/geoip.md index b966a292..8a2ed1d4 100644 --- a/docs/configuration/route/geoip.md +++ b/docs/configuration/route/geoip.md @@ -1,3 +1,11 @@ +--- +icon: material/delete-clock +--- + +!!! failure "Deprecated in sing-box 1.8.0" + + GeoIP is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geoip-to-rule-sets). + ### Structure ```json diff --git a/docs/configuration/route/geoip.zh.md b/docs/configuration/route/geoip.zh.md deleted file mode 100644 index 3ee70427..00000000 --- a/docs/configuration/route/geoip.zh.md +++ /dev/null @@ -1,33 +0,0 @@ -### 结构 - -```json -{ - "route": { - "geoip": { - "path": "", - "download_url": "", - "download_detour": "" - } - } -} -``` - -### 字段 - -#### path - -指定 GeoIP 资源的路径。 - -默认 `geoip.db`。 - -#### download_url - -指定 GeoIP 资源的下载链接。 - -默认为 `https://github.com/SagerNet/sing-geoip/releases/latest/download/geoip.db`。 - -#### download_detour - -用于下载 GeoIP 资源的出站的标签。 - -如果为空，将使用默认出站。 \ No newline at end of file diff --git a/docs/configuration/route/geosite.md b/docs/configuration/route/geosite.md index db700c6a..04630571 100644 --- a/docs/configuration/route/geosite.md +++ b/docs/configuration/route/geosite.md @@ -1,3 +1,11 @@ +--- +icon: material/delete-clock +--- + +!!! failure "Deprecated in sing-box 1.8.0" + + Geosite is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geosite-to-rule-sets). + ### Structure ```json diff --git a/docs/configuration/route/geosite.zh.md b/docs/configuration/route/geosite.zh.md deleted file mode 100644 index bee81fbf..00000000 --- a/docs/configuration/route/geosite.zh.md +++ /dev/null @@ -1,33 +0,0 @@ -### 结构 - -```json -{ - "route": { - "geosite": { - "path": "", - "download_url": "", - "download_detour": "" - } - } -} -``` - -### 字段 - -#### path - -指定 GeoSite 资源的路径。 - -默认 `geosite.db`。 - -#### download_url - -指定 GeoSite 资源的下载链接。 - -默认为 `https://github.com/SagerNet/sing-geosite/releases/latest/download/geosite.db`。 - -#### download_detour - -用于下载 GeoSite 资源的出站的标签。 - -如果为空，将使用默认出站。 \ No newline at end of file diff --git a/docs/configuration/route/index.md b/docs/configuration/route/index.md index 1ab85a4d..5deb44f5 100644 --- a/docs/configuration/route/index.md +++ b/docs/configuration/route/index.md @@ -1,5 +1,15 @@ +--- +icon: material/alert-decagram +--- + # Route +!!! quote "Changes in sing-box 1.8.0" + + :material-plus: [rule_set](#rule_set) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### Structure ```json @@ -8,6 +18,7 @@ "geoip": {}, "geosite": {}, "rules": [], + "rule_set": [], "final": "", "auto_detect_interface": false, "override_android_vpn": false, @@ -19,11 +30,20 @@ ### Fields -| Key | Format | -|-----------|-------------------------------| -| `geoip` | [GeoIP](./geoip/) | -| `geosite` | [Geosite](./geosite/) | -| `rules` | List of [Route Rule](./rule/) | +| Key | Format | +|-----------|----------------------| +| `geoip` | [GeoIP](./geoip/) | +| `geosite` | [Geosite](./geosite/) | + +#### rules + +List of [Route Rule](./rule/) + +#### rule_set + +!!! question "Since sing-box 1.8.0" + +List of [Rule Set](/configuration/rule-set/) #### final diff --git a/docs/configuration/route/index.zh.md b/docs/configuration/route/index.zh.md index 92e98e49..290268f4 100644 --- a/docs/configuration/route/index.zh.md +++ b/docs/configuration/route/index.zh.md @@ -1,5 +1,15 @@ +--- +icon: material/alert-decagram +--- + # 路由 +!!! quote "sing-box 1.8.0 中的更改" + + :material-plus: [rule_set](#rule_set) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### 结构 ```json @@ -7,8 +17,8 @@ "route": { "geoip": {}, "geosite": {}, - "ip_rules": [], "rules": [], + "rule_set": [], "final": "", "auto_detect_interface": false, "override_android_vpn": false, @@ -23,8 +33,17 @@ | 键 | 格式 | |-----------|-----------------------| | `geoip` | [GeoIP](./geoip/) | -| `geosite` | [GeoSite](./geosite/) | -| `rules` | 一组 [路由规则](./rule/) | +| `geosite` | [Geosite](./geosite/) | + +#### rule + +一组 [路由规则](./rule/) 。 + +#### rule_set + +!!! question "自 sing-box 1.8.0 起" + +一组 [规则集](/configuration/rule-set/)。 #### final diff --git a/docs/configuration/route/rule.md b/docs/configuration/route/rule.md index 2342ce22..9bedef86 100644 --- a/docs/configuration/route/rule.md +++ b/docs/configuration/route/rule.md @@ -1,3 +1,17 @@ +--- +icon: material/alert-decagram +--- + +!!! quote "Changes in sing-box 1.8.0" + + :material-plus: [rule_set](#rule_set) + :material-plus: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source) + :material-plus: [source_ip_is_private](#source_ip_is_private) + :material-plus: [ip_is_private](#ip_is_private) + :material-delete-clock: [source_geoip](#source_geoip) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### Structure ```json @@ -46,10 +60,12 @@ "10.0.0.0/24", "192.168.0.1" ], + "source_ip_is_private": false, "ip_cidr": [ "10.0.0.0/24", "192.168.0.1" ], + "ip_is_private": false, "source_port": [ 12345 ], @@ -89,6 +105,10 @@ "wifi_bssid": [ "00:00:00:00:00:00" ], + "rule_set": [ + "geoip-cn", + "geosite-cn" + ], "invert": false, "outbound": "direct" }, @@ -114,12 +134,14 @@ !!! note "" The default rule uses the following matching logic: - (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `geoip` || `ip_cidr`) && + (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `geoip` || `ip_cidr` || `ip_is_private`) && (`port` || `port_range`) && - (`source_geoip` || `source_ip_cidr`) && + (`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) && (`source_port` || `source_port_range`) && `other fields` + Additionally, included rule sets can be considered merged rather than as a single rule sub-item. + #### inbound Tags of [Inbound](/configuration/inbound/). @@ -160,23 +182,47 @@ Match domain using regular expression. #### geosite +!!! failure "Deprecated in sing-box 1.8.0" + + Geosite is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geosite-to-rule-sets). + Match geosite. #### source_geoip +!!! failure "Deprecated in sing-box 1.8.0" + + GeoIP is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geoip-to-rule-sets). + Match source geoip. #### geoip +!!! failure "Deprecated in sing-box 1.8.0" + + GeoIP is deprecated and may be removed in the future, check [Migration](/migration/#migrate-geoip-to-rule-sets). + Match geoip. #### source_ip_cidr -Match source ip cidr. +Match source IP CIDR. + +#### ip_is_private + +!!! question "Since sing-box 1.8.0" + +Match non-public IP. #### ip_cidr -Match ip cidr. +Match IP CIDR. + +#### source_ip_is_private + +!!! question "Since sing-box 1.8.0" + +Match non-public source IP. #### source_port @@ -250,6 +296,18 @@ Match WiFi SSID. Match WiFi BSSID. +#### rule_set + +!!! question "Since sing-box 1.8.0" + +Match [Rule Set](/configuration/route/#rule_set). + +#### rule_set_ipcidr_match_source + +!!! question "Since sing-box 1.8.0" + +Make `ipcidr` in rule sets match the source IP. + #### invert Invert match result. @@ -276,4 +334,4 @@ Tag of the target outbound. ==Required== -Included default rules. +Included rules. diff --git a/docs/configuration/route/rule.zh.md b/docs/configuration/route/rule.zh.md index 7c49eb43..1cec0a75 100644 --- a/docs/configuration/route/rule.zh.md +++ b/docs/configuration/route/rule.zh.md @@ -1,3 +1,17 @@ +--- +icon: material/alert-decagram +--- + +!!! quote "sing-box 1.8.0 中的更改" + + :material-plus: [rule_set](#rule_set) + :material-plus: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source) + :material-plus: [source_ip_is_private](#source_ip_is_private) + :material-plus: [ip_is_private](#ip_is_private) + :material-delete-clock: [source_geoip](#source_geoip) + :material-delete-clock: [geoip](#geoip) + :material-delete-clock: [geosite](#geosite) + ### 结构 ```json @@ -45,9 +59,11 @@ "source_ip_cidr": [ "10.0.0.0/24" ], + "source_ip_is_private": false, "ip_cidr": [ "10.0.0.0/24" ], + "ip_is_private": false, "source_port": [ 12345 ], @@ -87,6 +103,10 @@ "wifi_bssid": [ "00:00:00:00:00:00" ], + "rule_set": [ + "geoip-cn", + "geosite-cn" + ], "invert": false, "outbound": "direct" }, @@ -112,12 +132,14 @@ !!! note "" 默认规则使用以下匹配逻辑: - (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `geoip` || `ip_cidr`) && + (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `geoip` || `ip_cidr` || `ip_is_private`) && (`port` || `port_range`) && - (`source_geoip` || `source_ip_cidr`) && + (`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) && (`source_port` || `source_port_range`) && `other fields` + 另外，引用的规则集可视为被合并，而不是作为一个单独的规则子项。 + #### inbound [入站](/zh/configuration/inbound/) 标签。 @@ -158,24 +180,48 @@ #### geosite -匹配 GeoSite。 +!!! failure "已在 sing-box 1.8.0 废弃" + + Geosite 已废弃且可能在不久的将来移除，参阅 [迁移指南](/migration/#migrate-geosite-to-rule-sets)。 + +匹配 Geosite。 #### source_geoip +!!! failure "已在 sing-box 1.8.0 废弃" + + GeoIp 已废弃且可能在不久的将来移除，参阅 [迁移指南](/migration/#migrate-geoip-to-rule-sets)。 + 匹配源 GeoIP。 #### geoip +!!! failure "已在 sing-box 1.8.0 废弃" + + GeoIp 已废弃且可能在不久的将来移除，参阅 [迁移指南](/migration/#migrate-geoip-to-rule-sets)。 + 匹配 GeoIP。 #### source_ip_cidr 匹配源 IP CIDR。 +#### source_ip_is_private + +!!! question "自 sing-box 1.8.0 起" + +匹配非公开源 IP。 + #### ip_cidr 匹配 IP CIDR。 +#### ip_is_private + +!!! question "自 sing-box 1.8.0 起" + +匹配非公开 IP。 + #### source_port 匹配源端口。 @@ -248,6 +294,18 @@ 匹配 WiFi BSSID。 +#### rule_set + +!!! question "自 sing-box 1.8.0 起" + +匹配[规则集](/zh/configuration/route/#rule_set)。 + +#### rule_set_ipcidr_match_source + +!!! question "自 sing-box 1.8.0 起" + +使规则集中的 `ipcidr` 规则匹配源 IP。 + #### invert 反选匹配结果。 @@ -274,4 +332,4 @@ ==必填== -包括的默认规则。 \ No newline at end of file +包括的规则。 \ No newline at end of file diff --git a/docs/configuration/rule-set/headless-rule.md b/docs/configuration/rule-set/headless-rule.md new file mode 100644 index 00000000..6ab62eb2 --- /dev/null +++ b/docs/configuration/rule-set/headless-rule.md @@ -0,0 +1,207 @@ +--- +icon: material/new-box +--- + +### Structure + +!!! question "Since sing-box 1.8.0" + +```json +{ + "rules": [ + { + "query_type": [ + "A", + "HTTPS", + 32768 + ], + "network": [ + "tcp" + ], + "domain": [ + "test.com" + ], + "domain_suffix": [ + ".cn" + ], + "domain_keyword": [ + "test" + ], + "domain_regex": [ + "^stun\\..+" + ], + "source_ip_cidr": [ + "10.0.0.0/24", + "192.168.0.1" + ], + "ip_cidr": [ + "10.0.0.0/24", + "192.168.0.1" + ], + "source_port": [ + 12345 + ], + "source_port_range": [ + "1000:2000", + ":3000", + "4000:" + ], + "port": [ + 80, + 443 + ], + "port_range": [ + "1000:2000", + ":3000", + "4000:" + ], + "process_name": [ + "curl" + ], + "process_path": [ + "/usr/bin/curl" + ], + "package_name": [ + "com.termux" + ], + "wifi_ssid": [ + "My WIFI" + ], + "wifi_bssid": [ + "00:00:00:00:00:00" + ], + "invert": false + }, + { + "type": "logical", + "mode": "and", + "rules": [], + "invert": false + } + ] +} +``` + +!!! note "" + + You can ignore the JSON Array [] tag when the content is only one item + +### Default Fields + +!!! note "" + + The default rule uses the following matching logic: + (`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `ip_cidr`) && + (`port` || `port_range`) && + (`source_port` || `source_port_range`) && + `other fields` + +#### query_type + +DNS query type. Values can be integers or type name strings. + +#### network + +`tcp` or `udp`. + +#### domain + +Match full domain. + +#### domain_suffix + +Match domain suffix. + +#### domain_keyword + +Match domain using keyword. + +#### domain_regex + +Match domain using regular expression. + +#### source_ip_cidr + +Match source IP CIDR. + +#### ip_cidr + +!!! info "" + + `ip_cidr` is an alias for `source_ip_cidr` when the Rule Set is used in DNS rules or `rule_set_ipcidr_match_source` enabled in route rules. + +Match IP CIDR. + +#### source_port + +Match source port. + +#### source_port_range + +Match source port range. + +#### port + +Match port. + +#### port_range + +Match port range. + +#### process_name + +!!! quote "" + + Only supported on Linux, Windows, and macOS. + +Match process name. + +#### process_path + +!!! quote "" + + Only supported on Linux, Windows, and macOS. + +Match process path. + +#### package_name + +Match android package name. + +#### wifi_ssid + +!!! quote "" + + Only supported in graphical clients on Android and iOS. + +Match WiFi SSID. + +#### wifi_bssid + +!!! quote "" + + Only supported in graphical clients on Android and iOS. + +Match WiFi BSSID. + +#### invert + +Invert match result. + +### Logical Fields + +#### type + +`logical` + +#### mode + +==Required== + +`and` or `or` + +#### rules + +==Required== + +Included rules. diff --git a/docs/configuration/rule-set/index.md b/docs/configuration/rule-set/index.md new file mode 100644 index 00000000..5aff55b3 --- /dev/null +++ b/docs/configuration/rule-set/index.md @@ -0,0 +1,97 @@ +--- +icon: material/new-box +--- + +# Rule Set + +!!! question "Since sing-box 1.8.0" + +### Structure + +```json +{ + "type": "", + "tag": "", + "format": "", + + ... // Typed Fields +} +``` + +#### Local Structure + +```json +{ + "type": "local", + + ... + + "path": "" +} +``` + +#### Remote Structure + +!!! info "" + + Remote rule-set will be cached if `experimental.cache_file.enabled`. + +```json +{ + "type": "remote", + + ..., + + "url": "", + "download_detour": "", + "update_interval": "" +} +``` + +### Fields + +#### type + +==Required== + +Type of Rule Set, `local` or `remote`. + +#### tag + +==Required== + +Tag of Rule Set. + +#### format + +==Required== + +Format of Rule Set, `source` or `binary`. + +### Local Fields + +#### path + +==Required== + +File path of Rule Set. + +### Remote Fields + +#### url + +==Required== + +Download URL of Rule Set. + +#### download_detour + +Tag of the outbound to download rule-set. + +Default outbound will be used if empty. + +#### update_interval + +Update interval of Rule Set. + +`1d` will be used if empty. diff --git a/docs/configuration/rule-set/source-format.md b/docs/configuration/rule-set/source-format.md new file mode 100644 index 00000000..8e1934ae --- /dev/null +++ b/docs/configuration/rule-set/source-format.md @@ -0,0 +1,34 @@ +--- +icon: material/new-box +--- + +# Source Format + +!!! question "Since sing-box 1.8.0" + +### Structure + +```json +{ + "version": 1, + "rules": [] +} +``` + +### Compile + +Use `sing-box rule-set compile [--output .srs] .json` to compile source to binary rule-set. + +### Fields + +#### version + +==Required== + +Version of Rule Set, must be `1`. + +#### rules + +==Required== + +List of [Headless Rule](./headless-rule.md/). diff --git a/docs/manual/proxy/client.md b/docs/manual/proxy/client.md index 60db02de..11bc40ce 100644 --- a/docs/manual/proxy/client.md +++ b/docs/manual/proxy/client.md @@ -343,6 +343,83 @@ flowchart TB } ``` +=== ":material-dns: DNS rules (1.8.0+)" + + !!! info + + DNS rules are optional if FakeIP is used. + + ```json + { + "dns": { + "servers": [ + { + "tag": "google", + "address": "tls://8.8.8.8" + }, + { + "tag": "local", + "address": "223.5.5.5", + "detour": "direct" + } + ], + "rules": [ + { + "outbound": "any", + "server": "local" + }, + { + "clash_mode": "Direct", + "server": "local" + }, + { + "clash_mode": "Global", + "server": "google" + }, + { + "type": "logical", + "mode": "and", + "rules": [ + { + "rule_set": "geosite-geolocation-!cn", + "invert": true + }, + { + "rule_set": [ + "geosite-cn", + "geosite-category-companies@cn" + ] + } + ], + "server": "local" + } + ] + }, + "route": { + "rule_set": [ + { + "type": "remote", + "tag": "geosite-cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs" + }, + { + "type": "remote", + "tag": "geosite-geolocation-!cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-!cn.srs" + }, + { + "type": "remote", + "tag": "geosite-category-companies@cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-category-companies@cn.srs" + } + ] + } + } + ``` + === ":material-router-network: Route rules" ```json @@ -422,4 +499,111 @@ flowchart TB ] } } + ``` + +=== ":material-router-network: Route rules (1.8.0+)" + + ```json + { + "outbounds": [ + { + "type": "direct", + "tag": "direct" + }, + { + "type": "block", + "tag": "block" + } + ], + "route": { + "rules": [ + { + "type": "logical", + "mode": "or", + "rules": [ + { + "protocol": "dns" + }, + { + "port": 53 + } + ], + "outbound": "dns" + }, + { + "ip_is_private": true, + "outbound": "direct" + }, + { + "clash_mode": "Direct", + "outbound": "direct" + }, + { + "clash_mode": "Global", + "outbound": "default" + }, + { + "type": "logical", + "mode": "or", + "rules": [ + { + "port": 853 + }, + { + "network": "udp", + "port": 443 + }, + { + "protocol": "stun" + } + ], + "outbound": "block" + }, + { + "type": "logical", + "mode": "and", + "rules": [ + { + "rule_set": "geosite-geolocation-!cn", + "invert": true + }, + { + "rule_set": [ + "geoip-cn", + "geosite-cn", + "geosite-category-companies@cn" + ] + } + ], + "outbound": "direct" + } + ], + "rule_set": [ + { + "type": "remote", + "tag": "geoip-cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs" + }, + { + "type": "remote", + "tag": "geosite-cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs" + }, + { + "type": "remote", + "tag": "geosite-geolocation-!cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-geolocation-!cn.srs" + }, + { + "type": "remote", + "tag": "geosite-category-companies@cn", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-category-companies@cn.srs" + } + ] + } + } ``` \ No newline at end of file diff --git a/docs/migration.md b/docs/migration.md new file mode 100644 index 00000000..3e191780 --- /dev/null +++ b/docs/migration.md @@ -0,0 +1,195 @@ +--- +icon: material/arrange-bring-forward +--- + +# Migration + +## 1.8.0 + +!!! warning "Unstable" + + This version is still under development, and the following migration guide may be changed in the future. + +### :material-close-box: Migrate cache file from Clash API to independent options + +!!! info "Reference" + + [Clash API](/configuration/experimental/clash-api/) / + [Cache File](/configuration/experimental/cache-file/) + +=== ":material-card-remove: Deprecated" + + ```json + { + "experimental": { + "clash_api": { + "cache_file": "cache.db", // default value + "cahce_id": "my_profile2", + "store_mode": true, + "store_selected": true, + "store_fakeip": true + } + } + } + ``` + +=== ":material-card-multiple: New" + + ```json + { + "experimental" : { + "cache_file": { + "enabled": true, + "path": "cache.db", // default value + "cache_id": "my_profile2", + "store_fakeip": true + } + } + } + ``` + +### :material-checkbox-intermediate: Migrate GeoIP to rule sets + +!!! info "Reference" + + [GeoIP](/configuration/route/geoip/) / + [Route](/configuration/route/) / + [Route Rule](/configuration/route/rule/) / + [DNS Rule](/configuration/dns/rule/) / + [Rule Set](/configuration/rule-set/) + +!!! tip + + `sing-box geoip` commands can help you convert custom GeoIP into rule sets. + +=== ":material-card-remove: Deprecated" + + ```json + { + "route": { + "rules": [ + { + "geoip": "private", + "outbound": "direct" + }, + { + "geoip": "cn", + "outbound": "direct" + }, + { + "source_geoip": "cn", + "outbound": "block" + } + ], + "geoip": { + "download_detour": "proxy" + } + } + } + ``` + +=== ":material-card-multiple: New" + + ```json + { + "route": { + "rules": [ + { + "ip_is_private": true, + "outbound": "direct" + }, + { + "rule_set": "geoip-cn", + "outbound": "direct" + }, + { + "rule_set": "geoip-us", + "rule_set_ipcidr_match_source": true, + "outbound": "block" + } + ], + "rule_set": [ + { + "tag": "geoip-cn", + "type": "remote", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs", + "download_detour": "proxy" + }, + { + "tag": "geoip-us", + "type": "remote", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-us.srs", + "download_detour": "proxy" + } + ] + }, + "experimental": { + "cache_file": { + "enabled": true // required to save Rule Set cache + } + } + } + ``` + +### :material-checkbox-intermediate: Migrate Geosite to rule sets + +!!! info "Reference" + + [Geosite](/configuration/route/geosite/) / + [Route](/configuration/route/) / + [Route Rule](/configuration/route/rule/) / + [DNS Rule](/configuration/dns/rule/) / + [Rule Set](/configuration/rule-set/) + +!!! tip + + `sing-box geosite` commands can help you convert custom Geosite into rule sets. + +=== ":material-card-remove: Deprecated" + + ```json + { + "route": { + "rules": [ + { + "geosite": "cn", + "outbound": "direct" + } + ], + "geosite": { + "download_detour": "proxy" + } + } + } + ``` + +=== ":material-card-multiple: New" + + ```json + { + "route": { + "rules": [ + { + "rule_set": "geosite-cn", + "outbound": "direct" + } + ], + "rule_set": [ + { + "tag": "geosite-cn", + "type": "remote", + "format": "binary", + "url": "https://raw.githubusercontent.com/SagerNet/sing-geosite/rule-set/geosite-cn.srs", + "download_detour": "proxy" + } + ] + }, + "experimental": { + "cache_file": { + "enabled": true // required to save Rule Set cache + } + } + } + ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 1d4b1d8b..c5dd7df3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,12 +32,16 @@ theme: - content.code.copy - content.code.select - content.code.annotate + icon: + admonition: + question: material/new-box nav: - Home: - index.md + - Change Log: changelog.md + - Migration: migration.md - Deprecated: deprecated.md - Support: support.md - - Change Log: changelog.md - Installation: - Package Manager: installation/package-manager.md - Docker: installation/docker.md @@ -56,7 +60,7 @@ nav: - Proxy: - Server: manual/proxy/server.md - Client: manual/proxy/client.md -# - TUN: manual/proxy/tun.md + # - TUN: manual/proxy/tun.md - Proxy Protocol: - Shadowsocks: manual/proxy-protocol/shadowsocks.md - Trojan: manual/proxy-protocol/trojan.md @@ -79,8 +83,15 @@ nav: - Geosite: configuration/route/geosite.md - Route Rule: configuration/route/rule.md - Protocol Sniff: configuration/route/sniff.md + - Rule Set: + - configuration/rule-set/index.md + - Source Format: configuration/rule-set/source-format.md + - Headless Rule: configuration/rule-set/headless-rule.md - Experimental: - configuration/experimental/index.md + - Cache File: configuration/experimental/cache-file.md + - Clash API: configuration/experimental/clash-api.md + - V2Ray API: configuration/experimental/v2ray-api.md - Shared: - Listen Fields: configuration/shared/listen.md - Dial Fields: configuration/shared/dial.md @@ -180,9 +191,10 @@ plugins: name: 简体中文 nav_translations: Home: 开始 + Change Log: 更新日志 + Migration: 迁移指南 Deprecated: 废弃功能列表 Support: 支持 - Change Log: 更新日志 Installation: 安装 Package Manager: 包管理器 @@ -203,6 +215,10 @@ plugins: Route Rule: 路由规则 Protocol Sniff: 协议探测 + Rule Set: 规则集 + Source Format: 源文件格式 + Headless Rule: 无头规则 + Experimental: 实验性 Shared: 通用 @@ -215,10 +231,6 @@ plugins: Inbound: 入站 Outbound: 出站 - FAQ: 常见问题 - Known Issues: 已知问题 - Examples: 示例 - Linux Server Installation: Linux 服务器安装 - DNS Hijack: DNS 劫持 + Manual: 手册 reconfigure_material: true reconfigure_search: true \ No newline at end of file