New Updatable Configurations

FEATURES DESCRIBED ON THIS PAGE ARE AVAILABLE ONLY IN TUNNELBLICK 3.8.2beta03 AND HIGHER

On This Page
    Introduction
    What the User Sees
    How to Make a Configuration Updatable
        The Info.plist
        The two files
        version.txt
        config.tblk.zip
        Creating a .zip File
    Examples
    Debugging

Introduction

A single Tunnelblick VPN Configuration can be easily updated automatically.

There are two separate methods for updating configurations:

• The "old" method, which is powerful and can update multiple configurations at a time but is complex to set up and administer; and
• The "new" method, which can only update a single configuration at a time but is simple to set up and administer.

The rest of this page describes the new method.
The old method is described here.

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:

• Update the configuration and connect to the VPN using the updated configuration; or
• Skip the update and connect the VPN using the existing configuration; or
• Cancel connecting to the VPN.

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:

1. Include an Info.plist file in the configuration with entries to identify the configuration's version number and a URL for obtaining update information; and
2. Provide Internet access to two files.

The Info.plist

The Info.plist file is a simple XML file containing keys and values. The specific entries required for updating are:

• CFBundleVersion: the version number of the configuration. It must consist of digits and zero, one, or two periods, e.g. "104", "1.26", "1.33.6". It must not include a line terminator.
• TBConfigurationUpdateURL: an https: URL used as the base URL for information about updates, e.g. "https://tunnelblick.net/updatable-configs/config-1". It must not include a trailing slash or line terminator.

The Info.plist file must also contain the following entry:

• TBPackageVersion: a string containing "1".

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:

• URL/version.txt
• URL/config.tblk.zip

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

version.txt must contain only the version number. It must not include a line terminator.

config.tblk.zip

config.tblk.zip must contain a zipped copy of a .tblk.

The .tblk from which config.tblk.zip is created can have any name; the name will not be used because the existing name for the configuration (which may have been modified by the user) will be preserved. It 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. (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 or changed the name of a folder the configuration is already in 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 user.key) exists in the .tblk to be updated but not in the new, updating .tblk, the result will be different depending on how the update is being done:

• If the update is being done without a computer administrator's authorization, the final, updated .tblk will contain the original user.key; but
• If the update is done with a computer administrator's authorization, the final, updated .tblk will not contain the original user.key file.

(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.)

Creating a .zip File

You can create config.tblk.zip in Finder by right-clicking (or Control-clicking) on the .tblk and selecting "Compress...", then renaming the file to "config.tblk.zip". (The name of the .zip file that will be created is the name of the .tblk with ".zip" added at the end, so unless it is 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 whatever.tblk

which will create config.tblk.zip containing a compressed copy of whatever.tblk, making it unnecessary to rename the .zip before uploading.

Examples

The Tunnelblick website hosts two examples:

• The simplest possible example; and
• An slightly more complicated example with the configuration enclosed in a folder.

Each sample contains:

• A .zip of an updatable configuration, version 1.1; and
• The Info.plist from that updatable configuration (to show the proper structure of an Info.plist); and
• The two files with update information for updating to version 1.2.

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:

1. Tunnelblick will fetch the update version from https://tunnelblick.net/updatable-configs/config-1/version.txt (or …config-2.version.txt);
2. Tunnelblick will compare that to the version in the installed configuration and detect that a newer version is available;
3. Tunnelblick will ask the user if the user wants to update the configuration, skip the update, or cancel the connection attempt; and
4. If the user elects to update, Tunnelblick will download a .zip of the updated configuration from https://tunnelblick.net/updatable-configs/config-1/config.tblk.zip (or …config-2.config.tblk.zip), expand the .zip, and install the update.

As described earlier, the update may be done without further user interaction or may require authorization from a computer administrator.

Debugging

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