Documentation

 

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

Because of the security issues involved in script execution,
the Access Server client has a series of requirements that
must be met before it will execute a script pushed by an
Access Server:

1. The Access Server must be trusted by the client. This can
be done by:

(a) Installing the client by downloading it from the Access
Server to be trusted. In this case, the client will
implicitly trust the Access Server that it was downloaded
from (when the client is downloaded from an Access Server,
the Access Server will attach a profile to the installer
that will be implicitly trusted by the client when it
installs).

(b) The client may import a profile from the Access Server
when the client is running as an Administrator and
by specifying that the profile should be trusted.

2. The client global settings must be configured to allow
script execution (this setting can also be controlled from
the Access Server, when the client is downloaded from the
Access Server -- see the Access Server command line guide
for more info).

3. Either the end-user must approve the script, or the client
must be configured by an administrator to run scripts
silently (this setting can also be controlled from the
Access Server, when the client is downloaded from the
Access Server -- see the Access Server command line guide
for more info).

Scripts may be designated on the Access Server as requiring user
or 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.]