Configuration Reference

The server settings that change what the app's SSL VPN profiles do, what each field of a profile does on the wire, and the settings the app always uses. ocserv 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 by changing it on our ocserv 1.2.4 test server, connecting both phones, and reading the session back with occtl; the case names in the tables are the rows of Test results. Settings this page describes without a case were left as the package sets them.

Server settings (ocserv.conf)

ocserv reads /etc/ocserv/ocserv.conf when it starts; after a change, systemctl restart ocserv, which ends the sessions that are open. A user's group file in config-per-group replaces the routes for the users of that group.

Logins

SettingWhat it does for the appCases
auth = "plain[passwd=/etc/ocserv/ocpasswd]"Users and hashed passwords from the file ocpasswd writes. The app answers the server's login form with the profile's Username and Password. A wrong password or an unknown user ends with Authentication failed. Check the username and password.ocv-pass-download, ocv-wrong-password, ocv-wrong-user
enable-auth = "certificate"
ca-cert = /etc/ocserv/client-ca.pem
cert-user-oid = 2.5.4.3
A client certificate signed by the authority in ca-cert is enough on its own; the user is the certificate's common name, whatever the profile's Username says. A certificate from another authority fails the TLS handshake. With Method Certificate and no certificate imported the server asks for a password, and the login fails.ocv-cert-download, ocv-cert-other-username, ocv-cert-rogue-ca, ocv-cert-missing
max-ban-score = 80
ban-reset-time = 1200
Points for every connection and more for every wrong password; an address above the limit is refused until the points reset. The app sees the TLS handshake end and says so. For our other cases we set max-ban-score = 0, so that the cases with wrong passwords would not block our address.ocv-server-ban
camouflage = true
camouflage_secret = …
ocserv answers only requests that carry the secret in the URL, as https://vpn.example.com/?secret. Enter ? and the secret in the profile's Path. Without the secret, or with a wrong one, the app says The server did not answer as an AnyConnect server. The connection log shows only the secret's length.ocv-path-camouflage, ocv-path-camouflage-log, ocv-path-camouflage-reset-resume, ocv-path-camouflage-wrong-secret, ocv-server-camouflage

TLS and DTLS

SettingWhat it does for the appCases
tcp-port = 443The TLS connection: the login and, when there is no DTLS, the VPN's packets. The profile's Port is this port, or one the server forwards to it.ocv-port-8443
udp-port = 443DTLS over UDP. When it is reachable the VPN's packets go over DTLS; when UDP is blocked on the way, everything goes over the TLS connection and the app connects all the same.ocv-pass-download, ocv-tls-only-download, ocv-tls-only-full-duplex
tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1:-VERS-TLS1.3"The package's default allows only TLS 1.2. Without -VERS-TLS1.3 the app and the server use TLS 1.3. A server that offers only TLS 1.1 or older is refused: The server offers only TLS 1.1 or older; the app needs TLS 1.2 or later. On Ubuntu 24.04 ocserv cannot offer TLS 1.0 or 1.1 at all, because the system's GnuTLS turns them off; that case used another TLS server.ocv-server-tls13, ocv-server-tls11-only
dtls-psk = true (the default)DTLS 1.2 keyed from the TLS session (PSK); occtl show user shows (DTLS1.2)-(PSK)-(AES-256-GCM). With dtls-psk = false it showed (DTLS1.2)-(ECDHE-RSA)-(AES-256-GCM), and the app's traffic went over DTLS just as well.ocv-pass-download, ocv-server-dtls-no-psk
compression = trueThe server compresses the VPN's packets with LZS, which the app accepts (selected DTLS compression method lzs in the server's log).ocv-server-compression

Addresses, DNS and routes

SettingWhat it does for the appCases
ipv4-network = 10.83.0.0/24The phone's tunnel address; with predictable-ips = true a user gets the same address again.every connect case
dns = 1.1.1.1The phone's DNS servers while the VPN is on.every connect case
route = defaultAll the phone's IPv4 traffic goes through the tunnel.every connect case
route = 203.0.113.0/24 in a group fileOnly these ranges go through the tunnel (split tunnel). The app shows them in its log at Expert and Debug: routes through the tunnel: ….ocv-split-group
no-route = …Ranges that stay outside the tunnel. iOS applies them; Android does from version 13. Not part of our tests.

Sessions

SettingWhat it does for the appCases
cookie-timeout = 300How long the server keeps a session whose connection broke. Within it the app resumes the same session (same address, no new login) when the connection breaks or the phone moves to another network; the server's log shows temporarily closing session and then the same session again. Our resumes happened within seconds.ocv-life-reset-resume, ocv-life-path-switch
occtl disconnect user …Ends the session on the server. With Auto Reconnect on, the app logs in again; with it off, the VPN ends with The server ended the session (auto reconnect is off).ocv-life-server-ends-reconnect, ocv-life-server-ends-no-reconnect
max-same-clients = 2How many sessions one user may have at once. Left as the package sets it.
dpd = 90How often each side checks that the other is still there. The server suggested 90 seconds to the app (suggesting DPD of 90 secs in its log). Left as the package sets it.every connect case

What each profile field does

FieldOn the wire
Server TypeThe protocol: AnyConnect, F5 BIG-IP or Palo Alto GlobalProtect, all spoken by the same OpenConnect core (9.21). A type the server does not speak ends with The server did not answer as … server. Only AnyConnect was tested against a real server.
Server, Port, PathThe app connects to https://Server:Port and Path, with a / between them when Path does not start with one, for example https://vpn.example.com:443/?secret. An empty Port is 443; an empty Path is /. The log shows the part of Path after ? only as its length.
TLS Server VerificationOn: the server's certificate must chain to a root the phone trusts and be issued for the Server name. Before connecting, the app checks the certificate itself and shows a warning that can be accepted once. Off: any certificate is accepted.
Method, Username, Password / CertificatePassword: the app fills the server's login form; it answers a form at most three times and does not send a refused password again. Certificate: the app presents the imported client certificate during the TLS handshake.
Auto Reconnect, Retry TimesWhen the connection breaks, the app resumes the same session with its cookie: at once, then after waits of 2, 4, 6 … seconds. With Auto Reconnect on and Retry Times empty it keeps trying as long as the server keeps the session, and then logs in again. With Retry Times n it tries n times and then ends the VPN with Could not reconnect after n attempts. Before the first connection, Retry Times also repeats a failed login (Could not connect after n attempts.). With Auto Reconnect off a broken connection ends the VPN with Connection lost (auto reconnect is off).
Switch to Wi-Fi When AvailableWhen Wi-Fi appears, the app moves the running session to it: the connections close and the session resumes over Wi-Fi, without a new login.
On SleepStay keeps the connection while the phone sleeps. Pause closes it and connects again on wake. Off closes it; on wake the app connects again only with Auto Reconnect on, otherwise the VPN ends with The connection was closed while the device slept.
Log LevelNormal: the app's own milestones and OpenConnect's errors. Expert adds OpenConnect's progress lines and the routes. Debug adds the server's headers; the values of the server's cookies are written as <elided> at every level.
TLS FragmentationSplits the TLS ClientHello into several TCP writes; the TLS stream itself is unchanged. Auto: 43 bytes, then 256 bytes 3 ms apart (128 bytes, 10 ms apart, on cellular). Manual: First Chunk, then Following Chunks (32 and 256 when empty).

Settings the app always uses