Skip to main content

Tutorial: Setting Up a Host-Checker Query File on Access Server

Abstract

Set up compliance checks through software version validation with Access Server and OpenVPN Connect using host-checker queries.

Overview

OpenVPN Connect for Windows and macOS supports checking the presence of specific applications on a user's device and reporting their version numbers to Access Server. This host-checking feature allows administrators to enforce compliance checks based on specific software being present or updated on client devices. This tutorial will guide you through setting up a host-checker query file, loading it into your Access Server, and utilizing it in connection profiles to enhance security and compliance.

Prerequisites

  • An installed Access Server.

  • OpenVPN Connect for Windows or macOS.

  • Basic knowledge of regular expressions (regex) to construct application version checks.

  • Console access and the ability to get root access.

Important

Ensure that all cluster nodes run the same Access Server version.

Step 1: Understand the host-checker query file format

The host-checker query file defines which applications OpenVPN Connect will check for on the client device. The file consists of platform-specific or generic (all platforms) checks for specific applications, with each line specifying an application and a regex to match its name.

File format

[PLATFORM1]1
NAME12=REGEX13
NAME2=REGEX2
[PLATFORM2]
NAME1=REGEX1
NAME2=REGEX2

1

PLATFORM specifies the platform for the check. Use 'win' for Windows, 'mac' for macOS, or 'all' for both.

2

NAME is a short, user-defined name for the application (alphanumeric and underscore only).

3

REGEX is a case-insensitive regular expression to match the full application name.

The version number of each matching application is reported back to Access Server and accessible in a post-authentication script through the attributes['client_info'] dictionary.

A simple, one-line host-checker query file to check the version of Mozilla Firefox:

FIREFOX=^mozilla firefox

Additional examples:

  • Check if Firefox and TeamViewer are installed on a Windows device:

    ['win']
FIREFOX=^mozilla firefox
TEAMVIEWER=^teamviewer

  • Check if Firefox is installed on Windows devices and if TeamViewer is installed on macOS devices:

    ['win']
FIREFOX=^mozilla firefox
['mac']
TEAMVIEWER=^teamviewer

Step 2: Create the host-checker query file

  1. Create a file called appver.txt (or any other name of your choice).

  2. Add the desired contents to the file. For our example, we're checking for Mozilla Firefox on both Windows and macOS:

    ['all']
FIREFOX=^mozilla firefox

    Important

    Using single quotes is required. E.g., 'mac'.

  3. Before adding applications to the file, you should collect the full application names to ensure accurate matching in the query file. You can do this using commands to gather application details for each platform:

    • For Windows (via PowerShell):

      Get-ItemProperty HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\* | Select-Object DisplayName, DisplayVersion, Publisher, InstallDate

      This will provide you with the DisplayName of each application, which you can then use in your query file.

    • For macOS:

      system_profiler SPApplicationsDataType | grep -e "Location:" -e "Version:"

      This will list the installed applications along with their Location and Version, which can also be used for matching in the query file.

  4. Add multiple checks for different applications and platforms in the file as needed. For example, you can check for Firefox on Windows and TeamViewer on both Windows and macOS:

    ['win']
FIREFOX=^mozilla firefox
TEAMVIEWER=^teamviewer

['mac']
TEAMVIEWER=^teamviewer

  5. Save and exit.

Step 3: Load the host-checker query file into Access Server

  1. If you didn't create the file directly on your Access Server console, upload it using an SCP or SFTP client.

  3. Load the host-checker file into Access Server:

    ./sacli --key "vpn.client.app_verify" --value_file="appver.txt" ConfigPut

  4. Restart Access Server to apply the configuration:

    ./sacli start

  5. Download a new connection profile (.ovpn) so the information in appver.txt will be embedded into this profile. This ensures the new connection profile contains the app verification checks defined in your query file.

Step 4: Embed host-checker instructions into connection profiles

After you load the host-checker query file, the generated connection profiles from your Access Server will automatically include the host-checker instructions. These profiles will check the presence and versions of the specified applications during the VPN connection process.

When users connect to the VPN, OpenVPN Connect reports the version of the specified applications (such as Firefox) to Access Server. The reported version number can be accessed in the post-auth script using the following format:

attributes['client_info']['UV_APPVER_FIREFOX']

Step 5: Handle application version in post-auth script

You can now use the reported application version in your post-auth script to determine whether to allow or deny the connection. For example, here’s a simple Python code snippet for checking Firefox's version:

from pyovpn.plugin import *

# this function is called by the Access Server after normal authentication
def post_auth(authcred, attributes, authret, info):

    # set this to error string, if auth fails
    error = ""

    if attributes.get('vpn_auth'): # only do this for VPN authentication
        firefox_version = attributes['client_info']['UV_APPVER_FIREFOX']
		
        # Deny access if Firefox is not installed or has no version
        if firefox_version in ['ERR_NOT_FOUND', 'ERR_NO_VERSION']:
            error = "Firefox is not installed or version not detected."
            print("***** POST_AUTH APP CHECK: connection attempt        : FAILED")
        else:
            print(f"Client Firefox version: {firefox_version}")
            print("***** POST_AUTH APP CHECK: connection attempt        : SUCCESS")

    # process error, if one occurred
    if error:
        authret['status'] = FAIL
        authret['reason'] = error # this error string is written to the server log file
        authret['client_reason'] = error # this error string is reported to the client user

    return authret

This script checks if Firefox is installed on the client device. If not, it fails the authentication and informs the user.

To add it to a post-auth script, use these tutorials for help writing your Python script:

Error handling

The host-checker can return the following error strings:

  • ERR_NOT_FOUND: The application wasn't found on the client.

  • ERR_NO_VERSION: The application doesn't have a detectable version number.

  • ERR_MANY_FOUND: More than one application matched the regex.

  • ERR_REGEX: The regular expression couldn't be parsed.

You can handle these errors in the post-auth script as shown in the example above.

In this section: