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.
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
| Setting | What it does for the app | Cases |
|---|---|---|
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.pemcert-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 = 80ban-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 = truecamouflage_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
| Setting | What it does for the app | Cases |
|---|---|---|
tcp-port = 443 | The 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 = 443 | DTLS 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 = true | The 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
| Setting | What it does for the app | Cases |
|---|---|---|
ipv4-network = 10.83.0.0/24 | The phone's tunnel address; with predictable-ips = true a user gets the same address again. | every connect case |
dns = 1.1.1.1 | The phone's DNS servers while the VPN is on. | every connect case |
route = default | All the phone's IPv4 traffic goes through the tunnel. | every connect case |
route = 203.0.113.0/24 in a group file | Only 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
| Setting | What it does for the app | Cases |
|---|---|---|
cookie-timeout = 300 | How 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 = 2 | How many sessions one user may have at once. Left as the package sets it. | |
dpd = 90 | How 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
| Field | On the wire |
|---|---|
| Server Type | The 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, Path | The 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 Verification | On: 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 / Certificate | Password: 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 Times | When 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 Available | When 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 Sleep | Stay 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 Level | Normal: 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 Fragmentation | Splits 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
- The app's user agent is
SRP VPN Connect v9.21(occtl show usershows it), and it names its platformapple-ioson iPhone andandroidon Android. - It gives DTLS 60 seconds to start; until then, and whenever DTLS is not up, the packets go over TLS.
- For GlobalProtect it does not use ESP (UDP); the tunnel runs over TLS.
- The Android app routes IPv4 only: when the server also gives an IPv6 address, the log says so and the address is not used.