Tutorial: How to Use Debug Flags

Abstract

You can set debug flags to help with troubleshooting Access Server issues. This tutorial shows you how.

Overview

This tutorial provides information about Access Server debugging flags that can help you troubleshoot problems and determine the routes and instructions clients receive.

Important

Use these debug flags at your own risk.

We recommend working with OpenVPN Inc. support personnel to use debugging flags for specific needs.

Here we publish the most useful debug flags available to the general public for gathering more Access Server data.

Some of these debug flags can significantly increase the amount of logging data produced by Access Server; therefore, be cautious not to fill up your hard drive and run out of disk space. Not all flags generate a lot of information, but some do, and some even log passwords or session data to the log, so be aware of this.

We recommend using these flags to pinpoint a problem, retrieve log data, and then turn off the debug flag.

Prerequisites

An installed Access Server.
Root access to the console.
An open support ticket to coordinate with our team (recommended).

Step 1: Set a debug flag

You can set most debug flags in the /usr/local/openvpn_as/etc/as.conf file. You add the command to the bottom of the file and cold restart the Access Server service afterward:

Connect to the console and get root privileges.
Open the as.conf file for editing:
```
nano /usr/local/openvpn_as/etc/as.conf
```
Add the debug command (from step 2) to the bottom of the file.
Save and exit by pressing Ctrl+x, then y.
Restart the service:
```
systemctl restart openvpnas
```

Step 2: Select the needed debug flag

Here are many of the available debug flags you can work with. We recommend coordinating with our support team.

DEBUG_AWSINFO=1

This flag logs extra information about the licensing process in the liman info output and the /var/log/openvpnas.log file for troubleshooting AWS tiered licenses. This output helps troubleshoot the issue, especially when experiencing problems reaching a license activation server.

After you restart the Access Server service, run this command to filter for the words "AWS INFO" in the log file:

cat /var/log/openvpnas.log | grep -i "AWS INFO"

LOG_N_CLIENTS_CHANGE=1

This flag logs information whenever the internal, currently connected users count changes for troubleshooting the number of connected users. This can be useful if you suspect the connected user count is off for whatever reason. An example line from the log file:

0000-00-00 00:00:00+0000 [-] ***** N_CLIENTS CHANGE 0 -> 1

FAVOR_LZO=1

Use this debug flag to override the order in which compression algorithms are chosen for connecting clients. It forces the use of LZO. In extremely rare cases, this flag can help resolve connectivity problems from iOS devices with very specific compression problems.

API_TRACE_SA=1

This flag logs all changes to the configuration settings by logging all activity between Access Server and the configuration databases.

It may be useful for various use cases, such as the following:

Tracking if somebody or something is altering your configuration settings without your knowledge, such as a colleague with access to the system.
Determining whether a browser plugin, intended to perform tasks such as filling in forms or managing passwords, inadvertently alters settings you didn't intend to change while working on other settings.

This example line from the log file shows that the user, openvpn, signs on to the Admin Web UI successfully:

2017-09-19 17:11:54+0200 [-] *** API CALL f=authenticate args=[{'username': 'openvpn', 'password': '[redacted]', 'client_ip_addr': '12.34.56.78'}, {'log_service_name': 'WEB_ADMIN', 'request_superuser_privileges': True}] time=0.012

DEBUG_LOGDB=1

This flag logs everything that goes into the log database.

Access Server displays details about user logins and bandwidth usage on the Log Reports page in the Admin Web UI. This information comes from the log.db database file, separate from the log files, which helps you track and resolve Access Server problems rather than storing user actions, such as authentication and data usage.

However, use this flag to log everything to the log files.

This example line shows that the user openvpn logged on to the Admin Web UI web service:

0000-00-00 00:00:00+0000 [-] LOG ERR: 'LOG_DB RECORD {"username": "openvpn", "node": "OPENVPNAS", "service": "WEB_ADMIN", "real_ip": "12.34.56.78", "timestamp": 1505833476, "start_time": 1505833476, "session_id": "u1OfDeOuagO1sGQg", "auth": 1}'

LOG_DB_XML_API_VERBOSE=1

This flag logs calls made to the XML API.

The Access Server's XML-RPC interface is typically limited to authentication and retrieving user-specific data, such as a user-locked profile. OpenVPN Connect for Windows and macOS uses the XML-RPC's limited set of commands for authentication and retrieving a user-locked profile, with other functions disabled by default. For more details, refer to Tutorial: Changing the XML-RPC Function Support.

Once you activate this flag, you can use the logdba tool to query for XML-RPC API calls like so:

./logdba --csv --service_filt=XML_API --columns="+api_method"

And with API_TRACE_SA=1 this also gets dumped in openvpnas.log or syslog if the syslog function is enabled.

DEBUG_SUBSCRIPTION=2

This flag logs information for an activated subscription in /var/log/openvpnas.log. Specifically, it enables verbose debug subscription service logging. Once turned on, the communication between Access Server and the Subscription Tracking System is added to the log.

DEBUG_SAML=1

This flag will enable the SAML authentication module to log the decoded SAML assertion. This can help with debugging by providing detailed information in the logs, making it easier to troubleshoot SAML authentication issues for both web and VPN services.

DEBUG_CLUSTER=1

Available on Access Server 3.1.0 and newer. This flag enables verbose logging for cluster-related operations, which is useful for diagnosing synchronization, communication, or configuration issues between nodes in a cluster. The log will show detailed messages related to cluster behavior in /var/log/openvpnas.log and standard output.

Example log output:

[stdout#info] *********** MYSQL ERROR ***********
[stdout#info] Access denied for user 'root'@'203.0.113.234'

DEBUG_DB_CONVERT=1

Available on Access Server 3.1.0 and newer. Use this flag to log detailed information during database format conversion operations (e.g., when moving from SQLite to MariaDB). It's helpful for identifying authentication or permission errors and other conversion-related issues.

Example log output:

[stdout#info] mysql.ssl_mode was: ""
[stdout#info] (mariadb.OperationalError) Access denied for user 'root'@'203.0.113.234'

DEBUG_DNSPROXY=true

This flag enables verbose logging for the DNS proxy service. After restarting Access Server, the log will include configuration details and status messages for the DNS proxy, such as the listen address and port, upstream DNS server settings, IP address ranges in use, the firewall table, and chain configuration. It also provides real-time logging of DNS queries entering and leaving the proxy, including resolved addresses and any DNS-related errors.

Example log output showing startup configuration:

[stdout#info] [DNSPROXY] OUT: "Applied config '{'type': 'config', 'data': {'listen_addr': '203.0.113.1', 'listen_port': 953, 'forwarder_addr': '192.0.2.2', 'forwarder_port': 53, 'forwarder_timeout': 15.0, 'ipv4_pool_net': '100.64.0.0/10', 'ipv6_pool_net': 'fd15:6e1d:c3ab:49c3::/64', 'strip_aaaa': 'routed', 'firewall': 'nftables', 'table': 'as_nat', 'chain': 'AS_DOMAIN_RT'}}'"

Example lot output showing DNS query activity:

2026-04-15T21:15:34+0000 [stdout#info] [DNSPROXY] OUT: '[40] Received query from 203.0.113.3:53477'
2026-04-15T21:15:34+0000 [stdout#info] [DNSPROXY] OUT: '[40] Forwarding query for openvpn.example.com. IN A'
2026-04-15T21:15:34+0000 [stdout#info] [DNSPROXY] OUT: '[40] Received response'

Step 3: Review Access Server logs for debug flag output

After setting the debug flag and restarting Access Server, reproduce the issue you're troubleshooting.
Check the Access Server log file:
```
/var/log/openvpnas.log
```
Use filtering commands to find relevant debug output. For example:
- For client connection count changes (LOG_N_CLIENTS_CHANGE=1):
```
grep "N_CLIENTS" /var/log/openvpnas.log
```
- For AWS licensing and instance metadata issues (DEBUG_AWSINFO=1):
```
grep -Ei "AWS INFO|AWS INSTANCE|AWS Product" /var/log/openvpnas.log
```
- For configuration changes via API calls (API_TRACE_SA=1):
```
grep "API CALL" /var/log/openvpnas.log
```
- For log database activity (DEBUG_LOGDB=1):
```
grep "LOG_DB" /var/log/openvpnas.log
```
- For subscription and licensing communication (DEBUG_SUBSCRIPTION=2):
```
grep -i "Subscription" /var/log/openvpnas.log
```
- For SAML authentication troubleshooting (DEBUG_SAML=1):
```
grep "SAML" /var/log/openvpnas.log
```
```
grep -E "SAML AuthNRequest|SAML checking assertion|SAML pas_info attributes" /var/log/openvpnas.log
```
- For cluster synchronization or database errors (DEBUG_CLUSTER=1, DEBUG_DB_CONVERT=1):
```
cat /var/log/openvpnas.log
```
```
grep -Ei "sql|mariadb" /var/log/openvpnas.log
```
- For DNS proxy activity (DEBUG_DNSPROXY=true):
```
grep "DNSPROXY" /var/log/openvpnas.log
```
  Note
  Some debug flags (such as FAVOR_LZO=1 and LOG_DB_XML_API_VERBOSE=1) don't have specific keywords to filter for. In these cases, review the log output directly or use broader search terms based on the behavior you're investigating.
Review the log entries related to your debug flag to identify patterns, errors, or unexpected behavior.

Tip

Debug flags can generate large amounts of log data. After collecting the necessary information, remove the debug flag and restart Access Server to prevent excessive logging.