Installing and Running our Client on the Mac
The following instructions apply to 64-bit Mac OS X systems. The Tunnelblick VPN client supports OS X 10.7.5+.
I. Installing the Client Software
On the Mac platform, we use Tunnelblick as the VPN client of choice.
You may be able to use Viscosity, or a custom build of OpenVPN
from source code, but we have found Tunnelblick to be the easiest
to work with, and it is free to use.
The Tunnelblick client can be downloaded from here:
The current version ("stable") is 3.8.4. Use the 3.8.5 Beta version at your own risk.
We do suggest that you verify the SHA256 hash on the downloaded .dmg file versus what is shown on the website, to ensure the integrity of the download.
In order to permit the installation, you may need to edit your settings in System Preferences / Security & Privacy / General, in order to permit apps downloaded from "Anywhere." This is needed because Tunnelblick is not in the Mac App Store.
Then, as with any other software distributed in a .dmg volume, simply mount the volume by clicking on it in a Finder window. Double-click the Tunnelblick icon to start the installation process.
You will need to approve that you want to open the image. You will then be asked for your administrator password. When you have completed the install, an icon for Tunnelblick will appear in your system tray at the top right of your screen. (The icon looks something like a horseshoe or a magnet.) You can also place a shortcut in your dock. When the installation is finished, you can then unmount ("Eject") the Tunnelblick volume.
Note: Tunnelblick automatically downloads and asks to install future updates, so you will only need to download the installation volume once.
By default, Tunnelblick will start automatically when you log in. However it will not connect to a VPN until you tell it to (subject to configurable settings).
II. Installing the ElanVPN Max Configuration
We deliver a your account credentials to you in the form of a .zip file. This ZIP contains a directory structure supplying VPN configurations and associated files for each supported platform. After unzipping the file, navigate to the ./mac subdirectory. Here you will find a README file, containing your VPN credentials along with a copy of these instructions. You will also see a directory folder named ElanVPN-Max.tblk. This folder contains two files:
- this is the configuration file for use with our Max network
- the automatic login/authorization script
The file connected.sh also contains your VPN login credentials at the top (the same ones shown in the README file).
In order to import the VPN credentials, simply open a Finder window and navigate to wherever you have unzipped our .zip file containing your credentials, and go to the ./mac directory. Click on the ElanVPN-Max.tblk folder, and Tunnelblick will automatically import it. Note: Tunnelblick will require you to specifically approve the fact that a connect script is used. This is because the script is run as root (administrator), which in theory could damage or compromise your computer if the script did anything untoward. All that our connected.sh script does is a few cURL invocations, to submit your login credentials. Feel free to open ./mac/ElanVPN-Max.tblk/connected.sh in a text editor, if you wish to assure yourself of this before approving the import.
After importing, you will need to make a few modifications to your Settings. Do this by starting Tunnelblick from its icon in the dock to open the control window, or alternatively, by left-clicking the systray icon and picking "VPN Details" from the menu. Select the ElanVPN-Max configuration at the left, and then access the Settings tab on the right. Proceed to configure as follows:
- You may specify automatic connection, but we recommend Manually.
- Leave the "Set DNS/WINS" setting at the default value, "Set nameserver." This causes our private DNS servers to be used while connected to ElanVPN.
- We recommend that you select "Latest" for OpenVPN version (currently 2.5.0). This will cause Tunnelblick always to use the latest OpenVPN it has available.
- Also, we suggest that you check the box to "Route all IPv4 traffic through the VPN." This is useful for preventing any leakage of requests bypassing the VPN connection. You may do the same for IPv6 if you intend to use it.
Important! -Under the "Advanced" settings (see button bottom right), on the "Connecting & Disconnecting" tab, please make sure that you check the box for "Set DNS after routes are set instead of before routes are set." This is because the DNS servers on our VPN are only accessible via the routes pushed from the gateway. So without this setting, you may have trouble logging in, since the DNS lookups for our login servers will not succeed.
- Finally, you may specify alert sounds for connect and unexpected disconnect. This is optional. Do this on the Advanced / Sounds tab.
- You should not need to tweak other settings, as the defaults are suitable.
III. Connecting to the VPN
Now you are ready to connect to the ElanVPN-Max network! All you need to do is hover your mouse cursor over the Tunnelblick icon in the system tray. A list of available VPN configurations will pop up in a partly transparent window. Click on the "Connect" button for ElanVPN-Max. (You may see multiple boxes if you have imported other VPN credentials too.) You may also left-click the system tray icon and select "Connect ElanVPN-Max" from the menu. You can follow the connection process by opening Tunnelblick's control window and using the Log tab.
Once the VPN has established a connection, the automatic
authentication script ("connected.sh") will be invoked. You do not
need to do anything to make this happen. Although the script will
return immediately, it is really performing your login authorization
in the background. Once it is successful, your computer's apparent
IP address will change. On success,
these events will be shown at the end of the log:
"(timestamp) *Tunnelblick: The 'connected.sh' script executed successfully"
"(timestamp) *Tunnelblick: This computer's apparent public IP address changed from W.X.Y.Z before connection to A.B.C.D after connection"
If you see both of these, then the auto-authentication step worked, and you are good to go! You can close the Log window and begin surfing. Be patient; logins often take 30 seconds or more.
If you see the first line, about 'connected.sh' executed successfully, but do not see the second line appear in due course, something may have gone wrong with the automated login. In this case, when you attempt to surf, your browser will be redirected automatically to a login page. Login using your credentials.
IV. Troubleshooting Connections
If you have problems getting connected, please open Tunnelblick's control window. You may do this either by clicking on its icon in your dock (if you placed one there), or by left-clicking the icon in the system tray and selecting the "VPN Details" item from the menu. In the control window, make sure that ElanVPN-Max is selected under the Configurations menu on the left. Then select the Log tab, and scroll to the bottom.
After a normal successful connection, you will see something about how "the 'connected.sh' script executed successfully," and then a note about a change in your computer's apparent public IP address, as shown above. (Unless you turned the check for IP address changes off in your Tunnelblick Settings.)
If the connection failed, there should be some kind of useful information shown in the Log window. If you see evidence of some other problem, before 'connected.sh' is even invoked, you are probably looking at a connectivity error. Check your computer's connection to the internet. Also, your firewall settings could be blocking the outgoing connection. (Firewall settings are beyond the scope of this document.)
Performing Manual Logins
One of the good things about Macs is that so many tasks are automated, and normally done with just a few clicks. But this quickly becomes one of the bad things about Macs, when the automation fails.
First, to increase the level of detail reported in the Log window, you may edit the file elanvpn-max.ovpn in your ElanVPN-Max.tblk folder. To do this, use your favorite text editor and change the line "verb 1" (near the top) to "verb 3". We ask that you do not edit or comment out any other settings in the file, as these are set very precisely as they need to be for maximum security.
After you have made this change, you will need to repeat the step to import the credentials into Tunnelblick. Open a Finder window and click on the ElanVPN-Max.tblk folder. You will need to again approve the use of a script, plus enter your authorization password, and should then see a popup window stating that the configuration was replaced. The change to the verbosity level will take effect next time you attempt to connect.
If you are getting redirected to a manual login page, due to a failure with the automated authorization script, you will need to perform a manual login. Connect to the ElanVPN-Max VPN as usual (see above). Once you are connected (hover text turns green, your selected sound was played), please follow the Manual Authentication instructions given here.