OpenVPN profile portability: portable keys vs platform options

The same .ovpn file opens a tunnel in one client and fails to start in another, and the certificate is usually the first suspect. More often the file contains a directive that only one engine implements. A profile is a contract with a specific client, not a portable script.

Separate what travels with the identity from what belongs to a platform. The failure then usually names itself.

One file, two contracts

A profile bundles three kinds of content: identity material such as CA and client certificates and the private key, transport facts such as the remote endpoint and protocol, and behaviour directives such as DNS handling or device options. The first two are broadly portable across engines that support the same protocol. The third is where implementations diverge. Treating the whole file as one portable unit is what produces the confusing failures.

A file that works in a GUI on one platform is not automatically valid for the command-line client on another. Even when both are OpenVPN, the parsers and the option sets differ. That is why a successful import is not evidence of a portable profile.

Portable material versus platform directives

Identity and transport sections are the part to preserve. ca, cert, key and remote describe who is connecting and where, and they mean the same thing to any conforming client.

Behaviour directives are the part to compare. block-outside-dns, for example, exists to change Windows DNS behaviour. A Unix client may not recognise it at all.

Read the option list of the receiving client rather than the sending one. The OpenVPN 2.6 reference manual documents the engine's options, and a GUI's import dialog is not that list.

Read the parser error before the certificate

An error that names an unrecognised option is a parser failure, not an authentication failure. The connection never reached TLS, so changing certificates cannot help. Read the first error from the actual client and version, then remove or replace only the directive that client cannot implement. Deleting certificate or route sections to make the file load is how a working profile becomes an insecure one.

If the error mentions the handshake, a certificate or a cipher, the profile parsed and the problem is elsewhere.

Keep the original file next to the adapted one. When the adapted file fails later, the original is the control that tells you whether the change or the environment moved.

Privilege is a second boundary

Privilege is the other boundary: creating a tunnel device, installing routes and reading a private key all depend on local permissions. A key file readable only by root is a normal deployment, not a profile defect. The fix belongs in ownership or capability, not in the file.

Running the client with sudo can resolve a local permission denial, and it cannot add a directive the binary does not implement. It also changes which user's keyring, configuration paths and network manager context apply, so the result is not the same test.

Adapt deliberately

When a provider publishes separate profiles, take the one intended for the receiving client. Adapting another platform's file is a last resort. It needs a record of each changed option and a copy of the original.

Test identity, routing and DNS as three separate outcomes. A profile that authenticates and routes but breaks name resolution is a partially adapted profile, not a working one.