Each tunnel to be opened by Tunnelblick needs an OpenVPN configuration file. Tunnelblick considers any file located in ~/Library/openvpn with an extension of .conf or .ovpn to be a configuration file, and presents each such file as a potential "connection”. (The "~" refers to your home folder.) Often these configuration files will be supplied to you. Refer to the OpenVPN documentation for details about what the configuration file should contain. (Note that some OpenVPN options are available only on Windows.)
When using a "deployed" version of Tunnelblick, configuration files are all located within the Tunnelblick application itself, so ~/Library/openvpn is not used. See the Deploying Tunnelblick wiki for details.
Tunnelblick monitors the folder that contains the configuration files. If a configuration file is added, the new configuration is available immediately without restarting Tunnelblick or disturbing existing connections. If a configuration is removed from the folder, any connection using that configuration is immediately disconnected. To disable this behavior, use "doNotMonitorConfigurationFolder". (See the "Preferences" section.)
The configuration file may also be "shadow" copied to the /Library/Application Support Tunnelblick/Users/username folder. This is done transparently for configuration files located on network volumes. The user should never manipulate this folder or its contents directly; Tunnelblick will do so automatically. (See "useShadowConfigurationFiles" in the "Preferences" section.)
If Tunnelblick's "Set nameserver” option is used:
- Any "up” or "down” options in the configuration file will be ignored.
- If any "user” or "group” options appear in the configuration file, DNS settings will not be restored when a tunnel is disconnected.
Tunnelblick preferences are contained in ~/Library/Preferences/com.openvpn.tunnelblick.plist. (The "~” indicates your home folder.)
OpenVPN configuration files are stored in ~/Library/openvpn. Usually the key and certificate files are stored there, too. Since these files are all located in the user's Library folder, they must be set up separately for each user.
But note that deployed versions of Tunnelblick contain the configuration file(s), so they do not need to be set up for each user -- any user that can access Tunnelblick.app can connect to VPN.
Shadow" copies of configuration files (if they exist) are located in /Library/Application Support Tunnelblick/Users/username. (See "useShadowConfigurationFiles" in the "Preferences" section.)
See the Deploying Tunnelblick wiki for details of file locations when using a deployed version of Tunnelblick.
Within the Tunnelblick.app application, client up/down scripts and openvpn-down-root.so are located in Tunnelblick.app/Contents/Resources (see the "Set nameserver” checkbox in the "OpenVPN Log Window” section). To access Tunnelblick.app/Contents in the Finder, control-click Tunnelblick.app in the Applications folder, then click on "Show Package Contents”.
When there are no configuration files in ~/Library/openvpn (which is usually the case the first time Tunnelblick is run by each user) when using a non-deployed version of Tunnelblick, the following screen will be displayed:
If you click "Quit”, Tunnelblick will quit without doing anything. If you click "Continue”, Tunnelblick will create and save an example OpenVPN configuration file, ~/Library/openvpn/openvpn.conf, and then open it in TextEdit for you to modify. If you have an OpenVPN configuration file that you are supposed to use, copy its contents, paste them into this file (replacing the default contents), save, and exit TextEdit. Your configuration (named "openvpn.conf”) is all set. Tunnelblick changes the ownership of OpenVPN configuration files to root, so it is protected against unnoticed and possibly malicious changes.
If you have received key files or certificate files together with your personal configuration file, please make sure to put them in ~/Library/openvpn/ (or another location as specified by your network administrator). OpenVPN will try to locate the key files in this folder, unless absolute paths to them are specified in the configuration file.
The first time Tunnelblick is run on a particular computer (but only the first time the first user runs it), it will display the following screen:
Please enter the name and password of a computer administrator. Tunnelblick's imbedded OpenVPN needs root privileges because it needs to modify network settings by configuring new network devices, changing routes, and adding and removing nameservers. Because we don't want you to enter your administrator account name and password every time you start a VPN connection, Tunnelblick comes with a setuid root binary that allows it to do exactly one thing: start a VPN connection with super user rights. Tunnelblick needs your administrator account name password only on its first start after installation, so it can create this setuid root binary.
The second time Tunnelblick is run by each user, a screen similar to the following will be displayed:
Specify whether or not you wish to have Tunnelblick check for updates. Each time an update is available, you will be given a choice of whether to install the update or not.
Whenever a configuration file changes, you will need to enter the name and password of a computer administrator. This is done as a security measure: because configuration files can contain references to scripts that run as root, they are owned by root and an administrator must grant permission to use them.
Once Tunnelblick has been started, you control it from the icon in the Status 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 .ovpn or .conf file in ~/Library/openvpn/. Click on one to establish the corresponding pre-configured VPN connection. 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 opened, the icon will change to show an open tunnel:
You may be asked for a passphrase or username/password combination if key/certificate files are not being used. You can save your passphrase 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 or losing contact with the server (by lack of wlan signal, for example) will make Tunnelblick periodically try to re-establish 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.
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 "OpenVPN Log” 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 started.)
Click on the Tunnelblick icon in the Status Bar at the top of your screen between the time and the Spotlight icon then click on "Details…” to obtain details for all connections (open or closed). A window similar to the following will appear:
There will be a tab for each connection (i.e., each .ovpn or .conf file), whether the connection is open or closed. Each tab contains a pane with the OpenVPN Log for the connection and two checkboxes that provide options for that connection:
When a connection is attempted, the script for "Set nameserver” saves the current DNS settings and removes DNS settings that were set by DHCP (manual DNS settings are not removed). When a connection is disconnected (or if it fails to connect), the scripts restore the saved DNS settings. The scripts do not support the simultaneous use of two or more nameservers for different domains; custom up/down scripts must be used for this purpose.
In addition, the "OpenVPN Log” window contains four buttons:
You may use the standard keyboard shortcuts in the "OpenVPN Log" window: Command-C, Command-X, and Command-V for copy, cut, and paste; and Command-A, Command-M, Command-W, and Command-Q to select all the text in the log that is currently being displayed, minimize the window to the dock, close the window, and quit the program.
0 comments: