Using Scripts

On This Page
    Tunnelblick VPN Configuration scripts
    OpenVPN scripts
    Scripts Run at the Start and End of the Standard up, down, and route-pre-down Scripts
    Other Scripts and Executable Files
    Script Execution Order
    Environment Variables

Most Tunnelblick users do not need to use the information on this page; Tunnelblick uses scripts automatically.

Most scripts are run as root so they can make network configuration changes; thus caution is advised when modifying these scripts or using customized scripts.
Scripts with '.user.' in their name are run as the logged-in user.

This document is about the scripts that Tunnelblick uses. Some are built into Tunnelblick; some are optional and may be supplied by whoever sets up a configuration. Tunnelblick itself may be accessed from and/or controlled with AppleScript; see AppleScript Support.

Tunnelblick uses four types of scripts: Tunnelblick VPN Configuration scripts, OpenVPN scripts, the leasewatch script, and executable files (which may be scripts).

Tunnelblick VPN Configuration scripts

Tunnelblick VPN Configuration scripts are shell scripts that are run by Tunnelblick at particular points in the connection process.

Tunnelblick does not include any of these scripts; see the Downloads page for user-contributed scripts.
They may be used in special circumstances — for example, to make modifications to the network configuration when a tunnel is active.
The scripts are not run unless Tunnelblick is running, so they are not invoked in 'connect when computer starts' configurations.

The following scripts are run as "root". (Environment variables include the actual user's username.)

pre-connect.sh is executed before Tunnelblick would unload and/or load the tun or tap kexts (whether or not any unload or load takes place).
post-tun-tap-load.sh is executed after Tunnelblick unloads and/or loads the tun or tap kexts (whether or not any unload or load takes place). Thus, the script is executed immediately before starting OpenVPN.
connected.sh is executed when a configuration connects.
reconnecting.sh is executed when OpenVPN loses the VPN connection and is trying to reconnect.
post-disconnect.sh is executed after OpenVPN has closed the connection.
up-prefix.sh is executed before the 'up' script.
up-suffix.sh is executed after the 'up' script.
down-prefix.sh is executed before the 'down' script.
down-prefix.sh is executed after the 'down' script.
route-pre-down-prefix.sh is executed before the 'route-pre-down' script.
route-pre-down-prefix.sh is executed after the 'route-pre-down' script.

The following scripts are run as the logged-in user:

static-challenge-response.user.sh is executed to get a response to a static challenge.
dynamic-challenge-response.user.sh is executed to get a response to a dynamic challenge.
password-replace.user.sh is executed to get a string to replace a password before it is passed to OpenVPN.
password-prepend.user.sh is executed to get a string to prepend to a password before it is passed to OpenVPN.
password-append.user.sh is executed to get a string to be appended to a password before it is passed to OpenVPN.

If the output from the password… scripts ends in an ASCII LF character (0x0A), the LF will be removed before the output is used to replace or modify the password.

However, the output from the static-… and dynamic… scripts is used as is (without removing a trailing LF character). In a script, for example, that means you should use printf "%s" "$response" to avoid the trailing LF character that echo "$respose" adds to the end of the output.

The scripts will be executed automatically if they are included in the Tunnelblick VPN Configuration (".tblk"). For more information, see Creating and Installing a Tunnelblick VPN Configuration and Multi-factor and Two-factor Authentication.

OpenVPN scripts

OpenVPN scripts are scripts run by OpenVPN directly. Scripts referred to in the OpenVPN configuration file may be included in a Tunnelblick VPN configuration; use filenames without any path information to refer to them in the OpenVPN configuration file. These scripts include:

iproute is an alternate command to execute instead of the default iproute2.
auth-user-pass-verify is executed in server mode on new client connections, when the client is still untrusted.
client-connect is executed in server mode immediately after client authentication.
client-disconnect is executed in server mode on client instance shutdown.
down is executed after TCP/UDP and TUN/TAP close. (Timing depends on --down-pre.)
ipchange is executed after connection authentication, or remote IP address change.
learn-address is executed in server mode whenever an IPv4 address/route or MAC address is added to OpenVPN's internal routing table.
route-pre-down is executed right before the routes are removed.
route-up is executed after connection authentication, either immediately after, or some number of seconds after as defined by the --route-delay option.
tls-verify is executed when we have a still untrusted remote peer.
up is executed after TCP/UDP socket bind and TUN/TAP open. It is executed before routing changes are made unless Tunnelblick's "Set DNS after routes are set" checkbox is checked. Timing also depends on the presence of an --up-delay option. Note that these scripts may have any name; the script name is given as a parameter of the corresponding OpenVPN option. For example, "route-pre-down foo.bar" tells OpenVPN to run the script "foo.bar" during the disconnection process, immediately before the routes are removed.

(Many if not all of the OpenVPN options actually accept a command line, which may include any valid commands, not a script name, but typically they just name a script to be executed.)

Tunnelblick tells OpenVPN to run Tunnelblick's standard "up" and "down" scripts if Tunnelblick's "Set DNS/WINS" is set to anything other than "Do not set nameserver". In that situation, any "up" or "down" options in the configuration file will be ignored.

The standard client up- and down- scripts Tunnelblick provides are shell scripts that are run by OpenVPN immediately after connecting, and immediately after disconnecting, respectively.

The scripts are run only when a "Set nameserver" option is selected in the configuration's Settings tab.
To run the scripts, Tunnelblick passes --up and --down options to OpenVPN. This means that any "up" or "down" options specified in the OpenVPN configuration file are ignored. To use your own custom scripts from within the configuration file, select "Do not set nameserver".
Tunnelblick includes a standard up script and a standard down script (client.up.tunnelblick.sh and client.down.tunnelblick.sh, respectively) that are used if no other scripts are present. They are located in Tunnelblick.app/Contents/Resources. The scripts save the current DNS configuration and accept "pushed" configurations from the VPN server when the VPN is connected, and restore the DNS configurations when the VPN is disconnected. If "Monitor connection" is checked, the up script sets up to run the leasewatch script when a network configuration change is detected.
In a "Deployed" version of Tunnelblick, the standard scripts may be overridden by including "up.tunnelblick.sh" and "down.tunnelblick.sh" scripts in Tunnelblick.app/Contents/Resources/Deploy.
The standard scripts and Deployed scripts may be overridden by including "up.tunnelblick.sh", "down.tunnelblick.sh", and "route-pre-down.tunnelblick.sh" scripts in a Tunnelblick VPN Configuration.
For backward compatibility, deprecated scripts named "up.sh", "down.sh", "nomonitor.up.sh", "nomonitor.down.sh" will override any other scripts.

The up and down scripts may be called with optional arguments (before the standard OpenVPN-supplied arguments) that are prefixed by a '-'. The arguments are:

-m to monitor the network configuration (reflects the 'Monitor connection' checkbox);
-w to cause restoration of expected WINS configuration if it changes to the pre-VPN configuration (via DHCP renewal, for example); and
-d to cause restoration of expected DNS configuration if it changes to the pre-VPN configuration (via DHCP renewal, for example).
The -w and -d options are specified if the boolean Tunnelblick preferences '-doNotRestoreOnDnsReset' and/or '-doNotRestoreOnWinsReset' are TRUE.

Scripts Run at the Start and End of the Standard up, down, and route-pre-down Scripts

If the standard Tunnelblick "up", "down", and "route-pre-down" scripts are used, that is, if "Set DNS/WINS" is set to "Set nameserver", then the following scripts are run as root if they are present:

"up-prefix.sh" and "up-suffix.sh" are run at the start and end, respectively, of Tunnelblick's standard "up" script.
"down-prefix.sh" and "down-suffix.sh" are run at the start and end, respectively, of Tunnelblick's standard "down" script.
"route-pre-down-prefix.sh" and "route-pre-down-suffix.sh" are run at the start and end, respectively, of Tunnelblick's standard "route-pre-down" script.

Each script is called with the arguments which with the main script is called. For example, "up-prefix.sh" is called with the arguments with which the standard "up" script is called. Each of the scripts is called with optional Tunnelblick arguments to the script first, followed by the OpenVPN arguments. Tunnelblick arguments all begin with a hyphen ("-") character, so they are easy for a script to distinguish. For an example of one way to do that, see the section of Tunnelblick's "client.up.tunnelblick.sh" script (currently at line 1472 of the script) that starts with

# Handle the arguments we know about by setting ARG_ script variables to their values, then shift them out

Although the Tunnelblick arguments vary depending on Tunnelblick settings, the OpenVPN arguments to the "up" script (and thus also to "up-prefix.sh" and "up-suffix.sh") are as follows (from the OpenVPN man page):

–dev tun: tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [ init | restart ]
–dev tap: tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [ init | restart ]

These scripts can be used in 'connect when computer starts' configurations because they are not run by Tunnelblick.

Other Scripts and Executable Files

Tunnelblick uses other scripts, too:

leasewatch is a script that is run when a VPN is connected, "Monitor connections" is checked for the configuration, and a network configuration change is detected. It ignores the change, restarts the connection, or restores the VPN's DNS and WINS configuration as appropriate. It is located in Tunnelblick.app/Contents/Resources/leasewatch.

Executable files, which may be scripts, are files in /Deploy/Menu (see Deploying Tunnelblick) which are executed when Tunnelblick launches, when a connection is made, or when the user clicks on additional menu commands. See Additional Menu Commands and Programs for details.

Script Execution Order

Tunnelblick VPN Configuration scripts and -up and -down scripts are executed as follows:

USER ASKS for connection (or one is started by 'connect on launch')
pre-connect.sh will run before attempting to make a connection
post-tun-tap-load.sh will run after the tun/tap kext is loaded (or would have been loaded)
password-… scripts will be run after asking the user for a username/password or obtaining the username and password from the Keychain.
up script will run near the end of the connection process (up-prefix.sh and/or up-suffix.sh will be run before or after the up script).
connected.sh will run if/when the connection is successfully made
If OpenVPN detects a problem and attempts to reconnect, reconnecting.sh will run. (If the OpenVPN --persist-tun option is not specified, a down script will run at the start of the reconnection process and an up script wil be run at the end of the reconnection process.)
connected.sh will run each time (if any) a reconnection attempt is successful
USER ASKS for connection to be terminated (or quits Tunnelblicks and it isn't a 'when computer starts' configuration)
route-pre-down is run (route-pre-down-prefix.sh and/or route-pre-down-suffix.sh will be run before or after the route-pre-down script).
down script is run (down-prefix.sh and/or down-suffix.sh will be run before or after the down script).
post-disconnect.sh will run after disconnecting

Notes:

A reconnect attempt does NOT trigger the pre-connect.sh/post-disconnect.sh sequence.
The order of execution of the up script and the connected.sh script is undefined.
The order of execution of the down script and the post-disconnect.sh script is undefined.
The order of execution of the down and up scripts and the reconnecting.sh script is undefined. (This applies when the OpenVPN --persist-tun option is not specified, see above.)

Environment Variables

Tunnelblick VPN Configuration scripts are run with a standard set of environment variables:

PATH=/usr/bin:/bin:/usr/sbin:/sbin SHELL=/bin/bash COMMAND_MODE=unix2003 USER=short name of the logged-in user, from NSUserName() LOGNAME=short name of the logged-in user, from NSUserName() HOME=path to the home directory of the logged-in user, from NSHomeDirectory() TMPDIR=path to the temporary directory for the logged-in user, from NSTemporaryDirectory() TUNNELBLICK_CONFIG_FOLDER=path to the folder containing the OpenVPN configuration file

(TUNNELBLICK_CONFIG_FOLDER is only provided for scripts for which it is available)

The environment for "password-…" scripts also includes the "TunnelblickConfigurationName" variable, which is set to the unlocalized name of the configuration (which may include folder names if the configuration is nested in one or more folders).

OpenVPN scripts have environment variables set up as specified in the OpenVPN 2.4 man page or the OpenVPN 2.3 man page.