hesoyam/sing-box-extended-mirror
1
0
Fork 0
mirror of https://github.com/shtorm-7/sing-box-extended.git synced 2026-10-20 16:24:25 +00:00
Code Issues Packages Projects Releases 2 Wiki Activity
Files
fd9a076d252b6e868383bc23bc1a4fe44ce981f3
sing-box-extended-mirror/docs/configuration/endpoint/openvpn-client.md
T
世界 021e0877a3 Cleanup documentations
2026-10-02 18:00:09 +08:00

698 lines
16 KiB
Markdown
Raw Blame History

# 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.
### 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.
### 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.
### tls.crl_path
Path to a PEM or DER certificate revocation list used to reject revoked server certificates.
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.
### 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.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. 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.
### 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.
### 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`.
### mss_fix
Maximum OpenVPN UDP packet size used to clamp the MSS of TCP connections sent through the tunnel.
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`.
### 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_lzo
OpenVPN `comp-lzo` mode, one of `none`, `no`, `yes`, `adaptive`, `asym`, `disabled`, or `off`.
Disabled by default.
### 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. `yes` is a legacy alias for `asym`.
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.
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.
### route_gateway
IPv4 gateway for routes through the OpenVPN endpoint.
When empty, the VPN gateway received from the server is used.
### route_metric
Default metric for routes through the OpenVPN endpoint.
The platform default is used when `0`.
### redirect_gateway
Prefer the OpenVPN endpoint for all IPv4 destinations in sing-box routing.
Disabled by default.
### 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.
`local`, `autolocal`, `bypass-dhcp` and `bypass-dns` have no effect.
`block-local` is not supported.
Empty by default.
### redirect_private
Accept `redirect_gateway_flags` without adding a default-route preference.
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.
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.
Reference in New Issue View Git Blame Copy Permalink