Highlighted Articles
News
Installing Tunnelblick
Uninstalling Tunnelblick
Setting up Configurations
Using Tunnelblick
Getting VPN Service
Common Problems
Configuring OpenVPN
Release Notes
Thanks
FAQ

Discussion Group
Read Before You Post

On This Page
Setting Up and Installing Configurations
Converting OpenVPN Configurations to Tunnelblick VPN Configurations
Creating and Installing a Tunnelblick VPN Configuration
Modifying a Tunnelblick VPN Configuration
Files Contained in a Tunnelblick VPN Configuration
The 'Set Nameserver' Check Box and DNS & WINS Settings
The OpenVPN --user and --group options and openvpn-down-root.so

Stop if you have a 'Deployed' version of Tunnelblick. It comes already set up — you do no need to do anything more. Just start using it and enjoy!

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.

Otherwise, continue!

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:

• Tunnelblick VPN Configurations. A Tunnelblick VPN Configuration contains all of the information Tunnelblick needs to connect to one or more VPNs. A Tunnelblick VPN Configuration contains one or more OpenVPN configuration files, and may contain key, certificate, and script files. Everything needed is contained within the Tunnelblick VPN Configuration. Tunnelblick VPN Configurations may also contain other information, including information about default preferences for the configuration and identification and version information for the configuration itself that make managing widespread distribution easier. For details, see Tunnelblick VPN Configurations Details.

• OpenVPN configuration files. These are plain text files with extensions of .ovpn or .conf. These files usually contain only the configuration information; keys and certificates may be held in separate files. When installed, they are converted to Tunnelblick VPN Configurations. For more information about setting up Tunnelblick using OpenVPN configuration files, see Configuring OpenVPN.

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:

1. Create a folder anywhere (on your Desktop works well);
2. If you have only one OpenVPN configuration file, name the folder with the name you want the configuration known by in Tunnelblick. (Otherwise, each configuration will be known in Tunnelblick by the name of the OpenVPN configuration file that it is based on);
3. Copy all the files related to the configuration(s) into the folder (see Files Contained in a Tunnelblick VPN Configuration, below);
4. Add an extension of '.tblk' at the end of the folder name. When you do this the icon for the folder will change to an icon for a Tunnelblick VPN Configuration.
5. Drag and drop the folder's new icon onto the Tunnelblick icon in the menu bar to install it.

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:

• If you want to change the contents of an installed OpenVPN configuration file that is installed as a Private configuration, you should select the configuration in Tunnelblick's VPN Details window, then click the 'gear' button at the bottom of the list and select 'Edit OpenVPN Configuration File...'. That will open the installed OpenVPN configuration file in TextEdit. Changes take effect as soon as the file is saved in TextEdit. Note that this does not modify your original .tblk; it modifies the installed copy only.

• You can't change the contents of an installed OpenVPN configuration file that is installed as a Shared configuration. (You can convert it to be a Private configuration, edit it, and then change it back to be Shared.)

• If you want to make other changes (to the key/certificate files, for example), you'll have to

1. Modify your original .tblk to include the changes (rename it to not end in '.tblk', then make the changes, then rename it to end in '.tblk' again);
2. Drag and drop the modified .tblk onto the Tunnelblick icon in the menu bar to install it.

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:

• One or more OpenVPN configuration files (.ovpn or .conf files).
• Any certificate or key files for the configurations (.key, .crt, .pem, .cer, .der, .p12, .p7b, .p7c, and .pfx files); and
• Any script files for the configurations. Script files must must have a .sh extension so that Tunnelblick can secure them and use them properly.

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 you set your DNS servers manually, then regardless of the state of 'Set nameserver', your manual DNS servers, Search Domains, and WINS servers will always be the only ones used unless you set the configuration to 'Allow changes to manually-set network settings'.

• Each of these settings is independent of the others: if 'Set nameserver' is selected, those settings not configured manually will be replaced by the settings obtained from the VPN server. If 'Do not set nameserver' is selected, then as with Leopard/Tiger, no DNS/WINS settings will be applied unless you set the configuration to 'Allow changes to manually-set network setttings'.

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.

Highlighted Articles
News
Installing Tunnelblick
Uninstalling Tunnelblick
Setting up Configurations
Using Tunnelblick
Getting VPN Service
Common Problems
Configuring OpenVPN
Release Notes
Thanks
FAQ

Discussion Group
Read Before You Post

On This Page
Background
How to Load Tunnelblick's System Extensions
The Long-Term Problem
How to tell if you have a 'tap' VPN or a 'tun' VPN
When will this happen?
How to modify a 'tun' VPN so it will continue to work
If macOS still complains
Always load tun or always load tap
Disabling SIP
Old versions of Tunnelblick will not help
What Apple announced
What is Tunnelblick doing about it?

Background

To connect to a VPN, Tunnelblick needs to use a special kind of device driver:

• For a Tun VPN, macOS includes a built-in 'utun' device driver which can be
  used so that Tunnelblick's Tun system extension does not need to be loaded.
  Most OpenVPN configuration files will automatically use the 'utun' driver, but
  some include options that require Tunnelblick to use its own Tun system
  extension. Those configuration files should be modified so that the built-in
  macOS 'utun' device driver can be used. (For simple instructions to make such
  modifications, see Errors Loading System Extensions.)

• For a Tap VPN, Tunnelblick's Tap system extension must be loaded because
  macOS does not have a built-in Tap device driver.

Apple has made it more and more difficult to load system extensions with each
new version of macOS. They have also announced that in 'a future version' of
macOS, you will not be able to use system extensions at all.

How to Load Tunnelblick's System Extensions

If you are using any version of macOS up to and including macOS Sierra,
Tunneblick automatically loads and unloads its system extensions; you do not
need to do anything.

If you are using macOS High Sierra, Mojave, or Catalina, you need to

1. Attempt to connect the configuration so Tunnelblick attempts to use the system extension;
2. Open System Preferences >> Security & Privacy;
3. Give permission to load system extensions signed by 'Jonathan Bullard';
4. Close System Preferences; and
5. If you are using macOS Catalina**, restart your computer.

If you are using macOS Big Sur on an Intel Mac, you need to:

1. Restart your computer in Recovery mode;
2. Open /Applications/Utilities/Terminal;
3. Execute 'csrutil disable' command in Terminal;
4. Restart your computer normally;
5. Attempt to connect the configuration so Tunnelblick attempts to use the system extension;
6. Open System Preferences >> Security & Privacy;
7. Give permission to load system extensions signed by 'Jonathan Bullard';
8. Close System Preferences;
9. Restart your computer normally;
10. Restart your computer in Recovery mode;
11. Open /Applications/Utilities/Terminal;
12. Execute 'csrutil enable' command in Terminal; and
13. Restart your computer normally.

If you are using macOS Big Sur on an Apple Silicon Mac, you need to use the latest beta version of Tunnelblick. See Tunnelblick and Apple Silicon for details.

The Long-Term Problem

Apple has announced changes to macOS which affect many users of Tunnelblick.

You might see a warning from Tunnelblick about this change, or you might see the following warning when connecting your VPN:

What this means is:

• If you have a 'tap' VPN, a future version of macOS will cause your VPN to stop working. (Apple's announcement to developers is worded differently and may mean that users will be able to use some mechanism to enable 'tap' VPNs to continue to work, but that interpretation is contradicted by the warning shown above. See What Apple announced, below.) You may be able to convert your 'tap' VPN to a 'tun' VPN which will work. However, that requires being able to change the OpenVPN configurations on both your computer and on the VPN server, and it may not provide all of the networking facilities that you are currently using. Consult your VPN service provider or OpenVPN experts and support for help with doing this.

• On macOS Big Sur 11.0.1 you may be able to allow 'tap' VPNs to continue to work by disabling SIP.

• On macOS Big Sur 11.1.0 disabling SIP is not necessary.

• If you have a 'tun' VPN, your configurations may continue to work in future version of macOS without you doing anything, or you might need to make a simple change to the OpenVPN configuration file so that the configuration will continue to work. If your OpenVPN configuration file does not contain a 'dev-node' option, you do not need to do anything and the configuration will continue to work. If your OpenVPN configuration file does contain a 'dev-node' option, you will need to remove that option so the configuration continues to work (see below).

How to tell if you have a 'tap' VPN or a 'tun' VPN

First, click to select a configuration in the left side of the 'Configurations' panel of Tunnelblick's 'VPN Details' window.

Then, examine the title of the 'VPN Details' window. If it includes:

• '- UTUN -': you have a 'tun' VPN but it does not require a system extension. You don't need to do anything.
• '- TUN -': you have a 'tun' VPN which requires a system extension. See below for instructions for modifying the OpenVPN configuration file so the system extension is not required.
• '- TAP -': you have a 'tap' VPN which requires a system extension. Contact your VPN service provider for help.

When will this happen?

Apple does not announce its intentions in advance, so there may not be any prior notice of this change. It may appear in a version of macOS Big Sur, or may appear in a later version of macOS.

For updated information about macOS Big Sur, see Tunnelblick on macOS Big Sur.

How to modify a 'tun' VPN so it will continue to work

You need to remove the dev-node option if it exists in the VPN's OpenVPN configuration file:

1. Click to select a configuration in the left side of the 'Configurations' panel of Tunnelblick's 'VPN Details' window.
2. Click on the little 'gear' icon at the bottom of the list of configurations. If you can click 'Make Configuration Private…', do so and have a computer administrator authorize the change. (If you can't click it, don't : )
3. Click on the little 'gear' icon and click on 'Edit OpenVPN Configuration File…'. The configuration file will open in Apple's 'TextEdit' editor.
4. Find a line that starts with 'dev-node tun'. If you find one, delete the line. If you dont find one, skip the next step.
5. Look for a line that starts 'dev tun' or 'dev-type tun'. If neither one exists in the file, add a new line that says 'dev tun'.
6. Quit TextEdit, saving the changes if asked.
7. If you previously made the configuration private, make it shared by clicking the little 'gear' icon, clicking 'Make Configuration Shared', and having the change authorized by a computer administrator.

If you made changes to the file and did not change it from shared to private and back to shared, the next time you connect the configuration you will be asked to have a computer administrator authorize the changes.

If macOS still complains

Always load tun or always load tap

If you have a 'tun' VPN which does not need to be modified, or has been modified as described above, and Tunnelblick or macOS Catalina still complains, then you have changed a Tunnelblick setting and should restore it to the default setting. All configurations should be set to 'Load tun driver automatically' and 'Load tap driver automatically'. These settings are found on the 'Connecting & Disconnecting' tab of the 'Advanced' settings window. Recent versions of Tunnelblick will automatically disable loading of 'tun' and 'tap' system extensions on versions of macOS that do not allow Tunnelblick to load them.

Disabling SIP

System Integrity Protection ('SIP') is a feature of macOS which helps keep your computer safe (see About System Integrity Protection on your Mac).

Although it is not recommended because it makes your computer less safe, if you are using macOS Big Sur 11.0.1, disabling SIP may allow your computer to connect a 'tap' VPN. See Configuring System Integrity Protection for instructions to disable SIP.

It has been reported that on macOS Big Sur 11.1.0 disabling SIP is no longer necessary. This has not been verified by the Tunnelblick developers.

Old versions of Tunnelblick will not help

This situation is caused by changes in macOS, not a change in Tunnelblick, so older versions of Tunnelblick will not help. All Macs running OS X 7.5 or later should use the latest stable or beta version of Tunnelblick. See Deprecated Downloads for a version of Tunnelblick that should be used on earlier versions of OS X and on all PowerPC Macs.

What Apple announced

Apple has announced that 'future OS releases will no longer load system extensions that use deprecated KPIs by default'. Tunnelblick includes, and for some configurations loads one of two such extensions:

• 'tap' configurations always require the use of one system extension.
• 'tun' configurations may require the use of the other system extension but can easily be modified so no system extension is required.

It isn't clear what Apple means by the phrase 'by default'. It may mean that Apple will provide a mechanism for users to allow loading of system extensions that use deprecated KPIs. However, Apple's practice has been to make such mechanisms very difficult to use, and the warning in macOS Catalina does not indicate such a mechanism will be provided.

Early versions of macOS Big Sur may allow system extensions to be loaded if SIP is disabled, see Tunnelblick on macOS Big Sur.

On macOS Big Sur 11.1.0 disabling SIP is no longer necessary.

What is Tunnelblick doing about it?

In the short term:

• macOS Catalina loads Tunnelblick's system extensions (which are signed by 'Jonathan Bullard'), but the user must interactively allow this in the Security and Privacy window of System Preferences.

• macOS Big Sur 11.0.1 refuses to load Tunnelblick's existing, notarized system extensions unless SIP is disabled. It isn't known if this behavior will be present in future versions of Big Sur; 11.1.0 does not require SIP to be disabled. Apple's suggested workaround, using an 'installer package', cannot be easily integrated into the Tunnelblick installation process. It is possible that someone else will develop an installer which can load Tunnelblick's system extensions and make it publicly available, but there is no way to know if or when that will happen. (If it does happen, we expect to link to the installer or installers on the Downloads page.)

• Versions of Tunnelblick that are running on macOS Big Sur may disable loading of system extensions. You may override this; see Tunnelblick on macOS Big Sur for details.

• Apple proposes that programs such as Tunnelblick be modified to use a different method to accomplish the function that the system extensions currently perform. The current Tunnelblick developers do not have the time or expertise to use the new method Apple proposes and have no plans to do so. It is possible that someone else will develop such an alternative method and make it publicly available, but there is no way to know if or when that will happen. (If it does happen, we expect to include it in Tunnelblick.)

In the longer term:

At some point in the future when Tunnelblick no longer supports versions of macOS that can load system extensions, system extension loading and unloading will probably be removed from Tunnelblick. Historically, Tunnelblick has supported several years of macOS releases. As of June 2020 Tunnelblick supports OS X and macOS versions as far back as 10.7.5, which was released in 2012, so it is anticipated that the removal will not take place until the mid- to late-2020s.