Standard Users Installing or Replacing Configurations

Tunnelblick's "Require administrator authorization to install all configurations" checkbox is checked by default so that authorization by a computer administrator is required for any configuration to be installed or replaced.

If the box is not checked, a standard user (i.e., a non-administrator) will be allowed to install private "non-admin" configurations and make certain updates to configurations without an administrator's authorization.

The checkbox is on the "Preferences" panel of Tunnelblick's "OpenVPN Details" window.

Changing the checkbox can only be done by a computer administrator.

VPN Configurations Can be a Security Risk

VPN Configurations can contain commands or scripts. Because most commands and scripts are run as the 'root' user on macOS, if a standard user creates or modifies such a script they can make changes to the system that they would otherwise not be able to make. This is known as vertical privilege escalation. (Recent versions of macOS include features such as System Integrity Protection introduced in macOS El Capitan, and the dedicated read-only system volume introduced in macOS Catalina, which can limit some of the damage caused by such an escalation of privilege by a malicious user.)

"Non-admin" configurations are configurations whose contents are restricted to avoid the possibility of vertical privilege escalation. However, they may make other changes that could be considered serious risks, including changes to routing and changes to the VPN server's URL. In addition, if the checkbox is not checked it is possible for malware running on the computer to silently create or modify configurations to make such changes. System administrators will need to consider those risks against the benefits of allowing standard users to install or replace configurations.

Installing Configurations

To install a VPN configuration, drag it to the Tunnelblick icon in the menu bar. To install several configurations at one time, select them in Finder and drag all of them at once to the Tunnelblick icon in the menu bar.

A standard user will be allowed to install a new configuration if (A) the checkbox is not checked, (B) the configuration is being installed as a private configuration, and (C) the configuration does not contain any OpenVPN commands or scripts, references to such commands or scripts, or Tunnelblick VPN Configuration scripts that run as root. (Tunnelblick VPN Configuration scripts that run as the user are allowed.) OpenVPN options which invoke or reference scripts or commands include auth-user-pass-verify, client-connect, client-disconnect, config, down, ipchange, iproute, learn-address, plugin, route-pre-down, route-up, tls-verify, and up.

Updating or Replacing Configurations

To replace or update VPN configuration(s), drag the new configuration(s) to the Tunnelblick icon in the menu bar.

Normally when replacing a configuration, the old configuration is completely replaced by the new configuration.

However, a standard user will be allowed to update or replace an existing configuration if (A) the checkbox is not checked, (B) the configuration is being installed as a private configuration, and (C) the new configuration includes only files which are the same as corresponding files already in the configuration except for changes to or the addition of:

• User-mode Tunnelblick scripts (which need not exist in the original configuration); and
• The Info.plist file (which need not exist in the original configuration); and/or
• Certificate and key files (which need not exist in the original configuration); and/or
• The OpenVPN configuration file, but only if it does not contain any OpenVPN options which invoke commands or scripts (see above); and/or
• .DS_Store files, which are ignored.

When updating or replacing configurations this way, the configuration is updated done on a file-by-file basis: each file in a "non-admin" replacement configuration will be copied into the original configuration, overwriting the corresponding file if there is one. Files in the existing configuration which do not appear in the update will be left untouched.

This allows the initial installation by an administrator of a configuration that contains Tunnelblick VPN Configuration scripts that run as root or which otherwise require administrator authorization, but allows common updates to such a configuration to be done by a standard user. Common updates include changes to keys and certificates, changes to encryption, changes to OpenVPN server addresses, and changes to configuration version numbers.