New Updatable Configurations
FEATURES DESCRIBED ON THIS PAGE ARE AVAILABLE ONLY IN TUNNELBLICK 3.8.2beta03 AND HIGHER
A single Tunnelblick VPN Configuration can be easily updated automatically.
There are two separate methods for updating configurations:
The rest of this page describes the new method.
Using the new method, an update can be done by a "standard" user without a computer administrator's authorization if the "Require administrator authorization to install all configurations" checkbox on Tunnelblick's "Preferences" panel is not checked and the configuration complies with certain restrictions. See Standard Users Installing or Replacing Configurations for details about the restrictions. (The checkbox is checked by default and can only be changed by a computer administrator.)
Otherwise (if the checkbox is checked or if the new configuration does not comply with the restrictions), a computer administrator's authorization is required to update the configuration.
What the User Sees
Each time the user connects a VPN, Tunnelblick checks for an update to the configuration. If an update is available, the user is presented with a dialog asking what to do:
If the user selects Update, the update will be done without further user interaction if the checkbox described above is not checked and the update complies with the restrictions noted in Standard Users Installing or Replacing Configurations. Otherwise a computer administrator's authorization will be required to install the update.
How to Make a Configuration Updatable
A VPN service provider needs to do two things to make a configuration updatable:
The Info.plist file is a simple XML file containing keys and values. The specific entries required for updating are:
The Info.plist file must also contain the following entry:
The following keys in the Info.plist will be ignored during the update process: TBMinimumTunnelblickVersion, TBMaximumTunnelblickVersion, TBReplaceIdentical, TBSharePackage, and TBKeepExistingFilesList.
The Info.plist from the first (simplest) example Updatable.tblk (see Example, below) may be downloaded from https://tunnelblick.net/updatable-configs/config-1/Info.plist. (This is the Info.plist before the configuration is updated.)
The two files
Two files must be available on the Internet:
For example, if TBConfigurationUpdateURL is "https://example.com/updates/123", a GET request to "https://example.com/updates/123/version.txt" must return the version number of the update, and a GET request to "https://example.com/updates/123/config.tblk.zip" must return a .zip of a single Tunnelblick VPN Configuration (".tblk") of the new configuration.
version.txt must contain only the version number only. It must not include a line terminator.
config.tblk.zip must contain a zipped copy of a .tblk.
The .tblk from which config.tblk.zip is created may have any name, but must have the following folder and file structure:
whatever.tblk/ Contents/ Info.plist Resources/ config.ovpn
(Note: the "/" at the end of "Whatever.tblk/", "Contents/", and "Resources/" is used to indicate that they are folders. The "/" must not be included in the name of the folder.)
The "Contents" and "Resources" folders and the "Info.plist" and "config.ovpn" files must have those exact names, but the "whatever.tblk" may have any name as long as it has a ".tblk" extension. When the user's configuration is updated, the update will keep the name of the user's configuration; it will not change the name of the user's configuration to the name of the .tblk. (The user may have changed the name of the configuration and the supplier of updates would not know about such a change.) Similarly, if the configuration being updated is in a folder, the updated configuration will remain in that folder. (The user may have moved the configuration into a folder and the supplier of updates would not know about such a change.)
All other files associated with the configuration, such as key and certificate files and scripts, must be in the "Resources" folder.
If a file (such as
(That's because the "update" being done with a computer administrator's authorization is not really an "update", it is an "installation", and completely replaces the old configuration with the new one.)
So unless you know that the user either will or will not be using a computer administrator's authorization to update, you should be sure to include all files that are in the original .tblk in the updating .tblk.
Creating a .zip File
You can create a .zip of a .tblk in Finder by right-clicking (or Control-clicking) on the .tblk and selecting "Compress...". The name of the .zip file that will be created is the name of the .tblk with ".zip" added at the end. If your .tblk is not named "config.tblk", you must rename the .zip file to "config.tblk.zip" before uploading it to your webserver.
You can also create a .zip using the command line:
zip -r config.tblk.zip config-name.tblk
which will create config.tblk.zip containing a compressed copy of config-name.tblk, making it unnecessary to rename the .zip before uploading.
The Tunnelblick website hosts two examples:
Each sample contains:
To use the simplest example, download, expand, and install the Updatable.tblk at https://tunnelblick.net/updatable-configs/config-1/Updatable.tblk.zip. It will create a configuration named "Updatable".
To use the other example, download, expand, and install the Updatable.tblk at https://tunnelblick.net/updatable-configs/config-2/Updatable.tblk.zip. It will create a configuration named "DEF" inside a folder "SubfolderABC"; Tunnelblick will display the configuration name as "SubfolderABC/DEF".
Note: Both configurations are dummy configurations that will not connect to a VPN server either before or after it is updated. Tunnelblick will display an error message when you try to connect. The Tunnelblick log will show something similar to the following (the numbers at the start of each line will be different):
Contents of the OpenVPN log: 1577452373.883541 40 disabling NCP mode (--ncp-disable) because not in P2MP client or server mode 1577452373.883704 b000 Options error: --auth-user-pass requires --pull 1577452373.883748 1040 Use --help for more information.
When you attempt to connect Updatable (or SubfolderABC/DEF):
As described in the Introduction, the update may be done without further user interaction or may require authorization from a computer administrator.
While developing updatable configurations, it may help to enable additional Tunnelblick logging about the update process. To do that, issue the following command in Terminal:
defaults write net.tunnelblick.tunnelblick DB-UC -bool yes
to disable the extra logging, use
defaults delete net.tunnelblick.tunnelblick DB-UC