|
cPkgs
Tunnelblick VPN Configurations Details
IntroductionA Tunnelblick VPN Configuration (a "Configuration") is a folder with an extension of .tblk that contains information about one or more VPN configurations.
Tunnelblick VPN Configurations are available in Tunnelblick 3.1 and up. Configurations must be installed before they can be used. Install a Configuration by double-clicking it. (Tunnelblick must have been installed before the Configuration is double-clicked.) Creation and ModificationTunnelblick VPN Configurations are easily created and modified. See Creating and Installing a Tunnelblick VPN Configuration and Modifying a Tunnelblick VPN Configuration. File References in the OpenVPN Configuration FileWithin the OpenVPN configuration file itself, refer to other files, such as key or certificate files, without using a path or path prefix -- just use the name of the file. Example: Refer to the "xyz.key" file in the OpenVPN configuration file as "key xyz.key", not "key abc/xyz.key". InstallationInstallation of a Configuration can be done manually by double-clicking it or by dragging it to a Tunnelblick icon in Finder. (A Configuration cannot be dragged to the Tunnelblick icon in the Status Bar.) Installation can also be done automatically when Tunnelblick is installed from a disk image or certain other other volumes (see Automatic Installation). When a Configuration is installed, it's contents are copied and arranged in a specific way and the copy is secured by setting ownership and permissions on the copy's contents. An installed Configuration may be shared or private. Configurations to be shared are copied to /Library/Application Support/Tunnelblick/Shared, and Configurations to be kept private are copied to ~/Library/Application Support/Tunnelblick/Configurations. FormatTunnelblick Configurations are folders with an extension of ".tblk". The extension causes OS X 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 or right-click the package and select "Show Package Contents". Configurations may be nested one level deep. That is, a Configuration may contain within it other Configurations. When such a Configuration is installed, it installs all of the Configurations within it. The Configurations within it may not include Configurations, however -- only one level of included Configurations is allowed. The contents of a Tunnelblick VPN Configuration are arranged as follows after installation (files should not be arranged this way prior to installation: before installation all files should all just be at the top level of the .tblk, and the configuration file may have any name): sample.tblk/
Contents/
(Optional) Info.plist
Resources/
config.ovpn, containing OpenVPN configuration information
(Optional) up/down shell scripts
(Optional) Tunnelblick shell scripts
(Optional, deprecated shell scripts) up.sh, down.sh, nomonitor.up.sh, and/or nomonitor.down.sh
(Optional) key, certificate, and/or other shell script filesThe name of the Configuration (without ".tblk") is used as the display name of the configuration unless it conflicts with an existing name (see Name Conflicts During Installation). Info.plistInfo.plist is optional. If it exists, it must be an OS X property list file, with keys from the following table. The only mandatory key is TBPackageVersion; all others are optional.
PreferencesA Configuration's Info.plist may also optionally contain entries (strings, numbers, and booleans) with keys that start with "TBPreference". The entries are preferences for the configuration. If not already present (with any value), each entry will be copied to the user's regular preferences each time Tunnelblick loads the Configuration (when Tunnelblick is launched or the Configuration is installed). When the entries are copied, "TBPreference" 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. In a Deployed version of Tunnelblick, the forced-preferences in Deploy will override any Configuration-specified preferences. Up/Down Shell ScriptsIf the Configuration contains up.tunnelblick.sh, down.tunnelblick.sh, up.sh, down.sh, nomonitor.up.sh, and/or nomonitor.down.sh, those shell 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. Tunnelblick Shell ScriptsIf 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. Automatic InstallationWhen Tunnelblick itself is installed by double-clicking Tunnelblick.app on a disk image or other volume from which it cannot be used, all 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). CFBundleIdentifier ConflictsOn 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 InstallationIf 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 InstallationConfigurations are displayed from
PLEASE USE THE TUNNELBLICK DISCUSSION GROUP FOR COMMENTS OR QUESTIONS | |||||||||||||||||||||||||||||||||
|
|