Setting up Configurations
Getting VPN Service
Read Before You Post
On This Page
Tunnelblick VPN Configuration scripts
Other Scripts and Executable Files
Script Execution Order
Most Tunnelblick users do not need to use the information on this page; Tunnelblick uses scripts automatically.
Almost all scripts are run as root so they can make network configuration changes; thus caution is advised when modifying these scripts or using customized scripts.
Only the static-challenge-response.sh and dynamic-challenge-response.sh scripts 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 fromAppleScripts; 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.
- They are only available in Tunnelblick VPN Configurations (available in Tunnelblick 3.1beta06 or later).
- 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, which may or may not be the case for '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.
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.
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 ana Two-factor Authentication.
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:
- 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
- tls-verify is executed when we have a still untrusted remote peer.
- ipchange is executed after connection authentication, or remote IP address change.
- client-connect is executed in server mode immediately after client authentication.
- route-up is executed after connection authentication, either immediately after, or some number of seconds after as defined by the
- route-pre-down is executed right before the routes are removed.
- client-disconnect is executed in server mode on client instance shutdown.
- down is executed after TCP/UDP and TUN/TAP close. (Timing depends on
- learn-address is executed in server mode whenever an IPv4 address/route or MAC address is added to OpenVPN's internal routing table.
- auth-user-pass-verify is executed in server mode on new client connections, when the client is still untrusted.
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
--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.
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)
- up script will run near the end of the connection process
- 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)
- down script is run
- post-disconnect.sh will run after disconnecting
- 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.)
Tunnelblick VPN Configuration scripts are run with a standard set of environment variables:
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)
OpenVPN scripts have environment variables set up as specified in the OpenVPN 2.4 man page or the OpenVPN 2.3 man page.