Tunnelblick VPN Configurations Details
On This Page
A Tunnelblick VPN Configuration (a "Configuration") is a folder with an extension of .tblk that contains information about one or more VPN configurations.
Configurations are available in Tunnelblick 3.1 and up. Some features of Configurations described in this document may only be available on Tunnelblick 3.4beta30 and higher.
Configurations must be installed before they can be used. Install a Configuration by dragging it to the Tunnelblick icon in the menu bar. (The Tunnelblick application must have been installed before the Configuration is installed.)
Creation and Modification
A Configuration is installed by dropping it on the Tunnelblick icon in the menu bar. A configuration can be installed automatically when Tunnelblick is installed from a disk image or a folder expanded from a .zip file (see Automatic Installation).
If there is only one OpenVPN configuration file inside a .tblk, a single Configuration will be installed and will have the name of the .tblk — the name of the configuration file will be ignored.
If there is more than one OpenVPN configuration file inside a .tblk, a Configuration will be installed for each configuration file, and will have the name of the configuration file.
When a Configuration is installed, it's contents are copied and arranged in a special way and the copy is secured by setting the ownership and permissions on the copy's contents.
Unless specified otherwise in an Info.plist, when a Configuration is installed the user will be asked whether the Configuration is to be shared or private (for only that user). Configurations to be shared are copied to
When Tunnelblick is installed by Control-clicking a Tunnelblick.app that is not in /Applications and clicking "Open", all .tblk Configurations in the "auto-install" and ".auto-install" folders that are in the same folder that contains the Tunnelblick.app being installed are installed (subject to CFBundleIdentifier Conflicts and Name Conflicts During Installation).
The "auto-install" and ".auto-install" folders can also contain a file named "preferences.plist". It may contain a "set-only-if-not-present" key and/or a "always-set" key. The value for each key should be a dictionary containing preferences to be set under the specified conditions.
Thus, one can construct a disk image (or a .zipped folder) which contains Tunnelblick.app and an "auto-install" folder containing configurations and preferences to be installed along with Tunnelblick.
"Nested" Configurations make it easy to distribute many configurations in a single file.
Configurations may be nested one level deep. That is, a Configuration may contain within it other Configurations (and may also contain OpenVPN configuration files that are not in a Configuration). When such a Configuration is installed, everything within it is installed. The Configurations within a Configuration may not themselves include Configurations, however — only one level of included Configurations is allowed.
If configurations are in subfolders, the structure of the subfolders will be replicated when the configurations are installed.
Tunnelblick Configurations are folders with an extension of ".tblk". The extension causes macOS to treat the folder as a "package" — in most cases it is treated as if it were a single file. To look at the contents of a package (i.e. inside what was the folder), Control-click the package and select "Show Package Contents".
Before installation, a Tunnelblick VPN Configuration can contain files and folders including:
After installation, the contents of a Tunnelblick VPN Configuration are arranged as follows. Before installation all files can be arranged this way, or all files can be at the top level of the .tblk (that is, without the "Contents/Resources" structure).
Info.plist is optional. If it exists, it must be a macOS property list file, with keys from the following table. The only mandatory key is TBPackageVersion; all others are optional.
A Configuration's Info.plist may also optionally contain entries (strings, numbers, and booleans) with keys that start with "TBPreference" or "TBAlwaysSetPreference". The entries are preferences for the configuration. Each entry will be copied to the user's regular preferences each time Tunnelblick loads or uses the Configuration (when Tunnelblick is launched or the Configuration is installed or connected). "TBPreference" items are copied only if the preference is not already set, so they are for initial settings that a user is allowed to override. "TBAlwaysSetPreference" items always are copied, so the user is, in effect, not allowed to override them. When the entries are copied, "TBPreference" or "TBAlwaysSetPreference"is replaced with the display name of the Configuration. Note that the "autoConnect" option triggers a connection when Tunnelblick is started, so a configuration with "TBPreferenceautoConnect" is not connected automatically when it is installed, but is connected automatically the next time Tunnelblick is launched. Note: "TBAlwaysSetPreference" is only available in Tunnelblick 3.3beta10 and later.
In a Deployed version of Tunnelblick, the forced-preferences in Deploy will override any Configuration-specified preferences.
If the Configuration contains up.tunnelblick.sh, down.tunnelblick.sh, up.sh, down.sh, nomonitor.up.sh, and/or nomonitor.down.sh, those scripts will be used instead of Tunnelblick's standard scripts, or scripts in Deploy, when connecting with the Configuration and "Set nameserver" is selected for the Configuration's configuration.
For backward compatibility, scripts other than up.tunnelblick.sh and down.tunnelblick.sh will be used if they exist.
In a Deployed version of Tunnelblick, a Configuration's up/down scripts will override the corresponding scripts in Deploy.
If the Configuration includes pre-connect.sh, post-tun-tap-load.sh, connected.sh, reconnecting.sh, post-disconnect.sh scripts, they will be executed (as root) at the corresponding point in the connection process. This allows manipulation of kexts and/or the network configuration and user notification of events. (If the scripts load special kexts, you can use the "-doNotLoadTapKext" and "-doNotLoadTunKext" preferences to cause Tunnelblick to not try to load its own kexts.) post-tun-tap-load.sh, connected.sh, and reconnecting.sh are available in Tunnelblick 3.2beta02 and later only. See Using Scripts for more details.
On automatic or manual installation of a Configuration, if a Configuration with an identical CFBundleIdentifier is already installed:
When an existing Configuration is replaced, the new copy takes the display name of the existing version, regardless of the name of the new Configuration. Thus, the new version will inherit the existing version's preferences and Keychain items.
Name Conflicts During Installation
If the display name of a Configuration is the same as the name of an existing .ovpn or .conf file or an existing Configuration that has a different CFBundleIdentifier, the user will be asked to rename the Configuration or cancel the installation.
Name Conflicts After Installation
Configurations are displayed from
in that order. If a display name matches an earlier display name, the later configuration will be ignored and only the earlier display name will be displayed, making only the earlier configuration available.
Example Script to Create .tblks with IP Address Checking Disabled
Below is a bash script that creates .tblks from OpenVPN configuration files. Each .tblk includes an Info.plist that disables IP address checking. (The script can be modified to set different preferences for the configuration so IP address checking is enabled, or to enable or disable some other feature.)
The .tblks can be installed (as usual) by dragging/dropping them onto the Tunnelblick icon in the menu bar. They may be dragged/dropped individually or as a group.
Or the .tblks can be copied into a folder, and the folder renamed with an extension of .tblk. That (outer) .tblk can be compressed and sent to users as a single .zip file. After decompressing the .zip file, users could then drag/drop the (outer) .tblk onto the Tunnelblick icon in the menu bar to install all of the configurations at once.
(To create a subfolder structure to group configurations together, arrange the inner .tblks in folders as desired before renaming the outer folder to have a .tblk extension.)
Note: the script looks long and complicated but almost all of it is dealing with the command line arguments. The part of the script that actually creates the .tblk are these three commands near the end, which create the .tblk, copy the OpenVPN file, and create the Info.plist.