Access Server

Follow us

How to setup Client Scripting in OpenVPN Access Server



The Access Server supports the pushing of executable scripts to the
OpenVPN client.

Scripts are defined as group properties on the Access Server, meaning
that scripts that are associated with a given group will only be
pushed to clients that are members of that group. If you would like
to push scripts to all clients, it is possible to configure a default
group.

In the Group Permissions page on the Access Server,

(a) scripts can be defined for each of the platforms supported by the
Access Server client: Windows, Mac OS X, and Linux.

(b) scripts can be designated as requiring user or admin-level
privileges.

(c) environmental variables may be defined that will be pushed
to scripts.

OpenVPN-AS_Scripting

Script Security
---------------

Scripts may be designated on the Access Server as requiring useror administrative privileges. Admin-level script execution requires that an additional global setting be configured.

Scripting languages
-------------------

The Access Server client supports script execution using locally
installed script interpreters such as cmd.exe on Windows and
sh/bash on unix/linux. The client also supports execution of
Python scripts on all platforms, using an integrated python
interpreter.

Note that the integrated Python interpreter does not include 100%
of the standard Python library that would be present with a stock
Python install. This is done to save space in the client installer.
If you believe that a certain python module would be useful to
OpenVPN scripting that is not already bundled, please contact
suppport at OpenVPN Technologies, and we consider including it in
a future release.

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('')

Notes
-----

Admin-levels scripting notes:

* On Windows, scripts that run with admin privileges may not
be able to interact with the desktop.

* Admin-level scripts (if allowed) will be executed by the client
even if the end-user who is currently operating the client
does not possess admin privileges.

Special environmental variables that may be set on the AS:

PREPATH -- if defined, will be prepended to client's PATH before the
script is executed.

Special environmental variables set by the client backend before
scripts are executed:

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 the Access Server
client runs on unix, the OS will handle the shebang usage. However
since Windows doesn't natively recognize shebang usage, the Access
Server client will interpret the shebang line and use 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.]