Skip to content

Commit 03572bc

Browse files
nekohasekainekohasekai
committed
documentation: Add USB/IP server and client
1 parent a9fe3f3 commit 03572bc

15 files changed

Lines changed: 337 additions & 7 deletions

File tree

‎docs/configuration/route/rule_action.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,9 @@ Fragment TLS handshake into multiple TLS records to bypass firewalls.
256256

257257
!!! question "Since sing-box 1.14.0"
258258

259-
==Linux/macOS/Windows only, requires elevated privileges==
259+
!!! quote ""
260+
261+
Only supported on Linux, macOS, and Windows, and requires elevated privileges.
260262

261263
Inject a forged TLS ClientHello carrying this SNI before the real one,
262264
to fool SNI-filtering middleboxes that permit specific hostnames.

‎docs/configuration/route/rule_action.zh.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -248,7 +248,9 @@ UDP 连接超时时间。
248248

249249
!!! question "自 sing-box 1.14.0 起"
250250

251-
==仅 Linux/macOS/Windows，需要管理员权限==
251+
!!! quote ""
252+
253+
仅支持 Linux、macOS 和 Windows，需要提升的权限。
252254

253255
在真实 ClientHello 之前注入携带本字段所指定 SNI 的伪造 TLS ClientHello，
254256
用于欺骗仅放行特定主机名的 SNI 过滤中间盒。

‎docs/configuration/service/api.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ icon: material/new-box
88

99
The sing-box API service is a gRPC server for observing and controlling the running sing-box instance.
1010

11+
It can be accessed by the [sing-box graphical clients](/clients/) for iOS, macOS, and
12+
Android (via the Remote Control feature), or the
13+
[sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard).
14+
1115
The server also accepts [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) requests,
1216
including the WebSocket transport of [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web)
1317
for bidirectional streaming methods.

‎docs/configuration/service/api.zh.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ icon: material/new-box
88

99
sing-box API 服务是用于观察与控制正在运行的 sing-box 实例的 gRPC 服务器。
1010

11+
它可以由 iOS、macOS 和 Android 上的 [sing-box 图形客户端](/zh/clients/)（通过 Remote Control 功能）或 [sing-box dashboard](https://github.com/SagerNet/sing-box-dashboard) 访问。
12+
1113
服务器同时接受 [gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md) 请求,
1214
包括用于双向流方法的 [@improbable-eng/grpc-web](https://github.com/improbable-eng/grpc-web) WebSocket 传输。
1315

‎docs/configuration/service/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ icon: material/new-box
3030
| `ocm` | [OCM](./ocm) |
3131
| `resolved` | [Resolved](./resolved) |
3232
| `ssm-api` | [SSM API](./ssm-api) |
33+
| `usbip-server` | [USB/IP Server](./usbip-server) |
34+
| `usbip-client` | [USB/IP Client](./usbip-client) |
3335

3436
#### tag
3537

‎docs/configuration/service/index.zh.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@ icon: material/new-box
3030
| `ocm` | [OCM](./ocm) |
3131
| `resolved` | [Resolved](./resolved) |
3232
| `ssm-api` | [SSM API](./ssm-api) |
33+
| `usbip-server` | [USB/IP Server](./usbip-server) |
34+
| `usbip-client` | [USB/IP Client](./usbip-client) |
3335

3436
#### tag
3537

‎docs/configuration/service/usbip-client.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
icon: material/new-box
3+
---
4+
5+
!!! question "Since sing-box 1.14.0"
6+
7+
# USB/IP Client
8+
9+
USB/IP Client service imports remote USB devices over [USB/IP](https://usbip.sourceforge.net/),
10+
exported by the [USB/IP Server](/configuration/service/usbip-server/).
11+
12+
Available on Linux, Windows, and macOS (macOS requires a build with CGO). Not available on iOS.
13+
14+
The server must be a sing-box (or sing-usbip) server.
15+
16+
### Structure
17+
18+
```json
19+
{
20+
"type": "usbip-client",
21+
22+
... // Dial Fields
23+
24+
"server": "",
25+
"server_port": 0,
26+
"devices": []
27+
}
28+
```
29+
30+
!!! info "Difference from the official USB/IP protocol"
31+
32+
sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional
33+
set of protocols to support enhancements such as hotplug, while remaining interoperable with
34+
the standard USB/IP protocol.
35+
36+
### Dial Fields
37+
38+
See [Dial Fields](/configuration/shared/dial/) for details.
39+
40+
Only `detour` takes effect.
41+
42+
### Fields
43+
44+
#### server
45+
46+
==Required==
47+
48+
The remote `usbip-server` address.
49+
50+
#### server_port
51+
52+
The remote `usbip-server` port. Defaults to `3240`.
53+
54+
#### devices
55+
56+
List of device matches selecting which remote devices to import. If empty, all exported devices
57+
are imported.
58+
59+
Object format:
60+
61+
```json
62+
{
63+
"bus_id": "",
64+
"vendor_id": 0,
65+
"product_id": 0,
66+
"serial": ""
67+
}
68+
```
69+
70+
Object fields:
71+
72+
- `bus_id`: USB bus ID, e.g. `1-2`.
73+
- `vendor_id`: USB vendor ID, as a number.
74+
- `product_id`: USB product ID, as a number.
75+
- `serial`: Device serial number.
76+
77+
Within one object, all specified fields must match; multiple objects are combined as a union. At
78+
least one field is required.

‎docs/configuration/service/usbip-client.zh.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
icon: material/new-box
3+
---
4+
5+
!!! question "自 sing-box 1.14.0 起"
6+
7+
# USB/IP Client
8+
9+
USB/IP Client 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导入由 [USB/IP Server](/zh/configuration/service/usbip-server/) 导出的远程 USB 设备。
10+
11+
可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建）。不支持 iOS。
12+
13+
服务端必须是 sing-box（或 sing-usbip）服务端。
14+
15+
### 结构
16+
17+
```json
18+
{
19+
"type": "usbip-client",
20+
21+
... // 拨号字段
22+
23+
"server": "",
24+
"server_port": 0,
25+
"devices": []
26+
}
27+
```
28+
29+
!!! info "与官方 USB/IP 协议的区别"
30+
31+
sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。
32+
33+
### 拨号字段
34+
35+
参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。
36+
37+
仅 `detour` 生效。
38+
39+
### 字段
40+
41+
#### server
42+
43+
==必填==
44+
45+
远程 `usbip-server` 地址。
46+
47+
#### server_port
48+
49+
远程 `usbip-server` 端口。默认为 `3240`。
50+
51+
#### devices
52+
53+
设备匹配列表，用于选择要导入的远程设备。如果为空，则导入所有已导出的设备。
54+
55+
对象格式：
56+
57+
```json
58+
{
59+
"bus_id": "",
60+
"vendor_id": 0,
61+
"product_id": 0,
62+
"serial": ""
63+
}
64+
```
65+
66+
对象字段：
67+
68+
- `bus_id`：USB 总线 ID，例如 `1-2`。
69+
- `vendor_id`：USB 供应商 ID，为数字。
70+
- `product_id`：USB 产品 ID，为数字。
71+
- `serial`：设备序列号。
72+
73+
在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。

‎docs/configuration/service/usbip-server.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
icon: material/new-box
3+
---
4+
5+
!!! question "Since sing-box 1.14.0"
6+
7+
# USB/IP Server
8+
9+
USB/IP Server service exports local USB devices over [USB/IP](https://usbip.sourceforge.net/),
10+
to be imported by the [USB/IP Client](/configuration/service/usbip-client/) or a standard USB/IP
11+
client.
12+
13+
Available on Linux, Windows, and macOS (macOS requires a build with CGO, and exporting devices
14+
requires disabling System Integrity Protection). Not available on iOS.
15+
16+
### Structure
17+
18+
```json
19+
{
20+
"type": "usbip-server",
21+
22+
... // Listen Fields
23+
24+
"provider": "",
25+
"devices": []
26+
}
27+
```
28+
29+
!!! info "Difference from the official USB/IP protocol"
30+
31+
sing-box uses [sing-usbip](https://github.com/SagerNet/sing-usbip), which uses an additional
32+
set of protocols to support enhancements such as hotplug, while remaining interoperable with
33+
the standard USB/IP protocol.
34+
35+
### Listen Fields
36+
37+
See [Listen Fields](/configuration/shared/listen/) for details.
38+
39+
`listen_port` defaults to `3240`.
40+
41+
### Fields
42+
43+
#### provider
44+
45+
The device source provider.
46+
47+
- `default`: Exports the local devices matched by `devices`. The default value.
48+
- `dynamic`: Devices are provided at runtime through a [sing-box API](/configuration/service/api/)
49+
client instead of from configuration, on supported platforms: the sing-box graphical clients on
50+
[macOS](/clients/apple/) and [Android](/clients/android/), and Chromium-based browsers with
51+
[sing-box Dashboard](https://github.com/SagerNet/sing-box-dashboard).
52+
53+
!!! quote ""
54+
55+
The `default` provider is only supported when running directly via the CLI on Linux, Windows,
56+
and macOS, and requires elevated privileges.
57+
58+
#### devices
59+
60+
==Required== with the `default` provider.
61+
62+
List of device matches selecting which local USB devices to export.
63+
64+
Object format:
65+
66+
```json
67+
{
68+
"bus_id": "",
69+
"vendor_id": 0,
70+
"product_id": 0,
71+
"serial": ""
72+
}
73+
```
74+
75+
Object fields:
76+
77+
- `bus_id`: USB bus ID, e.g. `1-2`.
78+
- `vendor_id`: USB vendor ID, as a number.
79+
- `product_id`: USB product ID, as a number.
80+
- `serial`: Device serial number.
81+
82+
Within one object, all specified fields must match; multiple objects are combined as a union. At
83+
least one field is required.

‎docs/configuration/service/usbip-server.zh.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
icon: material/new-box
3+
---
4+
5+
!!! question "自 sing-box 1.14.0 起"
6+
7+
# USB/IP Server
8+
9+
USB/IP Server 服务通过 [USB/IP](https://usbip.sourceforge.net/) 导出本地 USB 设备，供 [USB/IP Client](/zh/configuration/service/usbip-client/) 或标准 USB/IP 客户端导入。
10+
11+
可用于 Linux、Windows 和 macOS（macOS 需要使用 CGO 构建，且导出设备需要禁用系统完整性保护）。不支持 iOS。
12+
13+
### 结构
14+
15+
```json
16+
{
17+
"type": "usbip-server",
18+
19+
... // 监听字段
20+
21+
"provider": "",
22+
"devices": []
23+
}
24+
```
25+
26+
!!! info "与官方 USB/IP 协议的区别"
27+
28+
sing-box 使用 [sing-usbip](https://github.com/SagerNet/sing-usbip)，它使用一套附加协议来支持热插拔等增强功能，但仍然可以与标准 USB/IP 互操作。
29+
30+
### 监听字段
31+
32+
参阅 [监听字段](/zh/configuration/shared/listen/) 了解详情。
33+
34+
`listen_port` 默认为 `3240`。
35+
36+
### 字段
37+
38+
#### provider
39+
40+
设备来源提供者。
41+
42+
- `default`：导出由 `devices` 匹配的本地设备。默认值。
43+
- `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 的浏览器。
44+
45+
!!! quote ""
46+
47+
`default` 提供者仅支持通过 CLI 直接运行在 Linux、Windows 和 macOS 上，并且需要提升的权限。
48+
49+
#### devices
50+
51+
使用 `default` 提供者时 ==必填==。
52+
53+
设备匹配列表，用于选择要导出的本地 USB 设备。
54+
55+
对象格式：
56+
57+
```json
58+
{
59+
"bus_id": "",
60+
"vendor_id": 0,
61+
"product_id": 0,
62+
"serial": ""
63+
}
64+
```
65+
66+
对象字段：
67+
68+
- `bus_id`：USB 总线 ID，例如 `1-2`。
69+
- `vendor_id`：USB 供应商 ID，为数字。
70+
- `product_id`：USB 产品 ID，为数字。
71+
- `serial`：设备序列号。
72+
73+
在一个对象内，所有指定的字段都必须匹配；多个对象之间取并集。至少需要一个字段。

0 commit comments

Comments
 (0)