---
title: 'Tutorial: How To Use Debug Flags'
canonical: https://openvpn.net/as-docs/tutorials/tutorial--debug-flags/
product: Access Server Docs
description: You can set debug flags to help with troubleshooting Access Server issues. This tutorial shows you how.
---

# 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.

> **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](https://support.openvpn.com/) 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:

1. Connect to the console and get root privileges.
2. Open the **as.conf** file for editing:

   ```
   nano /usr/local/openvpn_as/etc/as.conf
   ```
3. Add the debug command (from step 2) to the bottom of the file.
4. Save and exit by pressing Ctrl+x, then y.
5. 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.

### DEBUG\_AZUREINFO=1

This flag logs extra information about the licensing process in the **liman info** output and the **/var/log/openvpnas.log** file for troubleshooting Azure 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 -> 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:

1. Tracking if somebody or something is altering your configuration settings without your knowledge, such as a colleague with access to the system.
2. 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](https://openvpn.net/as-docs/tutorials/tutorial--xml-rpc-interface.md).

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](https://openvpn.net/as-docs/tutorials/tutorial--debug-flags/#api_trace_sa-1) this also gets dumped in **openvpnas.log** or syslog if the [syslog function is enabled](https://openvpn.net/as-docs/tutorials/tutorial--syslog.md).

### 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'
```

## Step 3: Review Access Server logs for debug flag output

1. After setting the debug flag and restarting Access Server, reproduce the issue you're troubleshooting.
2. Check the Access Server log file:

   ```
   /var/log/openvpnas.log
   ```
3. 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 Azure licensing and instance metadata issues (DEBUG\_AZUREINFO=1):

     ```
     grep -Ei "AZURE|License Info" /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.
4. 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.

> **Important**
>
> **Recommended**
>
> For complex issues, open a [support ticket](https://support.openvpn.com/) and share the relevant log output. Our support team can help analyze the logs and guide you toward a resolution.

---

Prev: [Tutorial: Turn Off Audit and Service Logging](https://openvpn.net/as-docs/tutorials/tutorial--turn-off-logging.md)
Next: [Web Services and UI Settings](https://openvpn.net/as-docs/tutorials/web-services-and-ui-settings.md)
Index: https://openvpn.net/as-docs/llms.txt