Skip to content

OpenVPN Client

Since sing-box 1.14.0

Build tags

OpenVPN endpoints require the with_openvpn build tag.

When system is disabled, the internal network stack also requires the with_gvisor build tag.

Structure

{
  "type": "openvpn-client",
  "tag": "ovpn-client",

  "server": "127.0.0.1",
  "server_port": 1194,
  "servers": [
    {
      "server": "127.0.0.1",
      "server_port": 1194,
      "network": "udp"
    }
  ],
  "remote_random": false,
  "network": "udp",
  "username": "",
  "password": "",
  "auth_retry": "none",
  "static_challenge": "",
  "static_challenge_echo": false,
  "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": "",
    "version_min": "1.2",
    "version_max": "",
    "cipher": "",
    "groups": "",
    "control_wrap": {
      "type": "",
      "key": [],
      "key_path": "",
      "direction": ""
    }
  },
  "data_ciphers": [],
  "data_ciphers_fallback": "",
  "auth": "",
  "mss_fix": 0,
  "fragment": 0,
  "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": [],
  "keepalive_interval": "",
  "keepalive_timeout": "",
  "renegotiate_interval": "",
  "explicit_exit_notify": 0,
  "system": false,
  "name": "",
  "mtu": 1500,
  "udp_timeout": "",

  ... // Dial Fields
}

You can ignore the JSON Array [] tag when the content is only one item.

Fields

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.

username

Username for OpenVPN username/password authentication.

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.

tls

Required

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.

Multiple values are combined, and all requested usages must be present.

Disabled by default.

tls.remote_certificate_eku

Required server certificate extended key usage, one of server or client.

Disabled by default. The standard OpenVPN server certificate usage check still applies.

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.

data_ciphers

Allowed OpenVPN data channel ciphers.

AES-256-GCM, AES-128-GCM, and CHACHA20-POLY1305 are used by default.

data_ciphers_fallback

Data channel cipher for peers that do not support cipher negotiation.

Disabled by default.

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.

This prevents TCP packets from exceeding the path MTU after OpenVPN encapsulation.

Disabled when 0.

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.

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. yes permits compression in both directions.

Conflict with non-stub compression enabled by compression or compression_lzo when set to no.

route_no_pull

Ignore routes, route gateways, and redirect-gateway options pushed by the server.

Other pushed options are still accepted, 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-insensitive 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-insensitive 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 route prefixes routed through the 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

Route all IPv4 traffic through the OpenVPN endpoint.

Disabled by default.

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.

Empty by default.

keepalive_interval

Interval for sending OpenVPN keepalive ping packets.

Locally configured values take precedence over server-pushed keepalive values.

Disabled by default.

keepalive_timeout

Time without receiving OpenVPN traffic before the connection is restarted.

Locally configured values take precedence over server-pushed keepalive values.

Disabled by default.

renegotiate_interval

OpenVPN TLS renegotiation interval.

If empty or set to 0s, the OpenVPN default 1h is used.

explicit_exit_notify

Number of OpenVPN exit notifications sent when closing a UDP connection.

Disabled when 0. At most 10 notifications are sent.

system

Use a system interface.

Requires privilege and cannot conflict with existing system interfaces.

If disabled, sing-box uses the internal network stack.

Requires the with_gvisor build tag when disabled.

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_timeout

UDP NAT expiration time.

5m is used by default.

Dial Fields

See Dial Fields for details.

Interactive authentication

Use Tools > Endpoints in the sing-box dashboard or any sing-box graphical client to authenticate and manage the endpoint.