Setting up Tunnelblick
On This Page
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.
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:
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:
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:
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:
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 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.