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 the 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|'all']1
NAME12=REGEX13
NAME2=REGEX2
[PLATFORM2|'all']
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.Tutorial: Implementing a Post-Auth Script in Access Server

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

FIREFOX=^mozilla firefox

Step 2: Creating 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:

    ['win'|'mac'|'all']
FIREFOX=^mozilla firefox

    Important

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

  3. Add multiple checks for different applications and platforms in the file as needed.

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

    • You've embedded the appver.txt query file into all client profiles generated from the Access Server after this point.

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:

def post_auth(authcred, attributes, authret, info):
    # Check if the Firefox version is reported
    if 'UV_APPVER_FIREFOX' in attributes['client_info']:
        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']:
            authret['status'] = FAIL
            authret['client_reason'] = "Mozilla Firefox is not installed or version not detected."
        else:
            # Log the Firefox version for debugging purposes
            print(f"Client Firefox version: {firefox_version}")
    
    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: