How To Set Up Client Scripting | OpenVPN Access Server

Introduction

OpenVPN Access Server supports client-side scripting, which uses executable scripts with OpenVPN Connect. The Admin Web UI lets you set up a script for user groups in the Admin Web UI. Setting the group as the default group will apply the script for all users. It is also possible to use the command line interface to configure client-side scripting, and this has a granularity down to the user level.

How to set client-side scripts for user groups

OpenVPN Access Server supports the following features for client-side scripting for groups:

Scripts defined for Windows and macOS.
Scripts requiring user or admin-level privileges.
Scripts defined with environmental variables.

To enable client-side scripting:

Sign in to your Admin Web UI.
Click User Management > Group Permissions.
Click the edit icon for More Settings of the group desired.
Click Yes for Use Client Scripting?

You can click on each available link to set variables, values, and scripts.

Script Security

The end-user must approve scripts pushed by the VPN server to the VPN client. The first time the script runs, the end-user must allow it. The end-user can click the checkbox present to remember the answer given, so they don’t need to grant the script permission to run each time.

Scripting languages

OpenVPN Connect supports script execution using locally-installed script interpreters such as cmd.exe or PowerShell on Windows.

OpenVPN Connect version 2.x bundled a limited version of Python2 that it can use.
OpenVPN Connect version 3.x can support Python scripts on Windows and macOS platforms if you install a Python interpreter separately.

Note: OpenVPN Connect version 2.x installed with an integrated Python2 interpreter. The integrated Python2 interpreter doesn’t include 100% of the standard Python2 library set that would be present with a stock Python install. This saves space in the client installer.

Sample Python Scripts

Launch a URL

#!/usr/bin/env python
# On VPN connection initiation, launch a URL in the default browser.
# Works on all client platforms (Windows, Mac, Linux).
# Environmental Variables:
# LAUNCH_URL -- URL to launch
import os, webbrowser
if os.environ['N_RECONNECTS'] == '0':
webbrowser.open_new(os.environ['LAUNCH_URL'])

Download and install an application on Windows

#!/usr/bin/env python
# Download and install an MSI-based application on Windows. Leave a marker
# file behind, so that we only install the application once per local user.
# Environmental Variables:
# MSI_URL -- URL of MSI file
# MSI_HASH -- sha1 hash of MSI file, for security verification
# MSI_OPT (optional) -- extra MSI arguments, such as /q for quiet install
import os, urllib, scripthelper as sh
url = os.environ['MSI_URL']
local = os.path.basename(url)
hash = os.environ['MSI_HASH']
if not os.path.exists(hash):
urllib.urlretrieve(url, local)
if sh.digest_file(local, 'sha1') != hash:
raise ValueError("downloaded file has incorrect hash")
os.system("msiexec /i %s %s /l* msi.log" % (local, os.environ.get('MSI_OPT', '')))
file(hash, 'w').write('')

Helpful Notes

Special environmental variables that may be set on Access Server

PREPATH — if defined, is prepended to client's PATH before the script executes.

Special environmental variables set by the client backend before scripts execute

N_RECONNECTS (integer rendered as string) — the number of reconnects that have occurred thus far in this session.

GRACEFUL_DISCONNECT ("0" or "1") — set to "1" if this disconnect was requested by the user, and "0" if the disconnect was unexpected.

Script shebang usage for Windows (on unix, shebangs are processed by the OS)

The "shebang" is a unix construct for designating the interpreter that should process a script, by including a specially coded line beginning with "#!" as the first line of the script. When OpenVPN Connect runs on unix, the OS handles the shebang usage. However since Windows doesn't natively recognize shebang usage, OpenVPN Connect interprets the shebang line and uses it to determine how to execute the script, using the following rules:

[script content] — defaults to cmd.exe processing

#!foo.exe
[script content...—- find foo.exe in path]

#!foo.exe -a somearg
[script content... — pass options (the last option is the implicit script filename)]

#!"c:\Program Files\Foo Corp\foo.exe" -a somearg
[script content... — quote the program exe]

#!foo.exe
#EXT foo
[script content... — script will be written to a .foo file before execution]

#PYTHON
[python code — execute python script using OpenVPN Client built-in python interpreter]

#!/usr/bin/env python
[python code — execute python script using OpenVPN Client built-in python interpreter on Windows, and using default python install on unix.]

Questions