# 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.