This document describes how to create a deployable version of Tunnelblick and was last modified 2009-12-19. It reflects the behavior of Tunnelblick built from the r313 version of the Tunnelblick source code.

Tunnelblick is an OS X Graphical User Interface (GUI) for the OpenVPN free and open-source program, which maintains VPN "tunnels". It provides easy-to-use control of OpenVPN server and/or client connections. It is written in Cocoa and runs on OS X Tiger (10.4), Leopard (10.5), and Snow Leopard (10.6). It comes as a ready to use Universal application with all necessary binaries and drivers, including OpenVPN and tun/tap. Tunnelblick is free software licensed under the GNU General Public License (GPL) Version 2.

For more information, including wikis and a discussion group, see the Tunnelblick home page.

This document may be obsolete! The latest versions of this document and related documents including release notes, FAQ, and instructions for using and building Tunnelblick from the source code may be found in the Tunnelblick Wiki.

This document contains the following sections:

• WHAT IS A DEPLOYABLE VERSION?
• HOW IT WORKS
• WHAT ABOUT AUTOMATIC UPDATES?
• FORCED PREFERENCES EXCEPTIONS
• UP AND DOWN SCRIPTS
• USING openvpn-down-root.so
• WHAT IS NEEDED TO MAKE A DEPLOYABLE VERSION
• HOW TO MAKE A DEPLOYABLE VERSION
• HOW TO USE A DEPLOYED VERSION
• CREATING A .ZIP FILE FOR DEPLOYMENT
• CREATING A .DMG FILE FOR DEPLOYMENT
• DOCUMENT HISTORY

WHAT IS A DEPLOYABLE VERSION?

A deployable version of Tunnelblick is a customized version of Tunnelblick.app which may include everything necessary to install and run Tunnelblick and connect to one or more VPNs. In particular, it may include one or more OpenVPN configuration files, and, usually, certificate and key files for authentication. It can also include shell scripts and text that will appear in Tunnelblick's "about" window, and can specify user preferences that are forced to particular values and are read-only.

HOW IT WORKS

• Each time Tunnelblick starts:
1. If there is no Tunnelblick.app/Contents/Resources/Deploy folder and there is a backup folder for it, the Deploy folder is restored from the backup without any user intervention
2. If not already the owner, "root" is made the owner of everything in Tunnelblick.app, including the Deploy folder and its contents
3. If not already set, the permissions of all items within Tunnelblick.app are set to "644" (root can read/write, everyone else can read), except
• The permissions of openvpnstart are set to 4111
• The permissions of the standard up/down scripts, installer, leasewatch, and openvpn are set to 744
• The permissions of the following files in Deploy are given different permissions:
• .cer, .crt, .der, .key, .p12, .p7b, .p7c, .pem, and .pfx files are given permissions of "600" (root can read/write, nobody else can read)
• .sh files are given permissions of "744" (root can read/write/execute, everyone else can read)
4. If any ownerships or permissions were changed, or if the Deploy folder has just been restored, a new backup of the Deploy folder is made. The backup is owned by root and has the same permissions as the original items in Deploy (as modified in 3, above).
• If there is a Deploy folder and it contains one or more .conf or .ovpn files, Tunnelblick uses it, instead of ~/Library/Application Support/Tunnelblick/Configurations, for configuration files (and, often, keys, certificates, and shell scripts, but whether the same folder is used for them depends on what is in the configuration file). When a connection is being attempted, the entry that Tunnelblick puts in the log will contain "from Deploy" if the Deploy folder is being used for configuration files.
• If the Deploy folder contains only *.conf, *.ovpn, *.up.sh, *.down.sh, and forced-preferences.plist files, then the ~/Library/Application Support/Tunnelblick/Configurations folder will be used as the target of the OpenVPN --cd option, which means that files in~/Library/Application Support/Tunnelblick/Configurations may be specified in the configuration file without path information -- e.g., "key xxx.key".
• If the Deploy folder contains any other files, then the Deploy folder will be used as the target of the OpenVPN --cd option, which means that files in Deploy may be specified in the configuration file without path information -- e.g., "key xxx.key".
• If the file Tunnelblick.app/Contents/Resources/about.html exists, its contents will replace the link to "http://code.google.com/p/tunnelblick" in Tunnelblick's "about" window. The content of about.html will be prefixed by '<html><body><center><div style="font-family: Verdana, Arial, Helvetica, sans-serif; font-size: 10px">', and followed by '<br><br>Based on Tunnelblick, free software available at <a href=\"http://code.google.com/p/tunnelblick\">http://code.google.com/p/tunnelblick</a></div></center><body></html>'. Note that there is only space for a couple of lines of text without causing scrollbars to be necessary.
• Whether or not the Deploy folder is being used for configuration files, if the file Tunnelblick.app/Contents/Resources/Deploy/forced-preferences.plist exists, the preferences contained in it override any preferences the user has set. Since this file is read-only, the user cannot change these preferences, and corresponding preferences in Tunnelblick's preferences stored in ~/Library/Preferences will be ignored. The user's preferences are not modified. Also see "FORCED PREFERENCES EXCEPTIONS".

Backups of the Deploy folder are created in /Library/Application Support/Tunnelblick/Backup/A/B/C/D/E.../TunnelblickBackup, where "/A/B/C/D/E..." is the absolute path to Tunnelbick.app itself. For example, if Tunnelblick.app is located in /Applications, the Deploy backup would be stored in /Library/Application Support/Tunnelblick/Backup/Applications/TunnelblickBackup. This allows each copy of Tunnelblick on a computer to have its own backup. Up to three backups are kept for each copy of Tunnelblick: the current and previous Deploy, and Deploy at the time Tunnelblick was first run from it's current location.

If Tunnelblick.app is moved, a new backup will be created for the new location the first time Tunnelblick.app is run in the new location. The old backup will continue to exist, however, this is not in itself a security risk because moving Tunnelblick.app (after it is first run and a backup of Deploy has been made) requires authorization by an administrator. It is suggested that any such move be followed by deletion of the backup, which also requires an administrator. Otherwise a fresh copy of Tunnelblick in the old position in the file hierarchy could be used to connect to the VPN because its Deploy folder could be "recovered" from the backup the first time it is run.

If Tunnelblick.app is renamed (which, depending on where it is stored, may not require an administrator's username/password), the backup mechanism still works normally. However, note that the updates will fail if the app has been renamed.

If two copies of Tunnelblick.app exist within the same folder in the filesystem hierarchy (with different names), they will use the same backup. This could lead to problems if one uses Deploy and the other doesn't, or if the contents of the Deploy folders are not identical. One way to have multiple Tunnelblicks in one folder without this problem is to locate the Tunnelblick.apps in different folders, but put aliases to both of them in the same folder that is visible to the user. Multiple copies of Tunnelblick.app cannot be placed in the same folder without an administrator doing it, so this should not be a security risk.

WHAT ABOUT AUTOMATIC UPDATES?

A version of Tunnelblick with a Deploy folder will work with Tunnelblick's standard automatic update process. The automatic update replaces Tunnelblick.app with a new copy without the Deploy folder; however, when the updated program is first run, the the Deploy folder will be restored from the backup copy, and will then be used normally. Note: "about.html" is not included in standard Tunnelblick updates, so it will be lost when there is a standard update because it is not located in the Deploy folder.

FORCED PREFERENCES EXCEPTIONS

There are two exceptions to the way preferences in "forced-preferences.plist" are treated:

• All forced preferences with a key beginning with "SU" are ignored. These preferences are used privately by Sparkle Updater, and should not be used otherwise. Tunnelblick will soon provide preferences that mirror most of Sparkle's preferences, and these will be able to be forced.
• The config-name-keychainHasPrivateKey and config-name-keychainHasUsernameAndPassword preferences -- regardless of value -- prevent the user from storing or using passphrases, usernames, or passwords for that configuration in the Keychain. Dialog boxes will not include a "Save to Keychain" checkbox, and any passphrases, usernames, and passwords in the Keychain will be ignored.

UP AND DOWN SCRIPTS

If "Set nameserver" is checked, Tunnelblick.app starts OpenVPN with the "--up" and "--down" options specifying scripts to be run after the tunnel is established and before it is torn down. The standard scripts are Resources/client.up.osx.sh and Resources/client.down.osx.sh.

If "Monitor connection" is not checked, however, and Resources/Deploy/config-name.up.sh or .down.sh exist, each will be used instead of the corresponding standard script.

If "Monitor connection" is checked, then Resources/Deploy/config-name.nomonitor.up and/or down.sh will be used if each exists, otherwise the standard Resources/client.nomonitor.up.osx.sh and Resources/client.nomonitor.down.osx.sh scripts will be used if they exist, otherwise the standard up and down scripts will be used.

USING openvpn-down-root.so

Using a Deployed version of Tunnelblick allows you to use relative path references to openvpn-down-root.so in a configuration file instead of the absolute path references which were previously required. That means that moving Tunnelblick.app to another location does not cause errors.

If a "config-name-useDownRootPlugin" preference exists (forced or otherwise), Tunnelblick will use the openvpn-down-root.so plugin. The down-script that it references will be the script described above.

WHAT IS NEEDED TO MAKE A DEPLOYABLE VERSION

To make a deployable version of Tunnelblick, you need whatever is required to connect to your VPN.

To be more specific specific, you need:

• A copy of the Tunnelblick .dmg file with Tunnelblick version 3.0b22 or later. The latest version may be downloaded from the Tunnelblick website.
• One or more OpenVPN configuration files, with extensions of ".ovpn" or ".conf".
• Certificate and key files for authentication.
• Optional: shell script files, with extension ".sh", if you do not use Tunnelblick's "Set nameserver" feature. If you have shell files, they must have an extension of "sh"; otherwise they will not have execute permissions.
• Optional: "about.html" file, containing text that will be displayed in Tunnelblick's "about" window.
• Optional: "forced-preferences.plist" file, containing user preferences that you wish to override.
• Optional: other files that you want your configuration file or scripts to be able to use.

HOW TO MAKE A DEPLOYABLE VERSION

1. Create a new folder on your Desktop and rename it "Deploy"
2. Copy the configuration files, any certificate and key files and shell scripts, and any of the optional files you wish to use, into the "Deploy" folder
3. Open the Tunnelblick .dmg file. A new Finder window will appear with (among other things) Tunnelblick.app
4. Drag Tunnelblick.app to the Desktop (or some other place you will work with it). This is the copy you will modify to create your deployable version.
5. Right-click on Tunnelblick.app, and click "Show Package Contents". A new Finder window will appear with a folder "Contents".
6. Double-click on "Contents". The window will change to show several items. One of them is a folder, "Resources"
7. Command-drag your "Deploy" folder and drop it onto "Resources" to copy the folder into "Resources"
8. If you have one, copy your "about.html" file into "Resources"
9. Close the window that contains "Resources"

That's it! You are done! Tunnelblick.app has your new version of Tunnelblick with a "Deploy" folder containing everything that Tunnelblick needs for connection to your VPN.

However, DO NOT RUN THIS COPY. Instead, make a copy of it and use the copy. (When Tunnelblick is first run it makes changes to the ownership and permissions of parts of the application. That makes it inconvenient to copy, move, or modify the application after it has been run without entering administrator credentials, so keep a copy that has never been run.)

HOW TO USE A DEPLOYED VERSION

Using a deployed version of Tunnelblick is the same as using a non-deployed version, except:

• You will not be asked for administrator credentials the first time you first connect to a VPN. (Because ownership and permissions on the configuration file(s) was secured the first time the deployed version of Tunnelblick was run on the computer.
• Anyone with access to a deployed version of Tunnelblick.app can connect to its VPN(s). For example, if a deployed version of Tunnelblick.app is placed in /Applications, it can be accessed by any user of the computer, without requiring administrator credentials to set up secure configuration files in ~/Library/Application Support/Tunnelblick/Configurations -- because ~/Library/Application Support/Tunnelblick/Configurations is not used and the configuration files are shared by all users with access to the application.

CREATING A .ZIP FILE FOR DEPLOYMENT

To create a .zip file of your new version of Tunnelblick:

1. Right-click on your new version of Tunnelblick, and click "Compress Tunnelblick.app"

CREATING A .DMG FILE FOR DEPLOYMENT

1. Create a new folder on your Desktop and rename it to "Tunnelblick"
2. Copy whatever you want to include in the .dmg file into the folder, including your new version of Tunnelblick.app
3. Open /Applications/Utilities/Disk Utility
4. Chose "File", then "New", then "Disk Image from Folder"
5. Select the folder you set up in steps 1. and 2. and click the "Image" button
6. Type a name for your .dmg file, and select a location in which to store it
7. Select "Image Format: compressed", and "Encryption: none"
8. Click "Save"

Within a few moments, your .dmg file will be created.

DOCUMENT HISTORY

• 2009-10-29 (r227, r228, r230)
• Initial creation of this document.
• 2009-10-31 (r238)
• Miscellaneous clarifications
• Added "USING openvpn-down-root.so" section.
• 2009-11-17 (r281)
• Clarified that a Deployable version is not required to contain configuration files.
• Changed to reflect that "from Deploy" appears in the OpenVPN Log when a connection is attempted, rather than at the start of the log.
• Changed to add comments about what happens when Tunnelblick.app is renamed and when two copies of Tunnelblick.app are in the same folder.
• Changed to indicate that it is possible to force the "SUEnableAutomaticChecks" preference.
• Added "UP AND DOWN SCRIPTS" section.
• Added explanation of the "config-name-useDownRootPlugin" preference.
• 2009-11-17 (r285)
• Specified behavior when only *.ovpn, *.conf, *.up.sh, *.down.sh, and forced-preferences.plist files are in Deploy folder.
• 2009-11-26 (r290)
• Clarified how the OpenVPN --cd option is set.
• Fixed error describing permissions of installer.
• Fixed several typos.
• 2009-12-03 (r295)
• Clarified that this document describes behavior of the current source code.
• Removed note saying that "SUEnableAutomaticChecks" can be forced.
• Clarified that Tunnelblick preferences that mirror Sparkle's preferences are not committed yet.
• 2009-12-19 (r314)
• Updated to reflect move from ~/Library/openvpn to ~/Library/Application Support/Tunnelblick/Configurations.
• Rewrote "UP AND DOWN SCRIPTS" section.
• Listed additional extensions that get permissions of "600".