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, so beware of filling up your hard drive and running out of disk space. Not all flags create a lot of information, but some do, and some even log passwords or session data to the log, so beware of this.

We recommend using these flags to pinpoint a problem, get 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:
```
service openvpnas restart
```

Step 2: Select your 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 that is supposed to perform tasks such as filling in forms or managing passwords somehow changes settings you didn't touch while you're 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 use 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 like 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 the XML-RPC interface paragraph in the command line tools section.

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.

In this section: