diff --git a/docs/configuration/route/rule_action.md b/docs/configuration/route/rule_action.md index b362eefe5..e3b8176d9 100644 --- a/docs/configuration/route/rule_action.md +++ b/docs/configuration/route/rule_action.md @@ -256,7 +256,9 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls. !!! question "Since sing-box 1.14.0" -==Linux/macOS/Windows only, requires elevated privileges== +!!! quote "" + + Only supported on Linux, macOS, and Windows, and requires elevated privileges. Inject a forged TLS ClientHello carrying this SNI before the real one, to fool SNI-filtering middleboxes that permit specific hostnames. diff --git a/docs/configuration/route/rule_action.zh.md b/docs/configuration/route/rule_action.zh.md index 3ef8d8d43..ef25ea1ff 100644 --- a/docs/configuration/route/rule_action.zh.md +++ b/docs/configuration/route/rule_action.zh.md @@ -248,7 +248,9 @@ UDP 连接超时时间。 !!! question "自 sing-box 1.14.0 起" -==仅 Linux/macOS/Windows，需要管理员权限== +!!! quote "" + + 仅支持 Linux、macOS 和 Windows，需要提升的权限。 在真实 ClientHello 之前注入携带本字段所指定 SNI 的伪造 TLS ClientHello， 用于欺骗仅放行特定主机名的 SNI 过滤中间盒。 diff --git a/docs/configuration/service/api.md b/docs/configuration/service/api.md index b12d53387..9baf71425 100644 --- a/docs/configuration/service/api.md +++ b/docs/configuration/service/api.md @@ -8,6 +8,10 @@ icon: material/new-box The sing-box API service is a gRPC server for observing and controlling the running sing-box instance. +It can be accessed by the [sing-box graphical clients](/clients/) for iOS, macOS, and +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. diff --git a/docs/configuration/service/api.zh.md b/docs/configuration/service/api.zh.md index 5c3bdcf9d..521ca5c99 100644 --- a/docs/configuration/service/api.zh.md +++ b/docs/configuration/service/api.zh.md @@ -8,6 +8,8 @@ icon: material/new-box sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gRPC 服务器。 +它可以由 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 传输。 diff --git a/docs/configuration/service/index.md b/docs/configuration/service/index.md index 8215285da..5ac7db167 100644 --- a/docs/configuration/service/index.md +++ b/docs/configuration/service/index.md @@ -30,6 +30,8 @@ icon: material/new-box | `ocm` | [OCM](./ocm) | | `resolved` | [Resolved](./resolved) | | `ssm-api` | [SSM API](./ssm-api) | +| `usbip-server` | [USB/IP Server](./usbip-server) | +| `usbip-client` | [USB/IP Client](./usbip-client) | #### tag diff --git a/docs/configuration/service/index.zh.md b/docs/configuration/service/index.zh.md index cc56975c0..a44209c37 100644 --- a/docs/configuration/service/index.zh.md +++ b/docs/configuration/service/index.zh.md @@ -30,6 +30,8 @@ icon: material/new-box | `ocm` | [OCM](./ocm) | | `resolved` | [Resolved](./resolved) | | `ssm-api` | [SSM API](./ssm-api) | +| `usbip-server` | [USB/IP Server](./usbip-server) | +| `usbip-client` | [USB/IP Client](./usbip-client) | #### tag diff --git a/docs/configuration/service/usbip-client.md b/docs/configuration/service/usbip-client.md new file mode 100644 index 000000000..3c7c99eb6 --- /dev/null +++ b/docs/configuration/service/usbip-client.md @@ -0,0 +1,78 @@ +--- +icon: material/new-box +--- + +!!! question "Since sing-box 1.14.0" + +# USB/IP Client + +USB/IP Client service imports remote USB devices over [USB/IP](https://usbip.sourceforge.net/), +exported by the [USB/IP Server](/configuration/service/usbip-server/). + +Available on Linux, Windows, and macOS (macOS requires a build with CGO). Not available on iOS. + +The server must be a sing-box (or sing-usbip) server. + +### Structure + +```json +{ + "type": "usbip-client", + + ... // Dial Fields + + "server": "", + "server_port": 0, + "devices": [] +} +``` + +!!! 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. + +Only `detour` takes effect. + +### Fields + +#### server + +==Required== + +The remote `usbip-server` address. + +#### server_port + +The remote `usbip-server` port. Defaults to `3240`. + +#### devices + +List of device matches selecting which remote devices to import. If empty, all exported devices +are imported. + +Object format: + +```json +{ + "bus_id": "", + "vendor_id": 0, + "product_id": 0, + "serial": "" +} +``` + +Object fields: + +- `bus_id`: USB bus ID, e.g. `1-2`. +- `vendor_id`: USB vendor ID, as a number. +- `product_id`: USB product ID, as a number. +- `serial`: Device serial number. + +Within one object, all specified fields must match; multiple objects are combined as a union. At +least one field is required. diff --git a/docs/configuration/service/usbip-client.zh.md b/docs/configuration/service/usbip-client.zh.md new file mode 100644 index 000000000..853ac575f --- /dev/null +++ b/docs/configuration/service/usbip-client.zh.md @@ -0,0 +1,73 @@ +--- +icon: material/new-box +--- + +!!! question "自 sing-box 1.14.0 起" + +# USB/IP Client + +USB/IP Client 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导入由 [USB/IP Server](/zh/configuration/service/usbip-server/) 导出的远程 USB 设备。 + +可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建）。不支持 iOS。 + +服务端必须是 sing-box（或 sing-usbip）服务端。 + +### 结构 + +```json +{ + "type": "usbip-client", + + ... // 拨号字段 + + "server": "", + "server_port": 0, + "devices": [] +} +``` + +!!! info "与官方 USB/IP 协议的区别" + + sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。 + +### 拨号字段 + +参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。 + +仅 `detour` 生效。 + +### 字段 + +#### server + +==必填== + +远程 `usbip-server` 地址。 + +#### server_port + +远程 `usbip-server` 端口。默认为 `3240`。 + +#### devices + +设备匹配列表，用于选择要导入的远程设备。如果为空，则导入所有已导出的设备。 + +对象格式： + +```json +{ + "bus_id": "", + "vendor_id": 0, + "product_id": 0, + "serial": "" +} +``` + +对象字段： + +- `bus_id`：USB 总线 ID，例如 `1-2`。 +- `vendor_id`：USB 供应商 ID，为数字。 +- `product_id`：USB 产品 ID，为数字。 +- `serial`：设备序列号。 + +在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。 diff --git a/docs/configuration/service/usbip-server.md b/docs/configuration/service/usbip-server.md new file mode 100644 index 000000000..6f9722027 --- /dev/null +++ b/docs/configuration/service/usbip-server.md @@ -0,0 +1,83 @@ +--- +icon: material/new-box +--- + +!!! question "Since sing-box 1.14.0" + +# USB/IP Server + +USB/IP Server service exports local USB devices over [USB/IP](https://usbip.sourceforge.net/), +to be imported by the [USB/IP Client](/configuration/service/usbip-client/) or a standard USB/IP +client. + +Available on Linux, Windows, and macOS (macOS requires a build with CGO, and exporting devices +requires disabling System Integrity Protection). Not available on iOS. + +### Structure + +```json +{ + "type": "usbip-server", + + ... // Listen Fields + + "provider": "", + "devices": [] +} +``` + +!!! 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. + +`listen_port` defaults to `3240`. + +### Fields + +#### provider + +The device source provider. + +- `default`: Exports the local devices matched by `devices`. The default value. +- `dynamic`: Devices are provided at runtime through a [sing-box API](/configuration/service/api/) + client instead of from configuration, on supported platforms: the sing-box graphical clients on + [macOS](/clients/apple/) and [Android](/clients/android/), and Chromium-based browsers with + [sing-box Dashboard](https://github.com/SagerNet/sing-box-dashboard). + +!!! quote "" + + The `default` provider is only supported when running directly via the CLI on Linux, Windows, + and macOS, and requires elevated privileges. + +#### devices + +==Required== with the `default` provider. + +List of device matches selecting which local USB devices to export. + +Object format: + +```json +{ + "bus_id": "", + "vendor_id": 0, + "product_id": 0, + "serial": "" +} +``` + +Object fields: + +- `bus_id`: USB bus ID, e.g. `1-2`. +- `vendor_id`: USB vendor ID, as a number. +- `product_id`: USB product ID, as a number. +- `serial`: Device serial number. + +Within one object, all specified fields must match; multiple objects are combined as a union. At +least one field is required. diff --git a/docs/configuration/service/usbip-server.zh.md b/docs/configuration/service/usbip-server.zh.md new file mode 100644 index 000000000..52e5bbb78 --- /dev/null +++ b/docs/configuration/service/usbip-server.zh.md @@ -0,0 +1,73 @@ +--- +icon: material/new-box +--- + +!!! question "自 sing-box 1.14.0 起" + +# USB/IP Server + +USB/IP Server 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导出本地 USB 设备，供 [USB/IP Client](/zh/configuration/service/usbip-client/) 或标准 USB/IP 客户端导入。 + +可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建，且导出设备需要禁用系统完整性保护）。不支持 iOS。 + +### 结构 + +```json +{ + "type": "usbip-server", + + ... // 监听字段 + + "provider": "", + "devices": [] +} +``` + +!!! info "与官方 USB/IP 协议的区别" + + sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。 + +### 监听字段 + +参阅 [监听字段](/zh/configuration/shared/listen/) 了解详情。 + +`listen_port` 默认为 `3240`。 + +### 字段 + +#### provider + +设备来源提供者。 + +- `default`：导出由 `devices` 匹配的本地设备。默认值。 +- `dynamic`：设备在运行时通过 [sing-box API](/zh/configuration/service/api/) 客户端提供，而非来自配置文件，支持的平台包括 [macOS](/zh/clients/apple/) 和 [Android](/zh/clients/android/) 上的 sing-box 图形客户端，以及配合 [sing-box Dashboard](https://github.com/SagerNet/sing-box-dashboard) 的基于 Chromium 的浏览器。 + +!!! quote "" + + `default` 提供者仅支持通过 CLI 直接运行在 Linux、Windows 和 macOS 上，并且需要提升的权限。 + +#### devices + +使用 `default` 提供者时 ==必填==。 + +设备匹配列表，用于选择要导出的本地 USB 设备。 + +对象格式： + +```json +{ + "bus_id": "", + "vendor_id": 0, + "product_id": 0, + "serial": "" +} +``` + +对象字段： + +- `bus_id`：USB 总线 ID，例如 `1-2`。 +- `vendor_id`：USB 供应商 ID，为数字。 +- `product_id`：USB 产品 ID，为数字。 +- `serial`：设备序列号。 + +在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。 diff --git a/docs/configuration/shared/tls.md b/docs/configuration/shared/tls.md index 70e3b5c4f..5929962c4 100644 --- a/docs/configuration/shared/tls.md +++ b/docs/configuration/shared/tls.md @@ -678,7 +678,11 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls. !!! question "Since sing-box 1.14.0" -==Client only, Linux/macOS/Windows only, requires elevated privileges== +==Client only== + +!!! quote "" + + Only supported on Linux, macOS, and Windows, and requires elevated privileges. Inject a forged TLS ClientHello carrying a whitelisted SNI before the real one, to fool SNI-filtering middleboxes that permit specific hostnames. diff --git a/docs/configuration/shared/tls.zh.md b/docs/configuration/shared/tls.zh.md index 40762c4f7..e6ded13a8 100644 --- a/docs/configuration/shared/tls.zh.md +++ b/docs/configuration/shared/tls.zh.md @@ -673,7 +673,11 @@ ECH 配置路径，PEM 格式。 !!! question "自 sing-box 1.14.0 起" -==仅客户端，仅 Linux/macOS/Windows，需要提权== +==仅客户端== + +!!! quote "" + + 仅支持 Linux、macOS 和 Windows，需要提升的权限。 在真实 ClientHello 之前注入一个伪造的、携带白名单 SNI 的 TLS ClientHello， 以欺骗基于 SNI 过滤的中间盒放行连接。 diff --git a/mkdocs.yml b/mkdocs.yml index 0e7c84378..7a2fc012e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -194,6 +194,8 @@ nav: - CCM: configuration/service/ccm.md - OCM: configuration/service/ocm.md - Hysteria Realm: configuration/service/hysteria-realm.md + - USB/IP Server: configuration/service/usbip-server.md + - USB/IP Client: configuration/service/usbip-client.md markdown_extensions: - toc: slugify: !!python/object/apply:pymdownx.slugs.slugify diff --git a/option/usbip.go b/option/usbip.go index cdfcb107d..32136e9e7 100644 --- a/option/usbip.go +++ b/option/usbip.go @@ -51,7 +51,7 @@ func (o *USBIPServerServiceOptions) UnmarshalJSON(content []byte) error { type USBIPClientServiceOptions struct { DialerOptions - Server string `json:"server,omitempty"` + ServerOptions Devices []USBIPDeviceMatch `json:"devices,omitempty"` } diff --git a/service/usbip/client.go b/service/usbip/client.go index 049573ca7..ae49165ec 100644 --- a/service/usbip/client.go +++ b/service/usbip/client.go @@ -13,7 +13,6 @@ import ( "github.com/sagernet/sing-box/option" "github.com/sagernet/sing-usbip" E "github.com/sagernet/sing/common/exceptions" - M "github.com/sagernet/sing/common/metadata" ) type ClientService struct { @@ -37,7 +36,7 @@ func NewClientService(ctx context.Context, logger log.ContextLogger, tag string, inner, err := usbip.NewClientService(ctx, usbip.ClientOptions{ Logger: logger, Dialer: serviceDialer, - ServerAddress: M.ParseSocksaddr(options.Server), + ServerAddress: options.ServerOptions.Build(), Devices: toDeviceMatches(options.Devices), }) if err != nil {