Learn OpenVPN - Logging, Monitoring & Troubleshooting

#Introduction

Your VPN is running with routing from episode 6 and cryptography from episode 7. The practical question now: how do you monitor that everything stays healthy, and what should you do when something goes wrong?

Episode 8 answers both. The first part covers logging: what OpenVPN records and how to control log volume with verb and mute. The second part covers monitoring: the management interface for realtime inspection and the openvpn-status.log file. The third part covers troubleshooting: the most frequent errors and how to dissect them with tcpdump and verb 6.

The ability to read logs is the difference between a panicked admin and a calm one. When a client reports it can't connect, you don't need to guess — logs and packets will show exactly where the flow stops.

#Logging in OpenVPN

#The status and log Directives

OpenVPN can write connection status to a separate file periodically, while also writing logs to a file:

status /var/log/openvpn-status.log
status-version 3
log /var/log/openvpn.log
verb 3
mute 20

status /var/log/openvpn-status.log writes the list of connected clients along with their addresses, connection times, and traffic. status-version 3 uses the newest format that's easier to parse. verb 3 sets the detail level, and mute 20 suppresses the same repeated message after 20 occurrences.

#Verbosity Levels

The verb level determines how much detail gets recorded:

• verb 0 to 3: only fatal errors, warnings, and connection summaries.
• verb 4: adds TLS handshake and initialization details.
• verb 5 and above: shows cipher negotiation and details of each phase.
• verb 6 to 9: extremely verbose with packet dumps for debugging.

For normal operation, verb 3 is ideal. Increase it only while debugging, because high verbosity produces large logs and burdens the CPU.

#System-Level Logging

When OpenVPN runs as a systemd service, make sure logs flow into journald:

systemctl status openvpn-server@server
journalctl -u openvpn-server@server -f

journalctl -u openvpn-server@server -f shows the service logs in realtime. To rewind from boot, add the -b flag. The log directive in the configuration can be omitted when relying on journald, to avoid duplication.

#Monitoring with the Management Interface

#Enabling the Management Interface

The management interface opens the door to runtime inspection and control without stopping the daemon. Enable it with the management directive:

management 127.0.0.1 7505
management-client-auth
management-log-cache 100

management 127.0.0.1 7505 binds the interface to loopback so it can't be reached from the external network. management-client-auth permits manual client authorization, and management-log-cache 100 stores the last 100 log lines for reading through the interface.

#Useful Commands in the Management Console

Connect with telnet or nc then type commands:

telnet 127.0.0.1 7505
status
log 50
version

The status command lists connected clients, log 50 shows the last 50 log lines, and version shows the OpenVPN version and library info. This management interface is the basis of the various monitoring exporters to be discussed in episode 19.

#Reading openvpn-status.log

The version 3 status file has two main blocks: OpenVPN CLIENT LIST, which contains connected clients, and ROUTING TABLE, which contains the subnets routed per client. The second block is important for verifying that the iroute from episode 6 is actually registered.

#Common Troubleshooting

#TLS Handshake Failure

The most classic error is a handshake failure due to mismatched certificates. Signs in the log:

TLS Error: TLS key negotiation failed
TLS Error: cannot locate HMAC in incoming packet
TLS Error: local/remote TLS keys are out of sync

There are three main causes: the client certificate isn't signed by the same CA, the system clocks of server and client are out of sync, or the tls-auth/tls-crypt keys don't match. Always check these three things in order.

#Route Issues and Firewall Blocking

If the handshake succeeds but traffic doesn't flow, direct your attention to routing and firewall. On the server, make sure IP forwarding is active and the masquerade rules from episode 6 are present. On the client, inspect the routing table:

ip route show
ping -c 3 10.8.0.1

ip route show verifies that the route to the VPN subnet was added by push "route ...". If the route exists but ping fails, the problem is usually the firewall: check iptables -L FORWARD on the server.

#Dissecting with tcpdump

When everything looks right but still fails, go down to the packet level. tcpdump is the most honest tool — it shows what actually happens on the wire:

tcpdump -i eth0 -n -vv port 1194

tcpdump -i eth0 -n -vv port 1194 displays every UDP packet arriving on the OpenVPN port. If there are no packets at all, the network firewall is blocking the port — a problem outside OpenVPN. If packets arrive but there's no handshake response, the problem is inside the daemon.

#Using verb 6 for Deep Debugging

verb 6 shows the TLS packet dump in the log, revealing at which point the handshake phase stops. Run the client in the foreground with this flag:

openvpn --config client.ovpn --verb 6

Watch at which phase the flow stops: SENT CONTROL [server]: 'P_CONTROL_V1' means a message was sent, TLS handshake failed indicates a cryptography problem, and AUTH_FAILED means the credentials or certificate were rejected by the server.

#Conclusion

Key takeaways:

• status, log, verb, and mute control OpenVPN's logging.
• The management interface allows runtime inspection and control without restart.
• openvpn-status.log shows the client list and active routing table.
• TLS handshake failures usually stem from mismatched CA, time, or keys.
• tcpdump and verb 6 dissect problems down to the packet level.
• Always check routing and firewall before suspecting the OpenVPN daemon.

In the next episode, episode 9, we will discuss client config distribution and per-client policy — using client-config-dir to give each client different configuration, the client-connect and client-disconnect scripts as lifecycle hooks, and static IP allocation with ifconfig-push and iroute. After this episode, you can create different network policies for each user.