Automatically Install Configurations and Forced Preferences

On This Page
    Creating a folder hierarchy
    Sample forced-preferences.plist file
    Creating a signed and notarized disk image

Tunnelblick can install Tunnelblick VPN configurations and forced preferences (preferences that cannot be modified by a standard user) at the same time that Tunnelblick itself is installed, using the same computer administrator authorization.

This will happen when

• Tunnelblick is installed interactively (not via the command line); and
• The configurations and/or preferences are located in a folder named "auto-install" or ".auto-install" in the same location as the Tunnelblick application that is being installed; and
• The Tunnelblick.app and "auto-install" or ".auto-install" folder are in a signed, notarized disk image.

To create such a signed, notarized disk image:

1. Create a folder with a signed copy of Tunnelblick;
2. Add a subfolder named "auto-install" or ".auto-install" that contains zero or more Tunnelblick VPN configurations^*;
3. If desired, add a file named "forced-preferences.plist" containing the preferences to the subfolder^**;
4. Create a disk image file (.dmg) from the folder;
5. Sign the disk image file;
6. Notarize the disk image file; and
7. Distribute the signed disk image file.

^* Configurations can be contained within a folder hierarchy; see Creating a folder hierarchy, below.

^** The "forced-preferences.plist" file must be a macOS property list file. See Sample forced-preferences.plist file, below.

Creating a folder hierarchy

To have configurations appear within a folder hierarchy, create a "container" .tblk and put the folders including the configurations inside the "Contents/Resources" folder of that .tblk, as follows:

    auto-install
        forced-preferences.plist
        FOO.tblk
            Contents
                Resources
                    CONFIGURATION-ONE.tblk
                    folderA
                        CONFIGURATION-TWO.tblk
                        folderB
                            CONFIGURATION-THREE.tblk

Then the user will see

    CONFIGURATION-ONE
    FolderA
        CONFIGURATION-TWO
        FolderB
            CONFIGURATION-THREE

Note that both "forced-preferences.plist" and the FOO.tblk are optional. (But if you're not using either one, you're not installing anything!)

Sample forced-preferences.plist file

The following sample file:

• Sets the "updateFeedURL" preference to "https://example.com/updates.rss"
• Sets the "-notOKToCheckThatIPAddressDidNotChangeAfterConnection" preference for all configurations to "true" (so it is not OK to check for IP address changes).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>TBPackageVersion</key><string>1</string>
    <key>updateFeedURL</key>
         <string>https://example.com/updates.rss</string>
    <key>*-notOKToCheckThatIPAddressDidNotChangeAfterConnection</key>
         <true/>
</dict>
</plist>

Creating a signed and notarized disk image

To help you do steps 4 - 6, here is a pseudocode script that performs steps 3-5. It omits important error checking and output parsing, so you should do the commands interactively, adjusting as needed to the output of the commands, or in a script which does error checking and output parsing and polls to check notarization status or waits until the notarization is complete.

# Pseudocode script to create, sign, and notarize a disk image file from a folder
#
# For more information, see https://developer.apple.com/developer-id.
#
# What you need:
#
# * Apple Developer account
# * Apple signing identity stored in your keychain
# * Apple ID (usually looks like an email address)
# * app password for that Apple ID, for notarization.
#     Create it on the Apple Developer site and
#     store it in your Keychain under the name "altool_password".
#
# * macOS Mojave or higher
# * Xcode 10.3 or higher
# * Xcode tools installed
#
# A folder with a copy of the Tunnelblick application and an
# "auto-install" folder of configurations
#
#
# These are the "variables" that will be used in the pseudocode below:
#
# FOLDER_PATH="path to the folder from which the .dmg is to be created.
#              This will be the name of the disk image and the volume"
# DMG_PATH="path to the .dmg to be created, signed and notarized;
#              this should end in '.dmg'"
# NOTARIZATION_USERNAME="Apple ID username (usually an email address)"
# NOTARIZATION_PASSWORD="altool_password, or whatever other name you used"
# SIGNING_IDENTITY="signing identity; whatever name it has
#              in your Keychain"



#####
# 1 #
#####
# Create a .dmg from the folder
rm -f "$DMG_PATH"
hdiutil create -noscrub -srcfolder "$FOLDER_PATH" "DMG_PATH"

#####
# 2 #
#####
# Sign the .dmg
codesign --verbose              \
         --timestamp            \
         --options runtime      \
         --deep                 \
         -s "$SIGNING_IDENTITY" \
         "$DMG_PATH"



#####
# 3 #
#####
# Upload the .dmg for notarization
xcrun altool --notarize-app                                 \
             --primary-bundle-id "$bundle_id"               \
             --username          "$NOTARIZATION_USERNAME"   \
             --password          "$NOTARIZATION_PASSWORD"   \
             --file              "$DMG_PATH"



#####
# 4 #
#####
# Wait for the upload to complete, examine the output
# for the UUID, which should appear as "RequestUUID"
UUID="UUID-from-the-upload-output"



#####
# 5 #
#####
# (OPTIONAL) Get information about the notarization
xcrun altool --notarization-info "$UUID"                    \
             --username          "$NOTARIZATION_USERNAME"   \
             --password          "@keychain:$NOTARIZATION_PASSWORD"

#####
# 6 #
#####
# Wait until the notarization is successful,
# then staple the notarization to the .dmg.
# (You'll be notified by an email from Apple
# when the notarization is finished.)
xcrun stapler staple -v "$DMG_PATH"