# OpenVPN Server !!! question "Since sing-box 1.14.0" ## Structure ```json { "type": "openvpn-server", "tag": "ovpn-server", ... // Listen Fields "system": false, "name": "", "mtu": 1500, "mode": "tls", "network": "udp", "remote": "", "remote_port": 0, "max_clients": 1024, "address": [], "peer_address": "", "peer_address_ipv6": "", "topology": "subnet", "duplicate_cn": false, "users": [ { "username": "", "password": "" } ], "static_key": [], "static_key_path": "", "key_direction": "", "tls": { "certificate": [], "certificate_path": "", "key": [], "key_path": "", "client_certificate": [], "client_certificate_path": "", "verify_client_certificate": "require", "client_name": "", "client_name_type": "name", "peer_fingerprint": [], "crl_path": "", "remote_certificate_ku": [], "remote_certificate_eku": "", "remote_certificate_tls": "", "certificate_profile": "", "ns_certificate_type": "", "version_min": "1.2", "version_max": "", "cipher": "", "groups": "", "control_wrap": { "type": "tls_crypt", "key": [], "key_path": "", "direction": "", "force_cookie": false } }, "cipher": "", "data_ciphers": [], "data_ciphers_fallback": "", "auth": "", "mss_fix": 0, "mss_fix_disabled": false, "mss_fix_mode": "", "replay_window": 0, "replay_window_time": "", "push": { "routes": [], "dns": [], "dns_servers": [], "search_domains": [], "dhcp_options": [], "redirect_gateway": false, "redirect_gateway_flags": [], "block_outside_dns": false, "ping_interval": "", "ping_restart": "" }, "ping_interval": "", "ping_restart": "", "renegotiate_interval": "", "renegotiate_disabled": false, "renegotiate_bytes": 0, "renegotiate_packets": 0, "handshake_window": "1m", ... // UDP NAT Fields } ``` !!! note "" You can ignore the JSON Array [] tag when the content is only one item ## Listen Fields See [Listen Fields](/configuration/shared/listen/) for details. `udp_timeout` is part of the [UDP NAT Fields](#udp-nat-fields) below. ## Fields ### system Use system interface. Requires privilege and cannot conflict with existing system interfaces. The endpoint configures interface addresses and MTU but does not install operating-system routes or DNS settings. If disabled, sing-box uses the internal network stack. ### name Custom interface name for system interface. An automatically generated `ovpn` interface name is used by default. ### mtu OpenVPN interface MTU. `1500` will be used by default. ### mode OpenVPN session mode, one of `tls` or `static_key`. `tls` is used by default. `static_key` serves one peer without a TLS control channel or forward secrecy. It is retained as an explicit compatibility option for immutable deployments. It does not use `tls`, `users`, push options, or TLS renegotiation options. ### network OpenVPN transport network, one of `udp` or `tcp`. `udp` will be used by default. Only one transport network is served per endpoint; to serve both TCP and UDP, configure two endpoints with separate `address` subnets, matching upstream OpenVPN which requires two server processes. ### remote Fixed remote peer address for a UDP `static_key` server. Required with `remote_port` in UDP `static_key` mode. TCP servers accept the single peer from the listening socket and do not use this field. ### remote_port Fixed remote peer port for a UDP `static_key` server. Required with `remote` in UDP `static_key` mode. ### max_clients Maximum number of established and pending TLS client sessions. `1024` is used by default. The value must be smaller than `16777216`, the size of the OpenVPN peer-id space. `static_key` mode supports one peer, so this value must be `0` or `1`. ### address ==Required== List of OpenVPN server address prefixes. At most one IPv4 prefix and one IPv6 prefix are supported. The prefix address is assigned to the server interface. The masked prefix is used as the client address pool and route. The first IPv4 and IPv6 prefix addresses are used as the endpoint's local addresses. In `static_key` mode these are the local tunnel prefixes rather than address pools. ### peer_address IPv4 tunnel peer address. Required when an IPv4 `address` is configured in `static_key` mode. ### peer_address_ipv6 IPv6 tunnel peer address. Required when an IPv6 `address` is configured in `static_key` mode. ### topology OpenVPN topology pushed to clients, one of `subnet`, `p2p` or `net30`. `subnet` is used by default in TLS mode. `p2p` is used by default in `static_key` mode. ### duplicate_cn Allow multiple active clients with the same authenticated certificate common name or username. When disabled, a newly authenticated session replaces the existing session with the same identity and reuses its tunnel address when available. Disabled by default. Only available in TLS mode. ### users List of OpenVPN username/password users. If set, clients must pass username/password authentication in addition to any certificate policy configured by `tls.verify_client_certificate`. Only available in TLS mode. ### users.username Username. ### users.password Password. ### static_key OpenVPN static key content. Required in `static_key` mode. Conflict with `static_key_path`. ### static_key_path OpenVPN static key path. Required in `static_key` mode when `static_key` is not set. Conflict with `static_key`. ### key_direction Static key direction, one of `server` or `client`. The key is used bidirectionally if empty. Conventionally the server uses `server` and the peer uses `client`. Only available in `static_key` mode. ### tls Required in TLS mode. OpenVPN control channel TLS configuration. ### tls.certificate TLS server certificate content. Either `tls.certificate` or `tls.certificate_path` is required. Conflict with `tls.certificate_path`. ### tls.certificate_path TLS server certificate path. Either `tls.certificate` or `tls.certificate_path` is required. Conflict with `tls.certificate`. ### tls.key TLS server private key content. Either `tls.key` or `tls.key_path` is required. Conflict with `tls.key_path`. ### tls.key_path TLS server private key path. Either `tls.key` or `tls.key_path` is required. Conflict with `tls.key`. ### tls.client_certificate TLS CA certificate content, used to verify client certificates. One of `tls.client_certificate`, `tls.client_certificate_path`, or `tls.peer_fingerprint` is required when `tls.verify_client_certificate` is `require` or `optional`. Conflict with `tls.client_certificate_path`. ### tls.client_certificate_path TLS CA certificate path, used to verify client certificates. One of `tls.client_certificate`, `tls.client_certificate_path`, or `tls.peer_fingerprint` is required when `tls.verify_client_certificate` is `require` or `optional`. Conflict with `tls.client_certificate`. ### tls.verify_client_certificate OpenVPN client certificate policy, one of `require`, `optional` or `none`. `require` will be used by default. If set to `optional`, a client certificate is verified when provided, but clients without a certificate are allowed. If set to `none`, client certificates are not requested. This field does not replace `users`; when `users` is set, username/password authentication is still required. ### tls.client_name Expected client certificate name. Disabled when empty. ### tls.client_name_type Certificate field matched by `tls.client_name`, one of `subject`, `name`, or `name-prefix`. `name` is used by default when `tls.client_name` is configured. ### tls.peer_fingerprint Allowed SHA-256 fingerprints of client leaf certificates. Fingerprint-only verification can be used without a client CA. ### tls.crl_path Path to a certificate revocation list used to reject revoked client certificates. ### tls.remote_certificate_ku Required client certificate key usage masks in OpenVPN `remote-cert-ku` format. ### tls.remote_certificate_eku Required client certificate extended key usage. Conflict with an explicitly configured `tls.remote_certificate_tls`. ### tls.remote_certificate_tls Client certificate purpose check, one of `server`, `client`, or `none`. `client` is used by default. ### tls.certificate_profile Certificate profile, one of `insecure`, `legacy`, `preferred`, or `suiteb`. `legacy` is used by default. `insecure` accepts MD5- and SHA-1-signed certificate chains and smaller legacy keys for compatibility with immutable peers. Use it only when the peer cannot be upgraded. `legacy` accepts SHA-1 but rejects MD5 signatures; `preferred` requires stronger signatures and keys. When `suiteb` is selected and `tls.cipher` is empty, the TLS 1.2 cipher list defaults to the Suite B ECDHE-ECDSA AES-GCM suites. Explicit `tls.cipher` and `tls.groups` values are not restricted by the profile. ### tls.ns_certificate_type Deprecated Netscape certificate type check, one of `server` or `client`. ### tls.version_min Minimum TLS version. `1.2` is used by default. ### tls.version_max Maximum TLS version. The maximum supported version is used by default. ### tls.cipher Colon-separated OpenSSL cipher suite names allowed for TLS 1.2 and earlier. The default TLS cipher suites are used when empty. TLS 1.3 cipher suites are not controlled by this field. ### tls.groups Colon-separated TLS key exchange groups in preference order. ### tls.control_wrap OpenVPN control channel wrapping. Equivalent to OpenVPN `tls-auth`, `tls-crypt` and `tls-crypt-v2`. Disabled by default. ### tls.control_wrap.type ==Required== Control channel wrapping type, one of `tls_auth`, `tls_crypt` or `tls_crypt_v2`. For `tls_crypt_v2`, the key is the server key. ### tls.control_wrap.key Control channel wrapping key content. Either `tls.control_wrap.key` or `tls.control_wrap.key_path` is required. Conflict with `tls.control_wrap.key_path`. ### tls.control_wrap.key_path Control channel wrapping key path. Either `tls.control_wrap.key` or `tls.control_wrap.key_path` is required. Conflict with `tls.control_wrap.key`. ### tls.control_wrap.direction OpenVPN `tls-auth` key direction, one of `server` or `client`. Only available when `tls.control_wrap.type` is `tls_auth`. `server` maps to OpenVPN key direction `0`, and `client` maps to `1`; by convention servers use `0` and clients use `1`. If empty, the key is used bidirectionally, matching an omitted `key-direction` on both peers. ### tls.control_wrap.force_cookie Require `tls-crypt-v2` clients over UDP to support stateless session cookies. Only available when `tls.control_wrap.type` is `tls_crypt_v2`. When disabled, clients without cookie support are accepted using the upstream `allow-noncookie` behavior. Disabled by default. ### cipher Data-channel cipher used in `static_key` mode. The upstream static-key default `BF-CBC` is used when empty. Supported static-key ciphers are the AES-CBC, ARIA-CBC, Camellia-CBC, DES-CBC, Blowfish-CBC, CAST5-CBC families, `SEED-CBC`, `SM4-CBC`, and `NONE`. Only available in `static_key` mode. `NONE` provides no confidentiality. ### data_ciphers Allowed OpenVPN data channel ciphers. `AES-256-GCM`, `AES-128-GCM` and `CHACHA20-POLY1305` are used by default. The AES-GCM family includes `AES-192-GCM`. Retained ciphers include the CBC, CFB, and OFB forms of AES, ARIA, Camellia, DES, Blowfish, and CAST5, the CBC, CFB, and OFB forms of SEED and SM4, and `NONE`. CFB and OFB are available only in TLS mode. Legacy ciphers provide weaker or no confidentiality and are not enabled by default. Only available in TLS mode. ### data_ciphers_fallback OpenVPN data channel cipher for legacy clients that do not support cipher negotiation. Equivalent to OpenVPN `data-ciphers-fallback`. Disabled by default. Only available in TLS mode. ### auth OpenVPN data channel authentication digest. `SHA1` will be used by default, matching the upstream default; it only applies to non-AEAD data ciphers and `tls_auth`. Legacy digests including `MD5` and `RIPEMD160` remain available when explicitly configured for compatibility. ### mss_fix Maximum encapsulated packet size used to clamp TCP MSS. The upstream default calculation uses `1492` with the default MTU. ### mss_fix_disabled Disable MSS clamping, including the default clamp. ### mss_fix_mode Calculation mode for an explicit `mss_fix`, one of `mtu` or `fixed`. Requires `mss_fix`. ### replay_window UDP data-channel replay window size. `64` is used by default; TCP packet IDs remain strictly consecutive. ### replay_window_time UDP replay window duration. `15s` is used by default. The value must use whole seconds. ### push Options pushed to clients. ### push.routes Routes to push to clients. IPv4 and IPv6 prefixes can be mixed. ### push.dns DNS server addresses to push to clients. Uses legacy `dhcp-option DNS`/`DNS6`. A pushed modern DNS server group overrides these addresses on compatible clients. ### push.dns_servers Modern OpenVPN DNS server groups to push. Each entry contains `priority`, `addresses`, optional `resolve_domains`, `dnssec`, `transport`, and `sni`. Addresses accept an IP address or `IP:port` (IPv6 ports use `[IPv6]:port`). `transport` is one of `plain`, `dot`, or `doh`; `dnssec` is one of `yes`, `optional`, or `no`. OpenVPN clients apply only the group with the lowest priority number. ### push.search_domains Modern OpenVPN search domains to push. ### push.dhcp_options Additional legacy `dhcp-option` values to push, without the `dhcp-option` prefix. ### push.redirect_gateway Push `redirect-gateway` to clients, which routes client traffic through the VPN according to `push.redirect_gateway_flags`. When `push.redirect_gateway_flags` is empty, `def1` is used by default. ### push.redirect_gateway_flags OpenVPN `redirect-gateway` flags to push to clients. Only available when `push.redirect_gateway` is enabled. `def1` is used by default. ### push.block_outside_dns Push `block-outside-dns` to clients, which blocks DNS queries outside the VPN on Windows clients. ### push.ping_interval OpenVPN `ping` interval pushed to clients. After the interval passes without sending a packet, the client sends a data-channel ping to the server. The value must use whole seconds. Disabled by default. ### push.ping_restart OpenVPN `ping-restart` timeout pushed to clients. After the timeout passes without receiving a packet, the client reconnects to the server. The value must use whole seconds. Disabled by default. ### ping_interval Interval after which the server sends a data-channel ping when no packet has been sent to a client. This value applies to the server. Use `push.ping_interval` to configure clients. The value must use whole seconds. Disabled by default. ### ping_restart Time without receiving a packet after which the server closes the client session. This value applies to the server. Use `push.ping_restart` to configure clients. The server timeout should be longer than the client timeout so the client can reconnect before the server discards its session. The value must use whole seconds. Disabled by default. ### renegotiate_interval OpenVPN TLS renegotiation interval. When empty, the OpenVPN default `1h` is used. Only available in TLS mode. ### renegotiate_disabled Disable time-based TLS renegotiation, including the default interval. Only available in TLS mode. ### renegotiate_bytes Renegotiate data-channel keys after this many bytes. `0` uses the cipher-dependent OpenVPN default. Only available in TLS mode. ### renegotiate_packets Renegotiate data-channel keys after this many packets. `0` uses the cipher-dependent OpenVPN default. Only available in TLS mode. ### handshake_window Maximum time allowed for the initial TLS handshake and each TLS renegotiation. `1m` is used by default. Only available in TLS mode. ## UDP NAT Fields These fields configure UDP sessions for traffic through the OpenVPN interface. See [UDP NAT Fields](/configuration/shared/udp-nat/) for details.