Skip to content

OpenVPN Client Troubleshooting

A fault tree for an OpenVPN client that will not establish, where the client is a firewall or router rather than a workstation. For the appliance itself see Netgate 6100 MAX Administration, and for the capture technique referenced below see Packet Capture as a Decision Procedure.

Read the Client Log Before Changing Anything

The client's own log states the failure reason explicitly and is the only source that distinguishes the symptoms below from one another. On pfSense it is at Status → System Logs → OpenVPN, filtered per instance. Note which of these the log reaches before it stops or loops:

Log milestone What it proves
RESOLVE / Cannot resolve host address Never got as far as sending a packet
UDP link local/remote then repeated TLS Error: TLS key negotiation failed Packets are being sent; nothing usable is coming back
Connection reset, restarting immediately after a TCP connect Something answered on the port, but it is not this service
VERIFY OK → Control Channel: TLSv1.3 → SENT CONTROL [...]: 'PUSH_REQUEST' → AUTH_FAILED The entire cryptographic configuration is correct; only credentials failed

Changing cipher, certificate or TLS settings after the log has already shown VERIFY OK wastes time and usually breaks a working configuration.

Symptom: Cannot Resolve Host Address

The endpoint hostname is dead, or the address family being requested does not exist for it.

  • Provider endpoints are not stable. Hostnames are retired and renumbered routinely, so a configuration file that connected previously can fail on resolution alone, with nothing else changed at either end.
  • Address family mismatch. A remote line pinned to IPv6 (proto udp6 / tcp6), or a client whose Protocol is set to an IPv6-only variant, will fail to resolve a hostname that has only an A record. The Protocol dropdown offers IPv4-only, IPv6-only and dual-stack variants of both UDP and TCP; select the one matching the proto line in the file.
  • The firewall's own resolver may differ from a client's. Resolution succeeding on a workstation proves nothing about the firewall, particularly where the firewall forwards or intercepts DNS — see DNS Filtering & Forced Resolution.

Verify resolution from the firewall itself, not from a host behind it. From the pfSense shell (Diagnostics → Command Prompt, or over SSH where it has been enabled under System → Advanced → Admin Access):

host vpn-endpoint.example.com
drill vpn-endpoint.example.com A
drill vpn-endpoint.example.com AAAA

dig is not present on a stock pfSense install; host and drill are. The same lookup is available in the GUI at Diagnostics → DNS Lookup, which additionally shows which configured resolver answered.

If the name does not resolve anywhere, obtain a current configuration file from the provider rather than editing the old one — the certificate name check is usually tied to the hostname too.

Symptom: Silence — Packets Leave, Nothing Returns

The client sends, times out, retries, and loops. It looks identical to a blocked path, which is why it is the most commonly misdiagnosed OpenVPN failure.

First establish that it really is silence rather than a rejection. Capture on the WAN interface filtered to the endpoint address and port and confirm outbound packets with no inbound reply of any kind — method in Packet Capture as a Decision Procedure. That result narrows the fault to the path or the far end without distinguishing between them; the causes below are all silent discards at the far end.

tls-auth and tls-crypt are not interchangeable

A mismatch here produces exactly this silence, with no error at either end. Both mechanisms wrap the control channel with a shared static key, but they do it differently:

tls-auth tls-crypt
What it does to the control packet Adds an HMAC; the packet stays in cleartext Encrypts the packet as well as authenticating it
Key direction 0 at one end and 1 at the other (client side 1), or omitted at both Not used
Inline block in the file <tls-auth>…</tls-auth> <tls-crypt>…</tls-crypt>
pfSense TLS Key Usage Mode TLS Authentication TLS Encryption and Authentication

A server expecting one mode and receiving the other cannot validate the very first control packet, so it discards it silently. There is no reply, and the client logs only its own timeouts. The static key material can be byte-for-byte identical between the two cases — only the mode differs, which is why comparing key blocks proves nothing.

  • Check which tag the configuration file actually contains, then set TLS Key Usage Mode on the client to match.
  • pfSense exposes no key-direction field: it writes key-direction 1 for client instances itself when the mode is TLS Authentication, and writes none for tls-crypt. Adding a key-direction line to Custom options is unnecessary and can conflict.
  • Providers frequently run both generations on the same endpoint, on different ports. If one configuration file is silent, downloading the other generation's file for the same endpoint is a fast discriminator — its remote port and its TLS tag will both differ, and usually one of the two combinations handshakes.

Other causes of the same silence

  • Wrong port. Read it from the remote line rather than assuming 1194 or 443.
  • Wrong protocol. A UDP client aimed at a TCP-only listener gets no answer at all. The reverse fails visibly at connect time — a reset if the far end refuses, a timeout if the SYN is dropped.
  • Client bound to the wrong interface. The Interface field selects the source address. If it points at an interface with no route to the endpoint, packets leave the wrong way or not at all — confirm with the capture, which will show nothing on the expected WAN.
  • Upstream filtering. Some transit paths drop the port entirely; testing the provider's alternative port for the same endpoint separates this from a configuration fault.

Symptom: Connection Reset Immediately After the TCP Session Opens

The TCP handshake completes and the session is torn down at once. Something is listening on that port, but it is not the service expected — commonly a web server, a management interface, or the provider having moved the service.

  • Re-read the port from the configuration file rather than trusting a conventional number.
  • Confirm the protocol field matches the file: a TCP client will connect to almost anything, then reset.
  • This exact sequence — TCP session established, then immediate teardown — only occurs in TCP mode. A UDP client can log a similar Connection reset, restarting line when an ICMP port-unreachable returns, but with no preceding TCP connect in the log.

Symptom: AUTH_FAILED After a Successful Handshake

If the log shows the certificate chain verified, a TLS control channel established, and a push request sent, the cryptographic configuration is entirely correct. Only the credential exchange failed. Do not change certificates, ciphers or TLS settings at this point.

  • Service credentials are often not the account login. Many providers issue a dedicated username and password for manual and router configurations, generated separately in the account dashboard. Check which pair the configuration expects before assuming a typing error.
  • Concurrent-session limits can present as an authentication rejection rather than a distinct error, so a session already established elsewhere on the same credentials is worth ruling out.

The configuration-import duplication trap

Some import tools copy the body of the .ovpn file into the client's Custom options field. If an auth-user-pass directive ends up there, the generated configuration contains that directive twice, and the client honours the first occurrence. The username and password entered in the interface are then ignored entirely, and authentication fails no matter how many times they are re-entered.

  • Inspect the client's Custom options field for any directive that duplicates a field elsewhere on the page — auth-user-pass, remote, proto, ca, tls-auth and tls-crypt are the usual offenders.
  • Strip the field back to only the directives that genuinely belong there, then save and restart the instance.

Verify what was actually stored

Re-typing credentials proves nothing if the stored value is not what it appears to be. The credential file can be inspected without displaying its contents, by printing line lengths and a checksum. From the pfSense shell (FreeBSD):

ls -l /var/etc/openvpn/
awk '{ print NR, length($0) }' /var/etc/openvpn/client1/up
md5 /var/etc/openvpn/client1/up

The instance directory name and file layout under /var/etc/openvpn/ have changed between pfSense versions, so list the directory first and confirm the actual path on screen rather than assuming the one above. Line 1 is the username and line 2 the password; a length that does not match the expected credential reveals a trailing space, a truncated paste or an entirely wrong value, without ever printing the secret. The checksum is useful for confirming that a re-entry actually changed the file.

Reading a .ovpn File

Values must be read from the file, not assumed. This is the mapping from directives to client settings:

Directive Meaning / where it maps
client Confirms the file is a client configuration, not a server one
dev tun / dev tap Device mode — Layer 3 tunnel or Layer 2 tap
proto udp / proto tcp Protocol; udp4/udp6/tcp4/tcp6 variants pin the address family
remote <host> <port> Server host or address and Server port — read the port, do not assume 1194
verify-x509-name <name> [type] Constrains the subject name the server certificate may present. Type is subject (the full DN, and the default), name (a single RDN, usually the CN) or name-prefix. There is no dedicated field for it on the client page — set it in Custom options, confirming the page layout on screen
remote-cert-tls server Requires the peer certificate to carry server key usage and extended key usage. Corresponds to the Server Certificate Key Usage Validation option under Cryptographic Settings; confirm the label on screen
auth-user-pass Username/password authentication is required; Client Certificate is then set to the "none required" option
key-direction 1 Only meaningful with tls-auth; absent with tls-crypt. pfSense writes it for client instances itself
cipher / auth Legacy data-channel cipher and digest. cipher is deprecated from OpenVPN 2.5 onward in favour of data-ciphers
data-ciphers / data-ciphers-fallback The 2.5-onward replacement: a negotiable cipher list, plus a fallback for peers that cannot negotiate
<ca>…</ca> Certificate authority to import under System → Certificates, on the tab labelled Authorities on current builds (older versions label it CAs; confirm on screen)
<tls-auth>…</tls-auth> TLS key, mode TLS Authentication
<tls-crypt>…</tls-crypt> TLS key, mode TLS Encryption and Authentication
  • The presence of <tls-auth> versus <tls-crypt> is what determines TLS Key Usage Mode. Nothing else in the file signals it.
  • Files written for OpenVPN 2.5 and later frequently omit cipher and auth entirely, relying on data-channel negotiation through data-ciphers. Do not invent values that are not there. Some import tools reject such a file outright because they cannot populate a mandatory fallback-cipher field — in that case the client has to be built by hand from the table above.
  • A file that carries both an IP on the remote line and a verify-x509-name hostname should be configured with the hostname, so the certificate name check has something to match.