Tutorial: Setting Up a Host-Checker Query File on Access Server
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.
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.
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]
NAME1=REGEX1
NAME2=REGEX2
[PLATFORM2]
NAME1=REGEX1
NAME2=REGEX2PLATFORM specifies the platform for the check. Use
'win'for Windows,'mac'for macOS, or'all'for both.NAME is a short, user-defined name for the application (alphanumeric and underscore only).
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 firefoxAdditional examples:
Check if Firefox and TeamViewer are installed on a Windows device:
['win'] FIREFOX=^mozilla firefox TEAMVIEWER=^teamviewerCheck if Firefox is installed on Windows devices and if TeamViewer is installed on macOS devices:
['win'] FIREFOX=^mozilla firefox ['mac'] TEAMVIEWER=^teamviewer
Create a file called
appver.txt(or any other name of your choice).Add the desired contents to the file. For our example, we're checking for Mozilla Firefox on both Windows and macOS:
['all'] FIREFOX=^mozilla firefoxBefore 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, InstallDateThis 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.
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=^teamviewerSave and exit.
If you didn't create the file directly on your Access Server console, upload it using an SCP or SFTP client.
Switch to the scripts directory:
cd /usr/local/openvpn_as/scripts/Load the host-checker file into Access Server:
./sacli --key "vpn.client.app_verify" --value_file="appver.txt" ConfigPutRestart Access Server to apply the configuration:
./sacli startDownload a new connection profile (.ovpn) so the information in
appver.txtwill be embedded into this profile. This ensures the new connection profile contains the app verification checks defined in your query file.
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']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 authretThis 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:
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.