Quick Start Guide

On This Page
    Installing Tunnelblick and Getting it Set Up
    Launching Tunnelblick
    Using Tunnelblick
    Connecting to a VPN
    Disconnecting from a VPN
    Quitting Tunnelblick
    Starting Tunnelblick Automatically
    Settings
    The "Set Nameserver" Check Box and DNS & WINS Settings

If you have alreay installed other VPN software: Some installations have backups that must be removed before installing Tunnelblick. See this Discussion Group thread.

Installing Tunnelblick and Getting it Set Up

Here is what you need to get started using Tunnelblick:

Access to a VPN server — your computer is one end of the tunnel and the VPN server is the other end. For more information, see Getting VPN Service.
A copy of the Tunnelblick installation disk image. You can get one from the Downloads page. Note: if you are asked "Do you want to allow downloads on 'tunnelblick.net'?", click "Allow".
A Tunnelblick VPN Configuration or an OpenVPN configuration file together with key and certificate files for encryption. You get these from whoever set up your VPN — usually your company or university or a VPN service provider (see Getting VPN Service).
The username and password of an administrator for your computer. (If you are the only user of your computer, only your password will be needed; macOS will fill in your username.)

If your browser hasn't opened the disk image, double-click the disk image to open it.

Double-click the Tunnelblick icon to start the installation process.

You may see a message saying that "'Tunnelblick' is an application downloaded from the Internet. Are you sure you want to open it?". Click "Open".

You should see a "Welcome to Tunnelblick" window, which allows you to choose whether to you want to allow Tunnelblick to access tunnelblick.net. Set the checkboxes as you wish and click "Continue".

You will be asked if you want to allow Tunnelblick to be installed in Applications. Enter an administrator username and password and click "OK". You aren't giving Tunnelblick your password, you are giving it to macOS, which will then allow Tunnelblick to install itself securely. (If you are reinstalling, upgrading, or downgrading Tunnelblick, your current copy of Tunnelblick will be put in the Trash before it is replaced.)

You may see the following notifications from macOS:

"Background Items Added. Software from 'Jonathan Bullard' added items that can run in the background…"
"Background Items Added. 'Tunnelblick' added items that can run in the background…"
"'Tunnelblick' notifications. Notifications may include alerts, sounds, and icon badges."

You can close the first two notifications. The first notification is for a program that runs briefly when you log in and launches Tunnelblick if necessary. The second notification is for a program used by Tunnelblick to perform network operations that must be done by a privileged program when setting up a VPN. Both of these programs must be allowed to run: they are necessary for the proper operation of Tunnelblick and they use only negligible amounts of processor time and memory, and no processor time or memory when Tunnelblick is not active.

Click on the "Options" button in the lower-right corner of the third notification, then click "Allow" or "Do not allow", as you prefer.

A new "Welcome to Tunnelblick" window will appear. Follow the instructions to add configurations.

Launching Tunnelblick

To launch Tunnelblick, double-click Tunnelblick in the Applications folder.

Tunnelblick will start automatically when you log in if it was running when you last logged out, shut down, or restarted your computer. It will also start automatically if you are connecting to or are connecting to a VPN, or if Tunnelblick has disabled all network access.

Using Tunnelblick

Once Tunnelblick has been launched, you control it from the Tunnelblick icon in the Status Bar at the top of your screen. When no VPN connection is active, the icon is dim.

If you click on the icon, you'll expose Tunnelblick's drop down menu. You can also expose the drop down menu by pressing Command-Option-F1.

Tunnelblick's drop down menu has:

A line showing the status your VPN connections and allowing you go quickly disconnect all VPNs.
A "VPN Details" line which will open a window with details and information about each VPN configuration.
A "Connect” line for each configuration. If there are no configurations, an "Add a configuration..." item will appear instead.
A "Quit" line.

If Tunnelblick has detected problems with your configurations, it will also display a "Warnings…" line; click on it to get a list of the warnings. Click on a warning to get more details about the warning.

You may use the standard keyboard shortcuts in the "Details" window: Command-M, Command-W, and Command-Q to minimize the window to the dock, close the window, and quit the program.

Connecting to a VPN

To connect to a VPN, either

Click on the "Connect" menu item for it's configuration, or
Select the configuration in the list on the left of the "VPN Details" window, then click on the "Connect" button.

To illustrate the connection being established, three dots will appear in the menu item, and the Tunnelblick icon will darken and lighten repeatedly. If the connection is successfully established, the Tunnelblick icon will be dark to show an open tunnel, and the "Connect..." menu item for the connection will change to "Disconnect...".

Depending on your setup, you may be asked for a passphrase or username/password combination before the connection can be established. You can save your passphrase, username, and/or password in Apple's Keychain by checking the appropriate checkbox.

The connection will be active as long as you do not end it or log out. Putting your computer to sleep will close the connection but upon waking up from sleep Tunnelblick will attempt to reestablish the connection. This behavior can be changed for each configuration in the configuration's settings.

Disconnecting from a VPN

To disconnect from a VPN, either

Click on the "Disconnect" menu item for it's configuration, or
Select the configuration in the list on the left of the "VPN Details" window, then click on the "Disconnect" button.
Quit Tunnelblick. All connections that are not marked "automatically connect when the computer starts" will be disconnected before Tunnelblick quits.

Quitting Tunnelblick

You can quit Tunnelblick by:

Clicking on the Tunnelblick icon, then on "Quit"
Typing Command-Q (also known as Apple-Q) from any open Tunnelblick window.

Tunnelblick will close all connections that are not marked "automatically connect when the computer starts" before it quits.

Starting Tunnelblick Automatically

If you don't quit Tunnelblick before logging out, it will be started automatically upon login. Don't confuse this automatic launch of Tunnelblick upon login with the "automatically connect” options, which cause a connection to be established when Tunnelblick is launched or when the computer is started or restarted.

If you have configurations that are marked "automatically connect when the computer starts", they will be connected whenever your computer starts or restarts. When Tunnelblick is running, it will show the status of, and you will be able to control, any connections that were established when the computer started.

Settings

The "Details" window allows you to control several settings for configurations. Select one or more configurations in the list on the left of the window, then change the settings as you wish. Commonly changed settings are:

Connect: Set Tunnelblick to be launched manually, when you log in, or when the computer is started.
Set DNS/WINS: If set to "Set nameserver", Tunnelblick will use its standard scripts before and after a connection is made to save and restore the computer's DNS and WINS settings, and allow DNS and WINS settings to be "pushed" from the VPN server.
Monitor network settings: (Only available if "Set nameserver" is selected.) If checked, Tunnelblick will monitor the network settings and restore settings or restart the connection if changes to the network DNS or WINS configurations are detected.

For more details on "Set nameserver" see the following section.

There are many other settings that control Tunnelblick's behavior. Click on the 'Advanced' button' or see Preferences for more details.

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:

If you set your DNS servers manually, then regardless of the state of "Set nameserver", your manual DNS servers will be the only ones used unless you check the "Allow changes to manually-set network settings" in the configuration's "Advanced" settings.
If you set your Search Domain(s) manually, then regardless of the state of "Set nameserver", your manual Search Domains will always be the only ones used.
If you set your WINS servers manually, then regardless of the state of "Set nameserver", your manual WINS servers will always be the only ones used.

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 "Do not set nameserver".