wangjia/sing-box
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve OpenVPN & OpenConnect interoperability

Browse Source
This commit is contained in:
世界
2026-07-21 09:38:21 +08:00
parent 5cad5ad42d
commit 2ff294c4f4
47 changed files with 3915 additions and 440 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration/endpoint/openconnect.md
+237 -8
View File
@@ -21,9 +21,11 @@
"username": "",
"password": "",
"auth_group": "",
"cookie": "",
"token": {
"mode": "",
"secret": "",
"secret_path": "",
"pin": "",
"password": "",
"device_id": "",
@@ -31,6 +33,13 @@
},
"reported_os": "",
"user_agent": "",
"version": "",
"local_hostname": "",
"mobile": {
"platform_version": "",
"device_type": "",
"device_unique_id": ""
},
"csd": {
"wrapper_path": ""
},
@@ -50,8 +59,28 @@
]
},
"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": [],
@@ -125,30 +154,56 @@ Password used to fill matching authentication form fields.
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
Software token configuration for automatically answering matching token fields.
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==
Software token mode, one of:
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
==Required==
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.
@@ -173,13 +228,41 @@ Operating system identity reported to the VPN server when supported by the selec
For `anyconnect`, `gp`, and `pulse`, the supported values are `linux`, `linux-64`, `win`, `mac-intel`, `android`, and `apple-ios`.
`anyconnect` uses `linux-64` by default. `gp` and `pulse` select a value based on the system platform by default.
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.
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
@@ -263,16 +346,158 @@ Conflict with `tncc.certificates.certificate`.
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 and GlobalProtect.
When enabled, external authentication is not advertised to the server and an unexpected external authentication request 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
Allow deprecated TLS and DTLS versions and cipher suites required by legacy VPN servers.
Enable weak TLS and DTLS cipher suites and TLS 1.0 compatibility required by legacy VPN servers.
Disabled by default. This option does not disable server certificate verification.
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.
@@ -392,3 +617,7 @@ 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
+237 -8
View File
@@ -21,9 +21,11 @@
"username": "",
"password": "",
"auth_group": "",
"cookie": "",
"token": {
"mode": "",
"secret": "",
"secret_path": "",
"pin": "",
"password": "",
"device_id": "",
@@ -31,6 +33,13 @@
},
"reported_os": "",
"user_agent": "",
"version": "",
"local_hostname": "",
"mobile": {
"platform_version": "",
"device_type": "",
"device_unique_id": ""
},
"csd": {
"wrapper_path": ""
},
@@ -50,8 +59,28 @@
]
},
"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": [],
@@ -125,30 +154,56 @@ OpenConnect 协议 flavor，可选值为 `anyconnect`、`gp`、`fortinet`、`f5`
认证组，用于在所选 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 字段的软件 token 配置。
用于自动回答匹配 token 字段或进行 HTTP Bearer 认证的 token 配置。
必须设置 `token.secret` 或 `token.secret_path` 之一。
### token.mode
==必填==
软件 token 模式，可选值为：
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。
@@ -173,13 +228,41 @@ OpenConnect 协议 flavor，可选值为 `anyconnect`、`gp`、`fortinet`、`f5`
对于 `anyconnect`、`gp` 和 `pulse`，支持的值为 `linux`、`linux-64`、`win`、`mac-intel`、`android` 和 `apple-ios`。
`anyconnect` 默认使用 `linux-64`。`gp` 和 `pulse` 默认根据系统平台选择值。
默认值根据系统平台选择：Windows 使用 `win`，macOS 使用 `mac-intel`，Android 使用 `android`，iOS 使用 `apple-ios`，其他 64 位或 32 位系统使用 `linux-64` 或 `linux`。
### user_agent
所选 flavor 支持时向 VPN 服务器报告的 User-Agent。
默认值由 flavor 决定。
默认值由 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
@@ -263,16 +346,158 @@ PEM 格式的 TNCC 机器证书路径。
禁用 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 的 SSO、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 版本及密码套件。
启用旧版 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 证书内容。
@@ -392,3 +617,7 @@ MCA 证书和私钥必须同时设置或同时为空。
## 交互式认证
在 sing-box dashboard 或任意 sing-box 图形客户端的 `工具` > `端点` 中认证和管理 endpoint。
## DNS
推送的 DNS 设置不会安装到操作系统中。配置 [OpenConnect DNS 服务器](/zh/configuration/dns/server/openconnect/) 以通过 sing-box 使用这些设置。
docs/configuration/endpoint/openvpn-client.md
+213 -5
View File
@@ -9,6 +9,7 @@
"type": "openvpn-client",
"tag": "ovpn-client",
"mode": "tls",
"server": "127.0.0.1",
"server_port": 1194,
"servers": [
@@ -20,11 +21,18 @@
],
"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",
@@ -40,6 +48,7 @@
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
@@ -51,11 +60,16 @@
"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",
@@ -71,9 +85,17 @@
"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": "",
@@ -91,6 +113,17 @@
## 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.
@@ -147,10 +180,38 @@ Default OpenVPN transport network, one of `udp` or `tcp`.
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.
@@ -171,9 +232,31 @@ Static challenge text shown when requesting an authentication response.
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==
Required in TLS mode.
OpenVPN control channel TLS configuration.
@@ -283,6 +366,19 @@ 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`.
@@ -341,24 +437,49 @@ Conflict with `tls.control_wrap.key`.
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.
@@ -368,6 +489,20 @@ This prevents TCP packets from exceeding the path MTU after OpenVPN encapsulatio
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.
@@ -376,6 +511,18 @@ 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`.
@@ -396,7 +543,7 @@ Compression can weaken traffic confidentiality. Enable it only when required by
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. `yes` permits compression in both directions.
`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`.
@@ -433,36 +580,66 @@ For example, `route ` matches pushed IPv4 route options without matching `route-
### routes
IPv4 and IPv6 route prefixes routed through the OpenVPN endpoint.
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
Route all IPv4 traffic through the OpenVPN endpoint.
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 the IPv4 default route, and `ipv6` also routes all IPv6 traffic through the endpoint. Other OpenVPN flags are accepted for compatibility but do not change endpoint routing.
`!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.
@@ -484,12 +661,40 @@ 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.
@@ -502,6 +707,9 @@ 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
docs/configuration/endpoint/openvpn-client.zh.md
+190 -5
View File
@@ -9,6 +9,7 @@
"type": "openvpn-client",
"tag": "ovpn-client",
"mode": "tls",
"server": "127.0.0.1",
"server_port": 1194,
"servers": [
@@ -20,11 +21,18 @@
],
"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",
@@ -40,6 +48,7 @@
"remote_certificate_eku": "",
"remote_certificate_tls": "",
"certificate_profile": "",
"ns_certificate_type": "",
"version_min": "1.2",
"version_max": "",
"cipher": "",
@@ -51,11 +60,16 @@
"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",
@@ -71,9 +85,17 @@
"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": "",
@@ -91,6 +113,16 @@
## 字段
### mode
OpenVPN 会话模式，可选值为 `tls` 或 `static_key`。
默认使用 `tls`。
`static_key` 是已弃用的 OpenVPN 模式，不使用 TLS 控制通道且不提供前向保密。
为兼容无法修改的企业 VPN 服务器，此模式仍作为显式兼容选项保留。该模式不使用
`tls`、用户名/密码认证、拉取选项或 TLS 重协商选项。
### server
OpenVPN 服务器地址。
@@ -147,10 +179,36 @@ OpenVPN 服务器端口。
该值应用于 `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 用户名/密码认证的密码。
@@ -171,9 +229,31 @@ OpenVPN 用户名/密码认证的密码。
以明文显示静态质询响应。
### 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 配置。
@@ -283,6 +363,16 @@ OpenVPN 控制通道 TLS 配置。
默认使用 `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`。
@@ -341,24 +431,43 @@ OpenVPN 控制通道封装。
仅当 `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。
@@ -367,6 +476,20 @@ OpenVPN UDP packet 的最大大小，用于限制通过隧道发送的 TCP 连
为空时使用上游 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 大小。
@@ -375,6 +498,18 @@ OpenVPN UDP packet 的最大大小，用于限制通过隧道发送的 TCP 连
与 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`。
@@ -395,7 +530,7 @@ Compression 可能削弱流量机密性。仅在服务器要求时启用。
服务器推送的 compression 策略，可选值为 `no`、`asym` 或 `yes`。
默认使用 `no`，仅允许 compression stub framing。`asym` 接受来自服务器的 compressed packet，但不压缩出站 packet。`yes` 允许双向 compression。
默认使用 `no`，仅允许 compression stub framing。`asym` 接受来自服务器的 compressed packet，但不压缩出站 packet。为兼容 OpenVPN 2.7，`yes` 作为 `asym` 的旧别名接受；客户端绝不会发送 compressed packet。
当设为 `no` 时，与通过 `compression` 或 `compression_lzo` 启用的非 stub compression 冲突。
@@ -432,36 +567,56 @@ Filter action，可选值为 `accept`、`ignore` 或 `reject`。
### routes
通过 OpenVPN endpoint 路由的 IPv4 和 IPv6 route prefix。
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
通过 OpenVPN endpoint 路由所有 IPv4 流量。
在 sing-box 路由中对所有 IPv4 目的地优先选择 OpenVPN endpoint。
默认禁用。
这不会安装操作系统默认路由。
### redirect_gateway_flags
OpenVPN `redirect-gateway` flag。
`!ipv4` 禁用 IPv4 default route，`ipv6` 还会通过 endpoint 路由所有 IPv6 流量。接受其他 OpenVPN flag 以兼容配置，但它们不会改变 endpoint 路由。
`!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 的间隔。
@@ -482,12 +637,40 @@ OpenVPN `redirect-gateway` flag。
为空时，启用了 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 数量。
@@ -500,6 +683,8 @@ Notification 之间间隔一秒。设为 `0` 时禁用。
需要权限，且不能与现有系统接口冲突。
endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。
禁用时，sing-box 使用内部网络栈。
### name
docs/configuration/endpoint/openvpn-server.md
+248 -4
View File
@@ -14,9 +14,14 @@
"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": [
@@ -25,6 +30,9 @@
"password": ""
}
],
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"certificate": [],
"certificate_path": "",
@@ -33,7 +41,19 @@
"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": [],
@@ -42,12 +62,21 @@
"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,
@@ -57,6 +86,9 @@
"ping_interval": "",
"ping_restart": "",
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"handshake_window": "1m",
... // UDP NAT Fields
@@ -79,6 +111,9 @@ 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
@@ -93,6 +128,16 @@ 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`.
@@ -103,12 +148,27 @@ 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==
@@ -121,11 +181,26 @@ The prefix address is assigned to the server interface. The masked prefix is use
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` will be used by default.
`subnet` is used by default in TLS mode. `p2p` is used by default in
`static_key` mode.
### duplicate_cn
@@ -135,12 +210,16 @@ When disabled, a newly authenticated session replaces the existing session with
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.
@@ -149,9 +228,34 @@ Username.
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==
Required in TLS mode.
OpenVPN control channel TLS configuration.
@@ -191,7 +295,7 @@ Conflict with `tls.key`.
TLS CA certificate content, used to verify client certificates.
Either `tls.client_certificate` or `tls.client_certificate_path` is required.
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`.
@@ -199,7 +303,7 @@ Conflict with `tls.client_certificate_path`.
TLS CA certificate path, used to verify client certificates.
Either `tls.client_certificate` or `tls.client_certificate_path` is required.
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`.
@@ -215,12 +319,71 @@ 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.
@@ -272,12 +435,30 @@ clients without cookie support are accepted using the upstream `allow-noncookie`
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.
@@ -286,12 +467,37 @@ 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.
@@ -306,6 +512,22 @@ IPv4 and IPv6 prefixes can be mixed.
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`.
@@ -372,12 +594,34 @@ 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.
docs/configuration/endpoint/openvpn-server.zh.md
+232 -4
View File
@@ -14,9 +14,14 @@
"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": [
@@ -25,6 +30,9 @@
"password": ""
}
],
"static_key": [],
"static_key_path": "",
"key_direction": "",
"tls": {
"certificate": [],
"certificate_path": "",
@@ -33,7 +41,19 @@
"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": [],
@@ -42,12 +62,21 @@
"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,
@@ -57,6 +86,9 @@
"ping_interval": "",
"ping_restart": "",
"renegotiate_interval": "",
"renegotiate_disabled": false,
"renegotiate_bytes": 0,
"renegotiate_packets": 0,
"handshake_window": "1m",
... // UDP NAT 字段
@@ -79,6 +111,8 @@
需要特权且不能与已有系统接口冲突。
endpoint 会配置接口地址和 MTU，但不会安装操作系统路由或 DNS 设置。
如果禁用，sing-box 将使用内部网络栈。
### name
@@ -93,6 +127,14 @@ OpenVPN 接口 MTU。
默认使用 `1500`。
### mode
OpenVPN 会话模式，`tls` 或 `static_key` 之一。
默认使用 `tls`。
`static_key` 在没有 TLS 控制信道和前向保密的情况下服务一个对端，仅作为不可变部署的显式兼容选项保留。该模式不使用 `tls`、`users`、推送选项或 TLS 重协商选项。
### network
OpenVPN 传输网络，`udp` 或 `tcp` 之一。
@@ -103,12 +145,26 @@ OpenVPN 传输网络，`udp` 或 `tcp` 之一。
需要配置两个端点并使用互不重叠的 `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
==必填==
@@ -121,11 +177,25 @@ OpenVPN 服务器地址前缀列表。
第一个 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` 之一。
默认使用 `subnet`。
TLS 模式默认使用 `subnet`，`static_key` 模式默认使用 `p2p`。
### duplicate_cn
@@ -135,12 +205,16 @@ OpenVPN 服务器地址前缀列表。
默认禁用。
仅在 TLS 模式下可用。
### users
OpenVPN 用户名/密码用户列表。
如果设置，客户端除了通过 `tls.verify_client_certificate` 配置的证书策略外，还必须通过用户名/密码认证。
仅在 TLS 模式下可用。
### users.username
用户名。
@@ -149,9 +223,33 @@ OpenVPN 用户名/密码用户列表。
密码。
### 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 配置。
@@ -191,7 +289,7 @@ TLS 服务器私钥路径。
TLS CA 证书内容，用于验证客户端证书。
`tls.client_certificate` 或 `tls.client_certificate_path` 必填其一。
当 `tls.verify_client_certificate` 为 `require` 或 `optional` 时，`tls.client_certificate`、`tls.client_certificate_path` 或 `tls.peer_fingerprint` 必填其一。
与 `tls.client_certificate_path` 冲突。
@@ -199,7 +297,7 @@ TLS CA 证书内容，用于验证客户端证书。
TLS CA 证书路径，用于验证客户端证书。
`tls.client_certificate` 或 `tls.client_certificate_path` 必填其一。
当 `tls.verify_client_certificate` 为 `require` 或 `optional` 时，`tls.client_certificate`、`tls.client_certificate_path` 或 `tls.peer_fingerprint` 必填其一。
与 `tls.client_certificate` 冲突。
@@ -215,12 +313,68 @@ OpenVPN 客户端证书策略，`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 控制信道包装。
@@ -271,12 +425,24 @@ OpenVPN `tls-auth` 密钥方向，`server` 或 `client` 之一。
默认禁用。
### 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 数据信道加密方式。
@@ -285,12 +451,36 @@ OpenVPN `tls-auth` 密钥方向，`server` 或 `client` 之一。
默认禁用。
仅在 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
推送给客户端的选项。
@@ -305,6 +495,22 @@ IPv4 和 IPv6 前缀可以混用。
推送给客户端的 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 路由客户端流量。
@@ -371,12 +577,34 @@ 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 会话。