This document describes how to use Tunnelblick version 3.2beta16 and later. For earlier versions, see Using Tunnelblick 3.1.

• Starting Tunnelblick
• Quitting Tunnelblick
• Automatically Starting Tunnelblick Upon Login
• Normal Tunnelblick Operation
• The "VPN Details…" Window
• Keyboard Shortcuts
• Using More than One VPN Configuration
• Connecting to More than One VPN Simultaneously
• Command-Line Interface

Starting Tunnelblick

To launch Tunnelblick after setting up configuration and other files, double-click Tunnelblick in the Applications folder or double-click "Launch Tunnelblick" in the configurations folder.

If you do not quit Tunnelblick before logging out or shutting down your computer, it will automatically be launched the next time you log in.

Quitting Tunnelblick

To quit Tunnelblick, click on the Tunnelblick icon in the menu bar at the top of your screen between the time and the Spotlight icon, then click on "Quit". Or type Command-Q when the Details or About window is at the front of the display.

• When you quit Tunnelblick, all open connections will be closed except those for configurations which are set to automatically connect "when the computer starts".

• If you quit Tunnelblick, it will not be launched automatically the next time you log in.

Automatically Starting Tunnelblick Upon Login

Tunnelblick was designed as a persistent menu icon that survives reboots. To this end, it inserts itself into the login items when it is started and only removes itself from the login items when you choose Quit from the menu or Command-Q from the "Details” window or "About..." window. So if you just log out, shut down, or restart your computer, or it crashes, the next time you log in, Tunnelblick will automatically start. If you do not want Tunnelblick to start automatically, quit Tunnelblick before you log out, shut down, or restart.

Normal Tunnelblick Operation

Once Tunnelblick has been launched, you control it from the Tunnelblick icon in the menu bar at the top of your screen. The Tunnelblick icon is usually placed between the time and the Spotlight icon. When no VPN connection is active, the icon is dark, indicating a closed tunnel:

If you click on the icon, you'll see a drop down menu similar to the following:

There will be a "Connect” menu item for each available configuration (configurations in subfolders appear on submenus). Click on a "Connect" item to establish the corresponding VPN connection. To illustrate the connection being established, a dash will appear in the menu item and the Tunnelblick icon will darken and lighten repeatedly. If the connection is successfully opened, the icon will change to show an open tunnel:

Depending on your setup, you may be asked for a passphrase or username/password combination. You can save your passphrase or username and 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. (Tunnelblick will not close a connection for a configuration that is set up to automatically connect "when the computer starts" if you log out or quit Tunnelblick. The connection will remain open until your computer shuts down, sleeps, or you specifically disconnect it.)

Putting your computer to sleep will close the connection but upon waking up from sleep Tunnelblick will attempt to reestablish the connection.

If a connection error occurs, or in the unlikely event of an interface crash, Tunnelblick will terminate the VPN tunnel and record the error in the Console Log.

Use "Disconnect” from the drop-down menu to close the VPN connection. Use "Quit” to close all open connections^* and quit the program and prevent Tunnelblick from starting itself at your next login at your computer.

^* Tunnelblick will not close a connection for a configuration that is set up to automatically connect "when the computer starts" if you log out or quit Tunnelblick. The connection will remain open until your computer shuts down or you specifically disconnect it.

If Tunnelblick is running when you logout (or your computer crashes, or is shut down or restarted), then Tunnelblick will be started automatically upon login. To stop Tunnelblick from being started automatically upon login, be sure to quit Tunnelblick before logging out, either by using the "Quit” command, or by using Command-Q (Apple-Q) when the "Details” or "About…” window is active. (Don't confuse this automatic launch of Tunnelblick upon login with the "automatically connect on launch” option, which causes a connection to be established when Tunnelblick is launched.)

The "VPN Details…" Window

When the Tunnelblick menu is displayed, if you click on "VPN Details…” a window similar to the following will appear:

This window has four sections: Configurations, Preferences, Appearance, and Info. Select the section by clicking on it in the top toolbar. The "Configurations" section is shown above.

Configurations

The Configurations section has an entry for each Configurations on the left side. Tabs with the log and settings for the configuration selected on the left side are displayed on the right side. You may adjust the relative sizes of the left and right side by dragging the small dot between the two sides.

The "Log" tab (shown above) displays the log for the configuration. A button allows you to copy the entire contents of the log to the Clipboard so you may paste it into an email or other document.

The "Settings" tab (shown above) allows you to see and modify several settings for the configuration:

• "Connect” specifies when the configuration should be connected:
• "Manually" specifies that you will connect the configuration manually;
• "When Tunnelblick launches" specifies that the configuration to be connected when Tunnelblick is launched (started) ;
• "When computer starts" specifies that the configuration to be connected when the computer starts. You can only choose "when the computer starts" for automatic Tunnelblick VPN Configurations] or "Deployed" configurations

• "Set DNS/WINS: Set nameserver” causes scripts to be run before a connection is opened and after the connection is closed. The scripts save and restore DHCP DNS and WINS information. Other choices for "Set DNS/WINS" are:
• "Do not set nameserver", which does not change DNS settings;
• "Set nameserver (3.1), which manipulates DNS settings the way that Tunnelblick 3.1 does;
• "Set nameserver (3.0b10), which manipulates DNS settings the way that Tunnelblick 3.0b10 does; and
• "Set nameserver (alternate 1)", which manipulates DNS settings in a different way that is more compatible with some configurations.

• "Monitor connection" causes the network connection to be monitored for changes. It is available only when "Set nameserver" or "Set nameserver 3.1" is selected. When a change is detected, the connection will be disconnected and reconnected.

• "Show configuration on Tunnelblick menu" lets you show or not show the configuration in the menu that pops down when you click the Tunnelblick icon.

• You may also select a sound to be played when a configuration connects or unexpectedly disconnects.

Additional settings may be examined and modified by clicking the "Advanced" button.)

"Connect" and "Disconnect" buttons will connect or disconnect the configuration selected on the left side of the window.

A help button displays detailed help.

At the bottom of the list of configurations on the left side of the window there are three small buttons:

• The "+" button guides you through the process of adding a new configuration.

• The "-" button deletes the selected configuration. The username and password of a computer administrator is required to delete a configuration.

• The "gear" button pops down a list of other actions to take using the selected configuration:

Preferences

The "Preferences" section of the "VPN Details..." window allows you to modify Tunnelblick's behavior, check for updates, and reset disabled warnings:

Appearance

The "Appearance" section of the "VPN Details..." window allows you to modify Tunnelblick's appearance:

Info

The "Info" section of the "VPN Details..." window displays information about the Tunnelblick program and the people who have contributed to it:

(Note: the credits scroll to reveal additional contributors, so not all contributors are displayed in the above screenshot.)

Keyboard Shortcuts

You may use the standard keyboard shortcuts in the "VPN Details..." window:

Using More than One VPN Configuration

You can have any number of configurations installed; each of the configurations will be available in the drop down menu and shown as a separate entry in the "Details” window.

Connecting to More than One VPN Simultaneously

Tunnelblick can maintain multiple simultaneous open connections to different VPNs.

However, this is for experts only:

• If you use "Set nameserver” (which uses standard scripts to save/change/restore DNS resolution data), on one or more connections your DNS settings may not be saved and restored properly and DNS might or might not work. It depends on the order in what DNS settings you want to use and which connections are opened and closed. Connections may close and be reopened because of communications errors over which you have no control, which can cause unpredictable results. Not recommended.
• If you don't use "Set nameserver”, and your customized configuration files are suitably written to work together with custom scripts, things can work. But if you don't handle the DNS and routing settings properly, lots of things could go wrong. So this isn't recommended either unless you really know what you're doing and have a NEED to connect to multiple VPNs simultaneously.
• VPN administrators might not be happy that you are connecting their networks together. Most VPN client software limits you to a single connection, probably for that reason.

Command-Line Interface

Tunnelblick also contains openvpnstart, an OS X command line interface to OpenVPN which provides a scriptable way to create and destroy OpenVPN tunnels. (But Tunnelblick also has support for !AppleScript.) openvpnstart is located in Tunnelblick.app/Contents/Resources. For details on using openvpnstart, run it from a Terminal window with no arguments. When a connection attempt is made, Tunnelblick inserts the openvpnstart command line into the log; it can be copied from there for use in your own shell scripts.

PLEASE USE THE TUNNELBLICK DISCUSSION GROUP FOR COMMENTS OR QUESTIONS