Tips for VPN Service Providers

On This Page
    Tips for VPN Service Providers
        Automatic Installation of Configurations when Tunnelblick is Installed
        Automatic Installation of Forced Preferences when Tunnelblick is Installed
        Non-administrator Installations and Updates of VPN Configurations
        Nested Configurations and Configurations in Folders
        Tunnelblick and Usernames, Passwords, and Passphrases
        Preferences Related to Usernames, Passwords, and Passphrases
        Named Credentials Sets
        Automatic Updating of VPN Configurations
        Automatic Updating of Tunnelblick

Automatic Installation of Configurations when Tunnelblick is Installed

Tunnelblick can install Tunnelblick VPN configurations at the same time that Tunnelblick itself is installed, using the same computer administrator authorization. For details, see Automatically Install Configurations and Forced Preferences.

Automatic Installation of Forced Preferences when Tunnelblick is Installed

Tunnelblick can install "forced" preferences (settings that cannot be modified by a standard user) at the same time that Tunnelblick itself is installed, using the same computer administrator authorization. For details, see Automatically Install Configurations and Forced Preferences.

Non-administrator Installations and Updates of VPN Configurations

For security reasons, by default Tunnelblick requires a computer administrator's authorization to install or update VPN configurations.

However, configurations or changes which are not security sensitive may be installed by a standard user (without authorization by a computer administrator) if a computer administrator has previously un-checked the "Require computer administrator authorization to install all configurations" checkbox on the "Preferences" panel of Tunnelblick's "VPN Details" window.

For details, see Standard Users Installing or Replacing Configurations.

Nested Configurations and Configurations in Folders

Tunnelblick can include one level of configurations within a configuration, and configurations can be contained in folders and subfolders to any depth. For details, see Nested Configurations.

For example,the following single Tunnelblick VPN Configuration sets up six configurations contained in three folders:

    EnclosingConfiguration.tblk/
        USA/
            New York City.tblk
            Miami.tblk
            Los Angeles.tblk
        France/
            Paris/
                UDP.tblk
                TCP.tblk
            Lyons.tblk

"EnclosingConfiguration.tblk" is used as a container for the folder structure that contains the actual VPN configurations. When combined with the "old" method of updating configurations (see below), this allows a single update to contain updates for all configurations.

Tunnelblick and Usernames, Passwords, and Passphrases

OpenVPN setups often use the --auth-user-pass option in client configurations to specify that a username and password are required to connect the VPN, and a passphrase may be required to unlock a private key. OpenVPN asks Tunnelblick for these items as needed. Tunnelblick in turn asks the user for them, and offers the option of saving them in the macOS Keychain so they can be retrieved later by Tunnelblick without asking the user for them. Note that Tunnelblick allows users to paste the username, password, or passphrase; they needn't type them.

Tunnelblick stores the username, password, and/or passphrase for each configuration in the user's login Keychain as an "application" password. Each is saved as a separate Keychain item named "Tunnelblick-Auth-XYZ" where "XYZ" is the name of the configuration. The username is saved in account "username", the password is saved in account "password", and the passphrase is saved in account "privateKey".

Preferences Related to Usernames, Passwords, and Passphrases

There are three per-configuration boolean preferences associated with usernames, passwords, and passphrases:

• -keychainHasUsername
• -keychainHasUsernameAndPassword
• -keychainHasPrivateKey

Each should be prefixed by the name of the configuration to which it applies, e.g. "XYZ-keychainHasUsername".

Note that:

• If any or all of these preferences exist as "forced" preferences, the user is not allowed to save the corresponding item in the Keychain. Otherwise, each preference indicates the existence of the corresponding item or items in the Keychain and is used to avoid unnecessarily accessing the Keychain.

• If you store such items into the Keychain (in an installation script, for example), you should also set the corresponding preference to true so Tunnelblick will use the item.

Named Credentials Sets

Tunnelblick allows configurations to share credentials (usernames, passwords, and passphrases). The user can enter the credentials once for one configuration and save them in the Keychain. After that, other configurations with which the credentials are shared will automatically obtain them from the Keychain as needed without requesting them from the user.

Credentials are shared on Tunnelblick's "Advanced" settings page. A simple checkbox allows all configurations to share the same credentials, or multiple sets of credentials can be created by giving them names, and then selected configurations set to use credentials with those names.

Automatic Updating of VPN Configurations

Tunnelblick has two separate methods for updating configurations:

• The "new" method, which can update only one configuration at a time but is simple to set up and administer; and

• The "old" method, which is powerful and can update multiple configurations at one time but is complex to set up and administer.

Automatic Updating of Tunnelblick

Tunnelblick includes a built-in updater, which checks for updates to the program and offers to update it when an update is available. Updating may be enabled or disabled on the "Preferences" panel of Tunnelblick's "VPN Details" window.

For security reasons, Tunnelblick must always be installed and updated by a computer administrator.