Installing and Deleting VPN Configurations

Installing Configurations

The information needed to connect to a VPN is stored in a VPN configuration. There are two types:

• OpenVPN configuration files, which are UTF-8 files with an extension of ".ovpn"; and
• Tunnelblick VPN Configurations, which are a macOS filesystem "packages" with an extension of ".tblk". The packages contain an OpenVPN configuration file along with other information used by Tunnelblick. Finder treats packages as if they were files, but to programs and scripts they are folders containing files and subfolders.

Tunnelblick requires all configurations to be installed before they can be used. The installation process involves converting the configuration into a specially structured Tunnelblick VPN Configuration and copying it to a special location on your computer that is maintained and secured by Tunnelblick. You can then delete the original .tblk you created, move it somewhere convenient as a backup, or copy or move it to another computer and install it on that computer.

To maintain configurations securely, Tunnelblick maintains a complex system of ownership and permissions for configurations. Directly manipulating these files and folders is discouraged. Instead, Tunnelblick itself should be used to install and delete them.

There are several ways to install VPN configurations:

A. Most methods require interaction with the user and/or specific authorization by a computer administrator:

1. Drag one or more OpenVPN configuration files and/or Tunnelblick VPN Configurations and drop them on the Tunnelblick icon in the menu bar.
2. Execute a Terminal command to simulate the drag-and-drop described above.
3. Execute an AppleScript command to simulate the drag-and-drop described above with little or no user interaction. This can only be used to install private configurations and will not interact with the user to install safe configurations if that has been authorized by a computer administrator. If any configurations are not safe, or if installation of safe configurations has not been authorized, authorization from a computer administrator will be obtained interactively.
4. Install a Tunnelblick VPN Configuration when Tunnelblick is installed.

B. Another method uses Tunnelblick's "install" command to install a Tunnelblick VPN Configuration from the command line without interaction. The command must be run as root.

1. Drag and Drop

This is a common way to install a VPN configuration. Using Finder, the user drags and drops one or more OpenVPN configuration files (".ovpn" files) or Tunnelblick VPN Configurations (".tblk" packages) onto the Tunnelblick icon in the menu bar.

• If there is not existing VPN configurations with the same name, the user will be asked if the configurations are to be shared or private.
• macOS asks for a computer administrator's authorization to install the configurations.

2. Simulate Drag and Drop in Terminal

The drag and drop described above can be simulated with the following command:

     open   -a   /Applications/Tunnelblick.app   PATH...

where PATH... is the path or paths to the .ovpn files or .tblk configurations.

3. Simulate Drag and Drop with AppleScript

The drag and drop described above can be simulated with the following Tunnelblick AppleScript command:

     install private configurations { PATH... }

where PATH... is the path or paths to the .ovpn files or .tblk configurations.

4. Install a Tunnelblick VPN Configuration when Tunnelblick is installed

Tunnelblick VPN Configurations can be installed at the same time Tunnelblick is installed, without requiring additional user interaction. See Automatically Install Configurations and Forced Preferences.

Install a Tunnelblick VPN Configuration from the Command Line without interaction

These commands are available in Tunnelblick 4.0.0beta06 and higher.

Tunnelblick VPN Configurations can be installed without user interaction with a command which must be executed as root.

This method cannot be used to install an OpenVPN configuration file, but you can easily create a Tunnelblick VPN Configuration from an OpenVPN configuration file; see Creating and Installing a Tunnelblick VPN Configuration.

To install a private Tunnelblick VPN Configuration, execute the following command:

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x6001 USERNAME PATH-TO-.TBLK [SUBFOLDER]

To install a shared Tunnelblick VPN Configuration, execute the following command:

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x7001 PATH-TO-.TBLK [SUBFOLDER]

where

• USERNAME is the short username for the user for which the configuration is to be installed
• PATH-TO-.TBLK is the path to the Tunnelblick VPN Configuration you wish to install
• [SUBFOLDER] is an optional folder in which the configuration is to be installed

For example, after creating a Tunnelblick VPN Configuration at ~/Desktop/Office.tblk, you can install it as a shared configuration named 'Office' with

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x7001 ~/Desktop/Office.tblk

Or you can install it named 'Client-1/Office' with

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x7001 ~/Desktop/Office.tblk Client-1

Or you can install it as a private configuration named 'Client-1/Office' for user 'janedoe' with

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x6001 janedoe ~/Desktop/Office.tblk Client-1

The first argument to installer is a number containing bit fields that control its operation. In the examples above, the 6 or 7 indicate the operation (install private or install shared) and the 1 instructs installer to clear its log before operating. For more information about what the bit fields do, see the INSTALLER_ variables defined in Tunnelblick's source code file tunnelblick/defines.h.

Deleting Configurations

There are two ways to delete VPN configurations:

1. Interactively from Tunnelblick's "VPN Details" window.
2. From the command line.

Deleting Configurations Interactively

To delete configurations interactively:

1. Select the configuration or configurations in the list on the left side of the "Configurations" panel of Tunnelblick's "VPN Details" window.
2. Click the little minus-sign button ("-") at the bottom of the list .

macOS will ask for a computer administrator's authorization to delete the configuration(s).

Deleting configurations from the Command Line

To delete a configuration from the command line without any user interaction, run the following command:

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x2001 PATH

where PATH is the path to the configuration. That path should either:

• For a "private" configuration, ~/Library/Application Support/Tunnelblick/Configurations/NAME
• For a "shared" configuration, /Library/Application Support/Tunnelblick/Shared/NAME

and NAME is the name of the configuration, with ".tblk" added to the end of the name.

For example, to delete a private configuration named "Office", execute the following command:

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x2001 ~/Library/Application\ Support/Tunnelblick/Configurations/Office.tblk

Subfolders

When configurations are in subfolders, include the subfolders in the path to the configuration.

For example, if a configuration to be deleted is a private configuration named "Office" which is in the "MegaCorp" subfolder of the "Clients" subfolder, use

sudo /Applications/Tunnelblick.app/Contents/Resources/installer 0x2001 ~/Library/Application\ Support/Tunnelblick/Configurations/Clients/MegaCorp/Office.tblk

The first argument to installer is a number containing bit fields that control its operation. In the examples above, the 2 indicates the operation (delete a configuration) and the 1 instructs installer to clear its log before operating. For more information about what the bit fields do, see the INSTALLER_ variables defined in Tunnelblick's source code file tunnelblick/defines.h.