From ebf5cbf1b9540e31a21e211de30b257cb82285a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=96=E7=95=8C?= Date: Sat, 10 Sep 2022 22:42:20 +0800 Subject: [PATCH] Update documentation --- constant/version.go | 2 +- docs/changelog.md | 25 ++++++++ docs/configuration/dns/rule.md | 5 ++ docs/configuration/dns/rule.zh.md | 5 ++ docs/configuration/experimental/index.md | 27 ++++++++- docs/configuration/experimental/index.zh.md | 27 ++++++++- docs/configuration/route/rule.md | 5 ++ docs/configuration/route/rule.zh.md | 5 ++ docs/configuration/shared/tls.md | 66 +++++++++++++++++---- docs/configuration/shared/tls.zh.md | 65 ++++++++++++++++---- docs/index.md | 2 + docs/index.zh.md | 2 + 12 files changed, 209 insertions(+), 27 deletions(-) diff --git a/constant/version.go b/constant/version.go index 594d8c12..008c78fc 100644 --- a/constant/version.go +++ b/constant/version.go @@ -1,6 +1,6 @@ package constant var ( - Version = "1.1-beta1" + Version = "1.1-beta2" Commit = "" ) diff --git a/docs/changelog.md b/docs/changelog.md index a6937bff..a56cf02e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,3 +1,28 @@ +#### 1.1-beta2 + +* Add Clash mode and persistence support **1** +* Add TLS ECH and uTLS support for outbound TLS options **2** +* Fix socks4 request +* Fix processing empty dns result + +*1*: + +Switching modes using the Clash API, and `store-selected` are now supported, +see [Experimental](/configuration/experimental). + +*2*: + +ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello +message, see [TLS#ECH](/configuration/shared/tls#ech). + +uTLS is a fork of "crypto/tls", which provides ClientHello fingerprinting resistance, +see [TLS#uTLS](/configuration/shared/tls#utls). + +#### 1.0.2 + +* Fix socks4 request +* Fix processing empty dns result + #### 1.1-beta1 * Add support for use with android VPNService **1** diff --git a/docs/configuration/dns/rule.md b/docs/configuration/dns/rule.md index 924defe1..486ad969 100644 --- a/docs/configuration/dns/rule.md +++ b/docs/configuration/dns/rule.md @@ -73,6 +73,7 @@ "user_id": [ 1000 ], + "clash_mode": "direct", "invert": false, "outbound": [ "direct" @@ -208,6 +209,10 @@ Match user name. Match user id. +#### clash_mode + +Match Clash mode. + #### invert Invert match result. diff --git a/docs/configuration/dns/rule.zh.md b/docs/configuration/dns/rule.zh.md index c332bbf6..c1fd092c 100644 --- a/docs/configuration/dns/rule.zh.md +++ b/docs/configuration/dns/rule.zh.md @@ -72,6 +72,7 @@ "user_id": [ 1000 ], + "clash_mode": "direct", "invert": false, "outbound": [ "direct" @@ -207,6 +208,10 @@ 匹配用户 ID。 +#### clash_mode + +匹配 Clash 模式。 + #### invert 反选匹配结果。 diff --git a/docs/configuration/experimental/index.md b/docs/configuration/experimental/index.md index 9a9792a6..ca145741 100644 --- a/docs/configuration/experimental/index.md +++ b/docs/configuration/experimental/index.md @@ -8,7 +8,10 @@ "clash_api": { "external_controller": "127.0.0.1:9090", "external_ui": "folder", - "secret": "" + "secret": "", + "default_mode": "rule", + "store_selected": false, + "cache_file": "cache.db" } } } @@ -26,7 +29,7 @@ #### external_controller -RESTful web API listening address. Disabled if empty. +RESTful web API listening address. Clash API will be disabled if empty. #### external_ui @@ -38,4 +41,22 @@ serve it at `http://{{external-controller}}/ui`. 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 \ No newline at end of file +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_selected + +!!! note "" + + The tag must be set for target outbounds. + +Store selected outbound for the `Selector` outbound in cache file. + +#### cache_file + +Cache file path, `cache.db` will be used if empty. \ No newline at end of file diff --git a/docs/configuration/experimental/index.zh.md b/docs/configuration/experimental/index.zh.md index 9595383e..66456532 100644 --- a/docs/configuration/experimental/index.zh.md +++ b/docs/configuration/experimental/index.zh.md @@ -8,7 +8,10 @@ "clash_api": { "external_controller": "127.0.0.1:9090", "external_ui": "folder", - "secret": "" + "secret": "", + "default_mode": "rule", + "store_selected": false, + "cache_file": "cache.db" } } } @@ -26,7 +29,7 @@ #### external_controller -RESTful web API 监听地址。 +RESTful web API 监听地址。如果为空，则禁用 Clash API。 #### external_ui @@ -36,4 +39,22 @@ RESTful web API 监听地址。 RESTful API 的密钥（可选） 通过指定 HTTP 标头 `Authorization: Bearer ${secret}` 进行身份验证 -如果 RESTful API 正在监听 0.0.0.0，请始终设置一个密钥。 \ No newline at end of file +如果 RESTful API 正在监听 0.0.0.0，请始终设置一个密钥。 + +#### default_mode + +Clash 中的默认模式，默认使用 `rule`。 + +此设置没有直接影响，但可以通过 `clash_mode` 规则项在路由和 DNS 规则中使用。 + +#### store_selected + +!!! note "" + + 必须为目标出站设置标签。 + +将 `Selector` 中出站的选定的目标出站存储在缓存文件中。 + +#### cache_file + +缓存文件路径，默认使用`cache.db`。 \ No newline at end of file diff --git a/docs/configuration/route/rule.md b/docs/configuration/route/rule.md index cc88943e..7e7ac210 100644 --- a/docs/configuration/route/rule.md +++ b/docs/configuration/route/rule.md @@ -80,6 +80,7 @@ "user_id": [ 1000 ], + "clash_mode": "direct", "invert": false, "outbound": "direct" }, @@ -219,6 +220,10 @@ Match user name. Match user id. +#### clash_mode + +Match Clash mode. + #### invert Invert match result. diff --git a/docs/configuration/route/rule.zh.md b/docs/configuration/route/rule.zh.md index f1439d71..f6ef4ab6 100644 --- a/docs/configuration/route/rule.zh.md +++ b/docs/configuration/route/rule.zh.md @@ -78,6 +78,7 @@ "user_id": [ 1000 ], + "clash_mode": "direct", "invert": false, "outbound": "direct" }, @@ -217,6 +218,10 @@ 匹配用户 ID。 +#### clash_mode + +匹配 Clash 模式。 + #### invert 反选匹配结果。 diff --git a/docs/configuration/shared/tls.md b/docs/configuration/shared/tls.md index 14a37a31..0f0b2a2a 100644 --- a/docs/configuration/shared/tls.md +++ b/docs/configuration/shared/tls.md @@ -30,10 +30,6 @@ } ``` -!!! warning "" - - ACME is not included by default, see [Installation](/#installation). - ### Outbound ```json @@ -47,7 +43,17 @@ "max_version": "", "cipher_suites": [], "certificate": "", - "certificate_path": "" + "certificate_path": "", + "ech": { + "enabled": false, + "pq_signature_schemes_enabled": false, + "dynamic_record_sizing_disabled": false, + "config": "" + }, + "utls": { + "enabled": false, + "fingerprint": "" + } } ``` @@ -155,8 +161,48 @@ The server private key, in PEM format. The path to the server private key, in PEM format. +#### ech + +==Client only== + +!!! warning "" + + ECH is not included by default, see [Installation](/#installation). + +ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello +message. + +If you don't know how to fill in the other configuration, just set `enabled`. + +#### utls + +==Client only== + +!!! warning "" + + uTLS is not included by default, see [Installation](/#installation). + +!!! note "" + + uTLS is poorly maintained and the effect may be unproven, use at your own risk. + +uTLS is a fork of "crypto/tls", which provides ClientHello fingerprinting resistance. + +Available fingerprint values: + +* chrome +* firefox +* ios +* android +* random + + ### ACME Fields +!!! warning "" + + ACME is not included by default, see [Installation](/#installation). + #### domain List of domain. @@ -205,10 +251,6 @@ listener for the HTTP challenge. The alternate port to use for the ACME TLS-ALPN challenge; the system must forward 443 to this port for challenge to succeed. -### Reload - -For server configuration, certificate and key will be automatically reloaded if modified. - #### external_account EAB (External Account Binding) contains information necessary to bind or map an ACME account to some other account known @@ -226,4 +268,8 @@ The key identifier. #### external_account.mac_key -The MAC key. \ No newline at end of file +The MAC key. + +### Reload + +For server configuration, certificate and key will be automatically reloaded if modified. \ No newline at end of file diff --git a/docs/configuration/shared/tls.zh.md b/docs/configuration/shared/tls.zh.md index f450e080..bef2727a 100644 --- a/docs/configuration/shared/tls.zh.md +++ b/docs/configuration/shared/tls.zh.md @@ -30,10 +30,6 @@ } ``` -!!! warning "" - - 默认安装不包含 ACME，参阅 [安装](/zh/#_2)。 - ### 出站 ```json @@ -47,7 +43,17 @@ "max_version": "", "cipher_suites": [], "certificate": "", - "certificate_path": "" + "certificate_path": "", + "ech": { + "enabled": false, + "pq_signature_schemes_enabled": false, + "dynamic_record_sizing_disabled": false, + "config": "" + }, + "utls": { + "enabled": false, + "fingerprint": "" + } } ``` @@ -155,8 +161,47 @@ TLS 版本值： 服务器 PEM 私钥路径。 +#### ech + +==仅客户端== + +!!! warning "" + + 默认安装不包含 ECH, 参阅 [安装](/zh/#_2)。 + +ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分 +信息。 + +如果您不知道如何填写其他配置，只需设置 `enabled` 即可。 + +#### utls + +==仅客户端== + +!!! warning "" + + 默认安装不包含 uTLS, 参阅 [安装](/zh/#_2)。 + +!!! note "" + + uTLS 维护不善且其效果可能未经证实，使用风险自负。 + +uTLS 是 "crypto/tls" 的一个分支，它提供了 ClientHello 指纹识别阻力。 + +可用的指纹值： + +* chrome +* firefox +* ios +* android +* random + ### ACME 字段 +!!! warning "" + + 默认安装不包含 ACME，参阅 [安装](/zh/#_2)。 + #### domain 一组域名。 @@ -203,10 +248,6 @@ ACME 数据目录。 用于 ACME TLS-ALPN 质询的备用端口； 系统必须将 443 转发到此端口以使质询成功。 -### Reload - -对于服务器配置，如果修改，证书和密钥将自动重新加载。 - #### external_account EAB（外部帐户绑定）包含将 ACME 帐户绑定或映射到其他已知帐户所需的信息由 CA。 @@ -222,4 +263,8 @@ EAB（外部帐户绑定）包含将 ACME 帐户绑定或映射到其他已知 #### external_account.mac_key -MAC 密钥。 \ No newline at end of file +MAC 密钥。 + +### 重载 + +对于服务器配置，如果修改，证书和密钥将自动重新加载。 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 20514724..600b9b8d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,6 +27,8 @@ go install -v -tags with_clash_api github.com/sagernet/sing-box/cmd/sing-box@lat | `with_quic` | Build with QUIC support, see [QUIC and HTTP3 dns transports](./configuration/dns/server), [Naive inbound](./configuration/inbound/naive), [Hysteria Inbound](./configuration/inbound/hysteria), [Hysteria Outbound](./configuration/outbound/hysteria) and [V2Ray Transport#QUIC](./configuration/shared/v2ray-transport#quic). | | `with_grpc` | Build with standard gRPC support, see [V2Ray Transport#gRPC](./configuration/shared/v2ray-transport#grpc). | | `with_wireguard` | Build with WireGuard support, see [WireGuard outbound](./configuration/outbound/wireguard). | +| `with_ech` | Build with TLS ECH extension support for TLS outbound, see [TLS](./configuration/shared/tls#ech). | +| `with_utls` | Build with [uTLS](https://github.com/refraction-networking/utls) support for TLS outbound, see [TLS](./configuration/shared/tls#utls). | | `with_acme` | Build with ACME TLS certificate issuer support, see [TLS](./configuration/shared/tls). | | `with_clash_api` | Build with Clash API support, see [Experimental](./configuration/experimental#clash-api-fields). | | `no_gvisor` | Build without gVisor Tun stack support, see [Tun inbound](./configuration/inbound/tun#stack). | diff --git a/docs/index.zh.md b/docs/index.zh.md index 944daff1..9dd1ab6e 100644 --- a/docs/index.zh.md +++ b/docs/index.zh.md @@ -27,6 +27,8 @@ go install -v -tags with_clash_api github.com/sagernet/sing-box/cmd/sing-box@lat | `with_quic` | 启用 QUIC 支持，参阅 [QUIC 和 HTTP3 DNS 传输层](./configuration/dns/server)，[Naive 入站](./configuration/inbound/naive)，[Hysteria 入站](./configuration/inbound/hysteria)，[Hysteria 出站](./configuration/outbound/hysteria) 和 [V2Ray 传输层#QUIC](./configuration/shared/v2ray-transport#quic)。 | | `with_grpc` | 启用标准 gRPC 支持，参阅 [V2Ray 传输层#gRPC](./configuration/shared/v2ray-transport#grpc)。 | | `with_wireguard` | 启用 WireGuard 支持，参阅 [WireGuard 出站](./configuration/outbound/wireguard)。 | +| `with_ech` | 启用 TLS ECH 扩展支持，参阅 [TLS](./configuration/shared/tls#ech)。 | +| `with_utls` | 启用 [uTLS](https://github.com/refraction-networking/utls) 支持， 参阅 [TLS](./configuration/shared/tls#utls)。 | | `with_acme` | 启用 ACME TLS 证书签发支持，参阅 [TLS](./configuration/shared/tls)。 | | `with_clash_api` | 启用 Clash api 支持，参阅 [实验性](./configuration/experimental#clash-api-fields)。 | | `no_gvisor` | 禁用 gVisor Tun 栈支持，参阅 [Tun 入站](./configuration/inbound/tun#stack)。 |