Tutorial: How To Use Debug Flags
Overview
This tutorial provides information about Access Server debugging flags that can help you troubleshoot problems and determine the routes and instructions clients receive.
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.
An installed Access Server.
Root access to the console.
An open support ticket to coordinate with our team (recommended).
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.confAdd 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
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.
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 -> 1FAVOR_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.012DEBUG_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_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'After setting the debug flag and restarting Access Server, reproduce the issue you're troubleshooting.
Check the Access Server log file:
/var/log/openvpnas.logUse 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.logFor AWS licensing and instance metadata issues (DEBUG_AWSINFO=1):
grep -Ei "AWS INFO|AWS INSTANCE|AWS Product" /var/log/openvpnas.logFor configuration changes via API calls (API_TRACE_SA=1):
grep "API CALL" /var/log/openvpnas.logFor log database activity (DEBUG_LOGDB=1):
grep "LOG_DB" /var/log/openvpnas.logFor subscription and licensing communication (DEBUG_SUBSCRIPTION=2):
grep -i "Subscription" /var/log/openvpnas.logFor SAML authentication troubleshooting (DEBUG_SAML=1):
grep "SAML" /var/log/openvpnas.loggrep -E "SAML AuthNRequest|SAML checking assertion|SAML pas_info attributes" /var/log/openvpnas.logFor cluster synchronization or database errors (DEBUG_CLUSTER=1, DEBUG_DB_CONVERT=1):
cat /var/log/openvpnas.loggrep -Ei "sql|mariadb" /var/log/openvpnas.logFor DNS proxy activity (DEBUG_DNSPROXY=true):
grep "DNSPROXY" /var/log/openvpnas.log
Review the log entries related to your debug flag to identify patterns, errors, or unexpected behavior.