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.
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
| Setting | What it does for the app | Cases |
|---|---|---|
proto udp, proto tcp, port | The 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 subnet | The 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-mtu | The tunnel's MTU on the phone (OpenVPN 2.6 pushes 1500). | ovpn-udp-download |
Keys, ciphers and certificates
| Setting | What it does for the app | Cases |
|---|---|---|
tls-crypt | The 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 SHA256 | The 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-POLY1305 | The 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-CBC | An 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-verify | Each 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 certificate | The 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-cn | One 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
| Setting | What it does for the app | Cases |
|---|---|---|
verify-client-cert none, auth-user-pass-verify … via-file, username-as-common-name | Login 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
| Setting | What it does for the app | Cases |
|---|---|---|
keepalive 10 60 | The 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 1 | When 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
| Setting | What it does for the app | Cases |
|---|---|---|
accept = 443, connect = 127.0.0.1:1194 | The 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 Encrypt | CA Certificate on System Trust: the app accepts it for the server's name. | ovpn-stunnel-download |
| A certificate of your own CA | Needs 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 certificate | stunnel 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.2 | The 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
| Field | On the wire | Cases |
|---|---|---|
| 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, Port | Left 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 Certificate | Where 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 Fragmentation | The 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, Password | OpenVPN's auth-user-pass login, inside the TLS control channel. | ovpn-pass-udp-download |
What the app always does
- Data-channel ciphers offered: AES-128-GCM, AES-192-GCM, AES-256-GCM, ChaCha20-Poly1305, and the AES-CBC ciphers for servers that have nothing else.
- No compression, whatever the profile or the server says.
- The control channel's TLS as the profile says (OpenVPN 2.6 negotiates TLS 1.3); stunnel's outer TLS 1.2 or 1.3.
- The server's address stays outside the tunnel; IPv4 goes through it as the server pushes.
- A profile with several remote lines: the app tries them in order when the first does not answer, before it gives up on a first connection.