Highlighted Articles
News
Installing Tunnelblick
Uninstalling Tunnelblick
Setting up Configurations
Using Tunnelblick
Getting VPN Service
Common Problems
Configuring OpenVPN
Release Notes
Thanks
FAQ

Discussion Group
Read Before You Post

On This Page
Setting Up and Installing Configurations
Converting OpenVPN Configurations to Tunnelblick VPN Configurations
Creating and Installing a Tunnelblick VPN Configuration
Modifying a Tunnelblick VPN Configuration
Files Contained in a Tunnelblick VPN Configuration
The 'Set Nameserver' Check Box and DNS & WINS Settings
The OpenVPN --user and --group options and openvpn-down-root.so

Stop if you have a 'Deployed' version of Tunnelblick. It comes already set up — you do no need to do anything more. Just start using it and enjoy!

Stop if you have purchased VPN service from a VPN service provider. They should provide you with configuration files and instructions on how to use them with Tunnelblick.

Stop if you have VPN service from a corporate or other network provided by your employer. Your network manager or IT department should provide you with configuration files and instructions on how to use them with Tunnelblick.

Stop if want details about the structure of a Tunnelblick VPN Configuration, see '.tblk' Details.

Otherwise, continue!

Setting Up and Installing Configurations

First, install Tunnelblick and launch it so it is running.

It is not enough to install Tunnelblick: you also need to tell Tunnelblick how to connect to a VPN.

You tell Tunnelblick how to connect to a VPN with a configuration file.

If you already have configuration files you can install them by dragging and dropping them onto the Tunnelblick icon in the menu bar.

After installing your configurations, continue with 'Set Nameserver' Check Box and DNS & WINS Settings, below.

If you don't have configuration files or you want more information about them continue reading.

Tunnelblick can use two types of configuration files:

• Tunnelblick VPN Configurations. A Tunnelblick VPN Configuration contains all of the information Tunnelblick needs to connect to one or more VPNs. A Tunnelblick VPN Configuration contains one or more OpenVPN configuration files, and may contain key, certificate, and script files. Everything needed is contained within the Tunnelblick VPN Configuration. Tunnelblick VPN Configurations may also contain other information, including information about default preferences for the configuration and identification and version information for the configuration itself that make managing widespread distribution easier. For details, see Tunnelblick VPN Configurations Details.

• OpenVPN configuration files. These are plain text files with extensions of .ovpn or .conf. These files usually contain only the configuration information; keys and certificates may be held in separate files. When installed, they are converted to Tunnelblick VPN Configurations. For more information about setting up Tunnelblick using OpenVPN configuration files, see Configuring OpenVPN.

Converting OpenVPN Configurations to Tunnelblick VPN Configurations

You can drag and drop OpenVPN configurations onto the Tunnelblick icon in the menu bar and they will be installed as Tunnelblick VPN Configurations.

Creating and Installing a Tunnelblick VPN Configuration

To create a Tunnelblick VPN Configuration:

1. Create a folder anywhere (on your Desktop works well);
2. If you have only one OpenVPN configuration file, name the folder with the name you want the configuration known by in Tunnelblick. (Otherwise, each configuration will be known in Tunnelblick by the name of the OpenVPN configuration file that it is based on);
3. Copy all the files related to the configuration(s) into the folder (see Files Contained in a Tunnelblick VPN Configuration, below);
4. Add an extension of '.tblk' at the end of the folder name. When you do this the icon for the folder will change to an icon for a Tunnelblick VPN Configuration.
5. Drag and drop the folder's new icon onto the Tunnelblick icon in the menu bar to install it.

When you install, you will be asked if you want each configuration to be private or shared. A private configuration may only be used when you are logged onto the computer. A shared configuration may be used by anyone who is logged into the computer. If the name you have given conflicts with the name of an existing installed configuration, you will be given the opportunity to change the name.

The process of installation will copy the .tblk to a special location on your computer (see File Locations) and make changes to it so it can be used securely. You can then delete the original .tblk you created, or move it somewhere convenient as a backup, or copy or move it to another computer and install it on that computer.

That's it! You are done. The configuration(s) will be available immediately in Tunnelblick.

Modifying a Tunnelblick VPN Configuration

You can modify a Tunnelblick VPN Configuration two ways:

• If you want to change the contents of an installed OpenVPN configuration file that is installed as a Private configuration, you should select the configuration in Tunnelblick's VPN Details window, then click the 'gear' button at the bottom of the list and select 'Edit OpenVPN Configuration File...'. That will open the installed OpenVPN configuration file in TextEdit. Changes take effect as soon as the file is saved in TextEdit. Note that this does not modify your original .tblk; it modifies the installed copy only.

• You can't change the contents of an installed OpenVPN configuration file that is installed as a Shared configuration. (You can convert it to be a Private configuration, edit it, and then change it back to be Shared.)

• If you want to make other changes (to the key/certificate files, for example), you'll have to

1. Modify your original .tblk to include the changes (rename it to not end in '.tblk', then make the changes, then rename it to end in '.tblk' again);
2. Drag and drop the modified .tblk onto the Tunnelblick icon in the menu bar to install it.

Files Contained in a Tunnelblick VPN Configuration

The files that should be contained in a Tunnelblick VPN Configuration (the 'files related to the connection' above) should all be 'plain text' files:

• One or more OpenVPN configuration files (.ovpn or .conf files).
• Any certificate or key files for the configurations (.key, .crt, .pem, .cer, .der, .p12, .p7b, .p7c, and .pfx files); and
• Any script files for the configurations. Script files must must have a .sh extension so that Tunnelblick can secure them and use them properly.

The 'Set Nameserver' Check Box and DNS & WINS Settings

If you are using DHCP, wish to use DNS and WINS servers at the far end of the tunnel when connected, and the VPN server you are connecting to 'pushes' DNS and WINS settings to your client, select 'Set nameserver'. (This is the situation for most users.)

If you are using DHCP, wish to use your original DNS and WINS servers when connected, and the VPN server you are connecting to does not 'push' DNS or WINS settings to your client, select 'Do not set nameserver'.

If you are using manual settings, different versions of macOS behave differently. This is due to a change in network behavior in Snow Leopard and is beyond the scope of this project to fix.

If you're using Leopard (OS X 10.5) or Tiger (OS X 10.4), then it is possible to use the VPN-server-supplied DNS and WINS settings in addition to your manual settings by selecting 'Set nameserver'. However, your manual settings will always take precedence over any VPN server-supplied settings. If 'Do not set nameserver' is selected, you will continue to use only your manually-configured settings and any VPN server-supplied settings will be ignored. 'Take precedence' means that the manual DNS server will be used for all DNS queries unless it fails to answer, in which case the VPN server-supplied DNS server will be used.

If you are using Snow Leopard (OS X 10.6) or later, then your usual DNS and WINS settings will always be used, and no aggregation of configurations will be performed.

• If you set your DNS servers manually, then regardless of the state of 'Set nameserver', your manual DNS servers, Search Domains, and WINS servers will always be the only ones used unless you set the configuration to 'Allow changes to manually-set network settings'.

• Each of these settings is independent of the others: if 'Set nameserver' is selected, those settings not configured manually will be replaced by the settings obtained from the VPN server. If 'Do not set nameserver' is selected, then as with Leopard/Tiger, no DNS/WINS settings will be applied unless you set the configuration to 'Allow changes to manually-set network setttings'.

If your situation is not described above (e.g., if you use manual DNS settings and wish to use DNS servers at the far end of a tunnel when connected, or you wish to use the macOS ability to use different nameservers for different domains), you must create your own up/down scripts and select 'Set nameserver'.

The OpenVPN --user and --group options and openvpn-down-root.so

When using 'Set nameserver' or your own down script for OpenVPN, it is usually necessary to avoid using the OpenVPN 'user' and 'group' options in the configuration file. These options cause OpenVPN to drop root privileges and take the privileges of the specified user and group (usually, 'nobody'). If this is done, then the down script that handles restarting connections when there is a transient problem fails, because it is run without root privileges. OpenVPN usually fails, too, if your configuration performs any routing (most configurations do).

However, Tunnelblick includes the 'openvpn-down-root.so' plugin for OpenVPN. When this plugin is activated, OpenVPN still drops root privileges and runs as the specified user:group after a connection is made, but runs the down script run as root:wheel, so reconnecting after transient network problems can work if OpenVPN does not need to restore any routes.

When you connect with a configuration that includes the 'user' and/or 'group' options in the configuration file, Tunnelblick will ask if you wish to use the openvpn-down-root plugin. Answer 'yes' and Tunnelblick will use the plugin each time it makes a connection. OpenVPN will still be unable to make route changes after the initial connection; they have to be made in the your own customized scripts.

Highlighted Articles
News
Installing Tunnelblick
Uninstalling Tunnelblick
Setting up Configurations
Using Tunnelblick
Getting VPN Service
Common Problems
Configuring OpenVPN
Release Notes
Thanks
FAQ

Discussion Group
Read Before You Post

On This Page
The Tunnelblick Application
OpenVPN, Drivers, and Standard Scripts
Log Files
Key and Certificate Files
Configuration Files
Custom Scripts
LaunchDaemons
Preferences
One More Thing

The Tunnelblick Application

The Tunnelblick application, Tunnelblick.app, must be stored directly in /Applications on the startup volume for security reasons. Thus it cannot be used from network drives or internal or external drives including thumb or flash drives, CD/DVD drives, etc. unless they are being used as the startup volume. Running Tunnelblick from from anywhere except /Applications on the startup volume will result in an offer to install Tunnelblick in /Applications on the startup volume.

OpenVPN, Drivers, and Standard Scripts

The OpenVPN program, openvpn-down-root.so, the 'tun' and 'tap' kext driver files, and standard client up/down scripts are included with, and contained within, Tunnelblick.app.

Log Files

Log files are stored in /Library/Application Support/Tunnelblick/Logs. (Early versions of Tunnelblick stored them in /tmp/tunnelblick). The log files for a configuration are created or deleted and recreated each time the connection is made. There are two log files for each configuration, an OpenVPN log file and a scripts log file. The contents of the files are merged in the display in Tunnelblick's 'VPN Details' window.

Key and Certificate Files

These may be stored anywhere, but typically they are stored in the same folder as the configuration (.ovpn or .conf) file. Key and certificate files associated with a Tunnelblick VPN Configuration (.tblk) are stored inside the configuration itself.

Key and certificate files usually have an extension of .cer, .crt, .der, .key, .p12, .p7b, .p7c, .pem, or .pfx.

Configuration Files

There are two types of configuration files:

• Tunnelblick VPN Connection files (.tblk files), which include within them one OpenVPN configuration file and all key, certificate, and script files used by the configuration; and

• OpenVPN configuration files (.ovpn and .conf files). Keys, certificates, and scripts associated with a configuration file are often stored as separate files, but may be included within the configuration file itself.

Note: Configurations should always be installed by dropping them on the Tunnelblick icon in the menu bar. If you just move or copy them they may not work properly.

There are five places configuration files may be stored:

• Private configurations, including both types of files, are stored in '~/Library/Application Support/Tunnelblick/Configurations'. Since these files are all located in the user's Library folder, they must be set up separately for each user. (Note that the '~' in the path indicates the user's home folder; thus the folder is actually located somewhere such as /Users/username/Library/Application Support/Tunnelblick/Configurations. Do not confuse this Library folder with the /Library folder located at the root of the filesystem.)

• Shared configurations, which can only be Tunnelblick VPN Connection files, are stored in /Library/Application Support/Tunnelblick/Shared. Shared configurations do not need to be set up for each user. (In fact, that's the whole point of sharing them!)

• Deployed configurations, including both types of files, are stored within the Contents/Resources folder of Tunnelblick.app itself. They do not need to be set up for each user, and are accessible to all users of the computer with access to the application. (To access the internal contents of Tunnelblick.app in the Finder, Control-click Tunnelblick.app in the Applications folder and click 'Show Package Contents”.)

• 'Shadow' copies of configuration files (if they exist) are located in /Library/Application Support Tunnelblick/Users/username. See 'useShadowConfigurationFiles' in Preferences for details. Shadow copies are created and maintained by Tunnelblick.

• Backup copies of Deployed configurations are stored in subfolders of /Library/Application Support/Tunnelblick/Backup. These configurations will be restored if a version of Tunnelblick which is not a Deployed version is installed, making it into a Deployed version.

Note: Prior to Tunnelblick version 3.0b24, private configuration files were stored in ~/Library/openvpn. Version 3.0b24 and later versions automatically move that folder to its new location, and replace it with a symbolic link to the new location.

Custom Scripts

There are two types of custom scripts that can be run at certain points in the connect/disconnect process:

• Scripts supported by OpenVPN: Scripts referred to in the OpenVPN configuration file may be included in a Tunnelblick VPN configuration; use filenames without any path information to refer to them in the OpenVPN configuration file.

• Scripts supported by Tunnelblick: Tunnelblick VPN Configurations ('.tblk's) can contain custom scripts that will be run automatically at other points in the connect/disconnect process.

These scripts should be located in a Tunnelblick VPN Configurations without any folder structure, and references to them should not contain any path information.

For more information, see Using Scripts.

LaunchDaemons

Durring installation, Tunnelblick sets up a 'daemon' to perform privileged operations such as starting OpenVPN as root. The daemon has a .plist file named net.tunnelblick.tunnelblick.tunnelblickd.plist in /Library/LaunchDaemons.

If a configuration is set to connect when the computer starts, it has a .plist file located in /Library/LaunchDaemons. These .plist files are all named starting with 'net.tunnelblick.startup.'

Preferences

A user's Tunnelblick preferences are contained in ~/Library/Preferences/net.tunnelblick.tunnelblick.plist.

Note: In Tunnelblick 3.2beta10 and earlier, preferences are stored in ~/Library/Preferences/com.openvpn.tunnelblick.plist.

Deployed versions of Tunnelblick may contain a 'forced-preferences.plist' file within the Tunnelblick application itself. They are used to override the user's normal preferences; see Deploying Tunnelblick for details.

Tunnelblick VPN Configurations may also include preference defaults, which are used to initialize the user's preferences (which may then be changed by the user).

One More Thing

Under certain circumstances, Tunnelblick replaces the configuration folder that very old versions of Tunnelblick use,
~/Library/openvpn
with a symbolic link to the new location of the folder,
~/Library/Application Support/Tunnelblick/Configurations