Configuration Reference

The server settings that change what the app's OpenVPN profiles do, what each field of a profile does on the wire, and the settings the app always uses. OpenVPN server builds the server this page refers to; Test results has the case behind each statement.

Where this page comes from

Every server setting below was tested on our OpenVPN 2.6.19 and stunnel 5.72 test server, in the configuration of OpenVPN server or in a second server instance that differed from it in the setting named, and both phones connected to it; the case names in the tables are the rows of Test results.

OpenVPN server settings

Each server configuration is one file in /etc/openvpn/server/, started as openvpn-server@NAME. After a change, systemctl restart openvpn-server@NAME applies it; the phones connected to it connect again by themselves when Auto Reconnect is on.

Transport and addresses

SettingWhat it does for the appCases
proto udp, proto tcp, portThe transport and port of the profile's remote line, which fill Server and Port. Both work; UDP is the usual one, TCP gets through networks that pass only TCP and is what stunnel carries.ovpn-udp-download, ovpn-tcp-download
topology subnetThe phone gets one address and the network's netmask.ovpn-udp-download
no topology line (net30, OpenVPN 2.6's default)The phone gets an address and a peer address instead of a netmask; the app sets it up that way, and the VPN works.ovpn-net30-topology
push "redirect-gateway def1 bypass-dhcp"All of the phone's IPv4 traffic goes through the VPN. Without it, only the networks the server pushes with route do; a route with the gateway net_gateway stays outside the VPN.ovpn-udp-download
push "dhcp-option DNS 1.1.1.1"The name servers the phone uses while connected. UDP, DNS included, goes through the VPN: a DNS question to OpenDNS for the asker's own address came back with the server's address.ovpn-udp-probe
tun-mtuThe tunnel's MTU on the phone (OpenVPN 2.6 pushes 1500).ovpn-udp-download

Keys, ciphers and certificates

SettingWhat it does for the appCases
tls-cryptThe profile's <tls-crypt> must be the server's key. With another key the server drops every packet: The server did not answer.ovpn-udp-download, ovpn-wrong-tls-crypt-key
tls-auth ta.key 0, auth SHA256The older way of signing the control channel works too; the profile needs <tls-auth>, key-direction 1 and the server's auth line.ovpn-cbc-tls-auth
data-ciphers AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305The phone and the server agree on AES-256-GCM (the server's log: Data Channel: cipher 'AES-256-GCM').ovpn-udp-download
data-ciphers AES-256-CBCAn older server with CBC only: the app connects with AES-256-CBC and the server's HMAC. BF-CBC, DES and other legacy ciphers the app does not have.ovpn-cbc-tls-auth
compress lz4-v2 pushed (allow-compression yes)The app refuses compression: The server pushes compression (lz4-v2), which this app does not take … OpenVPN 2.6 does not compress unless told to.ovpn-pushed-compression
remote-cert-tls client, crl-verifyEach phone needs a client certificate of the server's CA that is not revoked. A revoked certificate, or one from another CA, is refused by the server in the TLS handshake: The server stopped answering after the TLS handshake. …ovpn-revoked-certificate, ovpn-rogue-client-certificate
The server's certificateThe profile's <ca> must have signed it, and the profile's remote-cert-tls server asks for a server certificate. With another CA: The server's certificate could not be verified with the profile's CA (…).ovpn-wrong-server-ca
no duplicate-cnOne connection per certificate: when a second phone connects with the same certificate, the server drops the first one's session (its log: MULTI: new connection by client 'phone1' will cause previous active sessions by this client to be dropped), and the first phone's traffic stops. Give each phone its own.The guide's server, with the iPhone connected with phone1-udp.ovpn when Android connected with the same file

Username and password

SettingWhat it does for the appCases
verify-client-cert none, auth-user-pass-verify … via-file, username-as-common-nameLogin with the profile's Username and Password, over UDP, TCP or stunnel; a password may hold any character. A wrong one: The server refused the login. Check the username and password.ovpn-pass-udp-download, ovpn-pass-tcp-download, ovpn-pass-stunnel-download, ovpn-pass-special-characters, ovpn-pass-wrong

Keepalives and restarts

SettingWhat it does for the appCases
keepalive 10 60The server pushes ping 10 and ping-restart 60: the phone pings every 10 seconds and treats 60 seconds of silence as a dead path, then connects again with Auto Reconnect, or ends the VPN with The server stopped answering (keepalive timeout) (auto reconnect is off).ovpn-life-dead-path-reconnects, ovpn-life-dead-path-no-reconnect
explicit-exit-notify 1When the server stops or restarts, it tells the phones, which connect again at once. An administrator's client-kill does the same for one phone; client-kill … HALT tells it to stop: The server ended the session.ovpn-life-kick-udp, ovpn-life-kick-udp-no-reconnect, ovpn-life-halt, ovpn-life-retry-exhausted-udp

stunnel settings

SettingWhat it does for the appCases
accept = 443, connect = 127.0.0.1:1194The profile's stunnel Port (empty means 443) and the TCP server behind stunnel. The server sees the phone as 127.0.0.1. A port where nothing listens: The stunnel server … refused the connection: nothing listens on that port.ovpn-stunnel-download, ovpn-stunnel-closed-port
cert, key from Let's EncryptCA Certificate on System Trust: the app accepts it for the server's name.ovpn-stunnel-download
A certificate of your own CANeeds that CA in CA Certificate; on System Trust: The stunnel server's certificate is not trusted for …; with another CA imported: … not signed by the imported CA Certificate …ovpn-stunnel-private-ca, ovpn-stunnel-private-no-ca, ovpn-stunnel-private-wrong-ca
Names in the certificatestunnel SNI must be one of them: another name of the certificate works, a name it does not have is refused.ovpn-stunnel-custom-sni, ovpn-stunnel-sni-mismatch
sslVersionMax = TLSv1.2The app takes TLS 1.2 as well as 1.3.ovpn-stunnel-tls12-only
stunnel restarting (certbot's deploy hook)Ends the phones' connections; with Auto Reconnect they connect again.ovpn-life-stunnel-restart, ovpn-life-stunnel-restart-no-reconnect

What each profile field does

FieldOn the wireCases
Profile (.ovpn)OpenVPN's settings, certificates and keys. The app runs it with OpenVPN 3 Core 3.11.7, which tells the server IV_VER=3.11.7 and IV_PLAT=ios or android.every case
Server, PortLeft as the import filled them: the profile's remote lines, in order. Changed: the app connects there instead.ovpn-port-field-overrides-profile, ovpn-server-field-overrides-profile, ovpn-two-remotes-failover
Enable stunnel (TLS)OpenVPN over TCP inside TLS to stunnel; a UDP profile is turned to TCP.ovpn-stunnel-download, ovpn-stunnel-udp-profile
stunnel Host, Port, SNI, CA CertificateWhere the TLS connection goes, the name it sends and checks, and which CA it trusts.ovpn-stunnel-host-field, ovpn-stunnel-private-ca, ovpn-stunnel-custom-sni
TLS FragmentationThe TLS handshake to stunnel in pieces. Off: the ClientHello in one TCP segment. Auto: 43 bytes, then 256-byte pieces. Manual 10/40: 10, then 40-byte pieces (stunnel's side of the capture).ovpn-frag-off, ovpn-frag-auto, ovpn-frag-manual, ovpn-frag-auto-private-ca-sni, ovpn-frag-manual-download
Username, PasswordOpenVPN's auth-user-pass login, inside the TLS control channel.ovpn-pass-udp-download

What the app always does