Monitoring OpenVPN connections

Monitor OpenVPN server status, client connections, and bandwidth usage through logs, status files, and the management interface

This guide covers monitoring techniques for OpenVPN including logging, status reporting, and the management interface.

Logging configuration

Verbosity levels

Control log output detail with the --verb option:

verb 3  # Recommended for production

Verbosity level reference

• 0 - No output except fatal errors
• 1-4 - Normal usage range (3 recommended for good summary)
• 5 - Shows R/W characters for each packet (uppercase for TCP/UDP, lowercase for TUN/TAP)
• 6-11 - Debug info range (see errlevel.h for details)

Level 3 provides a good balance of information without excessive output. Use level 4-5 for troubleshooting.

Log output options

Log to file

Write logs to a file instead of stdout:

# Truncate file on startup
log /var/log/openvpn/server.log

# Append to existing file
log-append /var/log/openvpn/server.log

The --log option takes effect immediately and persists across SIGHUP, SIGUSR1, and --ping-restart events.

Log to syslog

Direct output to system logger:

syslog openvpn-server
daemon

On Windows, OpenVPN logs by default when started as a service without needing this option.

Machine-readable format

Enable structured logging for automated processing:

machine-readable-output

This ensures timestamps and message flags are always included.

Log management

# Limit repeated messages
mute 20

# Suppress common false alarms
mute-replay-warnings

# Timestamp control
suppress-timestamps  # Disable timestamps

# Error output
errors-to-stderr  # Send errors to stderr

The mute-replay-warnings option silences replay warnings which are common on WiFi networks. This preserves security while reducing log verbosity.

Status files

Basic status reporting

Generate status files with connection and routing information:

# Update every 60 seconds (default)
status /var/log/openvpn/status.log

# Update every 30 seconds
status /var/log/openvpn/status.log 30

# Set output format version
status-version 3

Status file formats

Version 1 - Traditional format (default)

Client list contains comma-separated fields:

• Common Name
• Real Address
• Bytes Received
• Bytes Sent
• Connected Since

status-version 1

Version 2 - Extended format

More reliable format with additional fields:

• Common Name
• Real Address
• Virtual Address
• Virtual IPv6 Address
• Username
• Client ID
• Peer ID
• Data Channel Cipher
• Bytes Received
• Bytes Sent
• Connected Since

status-version 2

Version 3 - Tab-separated format

Identical to version 2 but with tab separators for easier parsing:

status-version 3

Version 3 is recommended for external processing and monitoring tools.

Trigger status output

Generate status on demand:

# Send SIGUSR2 to write status to syslog
kill -USR2 $(pgrep openvpn)

# Via systemd
systemctl kill -s SIGUSR2 openvpn-server@server

Management interface

Enabling the management interface

The management interface provides real-time control and monitoring:

# Unix socket (recommended)
management /var/run/openvpn/management.sock unix
management /var/run/openvpn/management.sock unix /etc/openvpn/mgmt-password

# TCP socket on localhost
management 127.0.0.1 7505
management 127.0.0.1 7505 /etc/openvpn/mgmt-password

Security critical: Always use password protection when enabling TCP management interface:

• Set IP to 127.0.0.1 (localhost only)
• Use pw-file parameter for authentication
• Never expose management interface to untrusted networks

# Create password file
echo "your-secure-password" > /etc/openvpn/mgmt-password
chmod 600 /etc/openvpn/mgmt-password

Restricting access

For Unix sockets, restrict by user and group:

management /var/run/openvpn/mgmt.sock unix
management-client-user openvpn
management-client-group openvpn

Connecting to management interface

Connect using telnet or netcat in raw mode:

# Unix socket
socat - UNIX-CONNECT:/var/run/openvpn/management.sock

# TCP socket
telnet 127.0.0.1 7505

Once connected, type help for available commands.

Management interface commands

Status monitoring commands

status - View connection status

Display current daemon status:

# Default format
status

# Specific version
status 3

Output format matches --status directive and includes:

• Connected clients (server mode)
• Routing table
• Traffic statistics

state - Connection state

Show current OpenVPN state:

# Current state
state

# Enable real-time notifications
state on

# Show history
state all

# Show last 3 state transitions
state 3

# Atomic: show history and enable notifications
state on all

OpenVPN states:

• CONNECTING - Initial state
• WAIT - Waiting for server response (client)
• AUTH - Authenticating with server (client)
• GET_CONFIG - Downloading configuration (client)
• ASSIGN_IP - Assigning IP to interface
• ADD_ROUTES - Adding routes
• CONNECTED - Initialization complete
• RECONNECTING - Restart occurred
• EXITING - Graceful exit in progress
• RESOLVE - DNS lookup (client)
• TCP_CONNECT - Connecting to TCP server (client)
• AUTH_PENDING - Authentication pending (client)

Real-time notifications use >STATE: prefix with up to 9 comma-separated parameters including timestamp, state name, descriptive string, and network addresses.

log - View log messages

Access log file cache:

# Enable real-time log output
log on

# Show cached history
log all

# Show last 20 lines
log 20

# Atomic: show history and enable real-time
log on all

# Disable real-time output
log off

Configure log cache size:

management-log-cache 500

Real-time format: >LOG:timestamp,flags,message

Flags: I (info), F (fatal), N (non-fatal error), W (warning), D (debug)

bytecount - Bandwidth monitoring

Monitor real-time bandwidth usage:

# Enable notifications every 5 seconds
bytecount 5

# Disable notifications
bytecount 0

Client output:

>BYTECOUNT:{BYTES_IN},{BYTES_OUT}

Server output (per connected client):

>BYTECOUNT_CLI:{CID},{BYTES_IN},{BYTES_OUT}

When clients disconnect, final bandwidth numbers are included in bytes_received and bytes_sent environmental variables in the >CLIENT:DISCONNECT notification.

Client management commands

kill - Disconnect client

In server mode, disconnect specific clients:

# Kill by common name
kill Test-Client

# Kill by address and port
kill tcp:1.2.3.4:4000

Killing by IPv6 address is not yet supported. Use common name or CID instead.

client-kill - Kill by client ID

Immediately terminate a client session:

client-kill {CID}

Use status command to find client IDs (CID).

Control commands

signal - Send signals

Send control signals to OpenVPN daemon:

signal SIGUSR1  # Restart connection
signal SIGHUP   # Reload configuration
signal SIGTERM  # Graceful shutdown
signal SIGUSR2  # Write status to log

verb - Adjust verbosity

Change log verbosity at runtime:

# Set to level 4
verb 4

# Show current setting
verb

mute - Control message repetition

Adjust mute parameter:

# Mute after 40 repeated messages
mute 40

# Show current setting
mute

Utility commands

# Show process ID
pid

# Show version information
version

# Exit management session
exit
quit

Real-time notifications

When monitoring is enabled, the management interface sends real-time messages with > prefix:

Notification types

• >BYTECOUNT: - Bandwidth usage updates
• >BYTECOUNT_CLI: - Per-client bandwidth (server)
• >CLIENT: - Client connection/disconnection events
• >ECHO: - Echo messages from config
• >FATAL: - Fatal errors before exit
• >HOLD: - Hold state indication
• >INFO: - Informational messages
• >LOG: - Log message output
• >NEED-OK: - User action required
• >NEED-STR: - User input required
• >PASSWORD: - Password request or verification failure
• >STATE: - State changes
• >INFOMSG: - Authentication info from server

Client notifications (server mode)

With --management-client-auth, monitor client lifecycle:

management-client-auth

Notification sequence:

1. CONNECT/REAUTH - New connection or renegotiation

   >CLIENT:CONNECT,{CID},{KID}
   >CLIENT:ENV,name1=val1
   ...
   >CLIENT:ENV,END
   

2. ESTABLISHED - Successful authentication

   >CLIENT:ESTABLISHED,{CID}
   >CLIENT:ENV,name1=val1
   ...
   >CLIENT:ENV,END
   

3. ADDRESS - Virtual address assignment

   >CLIENT:ADDRESS,{CID},{ADDR},{PRI}
   

4. DISCONNECT - Client disconnection

   >CLIENT:DISCONNECT,{CID}
   >CLIENT:ENV,name1=val1
   ...
   >CLIENT:ENV,END
   

• CID = Client ID (sequential: 0, 1, 2, …)
• KID = Key ID for TLS session
• PRI = Primary (1) or Secondary (0) address

Integration with monitoring tools

Prometheus exporter pattern

Parse status file or use management interface:

# Example: Parse status-version 3 format
with open('/var/log/openvpn/status.log') as f:
    for line in f:
        if line.startswith('CLIENT_LIST'):
            fields = line.strip().split('\t')
            common_name = fields[1]
            bytes_received = int(fields[8])
            bytes_sent = int(fields[9])
            # Export metrics...

Log aggregation

Forward logs to centralized systems:

# Use syslog forwarding
syslog openvpn-server

# Or configure log shipper (e.g., Filebeat, rsyslog)
log-append /var/log/openvpn/server.log

Health checks

Implement monitoring checks:

1. Process check

   systemctl is-active openvpn-server@server
   
2. Interface check

   ip link show tun0
   
3. Management interface check

   echo "state" | socat - UNIX-CONNECT:/var/run/openvpn/mgmt.sock
   
4. Client count check (server)

   Parse status file for connected clients count

Alerting scenarios

Monitor and alert on these conditions:

Connection failures

• State stuck in RECONNECTING
• Repeated AUTH failures
• Certificate verification errors
• TLS negotiation failures

Performance issues

• High packet loss
• Excessive replay warnings
• Low bandwidth throughput
• High CPU usage

Security events

• Failed authentication attempts
• Certificate revocation list updates
• Management interface unauthorized access
• Unusual client connection patterns

Operational issues

• Process restarts
• Configuration reload failures
• Disk space issues (log files)
• Interface creation failures