hesoyam/sing-box-extended-mirror
1
0
Fork 0
mirror of https://github.com/shtorm-7/sing-box-extended.git synced 2026-10-15 02:23:59 +00:00
Code Issues Packages Projects Releases 2 Wiki Activity

Merge tag 'v1.14.0'

Browse Source
This commit is contained in:
Shtorm
2026-09-04 01:08:30 +03:00
parent 99bbd49406 0b8995879f
commit c0bfc731ec
987 changed files with 141481 additions and 11302 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/assets/icon.svg
+77 -33
View File
@@ -1,37 +1,81 @@
<svg width="1027" height="1109" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" overflow="hidden">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="148 90 728 820">
<defs>
<filter id="fx0" x="-10%" y="-10%" width="120%" height="120%" filterUnits="userSpaceOnUse" primitiveUnits="userSpaceOnUse">
<feComponentTransfer color-interpolation-filters="sRGB">
<feFuncR type="discrete" tableValues="0 0" />
<feFuncG type="discrete" tableValues="0 0" />
<feFuncB type="discrete" tableValues="0 0" />
<feFuncA type="linear" slope="0.4" intercept="0" />
</feComponentTransfer>
<feGaussianBlur stdDeviation="4.58333 4.58333" />
<linearGradient id="bg25" x1="0" y1="0" x2="0" y2="1">
<stop offset="0" stop-color="#242F37"/>
<stop offset="1" stop-color="#0D1317"/>
</linearGradient>
<radialGradient id="spot25" cx="0.5" cy="0.5" r="0.5">
<stop offset="0" stop-color="#46565F" stop-opacity="0.45"/>
<stop offset="1" stop-color="#46565F" stop-opacity="0"/>
</radialGradient>
<filter id="soft25" x="-40%" y="-40%" width="180%" height="180%">
<feGaussianBlur stdDeviation="18"/>
</filter>
<clipPath id="clip1">
<rect x="692" y="855" width="1027" height="1109" />
</clipPath>
<clipPath id="clip2">
<rect x="-2" y="-2" width="541" height="786" />
</clipPath>
<clipPath id="clip3">
<rect x="0" y="0" width="535" height="782" />
</clipPath>
<linearGradient id="top25" gradientUnits="userSpaceOnUse" x1="330" y1="320" x2="700" y2="490">
<stop offset="0" stop-color="#445863"/>
<stop offset="1" stop-color="#394C57"/>
</linearGradient>
<linearGradient id="left25" gradientUnits="userSpaceOnUse" x1="269.5" y1="480" x2="512" y2="720">
<stop offset="0" stop-color="#26323A"/>
<stop offset="1" stop-color="#1F2A31"/>
</linearGradient>
<linearGradient id="right25" gradientUnits="userSpaceOnUse" x1="512" y1="650" x2="754.5" y2="500">
<stop offset="0" stop-color="#30404A"/>
<stop offset="1" stop-color="#374854"/>
</linearGradient>
<filter id="grain25" x="0" y="0" width="280" height="280" filterUnits="userSpaceOnUse">
<feTurbulence type="fractalNoise" baseFrequency="0.22" numOctaves="4" seed="17" result="n"/>
<feColorMatrix in="n" type="matrix" values="0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0.45 0 0 0 -0.1"/>
</filter>
<filter id="grainD25" x="0" y="0" width="280" height="280" filterUnits="userSpaceOnUse">
<feTurbulence type="fractalNoise" baseFrequency="0.28" numOctaves="4" seed="41" result="n"/>
<feColorMatrix in="n" type="matrix" values="0 0 0 0 0.02 0 0 0 0 0.05 0 0 0 0 0.07 0.45 0 0 0 -0.1"/>
</filter>
<clipPath id="clipTopD"><path d="M512 262 754.5 402 512 542 269.5 402Z"/></clipPath>
<clipPath id="clipLeftD"><path d="M269.5 402 512 542 512 812 269.5 672Z"/></clipPath>
<clipPath id="clipRightD"><path d="M512 542 754.5 402 754.5 672 512 812Z"/></clipPath>
</defs>
<g clip-path="url(#clip1)" transform="translate(-692 -855)">
<path d="M692 1191 692 1575.69C692 1640.41 731.499 1651.19 731.499 1651.19L1148.03 1931.62C1212.66 1974.77 1194.71 1881.29 1194.71 1881.29L1194.71 1528.96 692 1191Z" fill="#37474F" fill-rule="evenodd" />
<g clip-path="url(#clip2)" filter="url(#fx0)" transform="translate(1184 1182)">
<g clip-path="url(#clip3)">
<path d="M520.482 15.4819 520.482 400.176C520.482 464.89 480.983 475.676 480.983 475.676 480.983 475.676 129.086 712.963 64.4523 756.106-0.181814 799.25 17.7721 705.773 17.7721 705.773L17.7721 353.437 520.482 15.4819Z" fill="#455A64" fill-rule="evenodd" />
</g>
</g>
<path d="M1698 1191 1698 1575.69C1698 1640.41 1658.5 1651.19 1658.5 1651.19 1658.5 1651.19 1306.6 1888.48 1241.97 1931.62 1177.34 1974.77 1195.29 1881.29 1195.29 1881.29L1195.29 1528.96 1698 1191Z" fill="#455A64" fill-rule="evenodd" />
<path d="M1241.71 868.473C1212.96 850.509 1169.85 850.509 1144.7 868.473L713.557 1163.07C684.814 1181.04 684.814 1213.37 713.557 1231.33L1144.7 1529.53C1173.44 1547.49 1216.56 1547.49 1241.71 1529.53L1676.44 1227.74C1705.19 1209.78 1705.19 1177.44 1676.44 1159.48L1241.71 868.473Z" fill="#546E7A" fill-rule="evenodd" />
<path d="M1195 1949C1173.4 1949 1159 1935.19 1159 1917.92L1159 1531.08C1159 1513.82 1173.4 1500 1195 1500 1216.6 1500 1231 1513.82 1231 1531.08L1231 1914.46C1231 1935.19 1216.6 1949 1195 1949Z" fill="#546E7A" fill-rule="evenodd" />
<path d="M1553.92 1435.92C1553.92 1471.89 1557.5 1486.27 1518.03 1511.45L1428.32 1568.99C1388.85 1594.17 1374.5 1572.59 1374.5 1540.22L1374.5 1446.71C1374.5 1439.52 1374.5 1435.92 1363.73 1428.73 1270.43 1363.99 911.591 1115.84 847 1069.09L1012.07 954C1058.72 982.772 1399.61 1209.35 1539.56 1306.45 1546.74 1310.05 1550.33 1317.24 1550.33 1320.84L1550.33 1435.92Z" fill="#99AAB5" fill-rule="evenodd" />
<path d="M1543.41 1310.21C1399.82 1213.17 1058.79 986.752 1015.72 958L951.103 997.534 847 1069.41C911.615 1116.14 1270.59 1360.53 1363.92 1425.22 1371.1 1428.81 1371.1 1432.41 1371.1 1436L1547 1313.8C1547 1313.8 1547 1310.21 1543.41 1310.21Z" fill="#CCD6DD" fill-rule="evenodd" />
<path d="M1554.9 1435.48 1554.9 1324.19C1554.9 1317.01 1551.3 1313.42 1544.11 1309.83 1400.28 1212.89 1058.67 986.721 1015.51 958L940 1008.26C1062.26 1090.83 1389.49 1306.24 1475.79 1367.27 1486.58 1374.45 1486.58 1381.63 1486.58 1385.22L1486.58 1536 1522.54 1510.87C1558.5 1485.74 1554.9 1467.79 1554.9 1435.48Z" fill="#CCD6DD" fill-rule="evenodd" />
<path d="M1543.23 1309.95C1399.6 1212.98 1058.49 986.731 1015.4 958L940 1008.28C1062.08 1090.88 1388.83 1306.36 1475.01 1367.41 1475.01 1367.41 1478.6 1371 1478.6 1371L1554 1317.13C1546.82 1313.54 1546.82 1309.95 1543.23 1309.95Z" fill="#E1E8ED" fill-rule="evenodd" />
<g transform="translate(-225.28 -273.28) scale(1.44)">
<!-- deep cardboard faces -->
<path d="M512 262 754.5 402 512 542 269.5 402Z" fill="url(#top25)"/>
<path d="M269.5 402 512 542 512 812 269.5 672Z" fill="url(#left25)"/>
<path d="M512 542 754.5 402 754.5 672 512 812Z" fill="url(#right25)"/>
<!-- paper grain, foreshortened per face -->
<g clip-path="url(#clipTopD)"><g transform="matrix(0.866 0.5 0.866 -0.5 269.5 402)">
<rect width="280" height="280" filter="url(#grain25)" opacity="0.30"/>
<rect width="280" height="280" filter="url(#grainD25)" opacity="0.38"/>
</g></g>
<g clip-path="url(#clipLeftD)"><g transform="matrix(0.866 0.5 0 0.96428 269.5 402)">
<rect width="280" height="280" filter="url(#grain25)" opacity="0.20"/>
<rect width="280" height="280" filter="url(#grainD25)" opacity="0.34"/>
</g></g>
<g clip-path="url(#clipRightD)"><g transform="matrix(0.866 -0.5 0 0.96428 512 542)">
<rect width="280" height="280" filter="url(#grain25)" opacity="0.25"/>
<rect width="280" height="280" filter="url(#grainD25)" opacity="0.34"/>
</g></g>
<!-- lid flap seam: two lid halves, paper-edge catchlight -->
<path d="M390.75 472 633.25 332" stroke="#141E24" stroke-width="4" fill="none" opacity="0.9"/>
<path d="M390.75 472 633.25 332" stroke="#6E8794" stroke-width="2" fill="none" opacity="0.7" transform="translate(0 -3)"/>
<!-- soft ambient occlusion at junctions -->
<path d="M269.5 402 512 542" stroke="#0B141A" stroke-width="10" opacity="0.28" filter="url(#soft25)" fill="none"/>
<path d="M512 542 754.5 402" stroke="#0B141A" stroke-width="10" opacity="0.22" filter="url(#soft25)" fill="none"/>
<path d="M512 542 512 812" stroke="#060D11" stroke-width="9" opacity="0.30" filter="url(#soft25)" fill="none"/>
<!-- paper-edge highlights on the top edges -->
<path d="M512 262 754.5 402" stroke="#66808D" stroke-width="2.5" fill="none"/>
<path d="M512 262 269.5 402" stroke="#5A737F" stroke-width="2.5" fill="none"/>
<path d="M269.5 402 512 542 754.5 402" stroke="#4E6773" stroke-width="2" fill="none" opacity="0.9"/>
<path d="M512 542 512 812" stroke="#445963" stroke-width="2" fill="none" opacity="0.9"/>
<!-- original two-tone tape, aligned tails -->
<path d="M356.8 351.6 390.75 332 633.25 472 599.3 491.6Z" fill="#99AAB5"/>
<path d="M390.75 332 424.7 312.4 667.2 452.4 633.25 472Z" fill="#E1E8ED"/>
<path d="M599.3 491.6 633.25 472 633.25 592 599.3 611.6Z" fill="#8296A1"/>
<path d="M633.25 472 667.2 452.4 667.2 572.4 633.25 592Z" fill="#CCD6DD"/>
<!-- tape soft shadow onto the paper -->
<path d="M360 358 602.5 498" stroke="#000000" opacity="0.25" stroke-width="7" filter="url(#soft25)" fill="none"/>
</g>
</svg>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.7 KiB

After

Width:  |  Height:  |  Size: 4.7 KiB

docs/changelog.md
+1364 -7
View File
File diff suppressed because it is too large Load Diff
docs/clients/android/features.md
+1
View File
@@ -42,6 +42,7 @@ SFA provides an unprivileged TUN implementation through Android VpnService.
| `process_path` | :material-close: | No permission |
| `process_path_regex` | :material-close: | No permission |
| `package_name` | :material-check: | / |
| `package_name_regex` | :material-check: | / |
| `user` | :material-close: | Use `package_name` instead |
| `user_id` | :material-close: | Use `package_name` instead |
| `wifi_ssid` | :material-check: | Fine location permission required |
docs/clients/apple/features.md
+6 -5
View File
@@ -40,12 +40,13 @@ SFI/SFM/SFT provides an unprivileged TUN implementation through NetworkExtension
| Route/DNS rule option | Available | Note |
|-----------------------|------------------|-----------------------|
| `process_name` | :material-close: | No permission |
| `process_path` | :material-close: | No permission |
| `process_path_regex` | :material-close: | No permission |
| `process_name` | :material-alert: | Only supported in the macOS standalone and iOS jailbreak versions |
| `process_path` | :material-alert: | Only supported in the macOS standalone and iOS jailbreak versions |
| `process_path_regex` | :material-alert: | Only supported in the macOS standalone and iOS jailbreak versions |
| `package_name` | :material-close: | / |
| `user` | :material-close: | No permission |
| `user_id` | :material-close: | No permission |
| `package_name_regex` | :material-close: | / |
| `user` | :material-alert: | Only supported in the macOS standalone and iOS jailbreak versions |
| `user_id` | :material-alert: | Only supported in the macOS standalone and iOS jailbreak versions |
| `wifi_ssid` | :material-alert: | Only supported on iOS |
| `wifi_bssid` | :material-alert: | Only supported on iOS |
docs/clients/apple/index.md
+15 -4
View File
@@ -9,7 +9,7 @@ platform-specific function implementation, such as TUN transparent proxy impleme
!!! failure ""
Due to non-technical reasons, we are temporarily unable to update the sing-box app on the App Store and release the standalone version of the macOS client (TestFlight users are not affected)
We are temporarily unable to update sing-box apps on the App Store because the reviewer mistakenly found that we violated the rules (TestFlight users are not affected).
## :material-graph: Requirements
@@ -26,15 +26,26 @@ TestFlight quota is only available to [sponsors](https://github.com/sponsors/nek
Once you donate, you can get an invitation by join our Telegram group for sponsors from [@yet_another_sponsor_bot](https://t.me/yet_another_sponsor_bot)
or sending us your Apple ID [via email](mailto:contact@sagernet.org).
## ~~:material-file-download: Download (macOS standalone version)~~
## :material-cellphone-arrow-down: Download (iOS jailbreak version)
* ~~[Homebrew Cask](https://formulae.brew.sh/cask/sfm)~~
* [GitHub Releases](https://github.com/SagerNet/sing-box/releases) (`SFI-iphoneos-arm64.deb`)
The jailbroken version of SFI: requires rootless iOS 15.0+
Additional features:
* It can run a [Tailscale SSH server](/configuration/endpoint/tailscale/#ssh_server) on the device.
* [Process matching](/configuration/route/rule/#process_name) (`process_name`, `process_path`, `user`, and so on) works in route and DNS rules.
## :material-file-download: Download (macOS standalone version)
* [Homebrew Cask](https://formulae.brew.sh/cask/sfm)
```bash
# brew install sfm
```
* ~~[GitHub Releases](https://github.com/SagerNet/sing-box/releases)~~
* [GitHub Releases](https://github.com/SagerNet/sing-box/releases)
## :material-source-repository: Source code
docs/clients/desktop/features.md
+9
View File
@@ -0,0 +1,9 @@
# :material-decagram: Features
#### Service
SFW runs sing-box as a system service, so no administrator elevation is required for daily use.
### Chore
* The working directory is located at `C:\ProgramData\sing-box-daemon`
docs/clients/desktop/index.md
+21
View File
@@ -0,0 +1,21 @@
---
icon: material/laptop
---
# sing-box for Desktop
sing-box for Desktop allows users to manage and run local or remote sing-box configuration files,
and provides platform-specific functionality, such as TUN transparent proxying.
## :material-graph: Requirements
* Windows 10+ (x64 / x86 / arm64)
* Linux (x64 / arm64 / armv7l)
## :material-download: Download
* [GitHub Releases](https://github.com/SagerNet/sing-box/releases)
## :material-source-repository: Source code
* [GitHub](https://github.com/SagerNet/sing-box-for-desktop)
docs/clients/index.md
+2 -1
View File
@@ -6,7 +6,8 @@ Maintained by Project S to provide a unified experience and platform-specific fu
|---------------------------------------|------------------------------------------|
| :material-android: Android | [sing-box for Android](./android/) |
| :material-apple: iOS/macOS/Apple tvOS | [sing-box for Apple platforms](./apple/) |
| :material-laptop: Desktop | Working in progress |
| :material-microsoft-windows: Windows | [sing-box for Desktop](./desktop/) |
| :material-linux: Linux | [sing-box for Desktop](./desktop/) |
Some third-party projects that claim to use sing-box or use sing-box as a selling point are not listed here. The core
motivation of the maintainers of such projects is to acquire more users, and even though they provide friendly VPN
docs/clients/index.zh.md
+2 -1
View File
@@ -6,7 +6,8 @@
|---------------------------------------|------------------------------------------|
| :material-android: Android | [sing-box for Android](./android/) |
| :material-apple: iOS/macOS/Apple tvOS | [sing-box for Apple platforms](./apple/) |
| :material-laptop: Desktop | 施工中 |
| :material-microsoft-windows: Windows | [sing-box for Desktop](./desktop/) |
| :material-linux: Linux | [sing-box for Desktop](./desktop/) |
此处没有列出一些声称使用或以 sing-box 为卖点的第三方项目。此类项目维护者的动机是获得更多用户，即使它们提供友好的商业
VPN 客户端功能， 但代码质量很差且包含广告。
docs/configuration/dns/fakeip.md
+4 -4
View File
@@ -1,10 +1,10 @@
---
icon: material/delete-clock
icon: material/note-remove
---
!!! failure "Deprecated in sing-box 1.12.0"
!!! failure "Removed in sing-box 1.14.0"
Legacy fake-ip configuration is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-servers).
Legacy fake-ip configuration is deprecated in sing-box 1.12.0 and removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-server-formats).
### Structure
@@ -26,6 +26,6 @@ Enable FakeIP service.
IPv4 address range for FakeIP.
#### inet6_address
#### inet6_range
IPv6 address range for FakeIP.
docs/configuration/dns/fakeip.zh.md
+3 -3
View File
@@ -1,10 +1,10 @@
---
icon: material/delete-clock
icon: material/note-remove
---
!!! failure "已在 sing-box 1.12.0 废弃"
!!! failure "已在 sing-box 1.14.0 移除"
旧的 fake-ip 配置已废弃且将在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/zh/migration/#迁移到新的-dns-服务器格式)。
旧的 fake-ip 配置已在 sing-box 1.12.0 废弃且已在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/zh/migration/#迁移到新的-dns-服务器格式)。
### 结构
docs/configuration/dns/index.md
+56 -2
View File
@@ -2,6 +2,12 @@
icon: material/alert-decagram
---
!!! quote "Changes in sing-box 1.14.0"
:material-delete-clock: [independent_cache](#independent_cache)
:material-plus: [optimistic](#optimistic)
:material-plus: [timeout](#timeout)
!!! quote "Changes in sing-box 1.12.0"
:material-decagram: [servers](#servers)
@@ -25,6 +31,8 @@ icon: material/alert-decagram
"disable_expire": false,
"independent_cache": false,
"cache_capacity": 0,
"optimistic": false, // or {}
"timeout": "",
"reverse_mapping": false,
"client_subnet": "",
"fakeip": {}
@@ -39,7 +47,7 @@ icon: material/alert-decagram
|----------|---------------------------------|
| `server` | List of [DNS Server](./server/) |
| `rules` | List of [DNS Rule](./rule/) |
| `fakeip` | [FakeIP](./fakeip/) |
| `fakeip` | :material-note-remove: [FakeIP](./fakeip/) |
#### final
@@ -57,12 +65,20 @@ One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
Disable dns cache.
Conflict with `optimistic`.
#### disable_expire
Disable dns cache expire.
Conflict with `optimistic`.
#### independent_cache
!!! failure "Deprecated in sing-box 1.14.0"
`independent_cache` is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-independent-dns-cache).
Make each DNS server's cache independent for special purposes. If enabled, will slightly degrade performance.
#### cache_capacity
@@ -73,6 +89,44 @@ LRU cache capacity.
Value less than 1024 will be ignored.
#### optimistic
!!! question "Since sing-box 1.14.0"
Enable optimistic DNS caching. When a cached DNS entry has expired but is still within the timeout window,
the stale response is returned immediately while a background refresh is triggered.
Conflict with `disable_cache` and `disable_expire`.
Accepts a boolean or an object. When set to `true`, the default timeout of `3d` is used.
```json
{
"enabled": true,
"timeout": "3d"
}
```
##### enabled
Enable optimistic DNS caching.
##### timeout
The maximum time an expired cache entry can be served optimistically.
`3d` is used by default.
#### timeout
!!! question "Since sing-box 1.14.0"
Default timeout for each DNS query.
`10s` is used by default.
Can be overridden by `rules.[].timeout` (DNS rule action) or `domain_resolver.timeout`.
#### reverse_mapping
Stores a reverse mapping of IP addresses after responding to a DNS query in order to provide domain names when routing.
@@ -88,4 +142,4 @@ Append a `edns0-subnet` OPT extra record with the specified IP prefix to every q
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
Can be overrides by `servers.[].client_subnet` or `rules.[].client_subnet`.
Can be overridden by `servers.[].client_subnet` or `rules.[].client_subnet`.
docs/configuration/dns/index.zh.md
+55 -1
View File
@@ -2,6 +2,12 @@
icon: material/alert-decagram
---
!!! quote "sing-box 1.14.0 中的更改"
:material-delete-clock: [independent_cache](#independent_cache)
:material-plus: [optimistic](#optimistic)
:material-plus: [timeout](#timeout)
!!! quote "sing-box 1.12.0 中的更改"
:material-decagram: [servers](#servers)
@@ -25,6 +31,8 @@ icon: material/alert-decagram
"disable_expire": false,
"independent_cache": false,
"cache_capacity": 0,
"optimistic": false, // or {}
"timeout": "",
"reverse_mapping": false,
"client_subnet": "",
"fakeip": {}
@@ -56,12 +64,20 @@ icon: material/alert-decagram
禁用 DNS 缓存。
与 `optimistic` 冲突。
#### disable_expire
禁用 DNS 缓存过期。
与 `optimistic` 冲突。
#### independent_cache
!!! failure "已在 sing-box 1.14.0 废弃"
`independent_cache` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除，参阅[迁移指南](/zh/migration/#迁移-independent-dns-cache)。
使每个 DNS 服务器的缓存独立，以满足特殊目的。如果启用，将轻微降低性能。
#### cache_capacity
@@ -72,6 +88,44 @@ LRU 缓存容量。
小于 1024 的值将被忽略。
#### optimistic
!!! question "自 sing-box 1.14.0 起"
启用乐观 DNS 缓存。当缓存的 DNS 条目已过期但仍在超时窗口内时，
立即返回过期的响应，同时在后台触发刷新。
与 `disable_cache` 和 `disable_expire` 冲突。
接受布尔值或对象。当设置为 `true` 时，使用默认超时 `3d`。
```json
{
"enabled": true,
"timeout": "3d"
}
```
##### enabled
启用乐观 DNS 缓存。
##### timeout
过期缓存条目可被乐观提供的最长时间。
默认使用 `3d`。
#### timeout
!!! question "自 sing-box 1.14.0 起"
每次 DNS 查询的默认超时时间。
默认使用 `10s`。
可被 `rules.[].timeout`（DNS 规则动作）或 `domain_resolver.timeout` 覆盖。
#### reverse_mapping
在响应 DNS 查询后存储 IP 地址的反向映射以为路由目的提供域名。
@@ -88,6 +142,6 @@ LRU 缓存容量。
可以被 `servers.[].client_subnet` 或 `rules.[].client_subnet` 覆盖。
#### fakeip
#### fakeip :material-note-remove:
[FakeIP](./fakeip/) 设置。
docs/configuration/dns/rule.md
+212 -15
View File
@@ -2,6 +2,23 @@
icon: material/alert-decagram
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [source_mac_address](#source_mac_address)
:material-plus: [source_hostname](#source_hostname)
:material-plus: [preferred_by](#preferred_by)
:material-plus: [match_response](#match_response)
:material-delete-clock: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)
:material-plus: [response_rcode](#response_rcode)
:material-plus: [response_answer](#response_answer)
:material-plus: [response_ns](#response_ns)
:material-plus: [response_extra](#response_extra)
:material-plus: [package_name_regex](#package_name_regex)
:material-plus: [query_client_subnet](#query_client_subnet)
:material-plus: [query_dnssec](#query_dnssec)
:material-alert: [ip_version](#ip_version)
:material-alert: [query_type](#query_type)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [interface_address](#interface_address)
@@ -62,6 +79,11 @@ icon: material/alert-decagram
"HTTPS",
32768
],
"query_client_subnet": [
"10.0.0.0/24",
"192.168.0.1"
],
"query_dnssec": false,
"network": "tcp",
"auth_user": [
"usera",
@@ -89,12 +111,6 @@ icon: material/alert-decagram
"192.168.0.1"
],
"source_ip_is_private": false,
"ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"ip_is_private": false,
"ip_accept_any": false,
"source_port": [
12345
],
@@ -124,6 +140,9 @@ icon: material/alert-decagram
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"user": [
"sekai"
],
@@ -149,6 +168,16 @@ icon: material/alert-decagram
"default_interface_address": [
"2000::/3"
],
"source_mac_address": [
"00:11:22:33:44:55"
],
"source_hostname": [
"my-device"
],
"preferred_by": [
"local",
"ts-dns"
],
"wifi_ssid": [
"My WIFI"
],
@@ -160,7 +189,17 @@ icon: material/alert-decagram
"geosite-cn"
],
"rule_set_ip_cidr_match_source": false,
"rule_set_ip_cidr_accept_empty": false,
"match_response": false,
"ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"ip_is_private": false,
"ip_accept_any": false,
"response_rcode": "",
"response_answer": [],
"response_ns": [],
"response_extra": [],
"invert": false,
"outbound": [
"direct"
@@ -169,7 +208,8 @@ icon: material/alert-decagram
"server": "local",
// Deprecated
"rule_set_ip_cidr_accept_empty": false,
"rule_set_ipcidr_match_source": false,
"geosite": [
"cn"
@@ -203,13 +243,13 @@ icon: material/alert-decagram
!!! note ""
The default rule uses the following matching logic:
(`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite`) &&
(`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `ip_cidr` || `ip_is_private` || `ip_accept_any`) &&
(`port` || `port_range`) &&
(`source_geoip` || `source_ip_cidr` ｜｜ `source_ip_is_private`) &&
(`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) &&
(`source_port` || `source_port_range`) &&
`other fields`
Additionally, each branch inside an included rule-set can be considered merged into the outer rule, while different branches keep OR semantics.
When a rule-set contains only a single default rule without `invert`, its fields are considered merged into the outer rule per the logic above; otherwise, it is matched as an `other field`; different rule-sets always keep OR semantics.
#### inbound
@@ -217,14 +257,64 @@ Tags of [Inbound](/configuration/inbound/).
#### ip_version
!!! quote "Changes in sing-box 1.14.0"
This field now also applies when a DNS rule is matched from an internal
domain resolution that does not target a specific DNS server, such as a
[`resolve`](../../route/rule_action/#resolve) route rule action without a
`server` set. In earlier versions, only DNS queries received from a
client evaluated this field. See
[Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules)
for the full list.
Setting this field makes the DNS rule incompatible in the same DNS
configuration with Legacy Address Filter Fields in DNS rules, the Legacy
`strategy` DNS rule action option, and the Legacy
`rule_set_ip_cidr_accept_empty` DNS rule item. To combine with
address-based filtering, use the [`evaluate`](../rule_action/#evaluate)
action and [`match_response`](#match_response).
4 (A DNS query) or 6 (AAAA DNS query).
Not limited if empty.
#### query_type
!!! quote "Changes in sing-box 1.14.0"
This field now also applies when a DNS rule is matched from an internal
domain resolution that does not target a specific DNS server, such as a
[`resolve`](../../route/rule_action/#resolve) route rule action without a
`server` set. In earlier versions, only DNS queries received from a
client evaluated this field. See
[Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules)
for the full list.
Setting this field makes the DNS rule incompatible in the same DNS
configuration with Legacy Address Filter Fields in DNS rules, the Legacy
`strategy` DNS rule action option, and the Legacy
`rule_set_ip_cidr_accept_empty` DNS rule item. To combine with
address-based filtering, use the [`evaluate`](../rule_action/#evaluate)
action and [`match_response`](#match_response).
DNS query type. Values can be integers or type name strings.
#### query_client_subnet
!!! question "Since sing-box 1.14.0"
Match the `edns0-subnet` OPT extra record (EDNS Client Subnet) in the query.
A listed prefix matches when it is no more specific than the received client subnet and contains its address.
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
#### query_dnssec
!!! question "Since sing-box 1.14.0"
Match queries with the DNSSEC OK (`DO`) bit set.
#### network
`tcp` or `udp`.
@@ -325,6 +415,12 @@ Match process path using regular expression.
Match android package name.
#### package_name_regex
!!! question "Since sing-box 1.14.0"
Match android package name using regular expression.
#### user
!!! quote ""
@@ -408,6 +504,41 @@ Matches network interface (same values as `network_type`) address.
Match default interface address.
#### source_mac_address
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device MAC address.
#### source_hostname
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device hostname from DHCP leases.
#### preferred_by
!!! question "Since sing-box 1.14.0"
Match specified DNS servers' preferred domains.
| Type | Match |
|---------------|------------------------------------------------------------------------------|
| `hosts` | Match predefined entries and entries in hosts files |
| `local` | Match hosts entries, neighbor-resolved hosts, and mDNS local domains |
| `mdns` | Match mDNS local domains (`*.local.` and IPv4/IPv6 link-local reverse zones) |
| `tailscale` | Match MagicDNS hosts and DNS route suffixes |
| `openconnect` | Match split DNS and search domains pushed by the VPN server |
| `resolved` | Match split DNS and search domains from systemd-resolved links |
#### wifi_ssid
!!! quote ""
@@ -446,6 +577,29 @@ Make `ip_cidr` rule items in rule-sets match the source IP.
Make `ip_cidr` rule items in rule-sets match the source IP.
#### match_response
!!! question "Since sing-box 1.14.0"
Enable response-based matching. When enabled, this rule matches against the evaluated response
(set by a preceding [`evaluate`](/configuration/dns/rule_action/#evaluate) action)
instead of only matching the original query.
`true` or the `tag` of an `evaluate` action: `true` matches against the response of the latest
`evaluate` action without `tag`; a tag matches against the response of the `evaluate` action with the tag.
The evaluated response can also be returned directly by a later [`respond`](/configuration/dns/rule_action/#respond) action;
in a rule with a `match_response` tag, `respond` returns the tagged response.
Required for Response Match Fields (`response_rcode`, `response_answer`, `response_ns`, `response_extra`).
Also required for `ip_cidr`, `ip_is_private`, and `ip_accept_any` when used with `evaluate` or Response Match Fields.
#### ip_accept_any
!!! question "Since sing-box 1.12.0"
Match when the DNS query response contains at least one address.
#### invert
Invert match result.
@@ -490,7 +644,12 @@ See [DNS Rule Actions](../rule_action/) for details.
Moved to [DNS Rule Action](../rule_action#route).
### Address Filter Fields
### Legacy Address Filter Fields
!!! failure "Deprecated in sing-box 1.14.0"
Legacy Address Filter Fields are deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Only takes effect for address requests (A/AAAA/HTTPS). When the query results do not match the address filtering rule items, the current rule will be skipped.
@@ -516,23 +675,61 @@ Match GeoIP with query response.
Match IP CIDR with query response.
As a Legacy Address Filter Field, deprecated. Use with `match_response` instead,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
#### ip_is_private
!!! question "Since sing-box 1.9.0"
Match private IP with query response.
As a Legacy Address Filter Field, deprecated. Use with `match_response` instead,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
#### rule_set_ip_cidr_accept_empty
!!! question "Since sing-box 1.10.0"
!!! failure "Deprecated in sing-box 1.14.0"
`rule_set_ip_cidr_accept_empty` is deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Make `ip_cidr` rules in rule-sets accept empty query response.
#### ip_accept_any
### Response Match Fields
!!! question "Since sing-box 1.12.0"
!!! question "Since sing-box 1.14.0"
Match any IP with query response.
Match fields for the evaluated response. Require `match_response` to be set to `true`
and a preceding rule with [`evaluate`](/configuration/dns/rule_action/#evaluate) action to populate the response.
That evaluated response may also be returned directly by a later [`respond`](/configuration/dns/rule_action/#respond) action.
#### response_rcode
Match DNS response code.
Accepted values are the same as in the [predefined action rcode](/configuration/dns/rule_action/#rcode).
#### response_answer
Match DNS answer records.
Record format is the same as in [predefined action answer](/configuration/dns/rule_action/#answer).
#### response_ns
Match DNS name server records.
Record format is the same as in [predefined action ns](/configuration/dns/rule_action/#ns).
#### response_extra
Match DNS extra records.
Record format is the same as in [predefined action extra](/configuration/dns/rule_action/#extra).
### Logical Fields
docs/configuration/dns/rule.zh.md
+202 -16
View File
@@ -2,6 +2,23 @@
icon: material/alert-decagram
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [source_mac_address](#source_mac_address)
:material-plus: [source_hostname](#source_hostname)
:material-plus: [preferred_by](#preferred_by)
:material-plus: [match_response](#match_response)
:material-delete-clock: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)
:material-plus: [response_rcode](#response_rcode)
:material-plus: [response_answer](#response_answer)
:material-plus: [response_ns](#response_ns)
:material-plus: [response_extra](#response_extra)
:material-plus: [package_name_regex](#package_name_regex)
:material-plus: [query_client_subnet](#query_client_subnet)
:material-plus: [query_dnssec](#query_dnssec)
:material-alert: [ip_version](#ip_version)
:material-alert: [query_type](#query_type)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [interface_address](#interface_address)
@@ -62,6 +79,11 @@ icon: material/alert-decagram
"HTTPS",
32768
],
"query_client_subnet": [
"10.0.0.0/24",
"192.168.0.1"
],
"query_dnssec": false,
"network": "tcp",
"auth_user": [
"usera",
@@ -89,12 +111,6 @@ icon: material/alert-decagram
"192.168.0.1"
],
"source_ip_is_private": false,
"ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"ip_is_private": false,
"ip_accept_any": false,
"source_port": [
12345
],
@@ -124,6 +140,9 @@ icon: material/alert-decagram
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"user": [
"sekai"
],
@@ -149,6 +168,16 @@ icon: material/alert-decagram
"default_interface_address": [
"2000::/3"
],
"source_mac_address": [
"00:11:22:33:44:55"
],
"source_hostname": [
"my-device"
],
"preferred_by": [
"local",
"ts-dns"
],
"wifi_ssid": [
"My WIFI"
],
@@ -160,7 +189,17 @@ icon: material/alert-decagram
"geosite-cn"
],
"rule_set_ip_cidr_match_source": false,
"rule_set_ip_cidr_accept_empty": false,
"match_response": false,
"ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"ip_is_private": false,
"ip_accept_any": false,
"response_rcode": "",
"response_answer": [],
"response_ns": [],
"response_extra": [],
"invert": false,
"outbound": [
"direct"
@@ -169,6 +208,8 @@ icon: material/alert-decagram
"server": "local",
// 已弃用
"rule_set_ip_cidr_accept_empty": false,
"rule_set_ipcidr_match_source": false,
"geosite": [
"cn"
@@ -202,13 +243,13 @@ icon: material/alert-decagram
!!! note ""
默认规则使用以下匹配逻辑:
(`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite`) &&
(`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `ip_cidr` || `ip_is_private` || `ip_accept_any`) &&
(`port` || `port_range`) &&
(`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) &&
(`source_port` || `source_port_range`) &&
`other fields`
`其他字段`
另外，引用规则集中的每个分支都可视为与外层规则合并，不同分支之间仍保持 OR 语义。
当规则集仅包含一条默认规则且非 invert 时，其中字段视为按以上规则与外层规则合并；否则，作为一条 `其他字段` 匹配；不同规则集之间始终保持 or。
#### inbound
@@ -216,14 +257,56 @@ icon: material/alert-decagram
#### ip_version
!!! quote "sing-box 1.14.0 中的更改"
此字段现在也会在 DNS 规则被未指定具体 DNS 服务器的内部域名解析匹配时生效，
例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。
此前只有来自客户端的 DNS 查询才会评估此字段。完整列表参阅
[迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。
在 DNS 规则中设置此字段后，该 DNS 规则在同一 DNS 配置中不能与
旧版地址筛选字段 (DNS 规则)、旧版 DNS 规则动作 `strategy` 选项，
或旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项共存。如需与
基于地址的筛选组合，请使用 [`evaluate`](../rule_action/#evaluate) 动作和
[`match_response`](#match_response)。
4 (A DNS 查询) 或 6 (AAAA DNS 查询)。
默认不限制。
#### query_type
!!! quote "sing-box 1.14.0 中的更改"
此字段现在也会在 DNS 规则被未指定具体 DNS 服务器的内部域名解析匹配时生效，
例如未设置 `server` 的 [`resolve`](../../route/rule_action/#resolve) 路由规则动作。
此前只有来自客户端的 DNS 查询才会评估此字段。完整列表参阅
[迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。
在 DNS 规则中设置此字段后，该 DNS 规则在同一 DNS 配置中不能与
旧版地址筛选字段 (DNS 规则)、旧版 DNS 规则动作 `strategy` 选项，
或旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项共存。如需与
基于地址的筛选组合，请使用 [`evaluate`](../rule_action/#evaluate) 动作和
[`match_response`](#match_response)。
DNS 查询类型。值可以为整数或者类型名称字符串。
#### query_client_subnet
!!! question "自 sing-box 1.14.0 起"
匹配查询中的 `edns0-subnet` OPT 附加记录（EDNS 客户端子网）。
列出的前缀在不比收到的客户端子网更具体、且包含其地址时匹配。
如果值是 IP 地址而不是前缀，则会自动附加 `/32` 或 `/128`。
#### query_dnssec
!!! question "自 sing-box 1.14.0 起"
匹配设置了 DNSSEC OK (`DO`) 位的查询。
#### network
`tcp` 或 `udp`。
@@ -324,6 +407,12 @@ DNS 查询类型。值可以为整数或者类型名称字符串。
匹配 Android 应用包名。
#### package_name_regex
!!! question "自 sing-box 1.14.0 起"
使用正则表达式匹配 Android 应用包名。
#### user
!!! quote ""
@@ -407,6 +496,41 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
匹配默认接口地址。
#### source_mac_address
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux、macOS，或在 Android 和 macOS 图形客户端中支持。参阅 [邻居解析](/configuration/shared/neighbor/) 了解设置方法。
匹配源设备 MAC 地址。
#### source_hostname
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux、macOS，或在 Android 和 macOS 图形客户端中支持。参阅 [邻居解析](/configuration/shared/neighbor/) 了解设置方法。
匹配源设备从 DHCP 租约获取的主机名。
#### preferred_by
!!! question "自 sing-box 1.14.0 起"
匹配指定 DNS 服务器的首选域名。
| 类型 | 匹配 |
|---------------|-------------------------------------------------------------|
| `hosts` | 匹配预定义条目和 hosts 文件中的条目 |
| `local` | 匹配 hosts 中的条目、邻居解析得到的主机名以及 mDNS 本地域名 |
| `mdns` | 匹配 mDNS 本地域名（`*.local.` 以及 IPv4/IPv6 链路本地反向区域） |
| `tailscale` | 匹配 MagicDNS 主机和 DNS 路由后缀 |
| `openconnect` | 匹配 VPN 服务器推送的分流 DNS 和搜索域 |
| `resolved` | 匹配 systemd-resolved 链路中的分流域名和搜索域 |
#### wifi_ssid
!!! quote ""
@@ -445,6 +569,25 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
使规则集中的 `ip_cidr` 规则匹配源 IP。
#### match_response
!!! question "自 sing-box 1.14.0 起"
启用响应匹配。启用后，此规则将匹配已评估的响应（由前序 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作设置），而不仅是匹配原始查询。
可以为 `true` 或 `evaluate` 动作的 `tag`：`true` 匹配最近一条无 `tag` 的 `evaluate` 动作的响应；标签则匹配对应 `evaluate` 动作的响应。
该已评估的响应也可以被后续的 [`respond`](/zh/configuration/dns/rule_action/#respond) 动作直接返回；在带 `match_response` 标签的规则中，`respond` 返回该标签的响应。
响应匹配字段（`response_rcode`、`response_answer`、`response_ns`、`response_extra`）需要此选项。
当与 `evaluate` 或响应匹配字段一起使用时，`ip_cidr`、`ip_is_private` 和 `ip_accept_any` 也需要此选项。
#### ip_accept_any
!!! question "自 sing-box 1.12.0 起"
当 DNS 查询响应包含至少一个地址时匹配。
#### invert
反选匹配结果。
@@ -489,7 +632,12 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
已移动到 [DNS 规则动作](../rule_action#route).
### 地址筛选字段
### 旧版地址筛选字段
!!! failure "已在 sing-box 1.14.0 废弃"
旧版地址筛选字段已废弃，且将在 sing-box 1.16.0 中被移除，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
仅对地址请求 (A/AAAA/HTTPS) 生效。 当查询结果与地址筛选规则项不匹配时，将跳过当前规则。
@@ -516,24 +664,62 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.
与查询响应匹配 IP CIDR。
作为旧版地址筛选字段已废弃。请改为配合 `match_response` 使用，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
#### ip_is_private
!!! question "自 sing-box 1.9.0 起"
与查询响应匹配非公开 IP。
#### ip_accept_any
!!! question "自 sing-box 1.12.0 起"
匹配任意 IP。
作为旧版地址筛选字段已废弃。请改为配合 `match_response` 使用，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
#### rule_set_ip_cidr_accept_empty
!!! question "自 sing-box 1.10.0 起"
!!! failure "已在 sing-box 1.14.0 废弃"
`rule_set_ip_cidr_accept_empty` 已废弃且将在 sing-box 1.16.0 中被移除，
参阅[迁移指南](/zh/migration/#迁移地址筛选字段到响应匹配)。
使规则集中的 `ip_cidr` 规则接受空查询响应。
### 响应匹配字段
!!! question "自 sing-box 1.14.0 起"
已评估的响应的匹配字段。需要将 `match_response` 设为 `true`，
且需要前序规则使用 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作来填充响应。
该已评估的响应也可以被后续的 [`respond`](/zh/configuration/dns/rule_action/#respond) 动作直接返回。
#### response_rcode
匹配 DNS 响应码。
接受的值与 [predefined 动作 rcode](/zh/configuration/dns/rule_action/#rcode) 中相同。
#### response_answer
匹配 DNS 应答记录。
记录格式与 [predefined 动作 answer](/zh/configuration/dns/rule_action/#answer) 中相同。
#### response_ns
匹配 DNS 名称服务器记录。
记录格式与 [predefined 动作 ns](/zh/configuration/dns/rule_action/#ns) 中相同。
#### response_extra
匹配 DNS 额外记录。
记录格式与 [predefined 动作 extra](/zh/configuration/dns/rule_action/#extra) 中相同。
### 逻辑字段
#### type
docs/configuration/dns/rule_action.md
+204 -3
View File
@@ -2,6 +2,17 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-delete-clock: [strategy](#strategy)
:material-plus: [evaluate](#evaluate)
:material-plus: [respond](#respond)
:material-plus: [disable_optimistic_cache](#disable_optimistic_cache)
:material-plus: [timeout](#timeout)
:material-plus: [race](#race)
:material-plus: [speculative](#speculative)
:material-plus: [remove_client_subnet](#remove_client_subnet)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [strategy](#strategy)
@@ -9,16 +20,57 @@ icon: material/new-box
!!! question "Since sing-box 1.11.0"
### Structure
```json
{
"action": "",
"race": false,
... // Action Fields
}
```
#### action
The action to perform. `route` will be used by default.
#### race
!!! question "Since sing-box 1.14.0"
Only available with `route`, `respond`, `reject` and `predefined` actions.
Requires [`match_response`](/configuration/dns/rule/#match_response) (for logical rules, in sub-rules).
Conflict with `speculative`.
By default, rules are matched one after another in listed order: a rule with `match_response`
waits for its referenced responses, and no later rule is matched until it has been judged.
A rule with `race` enabled does not hold this order: rule matching continues past it while its
referenced responses are still pending, so the matching of race rules runs in parallel — with
each other and with the rules after them. Each race rule is judged once its referenced
responses are available, and the first race rule that matches terminates rule evaluation
immediately; the remaining queries are canceled.
Rules without `race` still take effect strictly in listed order: while a preceding race rule is
not yet judged, the action of any other matched rule is held until none of the race rules
matched. The result may therefore depend on server speed only among race rules.
### route
```json
{
"action": "route", // default
"server": "",
"speculative": false,
"strategy": "",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"client_subnet": null
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
@@ -30,10 +82,27 @@ icon: material/new-box
Tag of target server.
#### speculative
!!! question "Since sing-box 1.14.0"
Conflict with `race`. Has no effect without a preceding `race` rule.
By default, no query is sent in parallel with pending race rules: a matched `route` action
holds its query until none of the race rules matched.
When `speculative` is enabled, the query is sent as soon as the rule matches, in parallel with
the pending race rules, and may be wasted: its response is still used only after none of the
race rules matched.
#### strategy
!!! question "Since sing-box 1.12.0"
!!! failure "Deprecated in sing-box 1.14.0"
`strategy` is deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0.
Set domain strategy for this query.
One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
@@ -42,17 +111,146 @@ One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.
Disable cache and save cache in this query.
#### disable_optimistic_cache
!!! question "Since sing-box 1.14.0"
Disable optimistic DNS caching in this query.
#### rewrite_ttl
Rewrite TTL in DNS responses.
#### timeout
!!! question "Since sing-box 1.14.0"
Override the DNS query timeout for matched queries.
Will override `dns.timeout`.
#### client_subnet
Append a `edns0-subnet` OPT extra record with the specified IP prefix to every query by default.
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
Will overrides `dns.client_subnet`.
Will override `dns.client_subnet`.
#### remove_client_subnet
!!! question "Since sing-box 1.14.0"
Remove the `edns0-subnet` OPT extra record from the query, and suppress `dns.client_subnet`.
Conflict with `client_subnet`.
### evaluate
!!! question "Since sing-box 1.14.0"
```json
{
"action": "evaluate",
"server": "",
"tag": "",
"speculative": false,
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
`evaluate` sends a DNS query to the specified server and saves the evaluated response for subsequent rules
to match against using [`match_response`](/configuration/dns/rule/#match_response) and response fields.
Unlike `route`, it does **not** terminate rule evaluation.
Only allowed on top-level DNS rules (not inside logical sub-rules).
Rules that use [`match_response`](/configuration/dns/rule/#match_response) or Response Match Fields
require a preceding top-level rule with `evaluate` action. A rule's own `evaluate` action
does not satisfy this requirement, because matching happens before the action runs.
#### server
==Required==
Tag of target server.
#### tag
Tag of the evaluated response.
A tagged response is only referenced via [`match_response`](/configuration/dns/rule/#match_response) with the tag;
`match_response: true` references the response of the latest `evaluate` action without `tag`.
#### speculative
!!! question "Since sing-box 1.14.0"
Has no effect without a preceding `race` rule.
By default, no query is sent in parallel with pending race rules: a matched `evaluate` action
holds its query, and rule matching stops there, until none of the race rules matched.
When `speculative` is enabled, the query is sent as soon as the rule matches, in parallel with
the pending race rules, and may be wasted: rule matching continues without waiting for them.
#### disable_cache
Disable cache and save cache in this query.
#### disable_optimistic_cache
!!! question "Since sing-box 1.14.0"
Disable optimistic DNS caching in this query.
#### rewrite_ttl
Rewrite TTL in DNS responses.
#### timeout
!!! question "Since sing-box 1.14.0"
Override the DNS query timeout for matched queries.
Will override `dns.timeout`.
#### client_subnet
Append a `edns0-subnet` OPT extra record with the specified IP prefix to every query by default.
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
Will override `dns.client_subnet`.
#### remove_client_subnet
!!! question "Since sing-box 1.14.0"
Remove the `edns0-subnet` OPT extra record from the query, and suppress `dns.client_subnet`.
Conflict with `client_subnet`.
### respond
!!! question "Since sing-box 1.14.0"
```json
{
"action": "respond"
}
```
`respond` terminates rule evaluation and returns the evaluated response from a preceding [`evaluate`](/configuration/dns/rule_action/#evaluate) action.
This action does not send a new DNS query.
Only allowed after a preceding top-level `evaluate` rule. If the action is reached without an evaluated response at runtime, the request fails with an error instead of falling through to later rules.
### route-options
@@ -60,8 +258,11 @@ Will overrides `dns.client_subnet`.
{
"action": "route-options",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"client_subnet": null
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
docs/configuration/dns/rule_action.zh.md
+190 -3
View File
@@ -2,6 +2,17 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-delete-clock: [strategy](#strategy)
:material-plus: [evaluate](#evaluate)
:material-plus: [respond](#respond)
:material-plus: [disable_optimistic_cache](#disable_optimistic_cache)
:material-plus: [timeout](#timeout)
:material-plus: [race](#race)
:material-plus: [speculative](#speculative)
:material-plus: [remove_client_subnet](#remove_client_subnet)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [strategy](#strategy)
@@ -9,16 +20,50 @@ icon: material/new-box
!!! question "自 sing-box 1.11.0 起"
### 结构
```json
{
"action": "",
"race": false,
... // 动作字段
}
```
#### action
要执行的动作。默认使用 `route`。
#### race
!!! question "自 sing-box 1.14.0 起"
仅可用于 `route`、`respond`、`reject` 和 `predefined` 动作。
需要 [`match_response`](/zh/configuration/dns/rule/#match_response)（对 logical 规则，位于子规则中）。
与 `speculative` 冲突。
默认情况下，规则逐条按顺序匹配：带 `match_response` 的规则等待其引用的响应，在它被判定之前不会匹配任何后续规则。
启用 `race` 的规则成为竞态规则，不再保持这一顺序：其引用的响应尚未到达时，规则匹配会越过它继续进行，因此竞态规则的匹配相互并行、也与后续规则并行。每条竞态规则在其引用的响应可用时被判定，首个匹配的竞态规则立即终止规则评估，其余查询将被取消。
未启用 `race` 的规则仍严格按顺序生效：只要前面还有未判定的竞态规则，其他已匹配规则的动作就被扣住，直到所有竞态规则均未匹配。因此只有竞态规则之间的结果取决于服务器速度。
### route
```json
{
"action": "route", // 默认
"server": "",
"speculative": false,
"strategy": "",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"client_subnet": null
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
@@ -30,10 +75,24 @@ icon: material/new-box
目标 DNS 服务器的标签。
#### speculative
!!! question "自 sing-box 1.14.0 起"
与 `race` 冲突。没有前序竞态规则时无效果。
默认情况下，查询决不与未判定的竞态规则并行发出：已匹配的 `route` 动作扣住其查询，直到所有竞态规则均未匹配后才发送。
启用 `speculative` 后，查询成为投机查询：在规则匹配时立即发出、与未判定的竞态规则并行，且可能被浪费；其响应仍仅在所有竞态规则均未匹配后才被使用。
#### strategy
!!! question "自 sing-box 1.12.0 起"
!!! failure "已在 sing-box 1.14.0 废弃"
`strategy` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除。
为此查询设置域名策略。
可选项：`prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`。
@@ -42,10 +101,24 @@ icon: material/new-box
在此查询中禁用缓存。
#### disable_optimistic_cache
!!! question "自 sing-box 1.14.0 起"
在此查询中禁用乐观 DNS 缓存。
#### rewrite_ttl
重写 DNS 回应中的 TTL。
#### timeout
!!! question "自 sing-box 1.14.0 起"
覆盖匹配查询的 DNS 查询超时时间。
将覆盖 `dns.timeout`。
#### client_subnet
默认情况下，将带有指定 IP 前缀的 `edns0-subnet` OPT 附加记录附加到每个查询。
@@ -54,14 +127,128 @@ icon: material/new-box
将覆盖 `dns.client_subnet`.
#### remove_client_subnet
!!! question "自 sing-box 1.14.0 起"
移除查询中的 `edns0-subnet` OPT 附加记录，并抑制 `dns.client_subnet`。
与 `client_subnet` 冲突。
### evaluate
!!! question "自 sing-box 1.14.0 起"
```json
{
"action": "evaluate",
"server": "",
"tag": "",
"speculative": false,
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
`evaluate` 向指定服务器发送 DNS 查询并保存已评估的响应，供后续规则通过 [`match_response`](/zh/configuration/dns/rule/#match_response) 和响应字段进行匹配。与 `route` 不同，它**不会**终止规则评估。
仅允许在顶层 DNS 规则中使用（不可在逻辑子规则内部使用）。
使用 [`match_response`](/zh/configuration/dns/rule/#match_response) 或响应匹配字段的规则，
需要位于更早的顶层 `evaluate` 规则之后。规则自身的 `evaluate` 动作不能满足这个条件，
因为匹配发生在动作执行之前。
#### server
==必填==
目标 DNS 服务器的标签。
#### tag
已评估响应的标签。
带标签的响应仅能通过 [`match_response`](/zh/configuration/dns/rule/#match_response) 以标签引用；
`match_response: true` 引用最近一条无 `tag` 的 `evaluate` 动作的响应。
#### speculative
!!! question "自 sing-box 1.14.0 起"
没有前序竞态规则时无效果。
默认情况下，查询决不与未判定的竞态规则并行发出：已匹配的 `evaluate` 动作扣住其查询，规则匹配在此处停止，直到所有竞态规则均未匹配。
启用 `speculative` 后，查询成为投机查询：在规则匹配时立即发出、与未判定的竞态规则并行，且可能被浪费；规则匹配继续进行而不等待竞态规则。
#### disable_cache
在此查询中禁用缓存。
#### disable_optimistic_cache
!!! question "自 sing-box 1.14.0 起"
在此查询中禁用乐观 DNS 缓存。
#### rewrite_ttl
重写 DNS 回应中的 TTL。
#### timeout
!!! question "自 sing-box 1.14.0 起"
覆盖匹配查询的 DNS 查询超时时间。
将覆盖 `dns.timeout`。
#### client_subnet
默认情况下，将带有指定 IP 前缀的 `edns0-subnet` OPT 附加记录附加到每个查询。
如果值是 IP 地址而不是前缀，则会自动附加 `/32` 或 `/128`。
将覆盖 `dns.client_subnet`.
#### remove_client_subnet
!!! question "自 sing-box 1.14.0 起"
移除查询中的 `edns0-subnet` OPT 附加记录，并抑制 `dns.client_subnet`。
与 `client_subnet` 冲突。
### respond
!!! question "自 sing-box 1.14.0 起"
```json
{
"action": "respond"
}
```
`respond` 会终止规则评估，并直接返回前序 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作保存的已评估的响应。
此动作不会发起新的 DNS 查询。
只能用于前面已有顶层 `evaluate` 规则的场景。如果运行时命中该动作时没有已评估的响应，则请求会直接返回错误，而不是继续匹配后续规则。
### route-options
```json
{
"action": "route-options",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"client_subnet": null
"timeout": "",
"client_subnet": null,
"remove_client_subnet": false
}
```
@@ -84,7 +271,7 @@ icon: material/new-box
- `default`: 返回 REFUSED。
- `drop`: 丢弃请求。
默认使用 `defualt`。
默认使用 `default`。
#### no_drop
docs/configuration/dns/server/hosts.md
+46 -19
View File
@@ -73,24 +73,51 @@ Example:
=== "Use hosts if available"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
}
],
"rules": [
{
"preferred_by": "hosts",
"action": "route",
"server": "hosts"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "hosts"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "hosts"
}
]
}
]
}
}
```
}
```
docs/configuration/dns/server/hosts.zh.md
+46 -19
View File
@@ -73,24 +73,51 @@ hosts 文件路径列表。
=== "如果可用则使用 hosts"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
}
],
"rules": [
{
"preferred_by": "hosts",
"action": "route",
"server": "hosts"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "hosts"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
...
},
{
"type": "hosts",
"tag": "hosts"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "hosts"
}
]
}
]
}
}
```
}
```
docs/configuration/dns/server/index.md
+8 -1
View File
@@ -2,6 +2,10 @@
icon: material/alert-decagram
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [mdns](./mdns/)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [type](#type)
@@ -29,7 +33,7 @@ The type of the DNS server.
| Type | Format |
|-----------------|---------------------------|
| empty (default) | [Legacy](./legacy/) |
| empty (default) | :material-note-remove: [Legacy](./legacy/) |
| `local` | [Local](./local/) |
| `hosts` | [Hosts](./hosts/) |
| `tcp` | [TCP](./tcp/) |
@@ -39,8 +43,11 @@ The type of the DNS server.
| `https` | [HTTPS](./https/) |
| `h3` | [HTTP/3](./http3/) |
| `dhcp` | [DHCP](./dhcp/) |
| `mdns` | [mDNS](./mdns/) |
| `fakeip` | [Fake IP](./fakeip/) |
| `tailscale` | [Tailscale](./tailscale/) |
| `openconnect` | [OpenConnect](./openconnect/) |
| `openvpn` | [OpenVPN](./openvpn/) |
| `resolved` | [Resolved](./resolved/) |
#### tag
docs/configuration/dns/server/index.zh.md
+8 -1
View File
@@ -2,6 +2,10 @@
icon: material/alert-decagram
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [mdns](./mdns/)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [type](#type)
@@ -29,7 +33,7 @@ DNS 服务器的类型。
| 类型 | 格式 |
|-----------------|---------------------------|
| empty (default) | [Legacy](./legacy/) |
| empty (default) | :material-note-remove: [Legacy](./legacy/) |
| `local` | [Local](./local/) |
| `hosts` | [Hosts](./hosts/) |
| `tcp` | [TCP](./tcp/) |
@@ -39,8 +43,11 @@ DNS 服务器的类型。
| `https` | [HTTPS](./https/) |
| `h3` | [HTTP/3](./http3/) |
| `dhcp` | [DHCP](./dhcp/) |
| `mdns` | [mDNS](./mdns/) |
| `fakeip` | [Fake IP](./fakeip/) |
| `tailscale` | [Tailscale](./tailscale/) |
| `openconnect` | [OpenConnect](./openconnect/) |
| `openvpn` | [OpenVPN](./openvpn/) |
| `resolved` | [Resolved](./resolved/) |
#### tag
docs/configuration/dns/server/legacy.md
+5 -5
View File
@@ -1,10 +1,10 @@
---
icon: material/delete-clock
icon: material/note-remove
---
!!! failure "Deprecated in sing-box 1.12.0"
!!! failure "Removed in sing-box 1.14.0"
Legacy DNS servers is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-servers).
Legacy DNS servers are deprecated in sing-box 1.12.0 and removed in sing-box 1.14.0, check [Migration](/migration/#migrate-to-new-dns-server-formats).
!!! quote "Changes in sing-box 1.9.0"
@@ -108,6 +108,6 @@ Append a `edns0-subnet` OPT extra record with the specified IP prefix to every q
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
Can be overrides by `rules.[].client_subnet`.
Can be overridden by `rules.[].client_subnet`.
Will overrides `dns.client_subnet`.
Will override `dns.client_subnet`.
docs/configuration/dns/server/legacy.zh.md
+3 -3
View File
@@ -1,10 +1,10 @@
---
icon: material/delete-clock
icon: material/note-remove
---
!!! failure "Deprecated in sing-box 1.12.0"
!!! failure "已在 sing-box 1.14.0 移除"
旧的 DNS 服务器配置已废弃且将在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/zh/migration/#迁移到新的-dns-服务器格式)。
旧的 DNS 服务器配置已在 sing-box 1.12.0 废弃且已在 sing-box 1.14.0 中被移除，参阅 [迁移指南](/zh/migration/#迁移到新的-dns-服务器格式)。
!!! quote "sing-box 1.9.0 中的更改"
docs/configuration/dns/server/local.md
+19 -1
View File
@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [neighbor_domain](#neighbor_domain)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [prefer_go](#prefer_go)
@@ -19,7 +23,8 @@ icon: material/new-box
{
"type": "local",
"tag": "",
"prefer_go": false
"prefer_go": false,
"neighbor_domain": []
// Dial Fields
}
@@ -56,6 +61,19 @@ On devices running Android versions lower than 10, this interface can only resol
2. On macOS, `local` will try DHCP first in Network Extension, since DHCP respects DIal Fields,
it will not be disabled by `prefer_go`.
#### neighbor_domain
!!! question "Since sing-box 1.14.0"
A list of domain suffixes for which A/AAAA queries are answered from the
[neighbor resolver](/configuration/shared/neighbor/) instead of the upstream.
Each entry must start with `.`. Only queries whose host part (the portion
before the suffix) contains no dots are matched; `.` matches any
single-label name such as `nas`.
Example: `[".", ".lan"]`.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/dns/server/local.zh.md
+16
View File
@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [neighbor_domain](#neighbor_domain)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [prefer_go](#prefer_go)
@@ -20,6 +24,7 @@ icon: material/new-box
"type": "local",
"tag": "",
"prefer_go": false,
"neighbor_domain": [],
// 拨号字段
}
@@ -56,6 +61,17 @@ icon: material/new-box
2. 在 macOS 上，`local` 会在 Network Extension 中首先尝试 DHCP，由于 DHCP 遵循拨号字段，
它不会被 `prefer_go` 禁用。
#### neighbor_domain
!!! question "自 sing-box 1.14.0 起"
用于从[邻居解析器](/zh/configuration/shared/neighbor/)而非上游回答 A/AAAA 查询的域后缀列表。
每一项必须以 `.` 开头。仅匹配后缀之前的主机名部分不包含点的查询；
`.` 匹配任意单标签名称，例如 `nas`。
示例：`[".", ".lan"]`。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。
docs/configuration/dns/server/mdns.md
+42
View File
@@ -0,0 +1,42 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# mDNS
### Structure
```json
{
"dns": {
"servers": [
{
"type": "mdns",
"tag": "",
"interface": [],
// Dial Fields
}
]
}
}
```
!!! info ""
You usually do not need an explicit `mdns` server in addition to a [Local](./local/) server: the local server already routes queries for `*.local.` and IPv4/IPv6 link-local reverse zones via mDNS on non-Apple platforms and via the system resolver on Apple platforms. Add an explicit `mdns` server only when you want to reference it from [`preferred_by`](../rule/#preferred_by) or use it standalone.
### Fields
#### interface
List of network interface names to send mDNS queries on.
When empty, all interfaces that are up, multicast-capable, and non-loopback are used.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/dns/server/mdns.zh.md
+42
View File
@@ -0,0 +1,42 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# mDNS
### 结构
```json
{
"dns": {
"servers": [
{
"type": "mdns",
"tag": "",
"interface": [],
// 拨号字段
}
]
}
}
```
!!! info ""
通常不需要在 [Local](./local/) 服务器之外再添加显式的 `mdns` 服务器：本地服务器已经会在非 Apple 平台通过 mDNS、在 Apple 平台通过系统解析器来回答 `*.local.` 与 IPv4/IPv6 链路本地反向区域的查询。仅当需要从 [`preferred_by`](../rule/#preferred_by) 引用，或独立使用时，才需要显式添加 `mdns` 服务器。
### 字段
#### interface
用于发送 mDNS 查询的网络接口名称列表。
留空时，将使用所有处于 up 状态、支持多播且非环回的接口。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。
docs/configuration/dns/server/openconnect.md
+97
View File
@@ -0,0 +1,97 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# OpenConnect
### Structure
```json
{
"dns": {
"servers": [
{
"type": "openconnect",
"tag": "",
"endpoint": "oc-client",
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
}
```
### Fields
#### endpoint
==Required==
The tag of the [OpenConnect Endpoint](/configuration/endpoint/openconnect).
DNS queries are sent to the resolvers pushed by the VPN server through the OpenConnect endpoint. Pushed split-DNS rules use their dedicated resolvers, while pushed split-DNS and search-domain suffixes use the general pushed resolvers. The most specific matching suffix takes precedence.
Pushed DNS settings are not installed into the operating system.
#### accept_default_resolvers
Accept the general resolvers pushed by the VPN server for unmatched queries.
When enabled, the general resolvers are used as the default only if the server requests all DNS through the tunnel, or if it does not provide split-DNS rules or suffixes. Otherwise, unmatched queries return `NXDOMAIN`.
#### accept_search_domain
When enabled and pushed search domains are available, single-label queries (for example, `intranet`) are retried with each search domain until one resolves.
If every search-domain expansion returns `NXDOMAIN`, the original unqualified name follows normal default-resolver behavior.
### Examples
=== "Split DNS only"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "openconnect",
"tag": "oc",
"endpoint": "oc-client"
}
],
"rules": [
{
"preferred_by": "oc",
"action": "route",
"server": "oc"
}
],
"final": "local"
}
}
```
=== "Accept pushed default resolvers"
```json
{
"dns": {
"servers": [
{
"type": "openconnect",
"endpoint": "oc-client",
"accept_default_resolvers": true,
"accept_search_domain": true
}
]
}
}
```
docs/configuration/dns/server/openconnect.zh.md
+97
View File
@@ -0,0 +1,97 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# OpenConnect
### 结构
```json
{
"dns": {
"servers": [
{
"type": "openconnect",
"tag": "",
"endpoint": "oc-client",
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
}
```
### 字段
#### endpoint
==必填==
[OpenConnect 端点](/zh/configuration/endpoint/openconnect) 的标签。
DNS 查询会通过 OpenConnect 端点发送到 VPN 服务器推送的解析器。推送的分流 DNS 规则使用各自的专用解析器，推送的分流 DNS 和搜索域后缀则使用通用推送解析器。匹配时优先使用最具体的后缀。
推送的 DNS 设置不会安装到操作系统中。
#### accept_default_resolvers
接受 VPN 服务器推送的通用解析器，用于未匹配的查询。
启用时，仅当服务器要求所有 DNS 通过隧道，或未提供分流 DNS 规则及后缀时，通用解析器才会作为默认解析器。否则，未匹配的查询将返回 `NXDOMAIN`。
#### accept_search_domain
启用且存在推送的搜索域时，单标签查询（例如 `intranet`）会依次附加各个搜索域进行重试，直到其中一个解析成功。
如果所有搜索域扩展均返回 `NXDOMAIN`，原始未限定名称将按普通默认解析器行为处理。
### 示例
=== "仅分流 DNS"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "openconnect",
"tag": "oc",
"endpoint": "oc-client"
}
],
"rules": [
{
"preferred_by": "oc",
"action": "route",
"server": "oc"
}
],
"final": "local"
}
}
```
=== "接受推送的默认解析器"
```json
{
"dns": {
"servers": [
{
"type": "openconnect",
"endpoint": "oc-client",
"accept_default_resolvers": true,
"accept_search_domain": true
}
]
}
}
```
docs/configuration/dns/server/openvpn.md
+82
View File
@@ -0,0 +1,82 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# OpenVPN
### Structure
```json
{
"dns": {
"servers": [
{
"type": "openvpn",
"tag": "",
"endpoint": "ovpn-client",
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
}
```
### Fields
#### endpoint
==Required==
The tag of the [OpenVPN Client Endpoint](/configuration/endpoint/openvpn-client).
DNS queries are sent through the endpoint to resolvers pushed by the OpenVPN server. Modern OpenVPN `dns server` options support plain DNS, DNS over TLS, DNS over HTTPS, custom ports, SNI, and `resolve-domains`. Only the server group with the lowest priority number is active. Legacy `dhcp-option DNS`/`DNS6` and `DOMAIN-ROUTE` are used when no modern server group is present.
A modern server group overrides legacy DHCP DNS resolver and domain options. A standalone modern `dns search-domains` option does not remove legacy resolvers. Required DNSSEC validation (`dnssec yes`) is rejected because this transport does not provide DNSSEC validation.
Pushed DNS settings are not installed into the operating system.
#### accept_default_resolvers
Use pushed resolvers for queries that do not match a pushed `resolve-domains`, `DOMAIN-ROUTE`, or search-domain suffix.
When disabled, unmatched queries return `NXDOMAIN`.
#### accept_search_domain
When enabled and pushed search domains are available, single-label queries (for example, `intranet`) are retried with each search domain until one resolves.
If no search domain is available, the original single-label query follows normal default-resolver behavior.
### Example
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "openvpn",
"tag": "ovpn-dns",
"endpoint": "ovpn-client",
"accept_default_resolvers": true,
"accept_search_domain": true
}
],
"rules": [
{
"preferred_by": "ovpn-dns",
"action": "route",
"server": "ovpn-dns"
}
],
"final": "local"
}
}
```
docs/configuration/dns/server/openvpn.zh.md
+82
View File
@@ -0,0 +1,82 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# OpenVPN
### 结构
```json
{
"dns": {
"servers": [
{
"type": "openvpn",
"tag": "",
"endpoint": "ovpn-client",
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
}
```
### 字段
#### endpoint
==必填==
[OpenVPN 客户端端点](/zh/configuration/endpoint/openvpn-client) 的标签。
DNS 查询会通过该端点发送到 OpenVPN 服务器推送的解析器。现代 OpenVPN `dns server` 选项支持普通 DNS、DNS over TLS、DNS over HTTPS、自定义端口、SNI 和 `resolve-domains`。只有优先级数字最低的服务器组会生效。没有现代服务器组时，使用传统的 `dhcp-option DNS`/`DNS6` 和 `DOMAIN-ROUTE`。
现代服务器组会覆盖传统 DHCP DNS 解析器及相关域选项。只有现代 `dns search-domains` 而没有现代服务器组时，不会移除传统解析器。由于此传输不提供 DNSSEC 验证，需要强制验证的 `dnssec yes` 会被拒绝。
推送的 DNS 设置不会安装到操作系统中。
#### accept_default_resolvers
对未匹配推送的 `resolve-domains`、`DOMAIN-ROUTE` 或搜索域后缀的查询使用推送解析器。
禁用时，未匹配查询返回 `NXDOMAIN`。
#### accept_search_domain
启用且存在推送的搜索域时，单标签查询（例如 `intranet`）会依次附加各个搜索域重试，直到其中一个解析成功。
不存在搜索域时，原始单标签查询按普通默认解析器规则处理。
### 示例
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "openvpn",
"tag": "ovpn-dns",
"endpoint": "ovpn-client",
"accept_default_resolvers": true,
"accept_search_domain": true
}
],
"rules": [
{
"preferred_by": "ovpn-dns",
"action": "route",
"server": "ovpn-dns"
}
],
"final": "local"
}
}
```
docs/configuration/dns/server/resolved.md
+50 -21
View File
@@ -43,29 +43,58 @@ If not enabled, `NXDOMAIN` will be returned for requests that do not match searc
=== "Split DNS only"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
}
],
"rules": [
{
"preferred_by": "resolved",
"action": "route",
"server": "resolved"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "resolved"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "resolved"
}
]
}
]
}
}
```
}
```
=== "Use as global DNS"
docs/configuration/dns/server/resolved.zh.md
+50 -21
View File
@@ -42,29 +42,58 @@ icon: material/new-box
=== "仅分割 DNS"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
}
],
"rules": [
{
"preferred_by": "resolved",
"action": "route",
"server": "resolved"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "resolved"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "resolved",
"tag": "resolved",
"service": "resolved"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "resolved"
}
]
}
]
}
}
```
}
```
=== "用作全局 DNS"
docs/configuration/dns/server/tailscale.md
+64 -22
View File
@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [accept_search_domain](#accept_search_domain)
!!! question "Since sing-box 1.12.0"
# Tailscale
@@ -17,7 +21,8 @@ icon: material/new-box
"tag": "",
"endpoint": "ts-ep",
"accept_default_resolvers": false
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
@@ -38,33 +43,70 @@ Indicates whether default DNS resolvers should be accepted for fallback queries
if not enabled, `NXDOMAIN` will be returned for non-Tailscale domain queries.
#### accept_search_domain
!!! question "Since sing-box 1.14.0"
When enabled, single-label queries (e.g. `my-device`) are retried against each Tailscale search domain until one resolves.
Default resolvers are not consulted for single-label queries regardless of `accept_default_resolvers`.
### Examples
=== "MagicDNS only"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
}
],
"rules": [
{
"preferred_by": "ts",
"action": "route",
"server": "ts"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "ts"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "ts"
}
]
}
]
}
}
```
}
```
=== "Use as global DNS"
docs/configuration/dns/server/tailscale.zh.md
+64 -22
View File
@@ -2,6 +2,10 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [accept_search_domain](#accept_search_domain)
!!! question "自 sing-box 1.12.0 起"
# Tailscale
@@ -17,7 +21,8 @@ icon: material/new-box
"tag": "",
"endpoint": "ts-ep",
"accept_default_resolvers": false
"accept_default_resolvers": false,
"accept_search_domain": false
}
]
}
@@ -38,33 +43,70 @@ icon: material/new-box
如果未启用，对于非 Tailscale 域名查询将返回 `NXDOMAIN`。
#### accept_search_domain
!!! question "自 sing-box 1.14.0 起"
启用后，单标签查询（例如 `my-device`）将依次附加 Tailscale 搜索域进行重试，直到其中一个解析成功。
对于单标签查询，无论 `accept_default_resolvers` 是否启用，都不会使用默认 DNS 解析器。
### 示例
=== "仅 MagicDNS"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
=== ":material-card-multiple: sing-box 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
}
],
"rules": [
{
"preferred_by": "ts",
"action": "route",
"server": "ts"
}
]
}
],
"rules": [
{
"ip_accept_any": true,
"server": "ts"
}
```
=== ":material-card-remove: sing-box < 1.14.0"
```json
{
"dns": {
"servers": [
{
"type": "local",
"tag": "local"
},
{
"type": "tailscale",
"tag": "ts",
"endpoint": "ts-ep"
}
],
"rules": [
{
"ip_accept_any": true,
"server": "ts"
}
]
}
]
}
}
```
}
```
=== "用作全局 DNS"
docs/configuration/endpoint/index.md
+7 -4
View File
@@ -19,10 +19,13 @@ An endpoint is a protocol with inbound and outbound behavior.
### Fields
| Type | Format |
|-------------|---------------------------|
| `wireguard` | [WireGuard](./wireguard/) |
| `tailscale` | [Tailscale](./tailscale/) |
| Type | Format |
|------------------|-----------------------------------------|
| `wireguard` | [WireGuard](./wireguard/) |
| `tailscale` | [Tailscale](./tailscale/) |
| `openconnect` | [OpenConnect Client](./openconnect/) |
| `openvpn-client` | [OpenVPN Client](./openvpn-client/) |
| `openvpn-server` | [OpenVPN Server](./openvpn-server/) |
#### tag
docs/configuration/endpoint/index.zh.md
+7 -4
View File
@@ -19,10 +19,13 @@
### 字段
| 类型 | 格式 |
|-------------|---------------------------|
| `wireguard` | [WireGuard](./wireguard/) |
| `tailscale` | [Tailscale](./tailscale/) |
| 类型 | 格式 |
|------------------|-----------------------------------------|
| `wireguard` | [WireGuard](./wireguard/) |
| `tailscale` | [Tailscale](./tailscale/) |
| `openconnect` | [OpenConnect 客户端](./openconnect/) |
| `openvpn-client` | [OpenVPN 客户端](./openvpn-client/) |
| `openvpn-server` | [OpenVPN 服务器](./openvpn-server/) |
#### tag
docs/configuration/endpoint/openconnect.md
+651
View File
@@ -0,0 +1,651 @@
# OpenConnect Client
!!! question "Since sing-box 1.14.0"
==Client only==
## Structure
```json
{
"type": "openconnect",
"tag": "oc-client",
"system": false,
"name": "",
... // UDP NAT Fields
"server": "vpn.example.com",
"flavor": "anyconnect",
"username": "",
"password": "",
"auth_group": "",
"cookie": "",
"token": {
"mode": "",
"secret": "",
"secret_path": "",
"pin": "",
"password": "",
"device_id": "",
"counter": 0
},
"reported_os": "",
"user_agent": "",
"version": "",
"local_hostname": "",
"mobile": {
"platform_version": "",
"device_type": "",
"device_unique_id": ""
},
"csd": {
"wrapper_path": ""
},
"hip": {
"wrapper_path": ""
},
"tncc": {
"wrapper_path": "",
"device_id": "",
"user_agent": "",
"machine_identification_enabled": false,
"certificates": [
{
"certificate": [],
"certificate_path": ""
}
]
},
"fortinet_host_check": {
"hostcheck": "",
"check_virtual_desktop": ""
},
"no_udp": false,
"dtls_local_port": 0,
"compression_disabled": false,
"compression_mode": "",
"ipv6_disabled": false,
"http_keepalive_disabled": false,
"xml_post_disabled": false,
"external_auth_disabled": false,
"password_authentication_disabled": false,
"tcp_keep_alive_enabled": false,
"pfs": false,
"mtu": 0,
"base_mtu": 0,
"dpd_interval": "",
"reconnect_timeout": "",
"trojan_interval": "",
"queue_length": 0,
"allow_insecure_crypto": false,
"tls": {
"insecure": false,
"server_name": "",
"peer_fingerprint": [],
"system_trust_disabled": false,
"certificate_authority": [],
"certificate_authority_path": "",
"client_certificate": [],
"client_certificate_path": "",
"client_key": [],
"client_key_path": "",
"client_key_password": "",
"mca_certificate": [],
"mca_certificate_path": "",
"mca_key": [],
"mca_key_path": "",
"mca_key_password": ""
},
"form_entries": [
{
"form_id": "",
"submission_key": "",
"name": "",
"value": "",
"promote": false
}
],
... // Dial Fields
}
```
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item.
## Fields
### system
Use a system interface.
Requires privilege and cannot conflict with existing system interfaces.
If disabled, sing-box uses the internal network stack.
### name
Custom interface name for the system interface.
An automatically generated `oc` interface name is used by default.
### server
==Required==
OpenConnect VPN server HTTPS URL.
The `https://` scheme is added if omitted. URL user information, queries, and fragments are not supported.
### flavor
OpenConnect protocol flavor, one of `anyconnect`, `gp`, `fortinet`, `f5`, `pulse`, or `nc`.
`anyconnect` is used by default.
### username
Username used to fill matching authentication form fields.
### password
Password used to fill matching authentication form fields.
### auth_group
Authentication group used to preselect a matching group, realm, domain, or gateway choice when supported by the selected flavor.
### cookie
Existing authentication session used to connect without first prompting for credentials.
The accepted format depends on `flavor`:
- `anyconnect`: A `webvpn` value, or a semicolon-separated cookie list containing `webvpn`.
- `gp`: The complete authenticated query string returned by GlobalProtect authentication.
- `nc`: A `DSID` value, or a semicolon-separated cookie list containing `DSID`.
- `pulse`: The raw Pulse authentication cookie value.
- `f5`: An `MRHSession` value, or a semicolon-separated cookie list containing `MRHSession` and optionally `F5_ST`.
- `fortinet`: An `SVPNCOOKIE` value, or a semicolon-separated cookie list containing `SVPNCOOKIE`.
If the server rejects the supplied session, normal authentication is attempted.
### token
Token configuration for automatically answering matching token fields or HTTP Bearer authentication.
One of `token.secret` or `token.secret_path` is required.
### token.mode
==Required==
Token mode, one of:
- `totp`: Time-based One-Time Password.
- `hotp`: HMAC-based One-Time Password.
- `stoken`: RSA SecurID software token.
- `oidc`: OIDC access token used for HTTP Bearer authentication.
### token.secret
Software token secret.
For `totp` and `hotp`, this can be a Base32 secret, a `base32:`-prefixed secret, or an `otpauth://` URI of the matching type.
For `stoken`, this is the encoded RSA SecurID CTF token content.
For `oidc`, this is the access token value. It is sent only after the VPN server requests HTTP Bearer authentication.
Conflict with `token.secret_path`.
### token.secret_path
Path to the software token secret or OIDC access token.
Conflict with `token.secret`.
### token.pin
RSA SecurID PIN for `stoken` mode.
### token.password
Password for decrypting a password-protected RSA SecurID token in `stoken` mode.
### token.device_id
Device ID for decrypting a device-bound RSA SecurID token in `stoken` mode.
### token.counter
Initial counter for `hotp` mode.
If zero, the counter from an `otpauth://` URI is used when present; otherwise the counter starts at zero.
### reported_os
Operating system identity reported to the VPN server when supported by the selected flavor.
For `anyconnect`, `gp`, and `pulse`, the supported values are `linux`, `linux-64`, `win`, `mac-intel`, `android`, and `apple-ios`.
The default is selected from the system platform: `win` on Windows, `mac-intel` on macOS, `android` on Android, `apple-ios` on iOS, and `linux-64` or `linux` on other 64-bit or 32-bit systems.
### user_agent
User agent reported to the VPN server when supported by the selected flavor.
The default is flavor-specific. AnyConnect, Network Connect, Pulse, and F5 use `AnyConnect-compatible OpenConnect VPN Agent v9.21`; GlobalProtect uses `PAN GlobalProtect`; Fortinet uses `Mozilla/5.0 SV1`.
### version
Client version reported separately from `user_agent` when supported by the selected flavor.
`v9.21` is used by default. Currently used by AnyConnect XML authentication.
### local_hostname
Local hostname reported to the VPN server when supported by the selected flavor.
The system hostname is used by default, or `localhost` if it is unavailable.
### mobile
AnyConnect mobile client identity. When configured, all three fields are required and are reported during XML authentication and tunnel establishment.
### mobile.platform_version
Mobile operating system version reported to the AnyConnect server.
### mobile.device_type
Mobile device model or type reported to the AnyConnect server.
### mobile.device_unique_id
Mobile device identifier reported to the AnyConnect server.
### csd
AnyConnect CSD/host scan compliance options.
Built-in CSD handling is used by default when requested by the server.
### csd.wrapper_path
Path to an external AnyConnect CSD wrapper executable.
Built-in CSD handling is used if empty.
### hip
GlobalProtect HIP check and report options.
Built-in HIP reporting is used by default when requested by the server.
### hip.wrapper_path
Path to an external GlobalProtect HIP report wrapper executable.
Built-in HIP reporting is used if empty.
### tncc
Network Connect TNCC compliance options.
Built-in TNCC handling is used by default when requested by the server.
### tncc.wrapper_path
Path to an external Network Connect TNCC wrapper executable.
Built-in TNCC handling is used if empty.
Conflict with `tncc.device_id`, `tncc.user_agent`, `tncc.machine_identification_enabled`, and `tncc.certificates`.
### tncc.device_id
Device ID reported by the built-in TNCC handler.
Conflict with `tncc.wrapper_path`.
### tncc.user_agent
User agent used by the built-in TNCC handler.
`Neoteris HC Http` is used by default.
Conflict with `tncc.wrapper_path`.
### tncc.machine_identification_enabled
Enable built-in TNCC machine identification, including the platform, hostname, and observed MAC addresses.
Conflict with `tncc.wrapper_path`.
### tncc.certificates
Machine certificates used by the built-in TNCC handler to answer certificate requests.
Requires `tncc.machine_identification_enabled`.
Conflict with `tncc.wrapper_path`.
### tncc.certificates.certificate
TNCC machine certificate content in PEM format.
Conflict with `tncc.certificates.certificate_path`.
### tncc.certificates.certificate_path
TNCC machine certificate path in PEM format.
Conflict with `tncc.certificates.certificate`.
### fortinet_host_check
Fortinet hostcheck result override.
Hostcheck is disabled by default. It is enabled only when `fortinet_host_check.hostcheck` is non-empty. No operating system, security product, or network interface information is collected automatically.
When enabled and a successful Fortinet login response requests hostcheck, both configured values are submitted to the server before the VPN session is used. The values are sent unchanged as `application/x-www-form-urlencoded` fields.
Some Fortinet servers only request hostcheck from recognized FortiClient user agents. Configure `user_agent` when required by the server policy.
### fortinet_host_check.hostcheck
Fortinet hostcheck result string.
The conventional format is `<security-status>,<os-version>`, for example `0100,10.0.19042`. `security-status` contains four `0` or `1` characters representing, in order, third-party firewall, third-party antivirus, FortiClient firewall, and FortiClient antivirus.
An empty value disables Fortinet hostcheck, even if `fortinet_host_check.check_virtual_desktop` is configured.
### fortinet_host_check.check_virtual_desktop
Fortinet virtual desktop check result string.
FortiClient conventionally sends colon-separated MAC addresses joined by `|`, for example `74:78:27:4d:81:93|84:1b:77:3a:95:84`. An empty value is submitted as an empty field when hostcheck is enabled.
### no_udp
Disable the DTLS or ESP secondary data channel and use the TLS data channel only.
### dtls_local_port
Local UDP port used by the direct DTLS or ESP secondary data channel.
An automatically selected ephemeral port is used by default.
### compression_disabled
Disable AnyConnect compression negotiation.
By default, stateless `oc-lz4` and `lzs` compression is negotiated for CSTP and DTLS when supported by the server.
Compression can weaken traffic confidentiality when an attacker can influence plaintext sent through the VPN tunnel.
Conflict with `compression_mode` set to `all`.
### compression_mode
AnyConnect compression mode, one of:
- `stateless`: Advertise stateless `oc-lz4` and `lzs` compression.
- `all`: Additionally advertise stateful `deflate` compression for CSTP.
`stateless` is used by default. DTLS always uses stateless compression, including when `all` is selected.
Stateful compression has additional traffic confidentiality risks and should only be enabled when required by the VPN server.
### ipv6_disabled
Disable requesting and using IPv6 tunnel configuration.
### http_keepalive_disabled
Disable HTTP connection reuse during authentication and configuration requests.
### xml_post_disabled
Disable AnyConnect XML POST authentication and start authentication with the legacy GET flow.
### external_auth_disabled
Disable external browser authentication such as SSO and SAML for AnyConnect, GlobalProtect, and Fortinet.
When enabled, external authentication is not advertised for AnyConnect or GlobalProtect, and any unexpected external authentication request, including Fortinet SAML, is rejected.
### password_authentication_disabled
Abort AnyConnect authentication if the server returns a non-success authentication form, matching OpenConnect `--no-passwd` behavior.
This does not affect the other flavors or a session supplied by `cookie`.
### tcp_keep_alive_enabled
Enable TCP keep alive for direct VPN server connections.
Disabled by default to match OpenConnect. Setting `tcp_keep_alive` or `tcp_keep_alive_interval` also enables it without requiring this field. When enabled without either duration, the operating system TCP keep alive timing is retained.
Conflict with `disable_tcp_keep_alive`.
### pfs
Require forward-secret TLS cipher suites for TLS 1.2 and earlier.
Disabled by default for compatibility with VPN servers that require RSA key exchange. This does not enable deprecated cipher suites; see `allow_insecure_crypto` for legacy crypto support.
### mtu
Preferred tunnel MTU.
The negotiated MTU is limited to this value for all flavors. For AnyConnect, this value is also sent to the server. GlobalProtect, F5, and Fortinet remove their protocol overhead before using it as the tunnel MTU.
Non-zero values below `576` are treated as `576`. The maximum value is `65535`.
### base_mtu
Base path MTU used to calculate the AnyConnect, GlobalProtect, F5, and Fortinet tunnel MTU after outer IP, transport, and protocol overhead.
`1406` is used by default.
These flavors treat values below `1280` as `1280`. The maximum value is `65535`.
### dpd_interval
Override the Dead Peer Detection interval.
The server-provided or flavor-specific interval is used by default.
Positive values below `2s` are treated as `2s`. The value must not be negative.
### reconnect_timeout
Maximum accumulated backoff time after failed reconnect attempts. The first reconnect attempt starts immediately, and this timeout does not cancel an attempt already in progress.
`300s` is used by default.
The value must not be negative.
### trojan_interval
Override the interval between GlobalProtect HIP reports or Network Connect TNCC checks.
The server-provided interval is used by default. GlobalProtect uses `1h` when the server does not provide one.
The value must not be negative.
### queue_length
Inbound and outbound packet queue length between the VPN transport and the tunnel interface.
`32` is used by default. A full queue applies backpressure until its consumer makes room; queued packets are not discarded.
### allow_insecure_crypto
Enable weak TLS and DTLS cipher suites and TLS 1.0 compatibility required by legacy VPN servers.
Disabled by default; TLS versions below 1.2 are otherwise rejected. This option does not disable server certificate verification.
### tls
OpenConnect TLS configuration.
### tls.insecure
Disable verification of the VPN server certificate and hostname.
Disabled by default. Enabling this permits an active attacker to impersonate the VPN server. Prefer `tls.certificate_authority` or `tls.peer_fingerprint` when possible.
### tls.server_name
Server name used for TLS SNI and certificate hostname verification.
The hostname from `server` is used by default.
### tls.peer_fingerprint
Allowed server certificate fingerprints. A single string or a list can be specified.
Supported formats:
- An unprefixed SHA-1 certificate fingerprint compatible with OpenConnect `--servercert`.
- `sha1:<hex>`: SHA-1 SPKI fingerprint.
- `sha256:<hex>`: SHA-256 SPKI fingerprint.
- `pin-sha256:<base64>`: Base64-encoded SHA-256 SPKI pin.
The encoded fingerprint in every format can be abbreviated to a prefix of at least four characters. When configured, the peer certificate must match one of these fingerprints; a match can authorize a certificate that is not otherwise trusted.
### tls.system_trust_disabled
Disable the system CA certificate pool.
Use `tls.certificate_authority` or `tls.peer_fingerprint` to establish trust when enabled.
### tls.certificate_authority
Additional trusted CA certificate content in PEM format.
The certificates are added to the system certificate pool.
Conflict with `tls.certificate_authority_path`.
### tls.certificate_authority_path
Path to additional trusted CA certificates in PEM format.
The certificates are added to the system certificate pool.
Conflict with `tls.certificate_authority`.
### tls.client_certificate
Client certificate chain content in PEM format.
Conflict with `tls.client_certificate_path`.
### tls.client_certificate_path
Client certificate chain path in PEM format.
Conflict with `tls.client_certificate`.
### tls.client_key
Client private key content in PEM format.
Conflict with `tls.client_key_path`.
### tls.client_key_path
Client private key path in PEM format.
Conflict with `tls.client_key`.
The client certificate and key must both be set or both be empty.
### tls.client_key_password
Password for the encrypted client private key.
### tls.mca_certificate
AnyConnect multiple-certificate authentication (MCA) certificate chain content in PEM format.
Conflict with `tls.mca_certificate_path`.
### tls.mca_certificate_path
AnyConnect multiple-certificate authentication (MCA) certificate chain path in PEM format.
Conflict with `tls.mca_certificate`.
### tls.mca_key
AnyConnect multiple-certificate authentication (MCA) private key content in PEM format.
Conflict with `tls.mca_key_path`.
### tls.mca_key_path
AnyConnect multiple-certificate authentication (MCA) private key path in PEM format.
Conflict with `tls.mca_key`.
The MCA certificate and key must both be set or both be empty.
### tls.mca_key_password
Password for the encrypted MCA private key.
### form_entries
Authentication form field overrides.
An entry matches by `submission_key` when set, or by the combination of `form_id` and `name`. Later matching entries take precedence.
### form_entries.form_id
Authentication form identifier used with `form_entries.name` when `form_entries.submission_key` is empty.
### form_entries.submission_key
Authentication field submission key.
Either `form_entries.submission_key` or both `form_entries.form_id` and `form_entries.name` are required.
### form_entries.name
Authentication field name used with `form_entries.form_id` when `form_entries.submission_key` is empty.
### form_entries.value
Value supplied automatically for the matching authentication field.
Conflict with `form_entries.promote`.
### form_entries.promote
Ask for the matching authentication field interactively instead of supplying an automatic value.
Conflict with `form_entries.value`.
## UDP NAT Fields
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
## Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
## Interactive authentication
Use `Tools` > `Endpoints` in the sing-box dashboard or any sing-box graphical client to authenticate and manage the endpoint.
## DNS
Pushed DNS settings are not installed into the operating system. Configure an [OpenConnect DNS server](/configuration/dns/server/openconnect/) to use them through sing-box.
docs/configuration/endpoint/openconnect.zh.md
+651
View File
@@ -0,0 +1,651 @@
# OpenConnect 客户端
!!! question "自 sing-box 1.14.0 起"
==仅客户端==
## 结构
```json
{
"type": "openconnect",
"tag": "oc-client",
"system": false,
"name": "",
... // UDP NAT 字段
"server": "vpn.example.com",
"flavor": "anyconnect",
"username": "",
"password": "",
"auth_group": "",
"cookie": "",
"token": {
"mode": "",
"secret": "",
"secret_path": "",
"pin": "",
"password": "",
"device_id": "",
"counter": 0
},
"reported_os": "",
"user_agent": "",
"version": "",
"local_hostname": "",
"mobile": {
"platform_version": "",
"device_type": "",
"device_unique_id": ""
},
"csd": {
"wrapper_path": ""
},
"hip": {
"wrapper_path": ""
},
"tncc": {
"wrapper_path": "",
"device_id": "",
"user_agent": "",
"machine_identification_enabled": false,
"certificates": [
{
"certificate": [],
"certificate_path": ""
}
]
},
"fortinet_host_check": {
"hostcheck": "",
"check_virtual_desktop": ""
},
"no_udp": false,
"dtls_local_port": 0,
"compression_disabled": false,
"compression_mode": "",
"ipv6_disabled": false,
"http_keepalive_disabled": false,
"xml_post_disabled": false,
"external_auth_disabled": false,
"password_authentication_disabled": false,
"tcp_keep_alive_enabled": false,
"pfs": false,
"mtu": 0,
"base_mtu": 0,
"dpd_interval": "",
"reconnect_timeout": "",
"trojan_interval": "",
"queue_length": 0,
"allow_insecure_crypto": false,
"tls": {
"insecure": false,
"server_name": "",
"peer_fingerprint": [],
"system_trust_disabled": false,
"certificate_authority": [],
"certificate_authority_path": "",
"client_certificate": [],
"client_certificate_path": "",
"client_key": [],
"client_key_path": "",
"client_key_password": "",
"mca_certificate": [],
"mca_certificate_path": "",
"mca_key": [],
"mca_key_path": "",
"mca_key_password": ""
},
"form_entries": [
{
"form_id": "",
"submission_key": "",
"name": "",
"value": "",
"promote": false
}
],
... // 拨号字段
}
```
!!! note ""
当内容只有一项时，可以忽略 JSON 数组 [] 标签。
## 字段
### system
使用系统接口。
需要权限，且不能与现有系统接口冲突。
禁用时，sing-box 使用内部网络栈。
### name
系统接口的自定义接口名称。
默认使用自动生成的 `oc` 接口名称。
### server
==必填==
OpenConnect VPN 服务器 HTTPS URL。
省略协议时会添加 `https://`。不支持 URL 用户信息、查询和片段。
### flavor
OpenConnect 协议 flavor，可选值为 `anyconnect`、`gp`、`fortinet`、`f5`、`pulse` 或 `nc`。
默认使用 `anyconnect`。
### username
用于填充匹配认证表单字段的用户名。
### password
用于填充匹配认证表单字段的密码。
### auth_group
认证组，用于在所选 flavor 支持时预选匹配的组、realm、domain 或 gateway 选项。
### cookie
用于跳过凭据提示并直接连接的现有认证会话。
接受的格式取决于 `flavor`：
- `anyconnect`：`webvpn` 值，或包含 `webvpn` 的分号分隔 cookie 列表。
- `gp`：GlobalProtect 认证返回的完整 authenticated query string。
- `nc`：`DSID` 值，或包含 `DSID` 的分号分隔 cookie 列表。
- `pulse`：原始 Pulse 认证 cookie 值。
- `f5`：`MRHSession` 值，或包含 `MRHSession` 及可选 `F5_ST` 的分号分隔 cookie 列表。
- `fortinet`：`SVPNCOOKIE` 值，或包含 `SVPNCOOKIE` 的分号分隔 cookie 列表。
如果服务器拒绝提供的会话，将尝试正常认证。
### token
用于自动回答匹配 token 字段或进行 HTTP Bearer 认证的 token 配置。
必须设置 `token.secret` 或 `token.secret_path` 之一。
### token.mode
==必填==
Token 模式，可选值为：
- `totp`：基于时间的一次性密码。
- `hotp`：基于 HMAC 的一次性密码。
- `stoken`：RSA SecurID 软件 token。
- `oidc`：用于 HTTP Bearer 认证的 OIDC access token。
### token.secret
软件 token 密钥。
对于 `totp` 和 `hotp`，可以是 Base32 密钥、带 `base32:` 前缀的密钥或类型匹配的 `otpauth://` URI。
对于 `stoken`，这是编码后的 RSA SecurID CTF token 内容。
对于 `oidc`，这是 access token 值。仅在 VPN 服务器请求 HTTP Bearer 认证后发送。
与 `token.secret_path` 冲突。
### token.secret_path
软件 token 密钥或 OIDC access token 的路径。
与 `token.secret` 冲突。
### token.pin
`stoken` 模式的 RSA SecurID PIN。
### token.password
`stoken` 模式下用于解密受密码保护的 RSA SecurID token 的密码。
### token.device_id
`stoken` 模式下用于解密设备绑定 RSA SecurID token 的设备 ID。
### token.counter
`hotp` 模式的初始计数器。
为零时，如果 `otpauth://` URI 中存在计数器，则使用该计数器；否则从零开始。
### reported_os
所选 flavor 支持时向 VPN 服务器报告的操作系统标识。
对于 `anyconnect`、`gp` 和 `pulse`，支持的值为 `linux`、`linux-64`、`win`、`mac-intel`、`android` 和 `apple-ios`。
默认值根据系统平台选择：Windows 使用 `win`，macOS 使用 `mac-intel`，Android 使用 `android`，iOS 使用 `apple-ios`，其他 64 位或 32 位系统使用 `linux-64` 或 `linux`。
### user_agent
所选 flavor 支持时向 VPN 服务器报告的 User-Agent。
默认值由 flavor 决定。AnyConnect、Network Connect、Pulse 和 F5 使用 `AnyConnect-compatible OpenConnect VPN Agent v9.21`；GlobalProtect 使用 `PAN GlobalProtect`；Fortinet 使用 `Mozilla/5.0 SV1`。
### version
所选 flavor 支持时，与 `user_agent` 分开报告的客户端版本。
默认使用 `v9.21`。当前用于 AnyConnect XML 认证。
### local_hostname
所选 flavor 支持时向 VPN 服务器报告的本地主机名。
默认使用系统主机名；无法获取时使用 `localhost`。
### mobile
AnyConnect 移动客户端身份。配置时三个字段均为必填，并会在 XML 认证和隧道建立阶段报告。
### mobile.platform_version
向 AnyConnect 服务器报告的移动操作系统版本。
### mobile.device_type
向 AnyConnect 服务器报告的移动设备型号或类型。
### mobile.device_unique_id
向 AnyConnect 服务器报告的移动设备标识符。
### csd
AnyConnect CSD/host scan 合规性选项。
服务器请求 CSD 时，默认使用内置 CSD 处理。
### csd.wrapper_path
外部 AnyConnect CSD wrapper 可执行文件的路径。
为空时使用内置 CSD 处理。
### hip
GlobalProtect HIP 检查和报告选项。
服务器请求 HIP 时，默认使用内置 HIP 报告。
### hip.wrapper_path
外部 GlobalProtect HIP report wrapper 可执行文件的路径。
为空时使用内置 HIP 报告。
### tncc
Network Connect TNCC 合规性选项。
服务器请求 TNCC 时，默认使用内置 TNCC 处理。
### tncc.wrapper_path
外部 Network Connect TNCC wrapper 可执行文件的路径。
为空时使用内置 TNCC 处理。
与 `tncc.device_id`、`tncc.user_agent`、`tncc.machine_identification_enabled` 和 `tncc.certificates` 冲突。
### tncc.device_id
内置 TNCC 处理程序报告的设备 ID。
与 `tncc.wrapper_path` 冲突。
### tncc.user_agent
内置 TNCC 处理程序使用的 User-Agent。
默认使用 `Neoteris HC Http`。
与 `tncc.wrapper_path` 冲突。
### tncc.machine_identification_enabled
启用内置 TNCC 机器标识，包括平台、主机名和观测到的 MAC 地址。
与 `tncc.wrapper_path` 冲突。
### tncc.certificates
内置 TNCC 处理程序用于回答证书请求的机器证书。
需要启用 `tncc.machine_identification_enabled`。
与 `tncc.wrapper_path` 冲突。
### tncc.certificates.certificate
PEM 格式的 TNCC 机器证书内容。
与 `tncc.certificates.certificate_path` 冲突。
### tncc.certificates.certificate_path
PEM 格式的 TNCC 机器证书路径。
与 `tncc.certificates.certificate` 冲突。
### fortinet_host_check
Fortinet hostcheck 结果覆盖选项。
默认禁用 hostcheck。仅当 `fortinet_host_check.hostcheck` 非空时启用。不会自动收集操作系统、安全产品或网络接口信息。
启用后，如果成功的 Fortinet 登录响应要求 hostcheck，将在使用 VPN 会话前向服务器提交两个配置值。这些值不经修改，作为 `application/x-www-form-urlencoded` 字段发送。
部分 Fortinet 服务器只会要求可识别的 FortiClient User-Agent 执行 hostcheck。服务器策略有要求时请配置 `user_agent`。
### fortinet_host_check.hostcheck
Fortinet hostcheck 结果字符串。
通常格式为 `<security-status>,<os-version>`，例如 `0100,10.0.19042`。`security-status` 包含四个 `0` 或 `1` 字符，依次表示第三方防火墙、第三方杀毒软件、FortiClient 防火墙和 FortiClient 杀毒软件。
空值会禁用 Fortinet hostcheck，即使配置了 `fortinet_host_check.check_virtual_desktop`。
### fortinet_host_check.check_virtual_desktop
Fortinet virtual desktop 检查结果字符串。
FortiClient 通常发送以冒号分隔的 MAC 地址，多个地址使用 `|` 连接，例如 `74:78:27:4d:81:93|84:1b:77:3a:95:84`。启用 hostcheck 时，空值会作为空字段提交。
### no_udp
禁用 DTLS 或 ESP 辅助数据通道，仅使用 TLS 数据通道。
### dtls_local_port
直连 DTLS 或 ESP 辅助数据通道使用的本地 UDP 端口。
默认自动选择临时端口。
### compression_disabled
禁用 AnyConnect 压缩协商。
默认情况下，当服务器支持时，CSTP 和 DTLS 会协商无状态 `oc-lz4` 和 `lzs` 压缩。
当攻击者能够影响通过 VPN 隧道发送的明文时，压缩可能削弱流量机密性。
与设置为 `all` 的 `compression_mode` 冲突。
### compression_mode
AnyConnect 压缩模式，可选值为：
- `stateless`：声明支持无状态 `oc-lz4` 和 `lzs` 压缩。
- `all`：额外声明支持 CSTP 有状态 `deflate` 压缩。
默认使用 `stateless`。即使选择 `all`，DTLS 也始终使用无状态压缩。
有状态压缩存在额外的流量机密性风险，仅应在 VPN 服务器需要时启用。
### ipv6_disabled
禁用请求和使用 IPv6 隧道配置。
### http_keepalive_disabled
在认证和配置请求中禁用 HTTP 连接复用。
### xml_post_disabled
禁用 AnyConnect XML POST 认证，并直接使用旧版 GET 流程开始认证。
### external_auth_disabled
禁用 AnyConnect、GlobalProtect 和 Fortinet 的 SSO、SAML 等外部浏览器认证。
启用时不会为 AnyConnect 或 GlobalProtect 向服务器声明外部认证支持，并会拒绝任何意外收到的外部认证请求，包括 Fortinet SAML。
### password_authentication_disabled
如果服务器返回非成功的认证表单，则中止 AnyConnect 认证，与 OpenConnect `--no-passwd` 行为一致。
此选项不影响其他 flavor，也不影响由 `cookie` 提供的会话。
### tcp_keep_alive_enabled
为直接 VPN 服务器连接启用 TCP keep alive。
默认禁用以匹配 OpenConnect。设置 `tcp_keep_alive` 或 `tcp_keep_alive_interval` 也会启用，无需同时设置此字段。启用但未设置这两个时间值时，保留操作系统的 TCP keep alive 时间设置。
与 `disable_tcp_keep_alive` 冲突。
### pfs
要求 TLS 1.2 及更早版本使用具有前向保密性的 TLS 密码套件。
默认禁用，以兼容需要 RSA 密钥交换的 VPN 服务器。此选项不会启用已弃用的密码套件；旧版加密支持参阅 `allow_insecure_crypto`。
### mtu
首选隧道 MTU。
所有 flavor 协商的 MTU 都不会超过此值。对于 AnyConnect，此值还会发送给服务器。GlobalProtect、F5 和 Fortinet 会先扣除各自的协议开销，再将结果作为隧道 MTU。
非零值小于 `576` 时按 `576` 处理。最大值为 `65535`。
### base_mtu
扣除外层 IP、传输和协议开销后，用于计算 AnyConnect、GlobalProtect、F5 和 Fortinet 隧道 MTU 的基础路径 MTU。
默认使用 `1406`。
这些 flavor 会将小于 `1280` 的值按 `1280` 处理。最大值为 `65535`。
### dpd_interval
覆盖 Dead Peer Detection 间隔。
默认使用服务器提供或 flavor 特定的间隔。
大于零且小于 `2s` 的值按 `2s` 处理。值不得为负数。
### reconnect_timeout
重连尝试失败后允许累计使用的最大退避时间。断线后的第一次重连会立即开始，且此超时不会取消已经进行中的尝试。
默认使用 `300s`。
值不得为负数。
### trojan_interval
覆盖 GlobalProtect HIP report 或 Network Connect TNCC check 的执行间隔。
默认使用服务器提供的间隔。服务器未提供时，GlobalProtect 使用 `1h`。
值不得为负数。
### queue_length
VPN transport 与隧道接口之间的入站和出站数据包队列长度。
默认使用 `32`。队列已满时会施加反压并等待消费者腾出空间，不会丢弃已排队的数据包。
### allow_insecure_crypto
启用旧版 VPN 服务器所需的弱 TLS 和 DTLS 密码套件及 TLS 1.0 兼容性。
默认禁用；未启用时会拒绝低于 TLS 1.2 的版本。此选项不会禁用服务器证书验证。
### tls
OpenConnect TLS 配置。
### tls.insecure
禁用 VPN 服务器证书和主机名验证。
默认禁用。启用后，主动攻击者可以冒充 VPN 服务器。应尽可能使用 `tls.certificate_authority` 或 `tls.peer_fingerprint`。
### tls.server_name
用于 TLS SNI 和证书主机名验证的服务器名称。
默认使用 `server` 中的主机名。
### tls.peer_fingerprint
允许的服务器证书指纹。可以指定单个字符串或列表。
支持的格式：
- 与 OpenConnect `--servercert` 兼容的无前缀 SHA-1 证书指纹。
- `sha1:<hex>`：SHA-1 SPKI 指纹。
- `sha256:<hex>`：SHA-256 SPKI 指纹。
- `pin-sha256:<base64>`：Base64 编码的 SHA-256 SPKI pin。
每种格式的编码指纹均可缩写为至少四个字符的前缀。配置后，对端证书必须匹配其中一个指纹；匹配的指纹可以授权未通过其他方式信任的证书。
### tls.system_trust_disabled
禁用系统 CA 证书池。
启用时，使用 `tls.certificate_authority` 或 `tls.peer_fingerprint` 建立信任。
### tls.certificate_authority
PEM 格式的附加受信任 CA 证书内容。
这些证书会添加到系统证书池。
与 `tls.certificate_authority_path` 冲突。
### tls.certificate_authority_path
PEM 格式的附加受信任 CA 证书路径。
这些证书会添加到系统证书池。
与 `tls.certificate_authority` 冲突。
### tls.client_certificate
PEM 格式的客户端证书链内容。
与 `tls.client_certificate_path` 冲突。
### tls.client_certificate_path
PEM 格式的客户端证书链路径。
与 `tls.client_certificate` 冲突。
### tls.client_key
PEM 格式的客户端私钥内容。
与 `tls.client_key_path` 冲突。
### tls.client_key_path
PEM 格式的客户端私钥路径。
与 `tls.client_key` 冲突。
客户端证书和私钥必须同时设置或同时为空。
### tls.client_key_password
加密客户端私钥的密码。
### tls.mca_certificate
PEM 格式的 AnyConnect 多证书认证（MCA）证书链内容。
与 `tls.mca_certificate_path` 冲突。
### tls.mca_certificate_path
PEM 格式的 AnyConnect 多证书认证（MCA）证书链路径。
与 `tls.mca_certificate` 冲突。
### tls.mca_key
PEM 格式的 AnyConnect 多证书认证（MCA）私钥内容。
与 `tls.mca_key_path` 冲突。
### tls.mca_key_path
PEM 格式的 AnyConnect 多证书认证（MCA）私钥路径。
与 `tls.mca_key` 冲突。
MCA 证书和私钥必须同时设置或同时为空。
### tls.mca_key_password
加密 MCA 私钥的密码。
### form_entries
认证表单字段覆盖。
设置 `submission_key` 时按该字段匹配，否则按 `form_id` 和 `name` 的组合匹配。后面的匹配项优先。
### form_entries.form_id
`form_entries.submission_key` 为空时，与 `form_entries.name` 一起使用的认证表单标识符。
### form_entries.submission_key
认证字段提交键。
`form_entries.submission_key` 或 `form_entries.form_id` 与 `form_entries.name` 的组合之一必填。
### form_entries.name
`form_entries.submission_key` 为空时，与 `form_entries.form_id` 一起使用的认证字段名称。
### form_entries.value
自动提供给匹配认证字段的值。
与 `form_entries.promote` 冲突。
### form_entries.promote
交互询问匹配的认证字段，而不是自动提供值。
与 `form_entries.value` 冲突。
## UDP NAT 字段
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
## 拨号字段
参阅[拨号字段](/zh/configuration/shared/dial/)了解详情。
## 交互式认证
在 sing-box dashboard 或任意 sing-box 图形客户端的 `工具` > `端点` 中认证和管理 endpoint。
## DNS
推送的 DNS 设置不会安装到操作系统中。配置 [OpenConnect DNS 服务器](/zh/configuration/dns/server/openconnect/) 以通过 sing-box 使用这些设置。
docs/configuration/endpoint/openvpn-client.md
+737
View File
@@ -0,0 +1,737 @@
# OpenVPN Client
!!! question "Since sing-box 1.14.0"
## Structure
```json
{
"type": "openvpn-client",
"tag": "ovpn-client",
"mode": "tls",
"server": "127.0.0.1",
"server_port": 1194,
"servers": [
{
"server": "127.0.0.1",
"server_port": 1194,
"network": "udp"
}
],
"remote_random": false,
"network": "udp",
"address": [],
"peer_address": "",
"peer_address_ipv6": "",
"topology": "",
"username": "",
"password": "",
"auth_retry": "none",
"static_challenge": "",
"static_challenge_echo": false,
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"server_name": "",
"server_name_type": "name",
"certificate": [],
"certificate_path": "",
"client_certificate": [],
"client_certificate_path": "",
"client_key": [],
"client_key_path": "",
"peer_fingerprint": [],
"crl_path": "",
"remote_certificate_ku": [],
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
"groups": "",
"control_wrap": {
"type": "",
"key": [],
"key_path": "",
"direction": ""
}
},
"cipher": "",
"data_ciphers": [],
"data_ciphers_fallback": "",
"auth": "",
"mss_fix": 0,
"mss_fix_disabled": false,
"mss_fix_mode": "",
"fragment": 0,
"replay_window": 0,
"replay_window_time": "",
"compression": "",
"compression_lzo": "",
"allow_compression": "no",
"route_no_pull": false,
"pull_filters": [
{
"action": "ignore",
"text": "route "
}
],
"routes": [],
"route_gateway": "",
"route_metric": 0,
"redirect_gateway": false,
"redirect_gateway_flags": [],
"redirect_private": false,
"block_ipv6": false,
"ping_interval": "",
"ping_restart": "",
"ping_restart_disabled": false,
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"tls_timeout": "",
"handshake_window": "",
"explicit_exit_notify": 0,
"system": false,
"name": "",
"mtu": 1500,
... // UDP NAT Fields
... // Dial Fields
}
```
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item.
## Fields
### mode
OpenVPN session mode, one of `tls` or `static_key`.
`tls` is used by default.
`static_key` is a deprecated OpenVPN mode without a TLS control channel or
forward secrecy. It is retained as an explicit compatibility option for
immutable enterprise VPN servers. It does not use `tls`, username/password
authentication, pull options, or TLS renegotiation options.
### server
OpenVPN server address.
Either `server` or `servers` is required.
Conflict with `servers`.
### server_port
OpenVPN server port.
Required when `server` is set.
### servers
List of OpenVPN servers.
The client tries the servers in order and moves to the next server when a connection fails.
Either `server` or `servers` is required.
Conflict with `server`.
### servers.server
==Required==
OpenVPN server address.
### servers.server_port
==Required==
OpenVPN server port.
### servers.network
OpenVPN transport network for this server, one of `udp` or `tcp`.
The top-level `network` is used by default.
### remote_random
Randomize the `servers` order before connecting.
Disabled by default.
### network
Default OpenVPN transport network, one of `udp` or `tcp`.
`udp` is used by default.
This value applies to `server` and to `servers` entries without their own `network`.
### address
Local IPv4 and IPv6 tunnel prefixes.
At least one address is required in `static_key` mode. In TLS mode these
addresses are optional and can be replaced by addresses pulled from the
server.
### peer_address
IPv4 tunnel peer address and VPN gateway.
Required when an IPv4 `address` is configured in `static_key` mode.
### peer_address_ipv6
IPv6 tunnel peer address and VPN gateway.
Required when an IPv6 `address` is configured in `static_key` mode.
### topology
Tunnel topology, one of `net30`, `p2p`, or `subnet`.
The topology pulled from the server is used when empty in TLS mode.
### username
Username for OpenVPN username/password authentication.
Only available in TLS mode.
### password
Password for OpenVPN username/password authentication.
### auth_retry
Behavior after username/password authentication fails, one of `none`, `nointeract`, or `interact`.
`none` is used by default and treats a permanent authentication failure as terminal.
`nointeract` and `interact` allow authentication retries.
### static_challenge
Static challenge text shown when requesting an authentication response.
### static_challenge_echo
Show the static challenge response as plain text.
### static_key
OpenVPN static key content.
Required in `static_key` mode.
Conflict with `static_key_path`.
### static_key_path
OpenVPN static key path.
Required in `static_key` mode when `static_key` is not set.
Conflict with `static_key`.
### key_direction
Static key direction, one of `server` or `client`.
The key is used bidirectionally if empty. Only available in `static_key` mode.
### tls
Required in TLS mode.
OpenVPN control channel TLS configuration.
### tls.server_name
Expected server certificate name.
Certificate name verification is disabled if empty. The certificate chain or fingerprint and server certificate usage are still verified.
### tls.server_name_type
Certificate field matched by `tls.server_name`, one of `subject`, `name`, or `name-prefix`.
`name` is used by default when `tls.server_name` is set.
`subject` matches the full certificate subject, `name` matches the common name exactly, and `name-prefix` matches a common name prefix.
### tls.certificate
Trusted CA certificate content.
One of `tls.certificate`, `tls.certificate_path`, or `tls.peer_fingerprint` is required.
Conflict with `tls.certificate_path`.
### tls.certificate_path
Trusted CA certificate path.
One of `tls.certificate`, `tls.certificate_path`, or `tls.peer_fingerprint` is required.
Conflict with `tls.certificate`.
### tls.client_certificate
Client certificate content.
Conflict with `tls.client_certificate_path`.
### tls.client_certificate_path
Client certificate path.
Conflict with `tls.client_certificate`.
### tls.client_key
Client private key content.
Conflict with `tls.client_key_path`.
### tls.client_key_path
Client private key path.
Conflict with `tls.client_key`.
The client certificate and key must both be set or both be empty.
### tls.peer_fingerprint
Allowed SHA-256 fingerprints of the server leaf certificate.
Each fingerprint must be 64 lowercase hexadecimal characters without separators.
When a trusted CA is also configured, both the certificate chain and fingerprint are verified. Without a trusted CA, the fingerprint, certificate validity period, configured name, and certificate usage are verified, but the certificate chain is not.
### tls.crl_path
Path to a PEM or DER certificate revocation list used to reject revoked server certificates.
The CRL signature and validity period are verified against the trusted certificate chain.
Disabled by default.
### tls.remote_certificate_ku
Required server certificate key usage masks, written as hexadecimal values in OpenVPN `remote-cert-ku` format.
The certificate must contain all bits from at least one configured mask.
Disabled by default.
### tls.remote_certificate_eku
Required server certificate extended key usage.
OpenSSL names, object identifiers, and the aliases `server` and `client` are accepted.
When set, this field replaces the default `tls.remote_certificate_tls` check.
Conflict with an explicitly configured `tls.remote_certificate_tls`.
### tls.remote_certificate_tls
Peer certificate purpose check, one of `server`, `client`, or `none`.
`server` is used by default.
`none` disables the certificate purpose check.
Conflict with `tls.remote_certificate_eku`.
### tls.certificate_profile
Certificate profile, one of `insecure`, `legacy`, `preferred`, or `suiteb`.
`legacy` is used by default.
`insecure` accepts MD5- and SHA-1-signed certificate chains and smaller legacy
keys for compatibility with immutable peers. Use it only when the peer cannot
be upgraded. `legacy` accepts SHA-1 but rejects MD5 signatures; `preferred`
requires stronger signatures and keys.
When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. Explicit `tls.cipher` and `tls.groups` values are not restricted by the profile.
### tls.ns_certificate_type
Deprecated Netscape certificate type check, one of `server` or `client`.
Disabled by default. Prefer `tls.remote_certificate_tls`.
### tls.version_min
Minimum TLS version, one of `1.0`, `1.1`, `1.2`, or `1.3`.
`1.2` is used by default.
### tls.version_max
Maximum TLS version, one of `1.0`, `1.1`, `1.2`, or `1.3`.
The maximum supported version is used by default.
The value cannot be lower than `tls.version_min`.
### tls.cipher
Colon-separated OpenSSL cipher suite names allowed for TLS 1.2 and earlier.
The default TLS cipher suites are used when empty. TLS 1.3 cipher suites are not controlled by this field.
### tls.groups
Colon-separated TLS key exchange groups in preference order.
Supported groups are `X25519`, `SECP256R1`, `SECP384R1`, and `SECP521R1`, including their common OpenSSL and NIST aliases.
The default TLS groups are used when empty.
### tls.control_wrap
OpenVPN control channel wrapping.
Equivalent to OpenVPN `tls-auth`, `tls-crypt`, and `tls-crypt-v2`.
Disabled if empty.
### tls.control_wrap.type
Control channel wrapping type, one of `tls_auth`, `tls_crypt`, or `tls_crypt_v2`.
### tls.control_wrap.key
Control channel wrapping key content.
Conflict with `tls.control_wrap.key_path`.
### tls.control_wrap.key_path
Control channel wrapping key path.
Conflict with `tls.control_wrap.key`.
### tls.control_wrap.direction
`tls-auth` key direction, one of `server` or `client`.
Only available when `tls.control_wrap.type` is `tls_auth`. The key is used bidirectionally if empty.
### cipher
Data-channel cipher used in `static_key` mode.
The upstream static-key default `BF-CBC` is used when empty. `BF-CBC` is a
legacy cipher with a 64-bit block size; configure the cipher required by the
server explicitly whenever possible. Static-key ciphers include `BF-CBC`,
`CAST5-CBC`, `DES-CBC`, `DES-EDE-CBC`, `DES-EDE3-CBC`, the AES-CBC,
ARIA-CBC, and Camellia-CBC families, `SEED-CBC`, `SM4-CBC`, and `NONE`.
Only available in `static_key` mode. `NONE` provides no confidentiality.
### data_ciphers
Allowed OpenVPN data channel ciphers.
Only available in TLS mode.
`AES-256-GCM`, `AES-128-GCM`, and `CHACHA20-POLY1305` are used by default.
The AES-GCM family includes `AES-192-GCM`. Retained ciphers include the CBC,
CFB, and OFB forms of AES, ARIA, Camellia, DES, Blowfish, and CAST5, the CBC,
CFB, and OFB forms of SEED and SM4, and `NONE`. CFB and OFB are available only
in TLS mode. Legacy ciphers provide weaker or no confidentiality and are not
enabled by default.
### data_ciphers_fallback
Data channel cipher for peers that do not support cipher negotiation.
Disabled by default.
Only available in TLS mode.
### auth
OpenVPN data channel authentication digest.
`SHA1` is used by default. It only applies to non-AEAD data ciphers and `tls_auth`.
Legacy digests including `MD5` and `RIPEMD160` remain available when explicitly
configured for compatibility.
### mss_fix
Maximum OpenVPN UDP packet size used to clamp the MSS of TCP connections sent through the tunnel.
This prevents TCP packets from exceeding the path MTU after OpenVPN encapsulation.
When empty, the upstream OpenVPN default is used: `fragment` when configured,
otherwise `1492` for the default tunnel MTU or the configured tunnel MTU.
### mss_fix_disabled
Disable MSS clamping, including the default clamp.
Conflict with `mss_fix` and `mss_fix_mode`.
### mss_fix_mode
OpenVPN MSS calculation mode for an explicit `mss_fix`, one of `mtu` or `fixed`.
An empty value uses the normal OpenVPN encapsulation-aware calculation. `mtu` also accounts for the outer IP and UDP/TCP transport headers. `fixed` treats `mss_fix` as an inner IPv4 packet size.
Requires `mss_fix`.
### fragment
Maximum OpenVPN UDP packet size used for OpenVPN data channel fragmentation.
Disabled when `0`. A non-zero value must be at least `68`.
Conflict with TCP transport.
### replay_window
UDP data-channel replay window size. `64` is used by default. The maximum is `65536`.
TCP always requires strictly consecutive packet IDs.
### replay_window_time
UDP data-channel replay window duration. `15s` is used by default and the maximum is `10m`.
The value must use whole seconds.
### compression
OpenVPN `compress` framing mode, one of `none`, `no`, `lz4`, `lz4-v2`, `stub`, `stub-v2`, `disabled`, or `off`.
Disabled by default.
Compression can weaken traffic confidentiality. Prefer `stub` or `stub-v2` only when framing compatibility is required.
### compression_lzo
OpenVPN `comp-lzo` mode, one of `none`, `no`, `yes`, `adaptive`, `asym`, `disabled`, or `off`.
Disabled by default.
Compression can weaken traffic confidentiality. Enable it only when required by the server.
### allow_compression
Policy for compression pushed by the server, one of `no`, `asym`, or `yes`.
`no` is used by default and permits only compression stub framing. `asym` accepts compressed packets from the server but does not compress outgoing packets. For OpenVPN 2.7 compatibility, `yes` is accepted as a legacy alias for `asym`; the client never sends compressed packets.
Conflict with non-stub compression enabled by `compression` or `compression_lzo` when set to `no`.
### route_no_pull
Ignore routes, DNS and DHCP settings, route metrics, `redirect-gateway`,
`redirect-private`, `block-ipv6`, and `block-outside-dns` pushed by the server.
Interface configuration, topology, tunnel MTU, `route-gateway`, and locally configured routes are still used.
Disabled by default.
### pull_filters
Ordered filters for options pushed by the server.
The first filter whose `text` is a case-sensitive prefix of the complete pushed option is applied. Options that match no filter are accepted.
### pull_filters.action
==Required==
Filter action, one of `accept`, `ignore`, or `reject`.
`accept` applies the option, `ignore` discards it, and `reject` terminates the connection.
### pull_filters.text
==Required==
Case-sensitive prefix to match against the pushed option name and value.
For example, `route ` matches pushed IPv4 route options without matching `route-gateway`.
### routes
IPv4 and IPv6 prefixes preferred by sing-box routing for this OpenVPN endpoint.
These routes are used in addition to routes accepted from the server.
They do not install operating-system routes. Select the endpoint through
sing-box route rules or its preferred-route behavior.
### route_gateway
IPv4 gateway for routes through the OpenVPN endpoint.
When empty, the VPN gateway received from the server is used.
The value is retained for OpenVPN configuration compatibility; endpoint route
preference is prefix-based and does not install a system gateway route.
### route_metric
Default metric for routes through the OpenVPN endpoint.
The platform default is used when `0`.
The value is retained for OpenVPN configuration compatibility and does not
install a system route.
### redirect_gateway
Prefer the OpenVPN endpoint for all IPv4 destinations in sing-box routing.
Disabled by default.
This does not install an operating-system default route.
### redirect_gateway_flags
OpenVPN `redirect-gateway` flags.
`!ipv4` disables IPv4 preference, `def1` represents it with two `/1`
prefixes, and `ipv6` also prefers the upstream-specific IPv6 prefixes. The
OpenVPN control connection always uses its configured outbound dialer rather
than endpoint routes, so `local` and `autolocal` require no system-route
exception. `bypass-dhcp` and `bypass-dns` are not applicable because sing-box
does not install pushed DHCP or DNS settings into the operating system.
`block-local` is unsupported because the endpoint has no cross-platform source
for the physical default gateway needed to preserve the gateway exception.
Empty by default.
### redirect_private
Accept `redirect_gateway_flags` without adding a default-route preference. Routes pushed or configured separately still affect the endpoint's preferred addresses, but no operating-system routes are installed.
Disabled by default.
### block_ipv6
Reject IPv6 traffic locally instead of sending it through the VPN.
Disabled by default.
### ping_interval
Interval after which the client sends a data-channel ping when no packet has been sent to the server.
A server-pushed OpenVPN `ping` value overrides this value.
The value must use whole seconds.
Disabled by default.
### ping_restart
Time without receiving a packet after which the client reconnects to the server.
A server-pushed OpenVPN `ping-restart` value overrides this value.
The value must use whole seconds.
When empty, `120s` is used for UDP connections with pull enabled until the
server pushes another value. No default receive timeout is used for TCP.
### ping_restart_disabled
Disable the initial `120s` UDP pull timeout and any locally configured ping restart timeout.
Conflict with `ping_restart`.
### renegotiate_interval
OpenVPN TLS renegotiation interval.
When empty, the OpenVPN default `1h` is used.
### renegotiate_disabled
Disable time-based TLS renegotiation, including the default interval.
Conflict with `renegotiate_interval`.
### renegotiate_bytes
Renegotiate data-channel keys after this many bytes. `0` uses the cipher-dependent OpenVPN default.
### renegotiate_packets
Renegotiate data-channel keys after this many packets. `0` uses the cipher-dependent OpenVPN default.
### tls_timeout
Initial retransmission timeout for TLS control packets. The OpenVPN default `2s` is used when empty.
### handshake_window
Maximum time allowed for the initial TLS handshake and each renegotiation. The OpenVPN default `1m` is used when empty.
### explicit_exit_notify
Number of OpenVPN exit notifications sent when closing a UDP connection.
Notifications are sent one second apart. Disabled when `0`.
### system
Use a system interface.
Requires privilege and cannot conflict with existing system interfaces.
The endpoint configures interface addresses and MTU but does not install
operating-system routes or DNS settings.
If disabled, sing-box uses the internal network stack.
### name
Custom interface name for the system interface.
An automatically generated `ovpn` interface name is used by default.
### mtu
OpenVPN interface MTU.
When empty, `1500` is used until a server-pushed MTU is received.
## UDP NAT Fields
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
## Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
## Interactive authentication
Use `Tools` > `Endpoints` in the sing-box dashboard or any sing-box graphical client to authenticate and manage the endpoint.
docs/configuration/endpoint/openvpn-client.zh.md
+712
View File
@@ -0,0 +1,712 @@
# OpenVPN 客户端
!!! question "自 sing-box 1.14.0 起"
## 结构
```json
{
"type": "openvpn-client",
"tag": "ovpn-client",
"mode": "tls",
"server": "127.0.0.1",
"server_port": 1194,
"servers": [
{
"server": "127.0.0.1",
"server_port": 1194,
"network": "udp"
}
],
"remote_random": false,
"network": "udp",
"address": [],
"peer_address": "",
"peer_address_ipv6": "",
"topology": "",
"username": "",
"password": "",
"auth_retry": "none",
"static_challenge": "",
"static_challenge_echo": false,
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"server_name": "",
"server_name_type": "name",
"certificate": [],
"certificate_path": "",
"client_certificate": [],
"client_certificate_path": "",
"client_key": [],
"client_key_path": "",
"peer_fingerprint": [],
"crl_path": "",
"remote_certificate_ku": [],
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
"groups": "",
"control_wrap": {
"type": "",
"key": [],
"key_path": "",
"direction": ""
}
},
"cipher": "",
"data_ciphers": [],
"data_ciphers_fallback": "",
"auth": "",
"mss_fix": 0,
"mss_fix_disabled": false,
"mss_fix_mode": "",
"fragment": 0,
"replay_window": 0,
"replay_window_time": "",
"compression": "",
"compression_lzo": "",
"allow_compression": "no",
"route_no_pull": false,
"pull_filters": [
{
"action": "ignore",
"text": "route "
}
],
"routes": [],
"route_gateway": "",
"route_metric": 0,
"redirect_gateway": false,
"redirect_gateway_flags": [],
"redirect_private": false,
"block_ipv6": false,
"ping_interval": "",
"ping_restart": "",
"ping_restart_disabled": false,
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"tls_timeout": "",
"handshake_window": "",
"explicit_exit_notify": 0,
"system": false,
"name": "",
"mtu": 1500,
... // UDP NAT 字段
... // 拨号字段
}
```
!!! note ""
当内容只有一项时，可以忽略 JSON 数组 [] 标签。
## 字段
### mode
OpenVPN 会话模式，可选值为 `tls` 或 `static_key`。
默认使用 `tls`。
`static_key` 是已弃用的 OpenVPN 模式，不使用 TLS 控制通道且不提供前向保密。
为兼容无法修改的企业 VPN 服务器，此模式仍作为显式兼容选项保留。该模式不使用
`tls`、用户名/密码认证、拉取选项或 TLS 重协商选项。
### server
OpenVPN 服务器地址。
`server` 和 `servers` 之一必填。
与 `servers` 冲突。
### server_port
OpenVPN 服务器端口。
设置 `server` 时必填。
### servers
OpenVPN 服务器列表。
客户端按顺序尝试服务器，并在连接失败时尝试下一台服务器。
`server` 和 `servers` 之一必填。
与 `server` 冲突。
### servers.server
==必填==
OpenVPN 服务器地址。
### servers.server_port
==必填==
OpenVPN 服务器端口。
### servers.network
该服务器的 OpenVPN 传输网络，可选值为 `udp` 或 `tcp`。
默认使用顶层 `network`。
### remote_random
连接前随机排列 `servers` 顺序。
默认禁用。
### network
默认 OpenVPN 传输网络，可选值为 `udp` 或 `tcp`。
默认使用 `udp`。
该值应用于 `server` 和未单独设置 `network` 的 `servers` 条目。
### address
本地 IPv4 和 IPv6 隧道前缀。
`static_key` 模式至少需要一个地址。在 TLS 模式下该字段可选，并可被服务器推送的地址替换。
### peer_address
IPv4 隧道对端地址及 VPN 网关。
在 `static_key` 模式下配置 IPv4 `address` 时必填。
### peer_address_ipv6
IPv6 隧道对端地址及 VPN 网关。
在 `static_key` 模式下配置 IPv6 `address` 时必填。
### topology
隧道拓扑，可选值为 `net30`、`p2p` 或 `subnet`。
TLS 模式下为空时使用服务器推送的拓扑。
### username
OpenVPN 用户名/密码认证的用户名。
仅在 TLS 模式下可用。
### password
OpenVPN 用户名/密码认证的密码。
### auth_retry
用户名/密码认证失败后的行为，可选值为 `none`、`nointeract` 或 `interact`。
默认使用 `none`，并将永久认证失败视为终止错误。
`nointeract` 和 `interact` 允许重试认证。
### static_challenge
请求认证响应时显示的静态质询文本。
### static_challenge_echo
以明文显示静态质询响应。
### static_key
OpenVPN 静态密钥内容。
在 `static_key` 模式下必填。
与 `static_key_path` 冲突。
### static_key_path
OpenVPN 静态密钥路径。
在 `static_key` 模式下未设置 `static_key` 时必填。
与 `static_key` 冲突。
### key_direction
静态密钥方向，可选值为 `server` 或 `client`。
为空时双向使用密钥。仅在 `static_key` 模式下可用。
### tls
在 TLS 模式下必填。
OpenVPN 控制通道 TLS 配置。
### tls.server_name
预期的服务器证书名称。
为空时禁用证书名称验证，但仍会验证证书链或 fingerprint 与服务器证书用途。
### tls.server_name_type
与 `tls.server_name` 匹配的证书字段，可选值为 `subject`、`name` 或 `name-prefix`。
设置 `tls.server_name` 时默认使用 `name`。
`subject` 匹配完整证书 subject，`name` 精确匹配 common name，`name-prefix` 匹配 common name 前缀。
### tls.certificate
受信任 CA 证书内容。
`tls.certificate`、`tls.certificate_path` 和 `tls.peer_fingerprint` 之一必填。
与 `tls.certificate_path` 冲突。
### tls.certificate_path
受信任 CA 证书路径。
`tls.certificate`、`tls.certificate_path` 和 `tls.peer_fingerprint` 之一必填。
与 `tls.certificate` 冲突。
### tls.client_certificate
客户端证书内容。
与 `tls.client_certificate_path` 冲突。
### tls.client_certificate_path
客户端证书路径。
与 `tls.client_certificate` 冲突。
### tls.client_key
客户端私钥内容。
与 `tls.client_key_path` 冲突。
### tls.client_key_path
客户端私钥路径。
与 `tls.client_key` 冲突。
客户端证书和私钥必须同时设置或同时为空。
### tls.peer_fingerprint
允许的服务器 leaf certificate 的 SHA-256 fingerprint。
每个 fingerprint 必须是不带分隔符的 64 字符小写十六进制字符串。
同时配置受信任 CA 时，会同时验证证书链和 fingerprint。未配置受信任 CA 时，会验证 fingerprint、证书有效期、配置的名称和证书用途，但不验证证书链。
### tls.crl_path
用于拒绝已吊销服务器证书的 PEM 或 DER CRL 文件路径。
根据受信任证书链验证 CRL 签名和有效期。
默认禁用。
### tls.remote_certificate_ku
服务器证书所需的 Key Usage mask，使用 OpenVPN `remote-cert-ku` 格式的十六进制值。
证书必须包含至少一个已配置 mask 中的所有 bit。
默认禁用。
### tls.remote_certificate_eku
服务器证书所需的 Extended Key Usage。
接受 OpenSSL 名称、Object Identifier 以及 `server` 和 `client` 别名。
设置后，该字段会替代默认的 `tls.remote_certificate_tls` 检查。
与显式配置的 `tls.remote_certificate_tls` 冲突。
### tls.remote_certificate_tls
对端证书用途检查，可选值为 `server`、`client` 或 `none`。
默认使用 `server`。
`none` 禁用证书用途检查。
与 `tls.remote_certificate_eku` 冲突。
### tls.certificate_profile
证书 profile，可选值为 `insecure`、`legacy`、`preferred` 或 `suiteb`。
默认使用 `legacy`。
`insecure` 为兼容不可变对端而接受使用 MD5 或 SHA-1 签名的证书链和较小的旧密钥，仅应在对端无法升级时使用。`legacy` 接受 SHA-1 但拒绝 MD5 签名；`preferred` 要求更强的签名和密钥。
选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。该 profile 不限制显式配置的 `tls.cipher` 和 `tls.groups`。
### tls.ns_certificate_type
已弃用的 Netscape 证书类型检查，`server` 或 `client` 之一。
默认禁用。请优先使用 `tls.remote_certificate_tls`。
### tls.version_min
最低 TLS 版本，可选值为 `1.0`、`1.1`、`1.2` 或 `1.3`。
默认使用 `1.2`。
### tls.version_max
最高 TLS 版本，可选值为 `1.0`、`1.1`、`1.2` 或 `1.3`。
默认使用支持的最高版本。
该值不能低于 `tls.version_min`。
### tls.cipher
TLS 1.2 及更低版本允许的 OpenSSL cipher suite 名称，以冒号分隔。
为空时使用默认 TLS cipher suite。该字段不控制 TLS 1.3 cipher suite。
### tls.groups
按偏好顺序排列的 TLS key exchange group，以冒号分隔。
支持 `X25519`、`SECP256R1`、`SECP384R1` 和 `SECP521R1`，包括其常用 OpenSSL 和 NIST 别名。
为空时使用默认 TLS group。
### tls.control_wrap
OpenVPN 控制通道封装。
等价于 OpenVPN `tls-auth`、`tls-crypt` 和 `tls-crypt-v2`。
为空时禁用。
### tls.control_wrap.type
控制通道封装类型，可选值为 `tls_auth`、`tls_crypt` 或 `tls_crypt_v2`。
### tls.control_wrap.key
控制通道封装密钥内容。
与 `tls.control_wrap.key_path` 冲突。
### tls.control_wrap.key_path
控制通道封装密钥路径。
与 `tls.control_wrap.key` 冲突。
### tls.control_wrap.direction
`tls-auth` 密钥方向，可选值为 `server` 或 `client`。
仅当 `tls.control_wrap.type` 为 `tls_auth` 时可用。为空时双向使用密钥。
### cipher
`static_key` 模式使用的数据通道 cipher。
为空时使用上游静态密钥模式的默认值 `BF-CBC`。`BF-CBC` 是采用 64 位 block size
的旧 cipher；应尽可能显式配置服务器要求的 cipher。静态密钥 cipher 包括
`BF-CBC`、`CAST5-CBC`、`DES-CBC`、`DES-EDE-CBC`、`DES-EDE3-CBC`、
AES-CBC、ARIA-CBC、Camellia-CBC 系列，以及 `SEED-CBC`、`SM4-CBC` 和 `NONE`。
仅在 `static_key` 模式下可用。`NONE` 不提供机密性。
### data_ciphers
允许的 OpenVPN 数据通道 cipher。
仅在 TLS 模式下可用。
默认使用 `AES-256-GCM`、`AES-128-GCM` 和 `CHACHA20-POLY1305`。
AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。旧 cipher 只能提供较弱的机密性或完全不加密，因此默认不启用。
### data_ciphers_fallback
用于不支持 cipher 协商的对端的数据通道 cipher。
默认禁用。
仅在 TLS 模式下可用。
### auth
OpenVPN 数据通道认证摘要。
默认使用 `SHA1`，仅应用于非 AEAD 数据 cipher 和 `tls_auth`。
为兼容既有服务器，显式配置时仍可使用 `MD5` 和 `RIPEMD160` 等旧摘要。
### mss_fix
OpenVPN UDP packet 的最大大小，用于限制通过隧道发送的 TCP 连接 MSS。
这可以避免 TCP packet 在 OpenVPN 封装后超过 path MTU。
为空时使用上游 OpenVPN 默认值：配置了 `fragment` 时使用其值；否则默认 tunnel MTU 使用 `1492`，自定义 tunnel MTU 使用该 MTU。
### mss_fix_disabled
禁用 MSS 限制，包括默认限制。
与 `mss_fix` 和 `mss_fix_mode` 冲突。
### mss_fix_mode
显式 `mss_fix` 的 OpenVPN MSS 计算模式，`mtu` 或 `fixed` 之一。
空值使用普通的 OpenVPN 封装开销计算。`mtu` 还会计算外层 IP 和 UDP/TCP 传输头；`fixed` 将 `mss_fix` 视为内层 IPv4 数据包大小。
需要 `mss_fix`。
### fragment
用于 OpenVPN 数据通道 fragmentation 的最大 OpenVPN UDP packet 大小。
设为 `0` 时禁用。非零值必须至少为 `68`。
与 TCP 传输冲突。
### replay_window
UDP 数据通道重放窗口大小。默认使用 `64`，最大值为 `65536`。
TCP 始终要求数据包 ID 严格连续。
### replay_window_time
UDP 数据通道重放窗口时长。默认使用 `15s`，最大值为 `10m`。
该值必须使用整秒。
### compression
OpenVPN `compress` framing 模式，可选值为 `none`、`no`、`lz4`、`lz4-v2`、`stub`、`stub-v2`、`disabled` 或 `off`。
默认禁用。
Compression 可能削弱流量机密性。仅在需要 framing 兼容性时使用 `stub` 或 `stub-v2`。
### compression_lzo
OpenVPN `comp-lzo` 模式，可选值为 `none`、`no`、`yes`、`adaptive`、`asym`、`disabled` 或 `off`。
默认禁用。
Compression 可能削弱流量机密性。仅在服务器要求时启用。
### allow_compression
服务器推送的 compression 策略，可选值为 `no`、`asym` 或 `yes`。
默认使用 `no`，仅允许 compression stub framing。`asym` 接受来自服务器的 compressed packet，但不压缩出站 packet。为兼容 OpenVPN 2.7，`yes` 作为 `asym` 的旧别名接受；客户端绝不会发送 compressed packet。
当设为 `no` 时，与通过 `compression` 或 `compression_lzo` 启用的非 stub compression 冲突。
### route_no_pull
忽略服务器推送的 route、DNS 和 DHCP 设置、route metric、`redirect-gateway`、
`redirect-private`、`block-ipv6` 和 `block-outside-dns`。
仍会使用接口配置、topology、tunnel MTU、`route-gateway` 和本地配置的 route。
默认禁用。
### pull_filters
服务器推送选项的有序 pull filter 列表。
应用第一个 `text` 为完整推送选项大小写敏感前缀的 filter。未匹配任何 filter 的选项会被接受。
### pull_filters.action
==必填==
Filter action，可选值为 `accept`、`ignore` 或 `reject`。
`accept` 应用选项，`ignore` 丢弃选项，`reject` 终止连接。
### pull_filters.text
==必填==
用于匹配推送选项名称和值的大小写敏感前缀。
例如，`route ` 会匹配推送的 IPv4 route 选项，但不会匹配 `route-gateway`。
### routes
sing-box 路由优先选择此 OpenVPN endpoint 的 IPv4 和 IPv6 前缀。
这些 route 会与从服务器接受的 route 一起使用。
它们不会安装操作系统路由。请通过 sing-box 路由规则或 endpoint 的首选路由行为选择此 endpoint。
### route_gateway
通过 OpenVPN endpoint 路由的 IPv4 gateway。
为空时使用从服务器接收的 VPN gateway。
该值仅为兼容 OpenVPN 配置而保留；endpoint 的路由偏好只按前缀判断，不会安装系统 gateway 路由。
### route_metric
通过 OpenVPN endpoint 路由的默认 metric。
设为 `0` 时使用平台默认值。
该值仅为兼容 OpenVPN 配置而保留，不会安装系统路由。
### redirect_gateway
在 sing-box 路由中对所有 IPv4 目的地优先选择 OpenVPN endpoint。
默认禁用。
这不会安装操作系统默认路由。
### redirect_gateway_flags
OpenVPN `redirect-gateway` flag。
`!ipv4` 禁用 IPv4 偏好，`def1` 使用两个 `/1` 前缀表示，`ipv6` 还会优先选择上游特定的 IPv6 前缀。OpenVPN 控制连接始终使用其配置的出站拨号器，不经过 endpoint 路由，因此 `local` 和 `autolocal` 不需要系统路由例外。由于 sing-box 不会把推送的 DHCP 或 DNS 设置安装到操作系统，`bypass-dhcp` 和 `bypass-dns` 不适用。`block-local` 不受支持，因为 endpoint 没有可跨平台获取物理默认网关的来源，无法保留网关例外。
默认为空。
### redirect_private
接受 `redirect_gateway_flags`，但不添加默认路由偏好。单独推送或配置的路由仍会影响 endpoint 的首选地址，但不会安装操作系统路由。
默认禁用。
### block_ipv6
在本地拒绝 IPv6 流量，而不是通过 VPN 发送。
默认禁用。
### ping_interval
客户端未向服务器发送任何 packet 时，发送 data channel ping 的间隔。
服务器推送的 OpenVPN `ping` 值优先于该值。
该值必须使用整秒。
默认禁用。
### ping_restart
客户端未收到任何 packet 后重新连接服务器的时间。
服务器推送的 OpenVPN `ping-restart` 值优先于该值。
该值必须使用整秒。
为空时，启用了 pull 的 UDP 连接会使用 `120s`，直到服务器推送其他值。TCP 不使用默认接收超时。
### ping_restart_disabled
禁用初始 `120s` UDP 拉取超时和本地配置的 ping 重启超时。
与 `ping_restart` 冲突。
### renegotiate_interval
OpenVPN TLS 重新协商间隔。
为空时使用 OpenVPN 默认值 `1h`。
### renegotiate_disabled
禁用基于时间的 TLS 重新协商，包括默认间隔。
与 `renegotiate_interval` 冲突。
### renegotiate_bytes
传输指定字节数后重新协商数据通道密钥。`0` 使用与密码算法相关的 OpenVPN 默认值。
### renegotiate_packets
传输指定数据包数后重新协商数据通道密钥。`0` 使用与密码算法相关的 OpenVPN 默认值。
### tls_timeout
TLS 控制数据包的初始重传超时。为空时使用 OpenVPN 默认值 `2s`。
### handshake_window
初始 TLS 握手及每次重新协商的最长允许时间。为空时使用 OpenVPN 默认值 `1m`。
### explicit_exit_notify
关闭 UDP 连接时发送的 OpenVPN exit notification 数量。
Notification 之间间隔一秒。设为 `0` 时禁用。
### system
使用系统接口。
需要权限，且不能与现有系统接口冲突。
endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。
禁用时，sing-box 使用内部网络栈。
### name
系统接口的自定义接口名称。
默认使用自动生成的 `ovpn` 接口名称。
### mtu
OpenVPN 接口 MTU。
为空时使用服务器推送的 MTU；收到服务器配置前使用 `1500`。
## UDP NAT 字段
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
## 拨号字段
参阅[拨号字段](/zh/configuration/shared/dial/)。
## 交互式认证
在 sing-box dashboard 或任意 sing-box 图形客户端的 `工具` > `端点` 中认证和管理 endpoint。
docs/configuration/endpoint/openvpn-server.md
+629
View File
@@ -0,0 +1,629 @@
# OpenVPN Server
!!! question "Since sing-box 1.14.0"
## Structure
```json
{
"type": "openvpn-server",
"tag": "ovpn-server",
... // Listen Fields
"system": false,
"name": "",
"mtu": 1500,
"mode": "tls",
"network": "udp",
"remote": "",
"remote_port": 0,
"max_clients": 1024,
"address": [],
"peer_address": "",
"peer_address_ipv6": "",
"topology": "subnet",
"duplicate_cn": false,
"users": [
{
"username": "",
"password": ""
}
],
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"certificate": [],
"certificate_path": "",
"key": [],
"key_path": "",
"client_certificate": [],
"client_certificate_path": "",
"verify_client_certificate": "require",
"client_name": "",
"client_name_type": "name",
"peer_fingerprint": [],
"crl_path": "",
"remote_certificate_ku": [],
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
"groups": "",
"control_wrap": {
"type": "tls_crypt",
"key": [],
"key_path": "",
"direction": "",
"force_cookie": false
}
},
"cipher": "",
"data_ciphers": [],
"data_ciphers_fallback": "",
"auth": "",
"mss_fix": 0,
"mss_fix_disabled": false,
"mss_fix_mode": "",
"replay_window": 0,
"replay_window_time": "",
"push": {
"routes": [],
"dns": [],
"dns_servers": [],
"search_domains": [],
"dhcp_options": [],
"redirect_gateway": false,
"redirect_gateway_flags": [],
"block_outside_dns": false,
"ping_interval": "",
"ping_restart": ""
},
"ping_interval": "",
"ping_restart": "",
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"handshake_window": "1m",
... // UDP NAT Fields
}
```
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item
## Listen Fields
See [Listen Fields](/configuration/shared/listen/) for details. `udp_timeout` is part of the [UDP NAT Fields](#udp-nat-fields) below.
## Fields
### system
Use system interface.
Requires privilege and cannot conflict with existing system interfaces.
The endpoint configures interface addresses and MTU but does not install
operating-system routes or DNS settings.
If disabled, sing-box uses the internal network stack.
### name
Custom interface name for system interface.
An automatically generated `ovpn` interface name is used by default.
### mtu
OpenVPN interface MTU.
`1500` will be used by default.
### mode
OpenVPN session mode, one of `tls` or `static_key`.
`tls` is used by default.
`static_key` serves one peer without a TLS control channel or forward secrecy.
It is retained as an explicit compatibility option for immutable deployments.
It does not use `tls`, `users`, push options, or TLS renegotiation options.
### network
OpenVPN transport network, one of `udp` or `tcp`.
`udp` will be used by default.
Only one transport network is served per endpoint; to serve both TCP and UDP,
configure two endpoints with separate `address` subnets,
matching upstream OpenVPN which requires two server processes.
### remote
Fixed remote peer address for a UDP `static_key` server.
Required with `remote_port` in UDP `static_key` mode. TCP servers accept the
single peer from the listening socket and do not use this field.
### remote_port
Fixed remote peer port for a UDP `static_key` server.
Required with `remote` in UDP `static_key` mode.
### max_clients
Maximum number of established and pending TLS client sessions.
`1024` is used by default. The value must be smaller than `16777216`, the size of the OpenVPN peer-id space.
`static_key` mode supports one peer, so this value must be `0` or `1`.
### address
==Required==
List of OpenVPN server address prefixes.
At most one IPv4 prefix and one IPv6 prefix are supported.
The prefix address is assigned to the server interface. The masked prefix is used as the client address pool and route.
The first IPv4 and IPv6 prefix addresses are used as the endpoint's local addresses.
In `static_key` mode these are the local tunnel prefixes rather than address pools.
### peer_address
IPv4 tunnel peer address.
Required when an IPv4 `address` is configured in `static_key` mode.
### peer_address_ipv6
IPv6 tunnel peer address.
Required when an IPv6 `address` is configured in `static_key` mode.
### topology
OpenVPN topology pushed to clients, one of `subnet`, `p2p` or `net30`.
`subnet` is used by default in TLS mode. `p2p` is used by default in
`static_key` mode.
### duplicate_cn
Allow multiple active clients with the same authenticated certificate common name or username.
When disabled, a newly authenticated session replaces the existing session with the same identity and reuses its tunnel address when available.
Disabled by default.
Only available in TLS mode.
### users
List of OpenVPN username/password users.
If set, clients must pass username/password authentication in addition to any certificate policy configured by `tls.verify_client_certificate`.
Only available in TLS mode.
### users.username
Username.
### users.password
Password.
### static_key
OpenVPN static key content.
Required in `static_key` mode.
Conflict with `static_key_path`.
### static_key_path
OpenVPN static key path.
Required in `static_key` mode when `static_key` is not set.
Conflict with `static_key`.
### key_direction
Static key direction, one of `server` or `client`.
The key is used bidirectionally if empty. Conventionally the server uses
`server` and the peer uses `client`.
Only available in `static_key` mode.
### tls
Required in TLS mode.
OpenVPN control channel TLS configuration.
### tls.certificate
TLS server certificate content.
Either `tls.certificate` or `tls.certificate_path` is required.
Conflict with `tls.certificate_path`.
### tls.certificate_path
TLS server certificate path.
Either `tls.certificate` or `tls.certificate_path` is required.
Conflict with `tls.certificate`.
### tls.key
TLS server private key content.
Either `tls.key` or `tls.key_path` is required.
Conflict with `tls.key_path`.
### tls.key_path
TLS server private key path.
Either `tls.key` or `tls.key_path` is required.
Conflict with `tls.key`.
### tls.client_certificate
TLS CA certificate content, used to verify client certificates.
One of `tls.client_certificate`, `tls.client_certificate_path`, or `tls.peer_fingerprint` is required when `tls.verify_client_certificate` is `require` or `optional`.
Conflict with `tls.client_certificate_path`.
### tls.client_certificate_path
TLS CA certificate path, used to verify client certificates.
One of `tls.client_certificate`, `tls.client_certificate_path`, or `tls.peer_fingerprint` is required when `tls.verify_client_certificate` is `require` or `optional`.
Conflict with `tls.client_certificate`.
### tls.verify_client_certificate
OpenVPN client certificate policy, one of `require`, `optional` or `none`.
`require` will be used by default.
If set to `optional`, a client certificate is verified when provided, but clients without a certificate are allowed.
If set to `none`, client certificates are not requested.
This field does not replace `users`; when `users` is set, username/password authentication is still required.
### tls.client_name
Expected client certificate name. Disabled when empty.
### tls.client_name_type
Certificate field matched by `tls.client_name`, one of `subject`, `name`, or `name-prefix`.
`name` is used by default when `tls.client_name` is configured.
### tls.peer_fingerprint
Allowed SHA-256 fingerprints of client leaf certificates. Fingerprint-only verification can be used without a client CA.
### tls.crl_path
Path to a certificate revocation list used to reject revoked client certificates.
### tls.remote_certificate_ku
Required client certificate key usage masks in OpenVPN `remote-cert-ku` format.
### tls.remote_certificate_eku
Required client certificate extended key usage. Conflict with an explicitly configured `tls.remote_certificate_tls`.
### tls.remote_certificate_tls
Client certificate purpose check, one of `server`, `client`, or `none`. `client` is used by default.
### tls.certificate_profile
Certificate profile, one of `insecure`, `legacy`, `preferred`, or `suiteb`.
`legacy` is used by default.
`insecure` accepts MD5- and SHA-1-signed certificate chains and smaller legacy
keys for compatibility with immutable peers. Use it only when the peer cannot
be upgraded. `legacy` accepts SHA-1 but rejects MD5 signatures; `preferred`
requires stronger signatures and keys.
When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. Explicit `tls.cipher` and `tls.groups` values are not restricted by the profile.
### tls.ns_certificate_type
Deprecated Netscape certificate type check, one of `server` or `client`.
### tls.version_min
Minimum TLS version. `1.2` is used by default.
### tls.version_max
Maximum TLS version. The maximum supported version is used by default.
### tls.cipher
Colon-separated OpenSSL cipher suite names allowed for TLS 1.2 and earlier.
The default TLS cipher suites are used when empty. TLS 1.3 cipher suites are not controlled by this field.
### tls.groups
Colon-separated TLS key exchange groups in preference order.
### tls.control_wrap
OpenVPN control channel wrapping.
Equivalent to OpenVPN `tls-auth`, `tls-crypt` and `tls-crypt-v2`.
Disabled by default.
### tls.control_wrap.type
==Required==
Control channel wrapping type, one of `tls_auth`, `tls_crypt` or `tls_crypt_v2`.
For `tls_crypt_v2`, the key is the server key.
### tls.control_wrap.key
Control channel wrapping key content.
Either `tls.control_wrap.key` or `tls.control_wrap.key_path` is required.
Conflict with `tls.control_wrap.key_path`.
### tls.control_wrap.key_path
Control channel wrapping key path.
Either `tls.control_wrap.key` or `tls.control_wrap.key_path` is required.
Conflict with `tls.control_wrap.key`.
### tls.control_wrap.direction
OpenVPN `tls-auth` key direction, one of `server` or `client`.
Only available when `tls.control_wrap.type` is `tls_auth`.
`server` maps to OpenVPN key direction `0`, and `client` maps to `1`; by convention servers use `0` and clients use `1`.
If empty, the key is used bidirectionally, matching an omitted `key-direction` on both peers.
### tls.control_wrap.force_cookie
Require `tls-crypt-v2` clients over UDP to support stateless session cookies.
Only available when `tls.control_wrap.type` is `tls_crypt_v2`. When disabled,
clients without cookie support are accepted using the upstream `allow-noncookie` behavior.
Disabled by default.
### cipher
Data-channel cipher used in `static_key` mode.
The upstream static-key default `BF-CBC` is used when empty. Supported
static-key ciphers are the AES-CBC, ARIA-CBC, Camellia-CBC, DES-CBC,
Blowfish-CBC, CAST5-CBC families, `SEED-CBC`, `SM4-CBC`, and `NONE`.
Only available in `static_key` mode. `NONE` provides no confidentiality.
### data_ciphers
Allowed OpenVPN data channel ciphers.
`AES-256-GCM`, `AES-128-GCM` and `CHACHA20-POLY1305` are used by default.
The AES-GCM family includes `AES-192-GCM`. Retained ciphers include the CBC,
CFB, and OFB forms of AES, ARIA, Camellia, DES, Blowfish, and CAST5, the CBC,
CFB, and OFB forms of SEED and SM4, and `NONE`. CFB and OFB are available only
in TLS mode. Legacy ciphers provide weaker or no confidentiality and are not
enabled by default.
Only available in TLS mode.
### data_ciphers_fallback
OpenVPN data channel cipher for legacy clients that do not support cipher negotiation.
Equivalent to OpenVPN `data-ciphers-fallback`.
Disabled by default.
Only available in TLS mode.
### auth
OpenVPN data channel authentication digest.
`SHA1` will be used by default, matching the upstream default; it only applies to non-AEAD data ciphers and `tls_auth`.
Legacy digests including `MD5` and `RIPEMD160` remain available when explicitly
configured for compatibility.
### mss_fix
Maximum encapsulated packet size used to clamp TCP MSS. The upstream default calculation uses `1492` with the default MTU.
### mss_fix_disabled
Disable MSS clamping, including the default clamp.
### mss_fix_mode
Calculation mode for an explicit `mss_fix`, one of `mtu` or `fixed`. Requires `mss_fix`.
### replay_window
UDP data-channel replay window size. `64` is used by default; TCP packet IDs remain strictly consecutive.
### replay_window_time
UDP replay window duration. `15s` is used by default. The value must use whole seconds.
### push
Options pushed to clients.
### push.routes
Routes to push to clients.
IPv4 and IPv6 prefixes can be mixed.
### push.dns
DNS server addresses to push to clients.
Uses legacy `dhcp-option DNS`/`DNS6`. A pushed modern DNS server group overrides these addresses on compatible clients.
### push.dns_servers
Modern OpenVPN DNS server groups to push. Each entry contains `priority`, `addresses`, optional `resolve_domains`, `dnssec`, `transport`, and `sni`.
Addresses accept an IP address or `IP:port` (IPv6 ports use `[IPv6]:port`). `transport` is one of `plain`, `dot`, or `doh`; `dnssec` is one of `yes`, `optional`, or `no`. OpenVPN clients apply only the group with the lowest priority number.
### push.search_domains
Modern OpenVPN search domains to push.
### push.dhcp_options
Additional legacy `dhcp-option` values to push, without the `dhcp-option` prefix.
### push.redirect_gateway
Push `redirect-gateway` to clients, which routes client traffic through the VPN according to `push.redirect_gateway_flags`.
When `push.redirect_gateway_flags` is empty, `def1` is used by default.
### push.redirect_gateway_flags
OpenVPN `redirect-gateway` flags to push to clients.
Only available when `push.redirect_gateway` is enabled.
`def1` is used by default.
### push.block_outside_dns
Push `block-outside-dns` to clients, which blocks DNS queries outside the VPN on Windows clients.
### push.ping_interval
OpenVPN `ping` interval pushed to clients.
After the interval passes without sending a packet, the client sends a data-channel ping to the server.
The value must use whole seconds.
Disabled by default.
### push.ping_restart
OpenVPN `ping-restart` timeout pushed to clients.
After the timeout passes without receiving a packet, the client reconnects to the server.
The value must use whole seconds.
Disabled by default.
### ping_interval
Interval after which the server sends a data-channel ping when no packet has been sent to a client.
This value applies to the server. Use `push.ping_interval` to configure clients.
The value must use whole seconds.
Disabled by default.
### ping_restart
Time without receiving a packet after which the server closes the client session.
This value applies to the server. Use `push.ping_restart` to configure clients.
The server timeout should be longer than the client timeout so the client can reconnect before the server discards its session.
The value must use whole seconds.
Disabled by default.
### renegotiate_interval
OpenVPN TLS renegotiation interval.
When empty, the OpenVPN default `1h` is used.
Only available in TLS mode.
### renegotiate_disabled
Disable time-based TLS renegotiation, including the default interval.
Only available in TLS mode.
### renegotiate_bytes
Renegotiate data-channel keys after this many bytes. `0` uses the cipher-dependent OpenVPN default.
Only available in TLS mode.
### renegotiate_packets
Renegotiate data-channel keys after this many packets. `0` uses the cipher-dependent OpenVPN default.
Only available in TLS mode.
### handshake_window
Maximum time allowed for the initial TLS handshake and each TLS renegotiation.
`1m` is used by default.
Only available in TLS mode.
## UDP NAT Fields
These fields configure UDP sessions for traffic through the OpenVPN interface.
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
docs/configuration/endpoint/openvpn-server.zh.md
+612
View File
@@ -0,0 +1,612 @@
# OpenVPN 服务器
!!! question "自 sing-box 1.14.0 起"
## 结构
```json
{
"type": "openvpn-server",
"tag": "ovpn-server",
... // 监听字段
"system": false,
"name": "",
"mtu": 1500,
"mode": "tls",
"network": "udp",
"remote": "",
"remote_port": 0,
"max_clients": 1024,
"address": [],
"peer_address": "",
"peer_address_ipv6": "",
"topology": "subnet",
"duplicate_cn": false,
"users": [
{
"username": "",
"password": ""
}
],
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"certificate": [],
"certificate_path": "",
"key": [],
"key_path": "",
"client_certificate": [],
"client_certificate_path": "",
"verify_client_certificate": "require",
"client_name": "",
"client_name_type": "name",
"peer_fingerprint": [],
"crl_path": "",
"remote_certificate_ku": [],
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
"groups": "",
"control_wrap": {
"type": "tls_crypt",
"key": [],
"key_path": "",
"direction": "",
"force_cookie": false
}
},
"cipher": "",
"data_ciphers": [],
"data_ciphers_fallback": "",
"auth": "",
"mss_fix": 0,
"mss_fix_disabled": false,
"mss_fix_mode": "",
"replay_window": 0,
"replay_window_time": "",
"push": {
"routes": [],
"dns": [],
"dns_servers": [],
"search_domains": [],
"dhcp_options": [],
"redirect_gateway": false,
"redirect_gateway_flags": [],
"block_outside_dns": false,
"ping_interval": "",
"ping_restart": ""
},
"ping_interval": "",
"ping_restart": "",
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"handshake_window": "1m",
... // UDP NAT 字段
}
```
!!! note ""
当内容只有一项时，可以忽略 JSON 数组 [] 标签
## 监听字段
参阅 [监听字段](/zh/configuration/shared/listen/)。`udp_timeout` 属于下方的 [UDP NAT 字段](#udp-nat-字段)。
## 字段
### system
使用系统接口。
需要特权且不能与已有系统接口冲突。
endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。
如果禁用，sing-box 将使用内部网络栈。
### name
系统接口的自定义接口名称。
默认使用自动生成的 `ovpn` 接口名称。
### mtu
OpenVPN 接口 MTU。
默认使用 `1500`。
### mode
OpenVPN 会话模式，`tls` 或 `static_key` 之一。
默认使用 `tls`。
`static_key` 在没有 TLS 控制信道和前向保密的情况下服务一个对端，仅作为不可变部署的显式兼容选项保留。该模式不使用 `tls`、`users`、推送选项或 TLS 重协商选项。
### network
OpenVPN 传输网络，`udp` 或 `tcp` 之一。
默认使用 `udp`。
每个端点仅服务一种传输网络；如需同时服务 TCP 与 UDP，
需要配置两个端点并使用互不重叠的 `address` 子网，
与上游 OpenVPN 需要两个服务进程一致。
### remote
UDP `static_key` 服务器的固定远端地址。
在 UDP `static_key` 模式下与 `remote_port` 一起必填。TCP 服务器从监听套接字接受单个对端，不使用此字段。
### remote_port
UDP `static_key` 服务器的固定远端端口。
在 UDP `static_key` 模式下与 `remote` 一起必填。
### max_clients
已建立与握手中的 TLS 客户端会话的最大数量。
默认使用 `1024`。该值必须小于 OpenVPN peer-id 空间的大小 `16777216`。
`static_key` 模式仅支持一个对端，因此此值必须为 `0` 或 `1`。
### address
==必填==
OpenVPN 服务器地址前缀列表。
最多支持一个 IPv4 前缀和一个 IPv6 前缀。
前缀地址被分配给服务器接口。掩码后的前缀用作客户端地址池和路由。
第一个 IPv4 和 IPv6 前缀地址用作端点的本地地址。
在 `static_key` 模式下，这些地址是本地隧道前缀，而不是地址池。
### peer_address
IPv4 隧道对端地址。
在 `static_key` 模式下配置 IPv4 `address` 时必填。
### peer_address_ipv6
IPv6 隧道对端地址。
在 `static_key` 模式下配置 IPv6 `address` 时必填。
### topology
推送给客户端的 OpenVPN topology，`subnet`、`p2p` 或 `net30` 之一。
TLS 模式默认使用 `subnet`，`static_key` 模式默认使用 `p2p`。
### duplicate_cn
允许具有相同认证证书 common name 或用户名的多个客户端同时在线。
禁用时，新认证的会话会替换具有相同身份的现有会话，并在可用时复用其 tunnel 地址。
默认禁用。
仅在 TLS 模式下可用。
### users
OpenVPN 用户名/密码用户列表。
如果设置，客户端除了通过 `tls.verify_client_certificate` 配置的证书策略外，还必须通过用户名/密码认证。
仅在 TLS 模式下可用。
### users.username
用户名。
### users.password
密码。
### static_key
OpenVPN 静态密钥内容。
在 `static_key` 模式下必填。
与 `static_key_path` 冲突。
### static_key_path
OpenVPN 静态密钥路径。
在 `static_key` 模式下未设置 `static_key` 时必填。
与 `static_key` 冲突。
### key_direction
静态密钥方向，`server` 或 `client` 之一。
为空时双向使用密钥。按照惯例，服务器使用 `server`，对端使用 `client`。
仅在 `static_key` 模式下可用。
### tls
在 TLS 模式下必填。
OpenVPN 控制信道 TLS 配置。
### tls.certificate
TLS 服务器证书内容。
`tls.certificate` 或 `tls.certificate_path` 必填其一。
与 `tls.certificate_path` 冲突。
### tls.certificate_path
TLS 服务器证书路径。
`tls.certificate` 或 `tls.certificate_path` 必填其一。
与 `tls.certificate` 冲突。
### tls.key
TLS 服务器私钥内容。
`tls.key` 或 `tls.key_path` 必填其一。
与 `tls.key_path` 冲突。
### tls.key_path
TLS 服务器私钥路径。
`tls.key` 或 `tls.key_path` 必填其一。
与 `tls.key` 冲突。
### tls.client_certificate
TLS CA 证书内容，用于验证客户端证书。
当 `tls.verify_client_certificate` 为 `require` 或 `optional` 时，`tls.client_certificate`、`tls.client_certificate_path` 或 `tls.peer_fingerprint` 必填其一。
与 `tls.client_certificate_path` 冲突。
### tls.client_certificate_path
TLS CA 证书路径，用于验证客户端证书。
当 `tls.verify_client_certificate` 为 `require` 或 `optional` 时，`tls.client_certificate`、`tls.client_certificate_path` 或 `tls.peer_fingerprint` 必填其一。
与 `tls.client_certificate` 冲突。
### tls.verify_client_certificate
OpenVPN 客户端证书策略，`require`、`optional` 或 `none` 之一。
默认使用 `require`。
设为 `optional` 时，客户端提供证书则验证，不提供证书的客户端也被允许。
设为 `none` 时，不请求客户端证书。
该字段不替代 `users`；设置 `users` 后仍然要求用户名/密码认证。
### tls.client_name
期望的客户端证书名称。为空时禁用。
### tls.client_name_type
`tls.client_name` 匹配的证书字段，`subject`、`name` 或 `name-prefix` 之一。
配置 `tls.client_name` 时默认使用 `name`。
### tls.peer_fingerprint
允许的客户端叶证书 SHA-256 指纹。可以在没有客户端 CA 时仅使用指纹验证。
### tls.crl_path
用于拒绝已吊销客户端证书的证书吊销列表路径。
### tls.remote_certificate_ku
OpenVPN `remote-cert-ku` 格式的客户端证书 Key Usage mask。
### tls.remote_certificate_eku
客户端证书所需的 Extended Key Usage。与显式配置的 `tls.remote_certificate_tls` 冲突。
### tls.remote_certificate_tls
客户端证书用途检查，`server`、`client` 或 `none` 之一。默认使用 `client`。
### tls.certificate_profile
证书 profile，可选值为 `insecure`、`legacy`、`preferred` 或 `suiteb`。
默认使用 `legacy`。
`insecure` 为兼容不可变对端而接受使用 MD5 或 SHA-1 签名的证书链和较小的旧密钥，仅应在对端无法升级时使用。`legacy` 接受 SHA-1 但拒绝 MD5 签名；`preferred` 要求更强的签名和密钥。
选择 `suiteb` 且 `tls.cipher` 为空时，TLS 1.2 cipher 列表默认使用 Suite B ECDHE-ECDSA AES-GCM 套件。该 profile 不限制显式配置的 `tls.cipher` 和 `tls.groups`。
### tls.ns_certificate_type
已弃用的 Netscape 证书类型检查，`server` 或 `client` 之一。
### tls.version_min
最低 TLS 版本。默认使用 `1.2`。
### tls.version_max
最高 TLS 版本。默认使用支持的最高版本。
### tls.cipher
TLS 1.2 及更低版本允许的 OpenSSL cipher suite 名称，以冒号分隔。
为空时使用默认 TLS cipher suite。该字段不控制 TLS 1.3 cipher suite。
### tls.groups
按偏好顺序排列的 TLS key exchange group，以冒号分隔。
### tls.control_wrap
OpenVPN 控制信道包装。
等价于 OpenVPN `tls-auth`、`tls-crypt` 和 `tls-crypt-v2`。
默认禁用。
### tls.control_wrap.type
==必填==
控制信道包装类型，`tls_auth`、`tls_crypt` 或 `tls_crypt_v2` 之一。
对于 `tls_crypt_v2`，密钥为服务器密钥。
### tls.control_wrap.key
控制信道包装密钥内容。
`tls.control_wrap.key` 或 `tls.control_wrap.key_path` 必填其一。
与 `tls.control_wrap.key_path` 冲突。
### tls.control_wrap.key_path
控制信道包装密钥路径。
`tls.control_wrap.key` 或 `tls.control_wrap.key_path` 必填其一。
与 `tls.control_wrap.key` 冲突。
### tls.control_wrap.direction
OpenVPN `tls-auth` 密钥方向，`server` 或 `client` 之一。
仅当 `tls.control_wrap.type` 为 `tls_auth` 时可用。
`server` 对应 OpenVPN 密钥方向 `0`，`client` 对应 `1`；按照惯例服务器使用 `0`，客户端使用 `1`。
如果为空，密钥被双向使用，与两端均省略 `key-direction` 的行为一致。
### tls.control_wrap.force_cookie
要求 UDP 上的 `tls-crypt-v2` 客户端支持无状态 session cookie。
仅当 `tls.control_wrap.type` 为 `tls_crypt_v2` 时可用。禁用时，不支持 cookie 的客户端会按照上游 `allow-noncookie` 行为被接受。
默认禁用。
### cipher
`static_key` 模式使用的数据信道加密方式。
为空时使用上游静态密钥模式的默认值 `BF-CBC`。支持 AES-CBC、ARIA-CBC、Camellia-CBC、DES-CBC、Blowfish-CBC、CAST5-CBC 系列，以及 `SEED-CBC`、`SM4-CBC` 和 `NONE`。
仅在 `static_key` 模式下可用。`NONE` 不提供机密性。
### data_ciphers
允许的 OpenVPN 数据信道加密方式。
默认使用 `AES-256-GCM`、`AES-128-GCM` 和 `CHACHA20-POLY1305`。
AES-GCM 系列还包括 `AES-192-GCM`。保留的 cipher 包括 AES、ARIA、Camellia、DES、Blowfish、CAST5、SEED 和 SM4 的 CBC、CFB、OFB 形式，以及 `NONE`。CFB 和 OFB 仅可用于 TLS 模式。旧 cipher 只能提供较弱的机密性或完全不加密，因此默认不启用。
仅在 TLS 模式下可用。
### data_ciphers_fallback
用于不支持加密方式协商的遗留客户端的 OpenVPN 数据信道加密方式。
等价于 OpenVPN `data-ciphers-fallback`。
默认禁用。
仅在 TLS 模式下可用。
### auth
OpenVPN 数据信道认证摘要。
默认使用 `SHA1`，与上游默认值一致；仅对非 AEAD 数据信道加密方式和 `tls_auth` 生效。
为兼容既有客户端，显式配置时仍可使用 `MD5` 和 `RIPEMD160` 等旧摘要。
### mss_fix
用于限制 TCP MSS 的最大封装数据包大小。默认 MTU 下使用上游默认值 `1492` 计算。
### mss_fix_disabled
禁用 MSS 限制，包括默认限制。
### mss_fix_mode
显式 `mss_fix` 的计算模式，`mtu` 或 `fixed` 之一。需要 `mss_fix`。
### replay_window
UDP 数据通道重放窗口大小。默认使用 `64`；TCP 数据包 ID 始终严格连续。
### replay_window_time
UDP 重放窗口时长。默认使用 `15s`。该值必须使用整秒。
### push
推送给客户端的选项。
### push.routes
推送给客户端的路由。
IPv4 和 IPv6 前缀可以混用。
### push.dns
推送给客户端的 DNS 服务器地址。
使用传统的 `dhcp-option DNS`/`DNS6`。兼容客户端收到现代 DNS 服务器组时会覆盖这些地址。
### push.dns_servers
推送的现代 OpenVPN DNS 服务器组。每项包含 `priority`、`addresses`，以及可选的 `resolve_domains`、`dnssec`、`transport` 和 `sni`。
地址接受 IP 或 `IP:port`（带端口的 IPv6 使用 `[IPv6]:port`）。`transport` 为 `plain`、`dot` 或 `doh` 之一；`dnssec` 为 `yes`、`optional` 或 `no` 之一。OpenVPN 客户端仅应用优先级数字最低的服务器组。
### push.search_domains
推送的现代 OpenVPN 搜索域。
### push.dhcp_options
推送的额外传统 `dhcp-option` 值，不包含 `dhcp-option` 前缀。
### push.redirect_gateway
向客户端推送 `redirect-gateway`，根据 `push.redirect_gateway_flags` 通过 VPN 路由客户端流量。
当 `push.redirect_gateway_flags` 为空时，默认使用 `def1`。
### push.redirect_gateway_flags
向客户端推送的 OpenVPN `redirect-gateway` flag。
仅当启用 `push.redirect_gateway` 时可用。
默认使用 `def1`。
### push.block_outside_dns
向客户端推送 `block-outside-dns`，在 Windows 客户端上阻止 VPN 之外的 DNS 查询。
### push.ping_interval
推送给客户端的 OpenVPN `ping` 间隔。
在该间隔内未发送任何 packet 后，客户端会向服务器发送一个 data channel ping。
该值必须使用整秒。
默认禁用。
### push.ping_restart
推送给客户端的 OpenVPN `ping-restart` 超时。
在该超时时间内未收到任何 packet 后，客户端会重新连接服务器。
该值必须使用整秒。
默认禁用。
### ping_interval
服务器未向客户端发送任何 packet 时，发送 data channel ping 的间隔。
该值应用于服务器。使用 `push.ping_interval` 配置客户端。
该值必须使用整秒。
默认禁用。
### ping_restart
服务器未收到任何 packet 后关闭客户端会话的时间。
该值应用于服务器。使用 `push.ping_restart` 配置客户端。
服务器超时应长于客户端超时，以便客户端在服务器丢弃其会话前重新连接。
该值必须使用整秒。
默认禁用。
### renegotiate_interval
OpenVPN TLS 重协商间隔。
为空时使用 OpenVPN 默认值 `1h`。
仅在 TLS 模式下可用。
### renegotiate_disabled
禁用基于时间的 TLS 重协商，包括默认间隔。
仅在 TLS 模式下可用。
### renegotiate_bytes
传输指定字节数后重新协商数据通道密钥。`0` 使用与密码算法相关的 OpenVPN 默认值。
仅在 TLS 模式下可用。
### renegotiate_packets
传输指定数据包数后重新协商数据通道密钥。`0` 使用与密码算法相关的 OpenVPN 默认值。
仅在 TLS 模式下可用。
### handshake_window
初始 TLS 握手和每次 TLS 重协商允许使用的最长时间。
默认使用 `1m`。
仅在 TLS 模式下可用。
## UDP NAT 字段
这些字段配置通过 OpenVPN 接口的流量的 UDP 会话。
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
docs/configuration/endpoint/tailscale.md
+81 -1
View File
@@ -2,6 +2,12 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [listen_port](#listen_port)
:material-plus: [ssh_server](#ssh_server)
:material-plus: [taildrop_directory](#taildrop_directory)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [relay_server_port](#relay_server_port)
@@ -30,12 +36,15 @@ icon: material/new-box
"advertise_routes": [],
"advertise_exit_node": false,
"advertise_tags": [],
"listen_port": 0,
"relay_server_port": 0,
"relay_server_static_endpoints": [],
"system_interface": false,
"system_interface_name": "",
"system_interface_mtu": 0,
"udp_timeout": "5m",
"ssh_server": false,
"taildrop_directory": "",
... // Dial Fields
}
@@ -55,7 +64,7 @@ Example: `$HOME/.tailscale`
!!! note
Auth key is not required. By default, sing-box will log the login URL (or popup a notification on graphical clients).
Auth key is not required. By default, sing-box will log the login URL.
The auth key to create the node. If the node is already created (from state previously stored), then this field is not
used.
@@ -76,6 +85,10 @@ The hostname of the node.
System hostname is used by default.
!!! question "Since sing-box 1.14.0"
On iOS, tvOS and Android, the device name is used by default.
Example: `localhost`
#### accept_routes
@@ -112,6 +125,14 @@ Tags to advertise for this node, for ACL enforcement purposes.
Example: `["tag:server"]`
#### listen_port
!!! question "Since sing-box 1.14.0"
The UDP port to listen on for WireGuard and peer-to-peer traffic.
A port is automatically selected by default.
#### relay_server_port
!!! question "Since sing-box 1.13.0"
@@ -148,6 +169,61 @@ UDP NAT expiration time.
`5m` will be used by default.
#### ssh_server
!!! question "Since sing-box 1.14.0"
Run a Tailscale SSH server on tailnet port 22.
Access is controlled by the SSH ACL in the Tailscale admin console, which maps each connection to a local user. How that user is resolved, and which users are allowed, depends on the platform:
- **Linux** and **macOS**: the user is resolved from the system user database. Switching to a user other than the one sing-box runs as requires running as root; without root, sessions are limited to the current user.
- **Windows**: in the command line client, sessions run as the sing-box process identity; the mapped user is not impersonated, so a session mapped to a different local account is refused. In the graphical client, there is no such restriction.
- **Android**: the user is resolved by the app rather than the system user database. `root` is the superuser (UID 0) and `shell` is the ADB shell user (UID 2000); every other name is resolved as the package name of an installed application, running as that application's UID with its data directory as the home directory, so the target application must be installed. `termux` is a shortcut for `com.termux`, and `sing-box` for the app's own package name; when Termux is installed, the `root` and `termux` users load the Termux environment. Running as the sing-box application itself requires no root, while any other user requires granted root access; without root, sessions are limited to the sing-box user.
- **macOS**: the SSH server is only available in the standalone version and requires the Helper Service; the App Store version is not supported.
- **iOS**: the SSH server is only available in the jailbreak build; the App Store and TestFlight versions are not supported.
- **tvOS**: not yet supported.
Object format:
```json
{
"enabled": true,
"disable_pty": false,
"disable_sftp": false,
"disable_forwarding": false
}
```
Setting `ssh_server` value to `true` is equivalent to `{ "enabled": true }`.
#### ssh_server.enabled
Enable the SSH server.
#### ssh_server.disable_pty
Refuse PTY allocation requests.
#### ssh_server.disable_sftp
Refuse the SFTP subsystem.
#### ssh_server.disable_forwarding
Refuse local and remote TCP and Unix-socket forwarding, including SSH agent forwarding.
#### taildrop_directory
!!! question "Since sing-box 1.14.0"
The directory where files received from tailnet peers are stored.
Relative paths are resolved against the working directory, as [state_directory](#state_directory)
is.
`Taildrop` is used by default.
### Dial Fields
!!! note
@@ -155,3 +231,7 @@ UDP NAT expiration time.
Dial Fields in Tailscale endpoints only control how it connects to the control plane and have nothing to do with actual connections.
See [Dial Fields](/configuration/shared/dial/) for details.
### Interactive authentication
Use `Tools` > `Endpoints` in the sing-box dashboard or any sing-box graphical client to authenticate and manage the endpoint.
docs/configuration/endpoint/tailscale.zh.md
+80 -1
View File
@@ -2,6 +2,12 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [listen_port](#listen_port)
:material-plus: [ssh_server](#ssh_server)
:material-plus: [taildrop_directory](#taildrop_directory)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [relay_server_port](#relay_server_port)
@@ -30,12 +36,15 @@ icon: material/new-box
"advertise_routes": [],
"advertise_exit_node": false,
"advertise_tags": [],
"listen_port": 0,
"relay_server_port": 0,
"relay_server_static_endpoints": [],
"system_interface": false,
"system_interface_name": "",
"system_interface_mtu": 0,
"udp_timeout": "5m",
"ssh_server": false,
"taildrop_directory": "",
... // 拨号字段
}
@@ -55,7 +64,7 @@ icon: material/new-box
!!! note
认证密钥不是必需的。默认情况下，sing-box 将记录登录 URL（或在图形客户端上弹出通知）。
认证密钥不是必需的。默认情况下，sing-box 将记录登录 URL。
用于创建节点的认证密钥。如果节点已经创建（从之前存储的状态），则不使用此字段。
@@ -75,6 +84,10 @@ icon: material/new-box
默认使用系统主机名。
!!! question "自 sing-box 1.14.0 起"
在 iOS、tvOS 和 Android 上，默认使用设备名称。
示例：`localhost`
#### accept_routes
@@ -111,6 +124,14 @@ icon: material/new-box
示例：`["tag:server"]`
#### listen_port
!!! question "自 sing-box 1.14.0 起"
监听 WireGuard 和点对点流量的 UDP 端口。
默认自动选择端口。
#### relay_server_port
!!! question "自 sing-box 1.13.0 起"
@@ -147,6 +168,60 @@ UDP NAT 过期时间。
默认使用 `5m`。
#### ssh_server
!!! question "自 sing-box 1.14.0 起"
在 tailnet 的 TCP 22 端口上运行 Tailscale SSH 服务器。
访问控制由 Tailscale 管理控制台中的 SSH ACL 决定，它将每个连接映射到一个本地用户。该用户如何解析、以及允许哪些用户，取决于平台：
- **Linux** 和 **macOS**：从系统用户数据库解析用户。要切换到 sing-box 运行身份以外的用户需要以 root 运行；非 root 时，会话仅限于当前用户。
- **Windows**：在命令行客户端中，会话以 sing-box 进程的身份运行；映射的用户不会被模拟，因此映射到其他本地账户的会话将被拒绝。在图形客户端中没有此限制。
- **Android**：用户由应用解析，而非系统用户数据库。`root` 即超级用户（UID 0），`shell` 为 ADB shell 用户（UID 2000）；其他名称均作为已安装应用的包名解析，以该应用的 UID 运行，并使用其数据目录作为主目录，因此目标应用必须已安装。`termux` 是 `com.termux` 的快捷方式，`sing-box` 是应用自身包名的快捷方式；当 Termux 已安装时，`root` 和 `termux` 用户将加载 Termux 环境。以 sing-box 应用自身身份运行无需 root，其他用户则需要已授予的 root 权限；非 root 时，会话仅限于 sing-box 用户。
- **macOS**：SSH 服务器仅在独立版本中可用，且需要辅助服务；App Store 版本不支持。
- **iOS**：SSH 服务器仅在越狱版本中可用；App Store 和 TestFlight 版本不支持。
- **tvOS**：暂不支持。
对象格式：
```json
{
"enabled": true,
"disable_pty": false,
"disable_sftp": false,
"disable_forwarding": false
}
```
将 `ssh_server` 值设置为 `true` 等同于 `{ "enabled": true }`。
#### ssh_server.enabled
启用 SSH 服务器。
#### ssh_server.disable_pty
拒绝 PTY 分配请求。
#### ssh_server.disable_sftp
拒绝 SFTP 子系统。
#### ssh_server.disable_forwarding
拒绝本地和远程的 TCP 与 Unix 套接字转发，包括 SSH agent 转发。
#### taildrop_directory
!!! question "自 sing-box 1.14.0 起"
存储从 tailnet 对等节点接收到的文件的目录。
相对路径基于工作目录解析，与 [state_directory](#state_directory) 相同。
默认使用 `Taildrop`。
### 拨号字段
!!! note
@@ -154,3 +229,7 @@ UDP NAT 过期时间。
Tailscale 端点中的拨号字段仅控制它如何连接到控制平面，与实际连接无关。
参阅 [拨号字段](/zh/configuration/shared/dial/) 了解详情。
### 交互式认证
在 sing-box dashboard 或任意 sing-box 图形客户端的 `工具` > `端点` 中认证和管理 endpoint。
docs/configuration/endpoint/wireguard.md
+13 -7
View File
@@ -1,3 +1,9 @@
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [udp_mapping](/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/configuration/shared/udp-nat/#udp_nat_max)
!!! question "Since sing-box 1.11.0"
### Structure
@@ -24,7 +30,9 @@
"reserved": [0, 0, 0]
}
],
"udp_timeout": "",
... // UDP NAT Fields
"workers": 0,
... // Dial Fields
@@ -112,18 +120,16 @@ Disabled by default.
WireGuard reserved field bytes.
#### udp_timeout
UDP NAT expiration time.
`5m` will be used by default.
#### workers
WireGuard worker count.
CPU count is used by default.
### UDP NAT Fields
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/endpoint/wireguard.zh.md
+13 -7
View File
@@ -1,3 +1,9 @@
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [udp_mapping](/zh/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/zh/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/zh/configuration/shared/udp-nat/#udp_nat_max)
!!! question "自 sing-box 1.11.0 起"
### 结构
@@ -24,7 +30,9 @@
"reserved": [0, 0, 0]
}
],
"udp_timeout": "",
... // UDP NAT 字段
"workers": 0,
... // 拨号字段
@@ -114,18 +122,16 @@ WireGuard 对等方的列表。
对等方的保留字段字节。
#### udp_timeout
UDP NAT 过期时间。
默认使用 `5m`。
#### workers
WireGuard worker 数量。
默认使用 CPU 数量。
### UDP NAT 字段
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/experimental/cache-file.md
+18 -2
View File
@@ -1,5 +1,10 @@
!!! question "Since sing-box 1.8.0"
!!! quote "Changes in sing-box 1.14.0"
:material-delete-clock: [store_rdrc](#store_rdrc)
:material-plus: [store_dns](#store_dns)
!!! quote "Changes in sing-box 1.9.0"
:material-plus: [store_rdrc](#store_rdrc)
@@ -14,7 +19,8 @@
"cache_id": "",
"store_fakeip": false,
"store_rdrc": false,
"rdrc_timeout": ""
"rdrc_timeout": "",
"store_dns": false
}
```
@@ -42,9 +48,13 @@ Store fakeip in the cache file
#### store_rdrc
!!! failure "Deprecated in sing-box 1.14.0"
`store_rdrc` is deprecated and will be removed in sing-box 1.16.0, check [Migration](/migration/#migrate-store-rdrc).
Store rejected DNS response cache in the cache file
The check results of [Address filter DNS rule items](/configuration/dns/rule/#address-filter-fields)
The check results of [Legacy Address Filter Fields](/configuration/dns/rule/#legacy-address-filter-fields)
will be cached until expiration.
#### rdrc_timeout
@@ -52,3 +62,9 @@ will be cached until expiration.
Timeout of rejected DNS response cache.
`7d` is used by default.
#### store_dns
!!! question "Since sing-box 1.14.0"
Store DNS cache in the cache file.
docs/configuration/experimental/cache-file.zh.md
+18 -2
View File
@@ -1,5 +1,10 @@
!!! question "自 sing-box 1.8.0 起"
!!! quote "sing-box 1.14.0 中的更改"
:material-delete-clock: [store_rdrc](#store_rdrc)
:material-plus: [store_dns](#store_dns)
!!! quote "sing-box 1.9.0 中的更改"
:material-plus: [store_rdrc](#store_rdrc)
@@ -14,7 +19,8 @@
"cache_id": "",
"store_fakeip": false,
"store_rdrc": false,
"rdrc_timeout": ""
"rdrc_timeout": "",
"store_dns": false
}
```
@@ -40,12 +46,22 @@
#### store_rdrc
!!! failure "已在 sing-box 1.14.0 废弃"
`store_rdrc` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除，参阅[迁移指南](/zh/migration/#迁移-store_rdrc)。
将拒绝的 DNS 响应缓存存储在缓存文件中。
[地址筛选 DNS 规则项](/zh/configuration/dns/rule/#地址筛选字段) 的检查结果将被缓存至过期。
[旧版地址筛选字段](/zh/configuration/dns/rule/#旧版地址筛选字段) 的检查结果将被缓存至过期。
#### rdrc_timeout
拒绝的 DNS 响应缓存超时。
默认使用 `7d`。
#### store_dns
!!! question "自 sing-box 1.14.0 起"
将 DNS 缓存存储在缓存文件中。
docs/configuration/inbound/cloudflared.md
+89
View File
@@ -0,0 +1,89 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
`cloudflared` inbound runs an embedded Cloudflare Tunnel client and routes all
incoming tunnel traffic (TCP, UDP, ICMP) through sing-box's routing engine.
### Structure
```json
{
"type": "cloudflared",
"tag": "",
"token": "",
"ha_connections": 0,
"protocol": "",
"post_quantum": false,
"edge_ip_version": 0,
"datagram_version": "",
"grace_period": "",
"region": "",
"control_dialer": {
... // Dial Fields
},
"tunnel_dialer": {
... // Dial Fields
}
}
```
### Fields
#### token
==Required==
Base64-encoded tunnel token from the Cloudflare Zero Trust dashboard
(`Networks → Tunnels → Install connector`).
#### ha_connections
Number of high-availability connections to the Cloudflare edge.
Capped by the number of discovered edge addresses.
#### protocol
Transport protocol for edge connections.
One of `quic` `http2`.
#### post_quantum
Enable post-quantum key exchange on the control connection.
#### edge_ip_version
IP version used when connecting to the Cloudflare edge.
One of `0` (automatic) `4` `6`.
#### datagram_version
Datagram protocol version used for UDP proxying over QUIC.
One of `v2` `v3`. Only meaningful when `protocol` is `quic`.
#### grace_period
Graceful shutdown window for in-flight edge connections.
#### region
Cloudflare edge region selector.
Conflict with endpoints embedded in `token`.
#### control_dialer
[Dial Fields](/configuration/shared/dial/) used when the tunnel client dials the
Cloudflare control plane.
#### tunnel_dialer
[Dial Fields](/configuration/shared/dial/) used when the tunnel client dials the
Cloudflare edge data plane.
docs/configuration/inbound/cloudflared.zh.md
+89
View File
@@ -0,0 +1,89 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
`cloudflared` 入站运行一个内嵌的 Cloudflare Tunnel 客户端，并将所有传入的隧道流量
（TCP、UDP、ICMP）通过 sing-box 的路由引擎转发。
### 结构
```json
{
"type": "cloudflared",
"tag": "",
"token": "",
"ha_connections": 0,
"protocol": "",
"post_quantum": false,
"edge_ip_version": 0,
"datagram_version": "",
"grace_period": "",
"region": "",
"control_dialer": {
... // 拨号字段
},
"tunnel_dialer": {
... // 拨号字段
}
}
```
### 字段
#### token
==必填==
来自 Cloudflare Zero Trust 仪表板的 Base64 编码隧道令牌
（`Networks → Tunnels → Install connector`）。
#### ha_connections
到 Cloudflare edge 的高可用连接数。
上限为已发现的 edge 地址数量。
#### protocol
edge 连接使用的传输协议。
`quic` `http2` 之一。
#### post_quantum
在控制连接上启用后量子密钥交换。
#### edge_ip_version
连接 Cloudflare edge 时使用的 IP 版本。
`0`（自动）`4` `6` 之一。
#### datagram_version
通过 QUIC 进行 UDP 代理时使用的数据报协议版本。
`v2` `v3` 之一。仅在 `protocol` 为 `quic` 时有效。
#### grace_period
正在处理的 edge 连接的优雅关闭窗口。
#### region
Cloudflare edge 区域选择器。
与 `token` 中嵌入的 endpoint 冲突。
#### control_dialer
隧道客户端拨向 Cloudflare 控制面时使用的
[拨号字段](/zh/configuration/shared/dial/)。
#### tunnel_dialer
隧道客户端拨向 Cloudflare edge 数据面时使用的
[拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/inbound/hysteria.md
+38 -27
View File
@@ -21,11 +21,16 @@
}
],
"tls": {},
... // QUIC Fields
// Deprecated
"recv_window_conn": 0,
"recv_window_client": 0,
"max_conn_client": 0,
"disable_mtu_discovery": false,
"tls": {}
"disable_mtu_discovery": false
}
```
@@ -76,32 +81,38 @@ Authentication password, in base64.
Authentication password.
#### recv_window_conn
The QUIC stream-level flow control window for receiving data.
`15728640 (15 MB/s)` will be used if empty.
#### recv_window_client
The QUIC connection-level flow control window for receiving data.
`67108864 (64 MB/s)` will be used if empty.
#### max_conn_client
The maximum number of QUIC concurrent bidirectional streams that a peer is allowed to open.
`1024` will be used if empty.
#### disable_mtu_discovery
Disables Path MTU Discovery (RFC 8899). Packets will then be at most 1252 (IPv4) / 1232 (IPv6) bytes in size.
Force enabled on for systems other than Linux and Windows (according to upstream).
#### tls
==Required==
TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
### Deprecated Fields
#### recv_window_conn
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `stream_receive_window` instead.
#### recv_window_client
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `connection_receive_window` instead.
#### max_conn_client
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `max_concurrent_streams` instead.
#### disable_mtu_discovery
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `disable_path_mtu_discovery` instead.
docs/configuration/inbound/hysteria.zh.md
+38 -27
View File
@@ -21,11 +21,16 @@
}
],
"tls": {},
... // QUIC 字段
// 废弃的
"recv_window_conn": 0,
"recv_window_client": 0,
"max_conn_client": 0,
"disable_mtu_discovery": false,
"tls": {}
"disable_mtu_discovery": false
}
```
@@ -76,32 +81,38 @@ base64 编码的认证密码。
认证密码。
#### recv_window_conn
用于接收数据的 QUIC 流级流控制窗口。
默认 `15728640 (15 MB/s)`。
#### recv_window_client
用于接收数据的 QUIC 连接级流控制窗口。
默认 `67108864 (64 MB/s)`。
#### max_conn_client
允许对等点打开的 QUIC 并发双向流的最大数量。
默认 `1024`。
#### disable_mtu_discovery
禁用路径 MTU 发现 (RFC 8899)。 数据包的大小最多为 1252 (IPv4) / 1232 (IPv6) 字节。
强制为 Linux 和 Windows 以外的系统启用（根据上游）。
#### tls
==必填==
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#入站)。
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#入站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
### 废弃字段
#### recv_window_conn
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `stream_receive_window` 代替。
#### recv_window_client
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `connection_receive_window` 代替。
#### max_conn_client
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `max_concurrent_streams` 代替。
#### disable_mtu_discovery
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `disable_path_mtu_discovery` 代替。
docs/configuration/inbound/hysteria2.md
+138 -2
View File
@@ -2,6 +2,12 @@
icon: material/alert-decagram
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [bbr_profile](#bbr_profile)
:material-plus: [realm](#realm)
:material-alert: [obfs](#obfstype)
!!! quote "Changes in sing-box 1.11.0"
:material-alert: [masquerade](#masquerade)
@@ -30,8 +36,26 @@ icon: material/alert-decagram
],
"ignore_client_bandwidth": false,
"tls": {},
... // QUIC Fields
"masquerade": "", // or {}
"brutal_debug": false
"bbr_profile": "",
"brutal_debug": false,
"realm": {
"server_url": "https://realm.example.com",
"token": "",
"realm_id": "",
"stun_servers": [],
"stun_domain_resolver": "", // or {}
"ip_version": 0,
"port_mapping": {
"enabled": false,
"timeout": "",
"lifetime": ""
},
"http_client": {}
}
}
```
@@ -58,7 +82,7 @@ Conflict with `ignore_client_bandwidth`.
#### obfs.type
QUIC traffic obfuscator type, only available with `salamander`.
QUIC traffic obfuscator type, one of `salamander` `gecko`.
Disabled if empty.
@@ -66,6 +90,22 @@ Disabled if empty.
QUIC traffic obfuscator password.
#### obfs.min_packet_size
!!! question "Since sing-box 1.14.0"
Minimum on-wire packet size in bytes. Gecko only.
`512` is used by default.
#### obfs.max_packet_size
!!! question "Since sing-box 1.14.0"
Maximum on-wire packet size in bytes. Gecko only.
`1200` is used by default.
#### users
Hysteria2 users
@@ -90,6 +130,10 @@ Deny clients to use the BBR CC.
TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
#### masquerade
HTTP3 server behavior (URL string configuration) when authentication fails.
@@ -141,6 +185,98 @@ Fixed response headers.
Fixed response content.
#### bbr_profile
!!! question "Since sing-box 1.14.0"
BBR congestion control algorithm profile, one of `conservative` `standard` `aggressive`.
`standard` is used by default.
#### brutal_debug
Enable debug information logging for Hysteria Brutal CC.
#### realm
!!! question "Since sing-box 1.14.0"
Register this inbound to a Hysteria Realm rendezvous service to enable NAT traversal.
The inbound discovers its public addresses via STUN, registers them on the realm, and uses UDP hole-punching to accept incoming clients without a publicly reachable listen address.
See [Hysteria Realm](/configuration/service/hysteria-realm/) for the rendezvous service.
#### realm.server_url
==Required==
Realm rendezvous service URL.
#### realm.token
Bearer token for the realm. Must match one of `users[].token` configured on the realm.
#### realm.realm_id
==Required==
Slot identifier on the realm.
1–64 characters, must match `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`.
Outbounds must use the same `realm_id` to find this server.
#### realm.stun_servers
==Required==
List of STUN servers (`host` or `host:port`) used to discover public addresses.
#### realm.stun_domain_resolver
Set domain resolver to use for resolving STUN server domain names.
This option uses the same format as the [route DNS rule action](/configuration/dns/rule_action/#route) without the `action` field.
Setting this option directly to a string is equivalent to setting `server` of this options.
If empty, the default domain resolver is used.
#### realm.ip_version
Restrict realm connections (STUN, hole punching, and the resulting QUIC path) to a single IP version.
`4` or `6`. Both are used if empty.
The `listen` address must be compatible with the selected version.
#### realm.port_mapping
Maintain a UDP port mapping on the local gateway via UPnP or NAT-PMP.
The mapping is established before STUN discovery and improves hole-punching reliability behind gateways that support it; failures are non-fatal.
Requires IPv4: conflicts with `"ip_version": 6`.
#### realm.port_mapping.enabled
Enable port mapping.
#### realm.port_mapping.timeout
Timeout for gateway discovery and mapping operations.
`10s` is used by default.
#### realm.port_mapping.lifetime
Lease lifetime of the mapping; it is renewed at half the lifetime.
`10m` is used by default.
#### realm.http_client
HTTP client used to talk to the realm.
See [HTTP Client](/configuration/shared/http-client/) for details.
docs/configuration/inbound/hysteria2.zh.md
+139 -3
View File
@@ -2,6 +2,12 @@
icon: material/alert-decagram
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [bbr_profile](#bbr_profile)
:material-plus: [realm](#realm)
:material-alert: [obfs](#obfstype)
!!! quote "sing-box 1.11.0 中的更改"
:material-alert: [masquerade](#masquerade)
@@ -30,8 +36,26 @@ icon: material/alert-decagram
],
"ignore_client_bandwidth": false,
"tls": {},
... // QUIC 字段
"masquerade": "", // 或 {}
"brutal_debug": false
"bbr_profile": "",
"brutal_debug": false,
"realm": {
"server_url": "https://realm.example.com",
"token": "",
"realm_id": "",
"stun_servers": [],
"stun_domain_resolver": "", // 或 {}
"ip_version": 0,
"port_mapping": {
"enabled": false,
"timeout": "",
"lifetime": ""
},
"http_client": {}
}
}
```
@@ -55,13 +79,29 @@ icon: material/alert-decagram
#### obfs.type
QUIC 流量混淆器类型，仅可设为 `salamander`。
QUIC 流量混淆器类型，可选 `salamander` `gecko`。
如果为空则禁用。
#### obfs.password
QUIC 流量混淆器密码.
QUIC 流量混淆器密码。
#### obfs.min_packet_size
!!! question "自 sing-box 1.14.0 起"
最小线上数据包大小（字节）。仅限 Gecko。
默认使用 `512`。
#### obfs.max_packet_size
!!! question "自 sing-box 1.14.0 起"
最大线上数据包大小（字节）。仅限 Gecko。
默认使用 `1200`。
#### users
@@ -87,6 +127,10 @@ Hysteria 用户
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#入站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
#### masquerade
HTTP3 服务器认证失败时的行为 （URL 字符串配置）。
@@ -138,6 +182,98 @@ HTTP3 服务器认证失败时的行为 （对象配置）。
固定响应内容。
#### bbr_profile
!!! question "自 sing-box 1.14.0 起"
BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。
默认使用 `standard`。
#### brutal_debug
启用 Hysteria Brutal CC 的调试信息日志记录。
#### realm
!!! question "自 sing-box 1.14.0 起"
将此入站注册到 Hysteria Realm 会合服务，以启用 NAT 穿透。
入站通过 STUN 发现自己的公网地址并注册到 realm，借助 UDP 打洞接受客户端连接，无需可公网直达的监听地址。
会合服务参阅 [Hysteria Realm](/zh/configuration/service/hysteria-realm/)。
#### realm.server_url
==必填==
Realm 会合服务 URL。
#### realm.token
Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配。
#### realm.realm_id
==必填==
Realm 上的槽位标识符。
1–64 字符，需匹配 `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`。
出站需使用相同的 `realm_id` 才能找到本服务器。
#### realm.stun_servers
==必填==
用于发现公网地址的 STUN 服务器列表（`host` 或 `host:port`）。
#### realm.stun_domain_resolver
用于解析 STUN 服务器域名的域名解析器。
此选项的格式与 [路由 DNS 规则动作](/zh/configuration/dns/rule_action/#route) 相同，但不包含 `action` 字段。
若直接将此选项设置为字符串，则等同于设置该选项的 `server` 字段。
如果为空，则使用默认域名解析器。
#### realm.ip_version
将 realm 连接（STUN、打洞与最终的 QUIC 路径）限制为单一 IP 版本。
`4` 或 `6`。默认使用两者。
`listen` 地址必须与所选版本兼容。
#### realm.port_mapping
通过 UPnP 或 NAT-PMP 在本地网关上维护 UDP 端口映射。
映射在 STUN 发现之前建立，可在支持的网关后提升打洞成功率；失败不影响正常流程。
需要 IPv4：与 `"ip_version": 6` 冲突。
#### realm.port_mapping.enabled
启用端口映射。
#### realm.port_mapping.timeout
网关发现与映射操作的超时。
默认使用 `10s`。
#### realm.port_mapping.lifetime
映射的租约时长；每过一半时长续期一次。
默认使用 `10m`。
#### realm.http_client
与 realm 通信使用的 HTTP 客户端。
参阅 [HTTP 客户端](/zh/configuration/shared/http-client/) 了解详情。
docs/configuration/inbound/index.md
+2 -1
View File
@@ -31,10 +31,11 @@
| `hysteria2` | [Hysteria2](./hysteria2/) | :material-close: |
| `vless` | [VLESS](./vless/) | TCP |
| `anytls` | [AnyTLS](./anytls/) | TCP |
| `mieru` | [Mieru](./mieru/) | :material-close: |
| `snell` | [Snell](./snell/) | TCP |
| `tun` | [Tun](./tun/) | :material-close: |
| `redirect` | [Redirect](./redirect/) | :material-close: |
| `tproxy` | [TProxy](./tproxy/) | :material-close: |
| `cloudflared` | [Cloudflared](./cloudflared/) | :material-close: |
#### tag
docs/configuration/inbound/index.zh.md
+2 -1
View File
@@ -31,10 +31,11 @@
| `hysteria2` | [Hysteria2](./hysteria2/) | :material-close: |
| `vless` | [VLESS](./vless/) | TCP |
| `anytls` | [AnyTLS](./anytls/) | TCP |
| `mieru` | [Mieru](./mieru/) | :material-close: |
| `snell` | [Snell](./snell/) | TCP |
| `tun` | [Tun](./tun/) | :material-close: |
| `redirect` | [Redirect](./redirect/) | :material-close: |
| `tproxy` | [TProxy](./tproxy/) | :material-close: |
| `cloudflared` | [Cloudflared](./cloudflared/) | :material-close: |
#### tag
docs/configuration/inbound/naive.md
+1 -4
View File
@@ -50,13 +50,10 @@ QUIC congestion control algorithm.
| Algorithm | Description |
|----------------|---------------------------------|
| `bbr` | BBR |
| `bbr_standard` | BBR (Standard version) |
| `bbr2` | BBRv2 |
| `bbr2_variant` | BBRv2 (An experimental variant) |
| `cubic` | CUBIC |
| `reno` | New Reno |
`bbr` is used by default (the default of QUICHE, used by Chromium which NaiveProxy is based on).
`bbr` is used by default.
#### tls
docs/configuration/inbound/naive.zh.md
+1 -4
View File
@@ -50,13 +50,10 @@ QUIC 拥塞控制算法。
| 算法 | 描述 |
|----------------|--------------------|
| `bbr` | BBR |
| `bbr_standard` | BBR (标准版) |
| `bbr2` | BBRv2 |
| `bbr2_variant` | BBRv2 (一种试验变体) |
| `cubic` | CUBIC |
| `reno` | New Reno |
默认使用 `bbr`（NaiveProxy 基于的 Chromium 使用的 QUICHE 的默认值）。
默认使用 `bbr`。
#### tls
docs/configuration/inbound/snell.md
+96
View File
@@ -0,0 +1,96 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
### Structure
```json
{
"type": "snell",
"tag": "snell-in",
... // Listen Fields
"version": 5,
"psk": "password",
"users": [
{
"name": "sekai",
"userkey": "user-password"
}
],
"obfs_mode": ""
}
```
### Version 6 Structure
```json
{
"type": "snell",
"tag": "snell-in",
... // Listen Fields
"version": 6,
"psk": "password",
"users": [
{
"name": "sekai",
"userkey": "user-password"
}
],
"mode": ""
}
```
### Listen Fields
See [Listen Fields](/configuration/shared/listen/) for details.
### Fields
#### version
==Required==
The Snell protocol version, one of `5` `6`.
Version `5` supports HTTP obfuscation (`obfs_mode`); version `6` replaces it
with traffic shaping (`mode`) and requires a `psk` of 12 to 255 bytes.
!!! note
Since we intentionally do not support the QUIC proxy mode of Snell v5, the v5 wire protocol
is effectively identical to v4, so no separate v4 server or v5 client is provided.
#### psk
==Required==
The pre-shared key.
#### users
Snell users.
When set, the server runs in multi-user mode: each entry has a `name` (optional, used in
logs) and a `userkey` (the user's key). The top-level `psk` remains the server key.
#### obfs_mode
==Version 5 only==
HTTP obfuscation mode, one of `none` `http`.
`none` is used by default.
#### mode
==Version 6 only==
Traffic shaping mode, one of `default` `unshaped` `unsafe-raw`.
`default` is used by default.
docs/configuration/inbound/snell.zh.md
+96
View File
@@ -0,0 +1,96 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
### 结构
```json
{
"type": "snell",
"tag": "snell-in",
... // 监听字段
"version": 5,
"psk": "password",
"users": [
{
"name": "sekai",
"userkey": "user-password"
}
],
"obfs_mode": ""
}
```
### 版本 6 结构
```json
{
"type": "snell",
"tag": "snell-in",
... // 监听字段
"version": 6,
"psk": "password",
"users": [
{
"name": "sekai",
"userkey": "user-password"
}
],
"mode": ""
}
```
### 监听字段
参阅 [监听字段](/zh/configuration/shared/listen/)。
### 字段
#### version
==必填==
Snell 协议版本，`5` `6` 之一。
版本 `5` 支持 HTTP 混淆（`obfs_mode`）；版本 `6` 以流量整形（`mode`）取而代之，并要求
`psk` 长度为 12 到 255 字节。
!!! note
由于我们有意不支持 Snell v5 的 QUIC 代理模式，v5 的线路协议实际上与 v4 没有区别，
因此不提供独立的 v4 服务器和 v5 客户端。
#### psk
==必填==
预共享密钥。
#### users
Snell 用户。
设置后，服务器运行于多用户模式：每一项包含 `name`（可选，用于日志）和 `userkey`
（用户密钥）。顶层的 `psk` 仍作为服务器密钥。
#### obfs_mode
==仅版本 5==
HTTP 混淆模式，`none` `http` 之一。
默认为 `none`。
#### mode
==仅版本 6==
流量整形模式，`default` `unshaped` `unsafe-raw` 之一。
默认为 `default`。
docs/configuration/inbound/tproxy.md
+13 -1
View File
@@ -1,3 +1,9 @@
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [udp_mapping](/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/configuration/shared/udp-nat/#udp_nat_max)
!!! quote ""
Only supported on Linux.
@@ -11,7 +17,9 @@
... // Listen Fields
"network": "udp"
"network": "udp",
... // UDP NAT Fields
}
```
@@ -26,3 +34,7 @@ See [Listen Fields](/configuration/shared/listen/) for details.
Listen network, one of `tcp` `udp`.
Both if empty.
### UDP NAT Fields
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
docs/configuration/inbound/tproxy.zh.md
+13 -1
View File
@@ -1,3 +1,9 @@
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [udp_mapping](/zh/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/zh/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/zh/configuration/shared/udp-nat/#udp_nat_max)
!!! quote ""
仅支持 Linux。
@@ -11,7 +17,9 @@
... // 监听字段
"network": "udp"
"network": "udp",
... // UDP NAT 字段
}
```
@@ -26,3 +34,7 @@
监听的网络协议，`tcp` `udp` 之一。
默认所有。
### UDP NAT 字段
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
docs/configuration/inbound/tuic.md
+8 -2
View File
@@ -18,7 +18,9 @@
"auth_timeout": "3s",
"zero_rtt_handshake": false,
"heartbeat": "10s",
"tls": {}
"tls": {},
... // QUIC Fields
}
```
@@ -75,4 +77,8 @@ Interval for sending heartbeat packets for keeping the connection alive
==Required==
TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
TLS configuration, see [TLS](/configuration/shared/tls/#inbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
docs/configuration/inbound/tuic.zh.md
+8 -2
View File
@@ -18,7 +18,9 @@
"auth_timeout": "3s",
"zero_rtt_handshake": false,
"heartbeat": "10s",
"tls": {}
"tls": {},
... // QUIC 字段
}
```
@@ -75,4 +77,8 @@ QUIC 拥塞控制算法
==必填==
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#入站)。
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#入站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
docs/configuration/inbound/tun.md
+112 -9
View File
@@ -4,8 +4,14 @@ icon: material/new-box
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [include_mac_address](#include_mac_address)
:material-plus: [exclude_mac_address](#exclude_mac_address)
:material-plus: [include_mac_address](#include_mac_address)
:material-plus: [exclude_mac_address](#exclude_mac_address)
:material-plus: [dns_mode](#dns_mode)
:material-plus: [dns_address](#dns_address)
:material-plus: [netns](#netns)
:material-plus: [udp_mapping](/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/configuration/shared/udp-nat/#udp_nat_max)
!!! quote "Changes in sing-box 1.13.3"
@@ -73,6 +79,11 @@ icon: material/new-box
"fdfe:dcba:9876::1/126"
],
"mtu": 9000,
"dns_mode": "hijack",
"dns_address": [
"172.18.0.2",
"fdfe:dcba:9876::2"
],
"auto_route": true,
"iproute2_table_index": 2022,
"iproute2_rule_index": 9000,
@@ -104,7 +115,9 @@ icon: material/new-box
"geoip-cn"
],
"endpoint_independent_nat": false,
"udp_timeout": "5m",
... // UDP NAT Fields
"stack": "system",
"include_interface": [
"lan0"
@@ -134,6 +147,12 @@ icon: material/new-box
"exclude_package": [
"com.android.captiveportallogin"
],
"include_mac_address": [
"00:11:22:33:44:55"
],
"exclude_mac_address": [
"66:77:88:99:aa:bb"
],
"platform": {
"http_proxy": {
"enabled": false,
@@ -184,6 +203,22 @@ icon: material/new-box
Virtual device name, automatically selected if empty.
#### netns
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux.
Create the tun interface in the specified network namespace, name, path, or the tag of a
[network namespace](/configuration/network-namespace/).
When set, `auto_route` and `auto_redirect` operate inside the namespace, and no root privilege is
required if the namespace is owned by the current user.
Conflict with `platform`.
#### address
!!! question "Since sing-box 1.10.0"
@@ -210,6 +245,52 @@ IPv6 prefix for the tun interface.
The maximum transmission unit.
#### dns_mode
!!! question "Since sing-box 1.14.0"
How DNS is handled on the TUN interface.
| Mode | Description |
|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `disabled` | Do not configure native DNS and do not hijack DNS traffic. |
| `native` | Set the platform's native interface DNS where possible: per-interface DNS on Windows and Apple platforms, and `systemd-resolved` interface DNS on Linux. |
| `hijack` | Same as `native`, with additional port 53 hijacking described below. Used by default. |
`hijack` adds the following on top of `native`:
*On Linux*: only DNS sent to non-local destinations can be intercepted.
Traffic destined to addresses on the host's own interfaces (such as
`127.0.0.53` or the host's LAN-side IP) is delivered through the kernel
`local` routing table before any user rule applies, and `OUTPUT` NAT cannot
redirect packets going through `lo`.
- Without `auto_redirect`, an `iproute2` rule makes port 53 skip the `main`
table's specific-route lookup, forcing DNS that would otherwise be
delivered through a directly-attached subnet through the TUN. Destination
addresses are not rewritten.
- With `auto_redirect`, an nftables rule DNATs port 53 traffic directly to
[`dns_address`](#dns_address).
*On Windows with [`strict_route`](#strict_route)*: a WFP filter blocks port
53 traffic going through interfaces other than the TUN.
#### dns_address
!!! question "Since sing-box 1.14.0"
List of DNS server addresses used by [`dns_mode`](#dns_mode).
When unset, sing-box derives one address per family by taking the next IP after
the first IPv4/IPv6 entry in [`address`](#address). Connections toward those
derived addresses are additionally hijacked into the sing-box DNS module,
equivalent to a [`hijack-dns`](/configuration/route/rule_action/#hijack-dns)
route action; this preserves the behaviour from before this option was added.
When set, this auto-hijack is not applied; configure an explicit
[`hijack-dns`](/configuration/route/rule_action/#hijack-dns) route rule if the
behaviour is still required.
#### gso
!!! failure "Deprecated in sing-box 1.11.0"
@@ -477,12 +558,6 @@ Enable endpoint-independent NAT.
Performance may degrade slightly, so it is not recommended to enable on when it is not needed.
#### udp_timeout
UDP NAT expiration time.
`5m` will be used by default.
#### stack
!!! quote "Changes in sing-box 1.8.0"
@@ -560,6 +635,30 @@ Limit android packages in route.
Exclude android packages in route.
#### include_mac_address
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux with `auto_route` and `auto_redirect` enabled.
Limit MAC addresses in route. Not limited by default.
Conflict with `exclude_mac_address`.
#### exclude_mac_address
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux with `auto_route` and `auto_redirect` enabled.
Exclude MAC addresses in route.
Conflict with `include_mac_address`.
#### platform
Platform-specific settings, provided by client applications.
@@ -600,6 +699,10 @@ Hostnames that bypass the HTTP proxy.
Hostnames that use the HTTP proxy.
### UDP NAT Fields
See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.
### Listen Fields
See [Listen Fields](/configuration/shared/listen/) for details.
docs/configuration/inbound/tun.zh.md
+107 -7
View File
@@ -2,6 +2,17 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [include_mac_address](#include_mac_address)
:material-plus: [exclude_mac_address](#exclude_mac_address)
:material-plus: [dns_mode](#dns_mode)
:material-plus: [dns_address](#dns_address)
:material-plus: [netns](#netns)
:material-plus: [udp_mapping](/zh/configuration/shared/udp-nat/#udp_mapping)
:material-plus: [udp_filtering](/zh/configuration/shared/udp-nat/#udp_filtering)
:material-plus: [udp_nat_max](/zh/configuration/shared/udp-nat/#udp_nat_max)
!!! quote "sing-box 1.13.3 中的更改"
:material-alert: [strict_route](#strict_route)
@@ -68,6 +79,11 @@ icon: material/new-box
"fdfe:dcba:9876::1/126"
],
"mtu": 9000,
"dns_mode": "hijack",
"dns_address": [
"172.18.0.2",
"fdfe:dcba:9876::2"
],
"auto_route": true,
"iproute2_table_index": 2022,
"iproute2_rule_index": 9000,
@@ -100,7 +116,9 @@ icon: material/new-box
"geoip-cn"
],
"endpoint_independent_nat": false,
"udp_timeout": "5m",
... // UDP NAT 字段
"stack": "system",
"include_interface": [
"lan0"
@@ -130,6 +148,12 @@ icon: material/new-box
"exclude_package": [
"com.android.captiveportallogin"
],
"include_mac_address": [
"00:11:22:33:44:55"
],
"exclude_mac_address": [
"66:77:88:99:aa:bb"
],
"platform": {
"http_proxy": {
"enabled": false,
@@ -181,6 +205,20 @@ icon: material/new-box
虚拟设备名称，默认自动选择。
#### netns
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux。
在指定的网络命名空间中创建 tun 接口，可以是名称、路径，或[网络命名空间](/zh/configuration/network-namespace/)的标签。
设置后，`auto_route` 和 `auto_redirect` 在该命名空间内生效；若命名空间归当前用户所有，则无需 root 权限。
与 `platform` 冲突。
#### address
!!! question "自 sing-box 1.10.0 起"
@@ -211,6 +249,46 @@ tun 接口的 IPv6 前缀。
最大传输单元。
#### dns_mode
!!! question "自 sing-box 1.14.0 起"
TUN 接口上 DNS 的处理方式。
| 模式 | 描述 |
|------------|-------------------------------------------------------------------------------------------------------|
| `disabled` | 不设置原生 DNS，也不劫持 DNS 流量。 |
| `native` | 尽可能设置平台的原生接口 DNS：Windows 与 Apple 上的接口 DNS，Linux 上的 `systemd-resolved` 接口 DNS。 |
| `hijack` | 与 `native` 相同，并额外执行下文所述的 53 端口劫持。默认使用。 |
`hijack` 在 `native` 之上额外执行：
*Linux*：只能劫持发往非本机地址的 DNS。发往本机接口地址（如 `127.0.0.53`
或本机 LAN 接口 IP）的流量由内核 `local` 路由表在所有用户规则之前直接交付，
`OUTPUT` 链 NAT 也无法对走 `lo` 的包生效。
- 未启用 `auto_redirect` 时：通过 `iproute2` 规则让 53 端口跳过 `main` 表的
具体路由查找，把本来会经直连子网直接送达的 DNS 改走 TUN —— 不重写目的地址。
- 启用 `auto_redirect` 时：通过 nftables 规则将 53 端口流量直接 DNAT 至
[`dns_address`](#dns_address)。
*Windows 启用 [`strict_route`](#strict_route) 时*：通过 WFP 过滤器阻止经由非
TUN 接口的 53 端口流量。
#### dns_address
!!! question "自 sing-box 1.14.0 起"
[`dns_mode`](#dns_mode) 使用的 DNS 服务器地址列表。
未设置时，sing-box 会按地址族在 [`address`](#address) 的第一个 IPv4/IPv6
条目后面取下一个 IP 作为 DNS 服务器地址，并将流向这些推导地址的连接额外劫持到
sing-box DNS 模块，等价于一条
[`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) 路由动作；这与此选项加入之前的行为一致。
设置后，将不再自动劫持；如仍需此行为，请显式配置
[`hijack-dns`](/zh/configuration/route/rule_action/#hijack-dns) 路由规则。
#### gso
!!! failure "已在 sing-box 1.11.0 废弃"
@@ -460,12 +538,6 @@ tun 接口的 IPv6 前缀。
性能可能会略有下降，所以不建议在不需要的时候开启。
#### udp_timeout
UDP NAT 过期时间。
默认使用 `5m`。
#### stack
!!! quote "sing-box 1.8.0 中的更改"
@@ -543,6 +615,30 @@ TCP/IP 栈。
排除路由的 Android 应用包名。
#### include_mac_address
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux，且需要 `auto_route` 和 `auto_redirect` 已启用。
限制被路由的 MAC 地址。默认不限制。
与 `exclude_mac_address` 冲突。
#### exclude_mac_address
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux，且需要 `auto_route` 和 `auto_redirect` 已启用。
排除路由的 MAC 地址。
与 `include_mac_address` 冲突。
#### platform
平台特定的设置，由客户端应用提供。
@@ -583,6 +679,10 @@ TCP/IP 栈。
代理的主机名列表。
### UDP NAT 字段
参阅 [UDP NAT 字段](/zh/configuration/shared/udp-nat/)。
### 监听字段
参阅 [监听字段](/zh/configuration/shared/listen/)。
docs/configuration/index.md
+9 -2
View File
@@ -1,15 +1,18 @@
# Introduction
sing-box uses JSON for configuration files.
### Structure
```json
{
"$schema": "https://sing-box.sagernet.org/schema.json",
"log": {},
"dns": {},
"ntp": {},
"certificate": {},
"certificate_providers": [],
"http_clients": [],
"network_namespaces": [],
"endpoints": [],
"inbounds": [],
"outbounds": [],
@@ -23,10 +26,14 @@ sing-box uses JSON for configuration files.
| Key | Format |
|----------------|---------------------------------|
| `$schema` | [JSON Schema](./schema/) |
| `log` | [Log](./log/) |
| `dns` | [DNS](./dns/) |
| `ntp` | [NTP](./ntp/) |
| `certificate` | [Certificate](./certificate/) |
| `certificate_providers` | [Certificate Provider](./shared/certificate-provider/) |
| `http_clients` | [HTTP Client](./shared/http-client/) |
| `network_namespaces` | [Network Namespace](./network-namespace/) |
| `endpoints` | [Endpoint](./endpoint/) |
| `inbounds` | [Inbound](./inbound/) |
| `outbounds` | [Outbound](./outbound/) |
@@ -50,4 +57,4 @@ sing-box format -w -c config.json -D config_directory
```bash
sing-box merge output.json -c config.json -D config_directory
```
```
docs/configuration/index.zh.md
+9 -2
View File
@@ -1,15 +1,18 @@
# 引言
sing-box 使用 JSON 作为配置文件格式。
### 结构
```json
{
"$schema": "https://sing-box.sagernet.org/schema.json",
"log": {},
"dns": {},
"ntp": {},
"certificate": {},
"certificate_providers": [],
"http_clients": [],
"network_namespaces": [],
"endpoints": [],
"inbounds": [],
"outbounds": [],
@@ -23,10 +26,14 @@ sing-box 使用 JSON 作为配置文件格式。
| Key | Format |
|----------------|------------------------|
| `$schema` | [JSON Schema](./schema/) |
| `log` | [日志](./log/) |
| `dns` | [DNS](./dns/) |
| `ntp` | [NTP](./ntp/) |
| `certificate` | [证书](./certificate/) |
| `certificate_providers` | [证书提供者](./shared/certificate-provider/) |
| `http_clients` | [HTTP 客户端](./shared/http-client/) |
| `network_namespaces` | [网络命名空间](./network-namespace/) |
| `endpoints` | [端点](./endpoint/) |
| `inbounds` | [入站](./inbound/) |
| `outbounds` | [出站](./outbound/) |
@@ -50,4 +57,4 @@ sing-box format -w -c config.json -D config_directory
```bash
sing-box merge output.json -c config.json -D config_directory
```
```
docs/configuration/network-namespace/default.md
+31
View File
@@ -0,0 +1,31 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# Default
Attach to an existing network namespace.
### Structure
```json
{
"network_namespaces": [
{
"type": "default", // optional
"tag": "",
"path": ""
}
]
}
```
### Fields
#### path
==Required==
Name or path of the network namespace, for example `sing` or `/run/netns/sing`.
docs/configuration/network-namespace/default.zh.md
+31
View File
@@ -0,0 +1,31 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# Default
附加到已存在的网络命名空间。
### 结构
```json
{
"network_namespaces": [
{
"type": "default", // 可选
"tag": "",
"path": ""
}
]
}
```
### 字段
#### path
==必填==
网络命名空间的名称或路径，例如 `sing` 或 `/run/netns/sing`。
docs/configuration/network-namespace/index.md
+43
View File
@@ -0,0 +1,43 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux.
# Network Namespace
Network namespaces let inbounds and outbounds run inside a separate Linux network namespace,
referenced by tag from the [tun](/configuration/inbound/tun/#netns),
[Listen Fields](/configuration/shared/listen/#netns) and [Dial Fields](/configuration/shared/dial/#netns).
### Structure
```json
{
"network_namespaces": [
{
"type": "",
"tag": ""
}
]
}
```
#### type
The type of the network namespace, `default` is used by default.
| Type | Format |
|-----------|------------------------|
| `default` | [Default](./default/) |
| `unshare` | [Unshare](./unshare/) |
#### tag
==Required==
The tag of the network namespace.
docs/configuration/network-namespace/index.zh.md
+43
View File
@@ -0,0 +1,43 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux。
# 网络命名空间
网络命名空间使入站和出站可以运行在独立的 Linux 网络命名空间中，
通过标签从 [tun](/zh/configuration/inbound/tun/#netns)、
[监听字段](/zh/configuration/shared/listen/#netns) 和 [拨号字段](/zh/configuration/shared/dial/#netns) 引用。
### 结构
```json
{
"network_namespaces": [
{
"type": "",
"tag": ""
}
]
}
```
#### type
网络命名空间的类型，默认使用 `default`。
| 类型 | 格式 |
|-----------|------------------------|
| `default` | [Default](./default/) |
| `unshare` | [Unshare](./unshare/) |
#### tag
==必填==
网络命名空间的标签。
docs/configuration/network-namespace/unshare.md
+36
View File
@@ -0,0 +1,36 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# Unshare
Create a new network namespace, without root privilege.
!!! info ""
Rootless operation requires the kernel to allow unprivileged user namespace creation.
### Structure
```json
{
"network_namespaces": [
{
"type": "unshare",
"tag": "",
"pid_file": ""
}
]
}
```
### Fields
#### pid_file
If set, the PID of the process holding the namespace open is written to this path.
The namespace can be entered with `nsenter -t <pid> -n` when sing-box is run as root,
or `nsenter -t <pid> -U --preserve-credentials -n` otherwise.
docs/configuration/network-namespace/unshare.zh.md
+36
View File
@@ -0,0 +1,36 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# Unshare
创建一个新的网络命名空间，无需 root 权限。
!!! info ""
无 root 运行需要内核允许非特权用户创建 user namespace。
### 结构
```json
{
"network_namespaces": [
{
"type": "unshare",
"tag": "",
"pid_file": ""
}
]
}
```
### 字段
#### pid_file
如果设置，持有该命名空间的进程 PID 将写入此路径。
当 sing-box 以 root 运行时，可通过 `nsenter -t <pid> -n` 进入该命名空间，
否则使用 `nsenter -t <pid> -U --preserve-credentials -n`。
docs/configuration/outbound/bridge.md
+77
View File
@@ -0,0 +1,77 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
# Bridge
!!! quote ""
Requires privileges. Supported on Linux, macOS, Windows, rooted Android, and jailbroken iOS.
For graphical clients: on macOS, only available in the standalone version and requires the
Helper Service; on Android, requires root permission; on iOS, requires jailbreak.
`bridge` is the L3 counterpart of the `direct` outbound: it forwards L3 connections
(TCP, UDP and ICMP) directly out of a network interface. Route L3 traffic to it from a TUN
or other L3 endpoints via the `route` action in
[Pre-match](/configuration/shared/pre-match/); L4 connections will be rejected.
Traffic to local addresses of the machine (loopback, or addresses assigned to its
network interfaces) will be rejected.
It is recommended to use [`preferred_by`](/configuration/route/rule/#preferred_by)
as a gate in the `route` rule: it only matches in
[pre-match](/configuration/shared/pre-match/) and excludes local addresses that
cannot be routed.
### Structure
```json
{
"type": "bridge",
"tag": "bridge-out",
"interface": "",
"bridge_name": "",
"iproute2_table_index": 0,
"iproute2_rule_index": 0
}
```
### Fields
#### interface
Interface name for forwarded traffic to egress.
The default interface will be used by default.
Forwarded traffic will be dropped while the interface is unavailable.
#### bridge_name
Custom bridge TUN interface name prefix, `bridge` is used by default.
Not effective on Apple platforms.
#### iproute2_table_index
!!! quote ""
Only supported on Linux, and only takes effect when `interface` is set.
Linux iproute2 table index for pinned egress routes.
`2200` + instance index is used by default.
#### iproute2_rule_index
!!! quote ""
Only supported on Linux.
Linux iproute2 rule start index.
`100` is used by default.
docs/configuration/outbound/bridge.zh.md
+72
View File
@@ -0,0 +1,72 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
# Bridge
!!! quote ""
需要特权。支持 Linux、macOS、Windows、rooted Android 和越狱 iOS。
对于图形客户端：macOS 仅独立版本可用，且需要辅助服务；Android 需要 root 权限；iOS 需要越狱。
`bridge` 是 `direct` 出站的 L3 版本：它将 L3 连接（TCP、UDP 和 ICMP）直接从网络接口转发出去。
通过[预匹配](/zh/configuration/shared/pre-match/)中的 `route` 动作，将 L3 流量从 TUN
或其他 L3 endpoints 路由到它；L4 连接将被拒绝。
到本机本地地址（loopback 或分配给本机网络接口的地址）的流量将被拒绝。
建议使用 [`preferred_by`](/zh/configuration/route/rule/#preferred_by) 作为 `route`
规则的门禁：它仅在[预匹配](/zh/configuration/shared/pre-match/)中匹配，且排除了无法路由的本地地址。
### 结构
```json
{
"type": "bridge",
"tag": "bridge-out",
"interface": "",
"bridge_name": "",
"iproute2_table_index": 0,
"iproute2_rule_index": 0
}
```
### 字段
#### interface
转发流量流出的网络接口名称。
默认使用默认接口。
接口不可用期间，转发流量将被丢弃。
#### bridge_name
自定义 bridge TUN 接口名前缀，默认使用 `bridge`。
在 Apple 平台上无效。
#### iproute2_table_index
!!! quote ""
仅支持 Linux，且仅在设置了 `interface` 时生效。
用于固定出口路由的 Linux iproute2 路由表索引。
默认使用 `2200` + 实例索引。
#### iproute2_rule_index
!!! quote ""
仅支持 Linux。
Linux iproute2 规则起始索引。
默认使用 `100`。
docs/configuration/outbound/hysteria.md
+34 -23
View File
@@ -27,13 +27,18 @@ icon: material/new-box
"obfs": "fuck me till the daylight",
"auth": "",
"auth_str": "password",
"network": "",
"tls": {},
... // QUIC Fields
... // Dial Fields
// Deprecated
"recv_window_conn": 0,
"recv_window": 0,
"disable_mtu_discovery": false,
"network": "tcp",
"tls": {},
... // Dial Fields
"disable_mtu_discovery": false
}
```
@@ -104,24 +109,6 @@ Authentication password, in base64.
Authentication password.
#### recv_window_conn
The QUIC stream-level flow control window for receiving data.
`15728640 (15 MB/s)` will be used if empty.
#### recv_window
The QUIC connection-level flow control window for receiving data.
`67108864 (64 MB/s)` will be used if empty.
#### disable_mtu_discovery
Disables Path MTU Discovery (RFC 8899). Packets will then be at most 1252 (IPv4) / 1232 (IPv6) bytes in size.
Force enabled on for systems other than Linux and Windows (according to upstream).
#### network
Enabled network
@@ -136,6 +123,30 @@ Both is enabled by default.
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
### Deprecated Fields
#### recv_window_conn
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `stream_receive_window` instead.
#### recv_window
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `connection_receive_window` instead.
#### disable_mtu_discovery
!!! failure "Deprecated in sing-box 1.14.0"
Use QUIC fields `disable_path_mtu_discovery` instead.
docs/configuration/outbound/hysteria.zh.md
+33 -23
View File
@@ -27,13 +27,18 @@ icon: material/new-box
"obfs": "fuck me till the daylight",
"auth": "",
"auth_str": "password",
"network": "",
"tls": {},
... // QUIC 字段
... // 拨号字段
// 废弃的
"recv_window_conn": 0,
"recv_window": 0,
"disable_mtu_discovery": false,
"network": "tcp",
"tls": {},
... // 拨号字段
"disable_mtu_discovery": false
}
```
@@ -104,24 +109,6 @@ base64 编码的认证密码。
认证密码。
#### recv_window_conn
用于接收数据的 QUIC 流级流控制窗口。
默认 `15728640 (15 MB/s)`。
#### recv_window
用于接收数据的 QUIC 连接级流控制窗口。
默认 `67108864 (64 MB/s)`。
#### disable_mtu_discovery
禁用路径 MTU 发现 (RFC 8899)。 数据包的大小最多为 1252 (IPv4) / 1232 (IPv6) 字节。
强制为 Linux 和 Windows 以外的系统启用（根据上游）。
#### network
启用的网络协议。
@@ -136,7 +123,30 @@ base64 编码的认证密码。
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#出站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
### 废弃字段
#### recv_window_conn
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `stream_receive_window` 代替。
#### recv_window
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `connection_receive_window` 代替。
#### disable_mtu_discovery
!!! failure "已在 sing-box 1.14.0 废弃"
请使用 QUIC 字段 `disable_path_mtu_discovery` 代替。
docs/configuration/outbound/hysteria2.md
+164 -4
View File
@@ -1,3 +1,11 @@
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [hop_interval_max](#hop_interval_max)
:material-plus: [bbr_profile](#bbr_profile)
:material-plus: [disable_chrome_parrot](#disable_chrome_parrot)
:material-plus: [realm](#realm)
:material-alert: [obfs](#obfstype)
!!! quote "Changes in sing-box 1.11.0"
:material-plus: [server_ports](#server_ports)
@@ -9,13 +17,14 @@
{
"type": "hysteria2",
"tag": "hy2-out",
"server": "127.0.0.1",
"server_port": 1080,
"server_ports": [
"2080:3000"
],
"hop_interval": "",
"hop_interval_max": "",
"up_mbps": 100,
"down_mbps": 100,
"obfs": {
@@ -25,8 +34,26 @@
"password": "goofy_ahh_password",
"network": "tcp",
"tls": {},
... // QUIC Fields
"bbr_profile": "",
"brutal_debug": false,
"disable_chrome_parrot": false,
"realm": {
"server_url": "https://realm.example.com",
"token": "",
"realm_id": "",
"stun_servers": [],
"ip_version": 0,
"port_mapping": {
"enabled": false,
"timeout": "",
"lifetime": ""
},
"http_client": {}
},
... // Dial Fields
}
```
@@ -51,6 +78,8 @@
The server address.
Conflicts with `realm`.
#### server_port
==Required==
@@ -59,13 +88,15 @@ The server port.
Ignored if `server_ports` is set.
Conflicts with `realm`.
#### server_ports
!!! question "Since sing-box 1.11.0"
Server port range list.
Conflicts with `server_port`.
Conflicts with `server_port` and `realm`.
#### hop_interval
@@ -75,6 +106,14 @@ Port hopping interval.
`30s` is used by default.
#### hop_interval_max
!!! question "Since sing-box 1.14.0"
Maximum port hopping interval, used for randomization.
If set, the actual hop interval will be randomly chosen between `hop_interval` and `hop_interval_max`.
#### up_mbps, down_mbps
Max bandwidth, in Mbps.
@@ -83,7 +122,7 @@ If empty, the BBR congestion control algorithm will be used instead of Hysteria
#### obfs.type
QUIC traffic obfuscator type, only available with `salamander`.
QUIC traffic obfuscator type, one of `salamander` `gecko`.
Disabled if empty.
@@ -91,6 +130,22 @@ Disabled if empty.
QUIC traffic obfuscator password.
#### obfs.min_packet_size
!!! question "Since sing-box 1.14.0"
Minimum on-wire packet size in bytes. Gecko only.
`512` is used by default.
#### obfs.max_packet_size
!!! question "Since sing-box 1.14.0"
Maximum on-wire packet size in bytes. Gecko only.
`1200` is used by default.
#### password
Authentication password.
@@ -109,10 +164,115 @@ Both is enabled by default.
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
#### bbr_profile
!!! question "Since sing-box 1.14.0"
BBR congestion control algorithm profile, one of `conservative` `standard` `aggressive`.
`standard` is used by default.
#### brutal_debug
Enable debug information logging for Hysteria Brutal CC.
#### disable_chrome_parrot
!!! question "Since sing-box 1.14.0"
Disable Chrome QUIC fingerprint parroting.
If it is not disabled, the client's QUIC handshake is made to parrot Chrome's, so that Hysteria traffic
is harder to identify by handshake fingerprinting.
To match Chrome, the client uses Chrome's own QUIC parameters, which override some settings:
`idle_timeout` is fixed at 30 seconds, `max_concurrent_streams` and `initial_packet_size` are replaced by
Chrome's values, and the receive windows start at Chrome's initial values before growing to the configured
maximums.
!!! warning ""
Chrome does not declare support for Ed25519, so a server using an Ed25519 certificate will fail the
handshake. Use an ECDSA or RSA certificate instead; certificates issued by ACME are unaffected.
#### realm
!!! question "Since sing-box 1.14.0"
Connect to a Hysteria2 server through a Hysteria Realm rendezvous service.
The outbound queries the realm for the server's current public addresses, performs UDP hole-punching, and proceeds with the normal QUIC handshake.
Conflicts with `server`, `server_port` and `server_ports`.
The TLS SNI defaults to the host portion of `server_url`. Set `tls.server_name` to match the certificate the Hysteria2 server presents.
See [Hysteria Realm](/configuration/service/hysteria-realm/) for the rendezvous service.
#### realm.server_url
==Required==
Realm rendezvous service URL.
#### realm.token
Bearer token for the realm. Must match one of `users[].token` configured on the realm.
#### realm.realm_id
==Required==
The same slot identifier the target Hysteria2 server registered.
#### realm.stun_servers
==Required==
List of STUN servers (`host` or `host:port`) used to discover this client's public addresses.
Domain names are resolved using [`domain_resolver`](/configuration/shared/dial/#domain_resolver) from Dial Fields.
#### realm.ip_version
Restrict realm connections (STUN, hole punching, and the resulting QUIC path) to a single IP version.
`4` or `6`. Both are used if empty.
#### realm.port_mapping
Maintain a UDP port mapping on the local gateway via UPnP or NAT-PMP.
The mapping is established before STUN discovery and improves hole-punching reliability behind gateways that support it; failures are non-fatal.
Requires IPv4: conflicts with `"ip_version": 6`.
#### realm.port_mapping.enabled
Enable port mapping.
#### realm.port_mapping.timeout
Timeout for gateway discovery and mapping operations.
`10s` is used by default.
#### realm.port_mapping.lifetime
Lease lifetime of the mapping; it is renewed at half the lifetime.
`10m` is used by default.
#### realm.http_client
HTTP client used to talk to the realm.
See [HTTP Client](/configuration/shared/http-client/) for details.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/outbound/hysteria2.zh.md
+162 -4
View File
@@ -1,3 +1,11 @@
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [hop_interval_max](#hop_interval_max)
:material-plus: [bbr_profile](#bbr_profile)
:material-plus: [disable_chrome_parrot](#disable_chrome_parrot)
:material-plus: [realm](#realm)
:material-alert: [obfs](#obfstype)
!!! quote "sing-box 1.11.0 中的更改"
:material-plus: [server_ports](#server_ports)
@@ -16,6 +24,7 @@
"2080:3000"
],
"hop_interval": "",
"hop_interval_max": "",
"up_mbps": 100,
"down_mbps": 100,
"obfs": {
@@ -25,8 +34,26 @@
"password": "goofy_ahh_password",
"network": "tcp",
"tls": {},
... // QUIC 字段
"bbr_profile": "",
"brutal_debug": false,
"disable_chrome_parrot": false,
"realm": {
"server_url": "https://realm.example.com",
"token": "",
"realm_id": "",
"stun_servers": [],
"ip_version": 0,
"port_mapping": {
"enabled": false,
"timeout": "",
"lifetime": ""
},
"http_client": {}
},
... // 拨号字段
}
```
@@ -49,6 +76,8 @@
服务器地址。
与 `realm` 冲突。
#### server_port
==必填==
@@ -57,13 +86,15 @@
如果设置了 `server_ports`，则忽略此项。
与 `realm` 冲突。
#### server_ports
!!! question "自 sing-box 1.11.0 起"
服务器端口范围列表。
与 `server_port` 冲突。
与 `server_port` 和 `realm` 冲突。
#### hop_interval
@@ -73,6 +104,14 @@
默认使用 `30s`。
#### hop_interval_max
!!! question "自 sing-box 1.14.0 起"
最大端口跳跃间隔，用于随机化。
如果设置，实际跳跃间隔将在 `hop_interval` 和 `hop_interval_max` 之间随机选择。
#### up_mbps, down_mbps
最大带宽。
@@ -81,13 +120,29 @@
#### obfs.type
QUIC 流量混淆器类型，仅可设为 `salamander`。
QUIC 流量混淆器类型，可选 `salamander` `gecko`。
如果为空则禁用。
#### obfs.password
QUIC 流量混淆器密码.
QUIC 流量混淆器密码。
#### obfs.min_packet_size
!!! question "自 sing-box 1.14.0 起"
最小线上数据包大小（字节）。仅限 Gecko。
默认使用 `512`。
#### obfs.max_packet_size
!!! question "自 sing-box 1.14.0 起"
最大线上数据包大小（字节）。仅限 Gecko。
默认使用 `1200`。
#### password
@@ -107,10 +162,113 @@ QUIC 流量混淆器密码.
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#出站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
#### bbr_profile
!!! question "自 sing-box 1.14.0 起"
BBR 拥塞控制算法配置，可选 `conservative` `standard` `aggressive`。
默认使用 `standard`。
#### brutal_debug
启用 Hysteria Brutal CC 的调试信息日志记录。
#### disable_chrome_parrot
!!! question "自 sing-box 1.14.0 起"
禁用 Chrome QUIC 指纹模仿。
如果没有禁用，客户端的 QUIC 握手将被构造为模仿 Chrome，使 Hysteria 流量更难通过握手指纹识别。
为了与 Chrome 一致，客户端使用 Chrome 自己的 QUIC 参数，其覆盖部分设置：
`idle_timeout` 固定为 30 秒，`max_concurrent_streams` 与 `initial_packet_size` 被替换为 Chrome 的值，
接收窗口从 Chrome 的初始值开始，再增长到配置的最大值。
!!! warning ""
Chrome 不声明支持 Ed25519，因此使用 Ed25519 证书的服务端将无法完成握手。
请改用 ECDSA 或 RSA 证书；由 ACME 签发的证书不受影响。
#### realm
!!! question "自 sing-box 1.14.0 起"
通过 Hysteria Realm 会合服务连接 Hysteria2 服务器。
出站从 realm 查询服务器当前的公网地址，执行 UDP 打洞，然后进行常规的 QUIC 握手。
与 `server`、`server_port` 和 `server_ports` 冲突。
TLS SNI 默认使用 `server_url` 中的主机名。需设置 `tls.server_name` 以匹配 Hysteria2 服务器证书覆盖的名字。
会合服务参阅 [Hysteria Realm](/zh/configuration/service/hysteria-realm/)。
#### realm.server_url
==必填==
Realm 会合服务 URL。
#### realm.token
Realm 的 Bearer 令牌，需与 realm 上配置的 `users[].token` 之一匹配。
#### realm.realm_id
==必填==
目标 Hysteria2 服务器注册时使用的相同槽位标识符。
#### realm.stun_servers
==必填==
用于发现本客户端公网地址的 STUN 服务器列表（`host` 或 `host:port`）。
域名通过 [拨号字段](/zh/configuration/shared/dial/) 中的 [`domain_resolver`](/zh/configuration/shared/dial/#domain_resolver) 解析。
#### realm.ip_version
将 realm 连接（STUN、打洞与最终的 QUIC 路径）限制为单一 IP 版本。
`4` 或 `6`。默认使用两者。
#### realm.port_mapping
通过 UPnP 或 NAT-PMP 在本地网关上维护 UDP 端口映射。
映射在 STUN 发现之前建立，可在支持的网关后提升打洞成功率；失败不影响正常流程。
需要 IPv4：与 `"ip_version": 6` 冲突。
#### realm.port_mapping.enabled
启用端口映射。
#### realm.port_mapping.timeout
网关发现与映射操作的超时。
默认使用 `10s`。
#### realm.port_mapping.lifetime
映射的租约时长；每过一半时长续期一次。
默认使用 `10m`。
#### realm.http_client
与 realm 通信使用的 HTTP 客户端。
参阅 [HTTP 客户端](/zh/configuration/shared/http-client/) 了解详情。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/outbound/index.md
+2 -1
View File
@@ -18,6 +18,7 @@
| Type | Format |
|----------------|--------------------------------|
| `direct` | [Direct](./direct/) |
| `bridge` | [Bridge](./bridge/) |
| `block` | [Block](./block/) |
| `socks` | [SOCKS](./socks/) |
| `http` | [HTTP](./http/) |
@@ -32,7 +33,7 @@
| `hysteria2` | [Hysteria2](./hysteria2/) |
| `mieru` | [Mieru](./mieru/) |
| `anytls` | [AnyTLS](./anytls/) |
| `mieru` | [Mieru](./mieru/) |
| `snell` | [Snell](./snell/) |
| `tor` | [Tor](./tor/) |
| `ssh` | [SSH](./ssh/) |
| `dns` | [DNS](./dns/) |
docs/configuration/outbound/index.zh.md
+2 -1
View File
@@ -18,6 +18,7 @@
| 类型 | 格式 |
|----------------|--------------------------------|
| `direct` | [Direct](./direct/) |
| `bridge` | [Bridge](./bridge/) |
| `block` | [Block](./block/) |
| `socks` | [SOCKS](./socks/) |
| `http` | [HTTP](./http/) |
@@ -32,7 +33,7 @@
| `hysteria2` | [Hysteria2](./hysteria2/) |
| `mieru` | [Mieru](./mieru/) |
| `anytls` | [AnyTLS](./anytls/) |
| `mieru` | [Mieru](./mieru/) |
| `snell` | [Snell](./snell/) |
| `tor` | [Tor](./tor/) |
| `ssh` | [SSH](./ssh/) |
| `dns` | [DNS](./dns/) |
docs/configuration/outbound/naive.md
+21 -1
View File
@@ -17,9 +17,11 @@ icon: material/new-box
"password": "password",
"insecure_concurrency": 0,
"extra_headers": {},
"stream_receive_window": "",
"udp_over_tcp": false | {},
"quic": false,
"quic_congestion_control": "",
"quic_session_receive_window": "",
"tls": {},
... // Dial Fields
@@ -78,6 +80,14 @@ Number of concurrent tunnel connections. Multiple connections make the tunneling
Extra headers to send in HTTP requests.
#### stream_receive_window
The flow control window.
When `quic` is enabled, it sets the initial QUIC stream receive window, and `6 MB` is used by default.
Otherwise, it sets the HTTP/2 session receive window, the stream receive window is set to half of it, and `4 MB` is used by default on iOS, `128 MB` on other platforms.
#### udp_over_tcp
UDP over TCP protocol settings.
@@ -99,7 +109,17 @@ QUIC congestion control algorithm.
| `cubic` | CUBIC |
| `reno` | New Reno |
`bbr` is used by default (the default of QUICHE, used by Chromium which NaiveProxy is based on).
`cubic` is used by default (the default of Chromium, which NaiveProxy is based on).
#### quic_session_receive_window
!!! note ""
Only used when `quic` is enabled.
The initial QUIC session receive window.
`15 MB` is used by default.
#### tls
docs/configuration/outbound/naive.zh.md
+21 -1
View File
@@ -17,9 +17,11 @@ icon: material/new-box
"password": "password",
"insecure_concurrency": 0,
"extra_headers": {},
"stream_receive_window": "",
"udp_over_tcp": false | {},
"quic": false,
"quic_congestion_control": "",
"quic_session_receive_window": "",
"tls": {},
... // 拨号字段
@@ -78,6 +80,14 @@ icon: material/new-box
HTTP 请求中发送的额外头部。
#### stream_receive_window
流量控制窗口。
当 `quic` 启用时，它设置 QUIC 初始流接收窗口，默认使用 `6 MB`。
否则，它设置 HTTP/2 会话接收窗口，流接收窗口被设置为它的一半，在 iOS 上默认使用 `4 MB`，在其他平台上默认使用 `128 MB`。
#### udp_over_tcp
UDP over TCP 配置。
@@ -99,7 +109,17 @@ QUIC 拥塞控制算法。
| `cubic` | CUBIC |
| `reno` | New Reno |
默认使用 `bbr`（NaiveProxy 基于的 Chromium 使用的 QUICHE 的默认值）。
默认使用 `cubic`（NaiveProxy 基于的 Chromium 的默认值）。
#### quic_session_receive_window
!!! note ""
仅在 `quic` 启用时使用。
QUIC 初始会话接收窗口。
默认使用 `15 MB`。
#### tls
docs/configuration/outbound/snell.md
+125
View File
@@ -0,0 +1,125 @@
---
icon: material/new-box
---
!!! question "Since sing-box 1.14.0"
### Structure
```json
{
"type": "snell",
"tag": "snell-out",
"server": "127.0.0.1",
"server_port": 1080,
"version": 4,
"psk": "password",
"userkey": "",
"reuse": false,
"network": "tcp",
"obfs_mode": "",
"obfs_host": "",
... // Dial Fields
}
```
### Version 6 Structure
```json
{
"type": "snell",
"tag": "snell-out",
"server": "127.0.0.1",
"server_port": 1080,
"version": 6,
"psk": "password",
"userkey": "",
"reuse": false,
"network": "tcp",
"mode": "",
... // Dial Fields
}
```
### Fields
#### server
==Required==
The server address.
#### server_port
==Required==
The server port.
#### version
==Required==
The Snell protocol version, one of `4` `6`.
Version `4` supports HTTP obfuscation (`obfs_mode` / `obfs_host`); version `6`
replaces it with traffic shaping (`mode`) and requires a `psk` of 12 to 255
bytes.
!!! note
Since we intentionally do not support the QUIC proxy mode of Snell v5, the v5 wire protocol
is effectively identical to v4, so no separate v4 server or v5 client is provided.
#### psk
==Required==
The pre-shared key.
#### userkey
The user key, used to authenticate against a multi-user server.
#### reuse
Enable connection reuse (the Snell v2 `CONNECT` command).
#### network
Enabled network
One of `tcp` `udp`.
Both is enabled by default.
#### obfs_mode
==Version 4 only==
HTTP obfuscation mode, one of `none` `http`.
`none` is used by default.
#### obfs_host
==Version 4 only==
The HTTP `Host` header sent when `obfs_mode` is `http`.
`bing.com` is used by default.
#### mode
==Version 6 only==
Traffic shaping mode, one of `default` `unshaped` `unsafe-raw`.
`default` is used by default.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/outbound/snell.zh.md
+124
View File
@@ -0,0 +1,124 @@
---
icon: material/new-box
---
!!! question "自 sing-box 1.14.0 起"
### 结构
```json
{
"type": "snell",
"tag": "snell-out",
"server": "127.0.0.1",
"server_port": 1080,
"version": 4,
"psk": "password",
"userkey": "",
"reuse": false,
"network": "tcp",
"obfs_mode": "",
"obfs_host": "",
... // 拨号字段
}
```
### 版本 6 结构
```json
{
"type": "snell",
"tag": "snell-out",
"server": "127.0.0.1",
"server_port": 1080,
"version": 6,
"psk": "password",
"userkey": "",
"reuse": false,
"network": "tcp",
"mode": "",
... // 拨号字段
}
```
### 字段
#### server
==必填==
服务器地址。
#### server_port
==必填==
服务器端口。
#### version
==必填==
Snell 协议版本，`4` `6` 之一。
版本 `4` 支持 HTTP 混淆（`obfs_mode` / `obfs_host`）；版本 `6` 以流量整形（`mode`）
取而代之，并要求 `psk` 长度为 12 到 255 字节。
!!! note
由于我们有意不支持 Snell v5 的 QUIC 代理模式，v5 的线路协议实际上与 v4 没有区别，
因此不提供独立的 v4 服务器和 v5 客户端。
#### psk
==必填==
预共享密钥。
#### userkey
用户密钥，用于向多用户服务器进行认证。
#### reuse
启用连接复用（Snell v2 `CONNECT` 命令）。
#### network
启用的网络协议。
`tcp` 或 `udp`。
默认所有。
#### obfs_mode
==仅版本 4==
HTTP 混淆模式，`none` `http` 之一。
默认为 `none`。
#### obfs_host
==仅版本 4==
`obfs_mode` 为 `http` 时发送的 HTTP `Host` 头。
默认为 `bing.com`。
#### mode
==仅版本 6==
流量整形模式，`default` `unshaped` `unsafe-raw` 之一。
默认为 `default`。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/outbound/ssh.md
+27
View File
@@ -1,3 +1,9 @@
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [cipher](#cipher)
:material-plus: [mac](#mac)
:material-plus: [kex_algorithm](#kex_algorithm)
### Structure
```json
@@ -17,6 +23,9 @@
],
"host_key_algorithms": [],
"client_version": "SSH-2.0-OpenSSH_7.4p1",
"cipher": [],
"mac": [],
"kex_algorithm": [],
... // Dial Fields
}
@@ -66,6 +75,24 @@ Host key algorithms.
Client version. Random version will be used if empty.
#### cipher
!!! question "Since sing-box 1.14.0"
Allowed ciphers. Default values are used if empty.
#### mac
!!! question "Since sing-box 1.14.0"
Allowed MAC algorithms. Default values are used if empty.
#### kex_algorithm
!!! question "Since sing-box 1.14.0"
Allowed key exchange algorithms. Default values are used if empty.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/outbound/ssh.zh.md
+27
View File
@@ -1,3 +1,9 @@
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [cipher](#cipher)
:material-plus: [mac](#mac)
:material-plus: [kex_algorithm](#kex_algorithm)
### 结构
```json
@@ -17,6 +23,9 @@
],
"host_key_algorithms": [],
"client_version": "SSH-2.0-OpenSSH_7.4p1",
"cipher": [],
"mac": [],
"kex_algorithm": [],
... // 拨号字段
}
@@ -66,6 +75,24 @@ SSH 用户, 默认使用 root。
客户端版本，默认使用随机值。
#### cipher
!!! question "自 sing-box 1.14.0 起"
允许的加密算法。留空使用默认值。
#### mac
!!! question "自 sing-box 1.14.0 起"
允许的 MAC 算法。留空使用默认值。
#### kex_algorithm
!!! question "自 sing-box 1.14.0 起"
允许的密钥交换算法。留空使用默认值。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/outbound/tuic.md
+7 -1
View File
@@ -16,7 +16,9 @@
"heartbeat": "10s",
"network": "tcp",
"tls": {},
... // QUIC Fields
... // Dial Fields
}
```
@@ -91,6 +93,10 @@ Both is enabled by default.
TLS configuration, see [TLS](/configuration/shared/tls/#outbound).
### QUIC Fields
See [QUIC Fields](/configuration/shared/quic/) for details.
### Dial Fields
See [Dial Fields](/configuration/shared/dial/) for details.
docs/configuration/outbound/tuic.zh.md
+7 -1
View File
@@ -16,7 +16,9 @@
"heartbeat": "10s",
"network": "tcp",
"tls": {},
... // QUIC 字段
... // 拨号字段
}
```
@@ -99,6 +101,10 @@ UDP 包中继模式
TLS 配置, 参阅 [TLS](/zh/configuration/shared/tls/#出站)。
### QUIC 字段
参阅 [QUIC 字段](/zh/configuration/shared/quic/) 了解详情。
### 拨号字段
参阅 [拨号字段](/zh/configuration/shared/dial/)。
docs/configuration/route/index.md
+52 -2
View File
@@ -4,6 +4,12 @@ icon: material/alert-decagram
# Route
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [default_http_client](#default_http_client)
:material-plus: [find_neighbor](#find_neighbor)
:material-plus: [dhcp_lease_files](#dhcp_lease_files)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [default_domain_resolver](#default_domain_resolver)
@@ -35,6 +41,10 @@ icon: material/alert-decagram
"override_android_vpn": false,
"default_interface": "",
"default_mark": 0,
"find_process": false,
"find_neighbor": false,
"dhcp_lease_files": [],
"default_http_client": "",
"default_domain_resolver": "", // or {}
"default_network_strategy": "",
"default_network_type": [],
@@ -107,13 +117,53 @@ Set routing mark by default.
Takes no effect if `outbound.routing_mark` is set.
#### find_process
!!! quote ""
Only supported on Linux, Windows, and macOS.
Enable process search for logging when no `process_name`, `process_path`, `package_name`, `user` or `user_id` rules exist.
#### find_neighbor
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux and macOS.
Enable neighbor resolution for logging when no `source_mac_address` or `source_hostname` rules exist.
See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
#### dhcp_lease_files
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux and macOS.
Custom DHCP lease file paths for hostname and MAC address resolution.
Automatically detected from common DHCP servers (dnsmasq, odhcpd, ISC dhcpd, Kea) if empty.
#### default_http_client
!!! question "Since sing-box 1.14.0"
Tag of the default [HTTP Client](/configuration/shared/http-client/) used by remote rule-sets.
If empty and `http_clients` is defined, the first HTTP client is used.
#### default_domain_resolver
!!! question "Since sing-box 1.12.0"
See [Dial Fields](/configuration/shared/dial/#domain_resolver) for details.
Can be overrides by `outbound.domain_resolver`.
Can be overridden by `outbound.domain_resolver`.
#### default_network_strategy
@@ -123,7 +173,7 @@ See [Dial Fields](/configuration/shared/dial/#network_strategy) for details.
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`.
Can be overridden by `outbound.network_strategy`.
Conflicts with `default_interface`.
docs/configuration/route/index.zh.md
+50
View File
@@ -4,6 +4,12 @@ icon: material/alert-decagram
# 路由
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [default_http_client](#default_http_client)
:material-plus: [find_neighbor](#find_neighbor)
:material-plus: [dhcp_lease_files](#dhcp_lease_files)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [default_domain_resolver](#default_domain_resolver)
@@ -37,6 +43,10 @@ icon: material/alert-decagram
"override_android_vpn": false,
"default_interface": "",
"default_mark": 0,
"find_process": false,
"find_neighbor": false,
"dhcp_lease_files": [],
"default_http_client": "",
"default_network_strategy": "",
"default_fallback_delay": ""
}
@@ -106,6 +116,46 @@ icon: material/alert-decagram
如果设置了 `outbound.routing_mark` 设置，则不生效。
#### find_process
!!! quote ""
仅支持 Linux、Windows 和 macOS。
在没有 `process_name`、`process_path`、`package_name`、`user` 或 `user_id` 规则时启用进程搜索以输出日志。
#### find_neighbor
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux 和 macOS。
在没有 `source_mac_address` 或 `source_hostname` 规则时启用邻居解析以输出日志。
参阅 [邻居解析](/configuration/shared/neighbor/) 了解设置方法。
#### dhcp_lease_files
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux 和 macOS。
用于主机名和 MAC 地址解析的自定义 DHCP 租约文件路径。
为空时自动从常见 DHCP 服务器（dnsmasq、odhcpd、ISC dhcpd、Kea）检测。
#### default_http_client
!!! question "自 sing-box 1.14.0 起"
远程规则集使用的默认 [HTTP 客户端](/zh/configuration/shared/http-client/) 的标签。
如果为空且 `http_clients` 已定义，将使用第一个 HTTP 客户端。
#### default_domain_resolver
!!! question "自 sing-box 1.12.0 起"
docs/configuration/route/rule.md
+47 -5
View File
@@ -2,6 +2,12 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [source_mac_address](#source_mac_address)
:material-plus: [source_hostname](#source_hostname)
:material-plus: [package_name_regex](#package_name_regex)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [interface_address](#interface_address)
@@ -124,6 +130,9 @@ icon: material/new-box
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"user": [
"sekai"
],
@@ -159,6 +168,12 @@ icon: material/new-box
"tailscale",
"wireguard"
],
"source_mac_address": [
"00:11:22:33:44:55"
],
"source_hostname": [
"my-device"
],
"rule_set": [
"geoip-cn",
"geosite-cn"
@@ -199,7 +214,7 @@ icon: material/new-box
(`source_port` || `source_port_range`) &&
`other fields`
Additionally, each branch inside an included rule-set can be considered merged into the outer rule, while different branches keep OR semantics.
When a rule-set contains only a single default rule without `invert`, its fields are considered merged into the outer rule per the logic above; otherwise, it is matched as an `other field`; different rule-sets always keep OR semantics.
#### inbound
@@ -343,6 +358,12 @@ Match process path using regular expression.
Match android package name.
#### package_name_regex
!!! question "Since sing-box 1.14.0"
Match android package name using regular expression.
#### user
!!! quote ""
@@ -444,10 +465,31 @@ See [Wi-Fi State](/configuration/shared/wifi-state/) for details.
Match specified outbounds' preferred routes.
| Type | Match |
|-------------|-----------------------------------------------|
| `tailscale` | Match MagicDNS domains and peers' allowed IPs |
| `wireguard` | Match peers's allowed IPs |
| Type | Match |
|-------------|----------------------------------------------------|
| `tailscale` | Match MagicDNS domains and peers' allowed IPs |
| `wireguard` | Match peers's allowed IPs |
| `bridge` | Match all addresses except local addresses of the machine, only in [pre-match](/configuration/shared/pre-match/) |
#### source_mac_address
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device MAC address.
#### source_hostname
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device hostname from DHCP leases.
#### rule_set
docs/configuration/route/rule.zh.md
+44 -2
View File
@@ -2,6 +2,12 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [source_mac_address](#source_mac_address)
:material-plus: [source_hostname](#source_hostname)
:material-plus: [package_name_regex](#package_name_regex)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [interface_address](#interface_address)
@@ -122,6 +128,9 @@ icon: material/new-box
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"user": [
"sekai"
],
@@ -157,6 +166,12 @@ icon: material/new-box
"tailscale",
"wireguard"
],
"source_mac_address": [
"00:11:22:33:44:55"
],
"source_hostname": [
"my-device"
],
"rule_set": [
"geoip-cn",
"geosite-cn"
@@ -195,9 +210,9 @@ icon: material/new-box
(`port` || `port_range`) &&
(`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) &&
(`source_port` || `source_port_range`) &&
`other fields`
`其他字段`
另外，引用规则集中的每个分支都可视为与外层规则合并，不同分支之间仍保持 OR 语义。
当规则集仅包含一条默认规则且非 invert 时，其中字段视为按以上规则与外层规则合并；否则，作为一条 `其他字段` 匹配；不同规则集之间始终保持 or。
#### inbound
@@ -341,6 +356,12 @@ icon: material/new-box
匹配 Android 应用包名。
#### package_name_regex
!!! question "自 sing-box 1.14.0 起"
使用正则表达式匹配 Android 应用包名。
#### user
!!! quote ""
@@ -446,6 +467,27 @@ icon: material/new-box
|-------------|--------------------------------|
| `tailscale` | 匹配 MagicDNS 域名和对端的 allowed IPs |
| `wireguard` | 匹配对端的 allowed IPs |
| `bridge` | 匹配除本机本地地址外的所有地址，仅在[预匹配](/zh/configuration/shared/pre-match/)中 |
#### source_mac_address
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux、macOS，或在 Android 和 macOS 图形客户端中支持。参阅 [邻居解析](/configuration/shared/neighbor/) 了解设置方法。
匹配源设备 MAC 地址。
#### source_hostname
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux、macOS，或在 Android 和 macOS 图形客户端中支持。参阅 [邻居解析](/configuration/shared/neighbor/) 了解设置方法。
匹配源设备从 DHCP 租约获取的主机名。
#### rule_set
docs/configuration/route/rule_action.md
+49 -2
View File
@@ -7,6 +7,13 @@ icon: material/new-box
:material-plus: [bypass](#bypass)
:material-alert: [reject](#reject)
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [resolve.disable_optimistic_cache](#disable_optimistic_cache)
:material-plus: [resolve.timeout](#timeout)
:material-plus: [tls_spoof](#tls_spoof)
:material-plus: [tls_spoof_method](#tls_spoof_method)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [tls_fragment](#tls_fragment)
@@ -144,7 +151,9 @@ Not available when `method` is set to drop.
"udp_timeout": "",
"tls_fragment": false,
"tls_fragment_fallback_delay": "",
"tls_record_fragment": ""
"tls_record_fragment": "",
"tls_spoof": "",
"tls_spoof_method": ""
}
```
@@ -243,6 +252,28 @@ The fallback value used when TLS segmentation cannot automatically determine the
Fragment TLS handshake into multiple TLS records to bypass firewalls.
#### tls_spoof
!!! question "Since sing-box 1.14.0"
!!! 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.
See outbound TLS [`spoof`](/configuration/shared/tls/#spoof) for details
and required privileges.
#### tls_spoof_method
!!! question "Since sing-box 1.14.0"
How the forged segment is rejected by the real server. See outbound TLS
[`spoof_method`](/configuration/shared/tls/#spoof_method) for the full table
of accepted values and platform notes.
### sniff
```json
@@ -279,7 +310,9 @@ Timeout for sniffing.
"server": "",
"strategy": "",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"timeout": "",
"client_subnet": null
}
```
@@ -302,12 +335,26 @@ DNS resolution strategy, available values are: `prefer_ipv4`, `prefer_ipv6`, `ip
Disable cache and save cache in this query.
#### disable_optimistic_cache
!!! question "Since sing-box 1.14.0"
Disable optimistic DNS caching in this query.
#### rewrite_ttl
!!! question "Since sing-box 1.12.0"
Rewrite TTL in DNS responses.
#### timeout
!!! question "Since sing-box 1.14.0"
Override the DNS query timeout for this lookup.
Will override `dns.timeout`.
#### client_subnet
!!! question "Since sing-box 1.12.0"
@@ -316,4 +363,4 @@ Append a `edns0-subnet` OPT extra record with the specified IP prefix to every q
If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
Will overrides `dns.client_subnet`.
Will override `dns.client_subnet`.
docs/configuration/route/rule_action.zh.md
+49 -1
View File
@@ -7,6 +7,13 @@ icon: material/new-box
:material-plus: [bypass](#bypass)
:material-alert: [reject](#reject)
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [resolve.disable_optimistic_cache](#disable_optimistic_cache)
:material-plus: [resolve.timeout](#timeout)
:material-plus: [tls_spoof](#tls_spoof)
:material-plus: [tls_spoof_method](#tls_spoof_method)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [tls_fragment](#tls_fragment)
@@ -134,7 +141,12 @@ icon: material/new-box
"fallback_delay": "",
"udp_disable_domain_unmapping": false,
"udp_connect": false,
"udp_timeout": ""
"udp_timeout": "",
"tls_fragment": false,
"tls_fragment_fallback_delay": "",
"tls_record_fragment": false,
"tls_spoof": "",
"tls_spoof_method": ""
}
```
@@ -232,6 +244,26 @@ UDP 连接超时时间。
通过分段 TLS 握手数据包到多个 TLS 记录来绕过防火墙检测。
#### tls_spoof
!!! question "自 sing-box 1.14.0 起"
!!! quote ""
仅支持 Linux、macOS 和 Windows，需要提升的权限。
在真实 ClientHello 之前注入携带本字段所指定 SNI 的伪造 TLS ClientHello，
用于欺骗仅放行特定主机名的 SNI 过滤中间盒。
详情与所需权限参阅出站 TLS [`spoof`](/zh/configuration/shared/tls/#spoof)。
#### tls_spoof_method
!!! question "自 sing-box 1.14.0 起"
控制伪造报文被真实服务器拒绝的方式。完整取值表与平台说明参阅出站 TLS
[`spoof_method`](/zh/configuration/shared/tls/#spoof_method)。
### sniff
```json
@@ -268,7 +300,9 @@ UDP 连接超时时间。
"server": "",
"strategy": "",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"timeout": "",
"client_subnet": null
}
```
@@ -291,12 +325,26 @@ DNS 解析策略，可用值有：`prefer_ipv4`、`prefer_ipv6`、`ipv4_only`、
在此查询中禁用缓存。
#### disable_optimistic_cache
!!! question "自 sing-box 1.14.0 起"
在此查询中禁用乐观 DNS 缓存。
#### rewrite_ttl
!!! question "自 sing-box 1.12.0 起"
重写 DNS 回应中的 TTL。
#### timeout
!!! question "自 sing-box 1.14.0 起"
覆盖此查询的 DNS 查询超时时间。
将覆盖 `dns.timeout`。
#### client_subnet
!!! question "自 sing-box 1.12.0 起"
docs/configuration/rule-set/headless-rule.md
+28
View File
@@ -2,6 +2,11 @@
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [package_name_regex](#package_name_regex)
:material-alert: [query_type](#query_type)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [network_interface_address](#network_interface_address)
@@ -78,6 +83,9 @@ icon: material/new-box
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"network_type": [
"wifi"
],
@@ -125,6 +133,20 @@ icon: material/new-box
#### query_type
!!! quote "Changes in sing-box 1.14.0"
When a DNS rule references this rule-set, this field now also applies
when the DNS rule is matched from an internal domain resolution that
does not target a specific DNS server. In earlier versions, only DNS
queries received from a client evaluated this field. See
[Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules)
for the full list.
When a DNS rule references a rule-set containing this field, the DNS
rule is incompatible in the same DNS configuration with Legacy Address
Filter Fields in DNS rules, the Legacy `strategy` DNS rule action
option, and the Legacy `rule_set_ip_cidr_accept_empty` DNS rule item.
DNS query type. Values can be integers or type name strings.
#### network
@@ -205,6 +227,12 @@ Match process path using regular expression.
Match android package name.
#### package_name_regex
!!! question "Since sing-box 1.14.0"
Match android package name using regular expression.
#### network_type
!!! question "Since sing-box 1.11.0"
docs/configuration/rule-set/headless-rule.zh.md
+25
View File
@@ -2,6 +2,11 @@
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [package_name_regex](#package_name_regex)
:material-alert: [query_type](#query_type)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [network_interface_address](#network_interface_address)
@@ -78,6 +83,9 @@ icon: material/new-box
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"network_type": [
"wifi"
],
@@ -125,6 +133,17 @@ icon: material/new-box
#### query_type
!!! quote "sing-box 1.14.0 中的更改"
当 DNS 规则引用此规则集时，此字段现在也会在 DNS 规则被未指定具体
DNS 服务器的内部域名解析匹配时生效。此前只有来自客户端的 DNS 查询
才会评估此字段。完整列表参阅
[迁移指南](/zh/migration/#dns-规则中的-ip_version-和-query_type-行为更改)。
当 DNS 规则引用了包含此字段的规则集时，该 DNS 规则在同一 DNS 配置中
不能与旧版地址筛选字段 (DNS 规则)、旧版 DNS 规则动作 `strategy` 选项，
或旧版 `rule_set_ip_cidr_accept_empty` DNS 规则项共存。
DNS 查询类型。值可以为整数或者类型名称字符串。
#### network
@@ -201,6 +220,12 @@ DNS 查询类型。值可以为整数或者类型名称字符串。
匹配 Android 应用包名。
#### package_name_regex
!!! question "自 sing-box 1.14.0 起"
使用正则表达式匹配 Android 应用包名。
#### network_type
!!! question "自 sing-box 1.11.0 起"
docs/configuration/rule-set/index.md
+59 -7
View File
@@ -1,3 +1,10 @@
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [http_client](#http_client)
:material-delete-clock: [download_detour](#download_detour)
:material-alert: [tag](#tag)
:material-plus: [initial_path](#initial_path)
!!! quote "Changes in sing-box 1.10.0"
:material-plus: `type: inline`
@@ -25,7 +32,7 @@
```json
{
"type": "local",
"tag": "",
"tag": "", // or []
"format": "source", // or binary
"path": ""
}
@@ -40,11 +47,16 @@
```json
{
"type": "remote",
"tag": "",
"tag": "", // or []
"format": "source", // or binary
"url": "",
"download_detour": "", // optional
"update_interval": "" // optional
"initial_path": "",
"http_client": "", // or {}
"update_interval": "",
// Deprecated
"download_detour": ""
}
```
@@ -62,6 +74,15 @@ Type of rule-set, `local` or `remote`.
Tag of rule-set.
!!! question "Since sing-box 1.14.0"
`tag` also accepts a list of tags to define multiple rule-sets sharing other options at once.
The `{tag}` placeholder in `path`, `url` or `initial_path` is replaced by each tag,
and is required when multiple tags are set.
Multiple tags conflict with `type: inline`.
### Inline Fields
!!! question "Since sing-box 1.10.0"
@@ -102,14 +123,45 @@ File path of rule-set.
Download URL of rule-set.
#### download_detour
#### initial_path
Tag of the outbound to download rule-set.
!!! question "Since sing-box 1.14.0"
Default outbound will be used if empty.
File path of the initial rule-set content.
Read once at startup when no cached rule-set is available, so startup is not
blocked by the initial download. The rule-set is still updated in the background
immediately after startup.
#### http_client
!!! question "Since sing-box 1.14.0"
HTTP Client for downloading rule-set.
See [HTTP Client Fields](/configuration/shared/http-client/) for details.
When empty, the default HTTP client is used: the one named by
[`default_http_client`](/configuration/route/#default_http_client), or the first top-level
`http_clients` entry when `default_http_client` is empty.
!!! failure "Implicit default deprecated in sing-box 1.14.0"
When neither `http_clients` nor `default_http_client` is configured, an implicit HTTP
client connecting through the default outbound is used. This implicit default is
deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0; define
`http_clients` instead.
#### update_interval
Update interval of rule-set.
`1d` will be used if empty.
#### download_detour
!!! failure "Deprecated in sing-box 1.14.0"
`download_detour` is deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0, use `http_client` instead.
Tag of the outbound to download rule-set.

Some files were not shown because too many files have changed in this diff Show More