tunnelblick icon Tunnelblick free software for OpenVPN on macOS We need translators for several languages…

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

Preferences

For help configuring and using Tunnelblick, see Using Tunnelblick and the Tunnelblick Discussion Group.

On This Page
        Overview
        Normal and Forced Preferences
        Modifying Preferences
        Program Preferences
        Per-Configuration Preferences

Overview

Much of Tunnelblick's behavior is controlled by more than 200 per-user preferences.

There are two types of preference:

  • Program preferences, which affect Tunnelblick globally (for example, whether or not to check for updates), and
  • Per-configuration preferences, which only affect one configuration.

A few preferences are described below, but complete lists of each type of preference can be found in the source code. In Tunnelblick 3.7.7beta05 and later the lists are in defines.h; prior to that the lists are near the start of MenuController.m.

Normal and Forced Preferences

Normal preferences for a user are stored in ~/Library/Preferences/net.tunnelblick.tunnelblick.plist. (This file should never be manipulated directly because macOS caches it.)

Forced preferences override corresponding normal preferences but can only be changed by a computer administrator. They are contained in files located as follows:

  • In /Applications/Tunnelblick.app/Contents/Resources/Deploy/forced-preferences.plist (see Deploying Tunnelblick).

  • In /Library/Application Support/Tunnelblick/forced-preferences.plist.

The files should be owned by root:wheel and have permissions of 0644.

Modifying Preferences

Commonly-used preferences can be controlled by the Tunnelblick user interface. All other preferences can be modified by:

  • Modifying them using the 'defaults' command in Terminal, e.g. defaults write net.tunnelblick.tunnelblick updateCheckAutomatically -bool yes.
  • Specifying values for them in the Info.plist of a Tunnelblick VPN Configuration.
  • Using Tunnelblick's import/export mechanism (Tunnelblick 3.7.7beta05 and higher).
  • Forcing them, as described above.

If you can't figure out what the name of a preference is or how it works, do a diff on the output of defaults read net.tunnelblick.tunnelblick before and after changing something in Tunnelblick to see what preference changes and how it changes.

Program Preferences

Here are some commonly-used program preferences:

  • placeIconInStandardPositionInStatusBar (Boolean): If set, the Tunnelblick icon will be positioned normally, to the left of the other icons at the time Tunnelblick is started. If cleared or not present, the Tunnelblick icon will be placed between the time display and the Spotlight icon. The default is not present.
  • doNotMonitorConfigurationFolder (Boolean): If set, Tunnelblick does not monitor the ~/Library/Application Support/Tunnelblick/Configurations folder for changes to configuration files. If cleared or not present, Tunnelblick monitors the folder and reacts appropriately to configuration files that are added or removed. If set, Tunnelblick must be restarted before showing added or removed configurations. The default is not present.
  • onlyAdminsCanUnprotectConfigurationFiles (Boolean): If set, the user will be warned that they will only be allowed to examine configuration files when using the "Edit Configuration" button on OS X 10.4 (Tiger) or 10.5 (Leopard) and will be unable to modify them. If cleared or not present, the user will be asked if they wish to unprotect the configuration file before editing it on Tiger or Leopard. On OS X 10.6 (Snow Leopard), this preference is ignored. On Tiger and Leopard, TextEdit will be unable to save a modified configuration file that is protected; on Leopard, TextEdit will silently unprotect the configuration file if it is saved after being modified. The default is not present.
  • doNotCreateLaunchTunnelblickLinkinConfigurations (Boolean): If set, no link will be created. If cleared or not present, Tunnelblick will create a link to itself in the ~/Library/Application Support/Tunnelblick/Configurations folder each time it is started. The default is to create the link.
  • menuIconSet (String): If set, specifies the name of the folder of icons that Tunnelblick should use to display the connection status in the status bar (usually, near the Spotlight icon). The default is "TunnelBlick.TBMenuIcons". The folder must be located in Tunnelblick.app/Contents/Resources/IconSets.
  • doNotShowForcedPreferenceMenuItems (Boolean): If set, any preferences that are forced will not be displayed on the "Options..." submenu. If cleared or not present, such preferences are shown dimmed, and are disabled. The default is not present.
  • doNotShowOptionsSubmenu (Boolean): If set, the "Options..." submenu will not be displayed. If cleared or not present, the submenu will be displayed. The default is not present.
  • doNotShowCheckForUpdatesNowMenuItem (Boolean): If set, the "Check for Updates Now" item on the "Options..." submenu will not be displayed. If cleared or not present, the item will be displayed. The default is not present.
  • updateCheckAutomatically (Boolean): If set, Tunnelblick checks for updates each time it is launched, and periodically thereafter. If cleared or not present, no checking is done. There is no default value; the user is asked if they want to enable automatic updates the first time Tunnelblick is launched and whenever the information that Tunnelblick sends when checking for an update changes (so the user can decide whether or not to include the information).
  • updateSendProfileInfo (Boolean): If set, Tunnelblick will send "system profile" information to the Tunnelblick website when checking for updates. If cleared or not present, no such profile information will be sent when checking for updates. There is no default value; when the user is asked if they want to enable automatic updates the first time Tunnelblick is launched and whenever the information the profile information changes, a check box allows the user to set or clear this value.
  • updateCheckInterval (String or Number): If set, the number of seconds between automatic checks for updates. If not present or empty, the default time (86,400 seconds = 24 hours) is used. If a time less than 3600 seconds (one hour) is specified, it will be changed to 3600 seconds. The default is not present.
  • updateFeedURL (String): If present, the URL to check for updates. If not present or blank, "https://tunnelblick.net/appcast.rss" (for Tunnelblick 3.0b24 and earlier) or "https://tunnelblick.net/updates/update.php" is used. This preference may ONLY be forced; the user's normal preference is ignored for security reasons. The default is not present.
  • updateAutomatically (Boolean): If set, when Tunnelblick detects an update it will be downloaded and installed automatically. If cleared or not present, the user will be asked This preference may ONLY be forced; the user's normal preference is ignored because it can be changed at any time by a Sparkle check box. The default is not present.
  • onlyAdminCanUpdate (Boolean): If set, update checking will be disabled unless the logged-in user is a member of the "administrator" group. If cleared or not present, update checking will be performed even if the user is not a member of the "administrator" gouger. After an update, an administrator username/password will be required to run Tunnelblick (so the new copy can secure itself). The default is not present.
  • updateUUID: This is an anonymous, unique ID string. If updateSendProfileInfo is set, this string is sent to the Tunnelblick update website when checking for updates. It allows the website to count the number of unique Tunnelblick users.
  • skipWarningAboutReprotectingConfigurationFile (Boolean): If set, Tunnelblick on Snow Leopard will not warn the user that any changes made to a configuration file will require an administrator username/password before the changed configuration can be used. If cleared or not present, the warning will be displayed. Default is not present.
  • skipWarningAboutSimultaneousConnections (Boolean): If set, Tunnelblick will not warn the user when a user tries to connect and there is at least one existing connection. If cleared or not present, the warning will be displayed. Default is not present.
  • skipWarningThatCannotModifyConfigurationFile (Boolean): If set, Tunnelblick on Tiger or Leoaprd will not warn the user that any changes made to a configuration file will not be able to be saved. If cleared or not present, the warning will be displayed. Default is not present.
  • skipWarningThatNameChangeDisabledUpdates (Boolean): If set Tunnelblick will warn that an update will fail if the name of Tunnelblick.app has been changed by the user. If cleared or not present, the warning will be displayed. Default is not present.
  • skipWarningAboutNonAdminUpdatingTunnelblick (Boolean): If set, Tunnelblick will not warn a non-administrator user that an update will require an administrator username/password before the changed updated application can be used. If cleared or not present, the warning will be displayed. Default is not present.
  • showConnectedDurations (Boolean): If set, the time that a configuration has been connected is displayed on the configuration's tab in the "Details" window. If cleared, the time is not displayed. The default is set.
  • haveDealtWithSparkle1dot5b6 (Boolean): If set, Tunnelblick has reset the Sparkle Updater preferences for Sparkle version 1.5b6, so the user will be or has been asked about automatically checking for updates and including system profile information. If cleared, this has not been done yet. See the "updateCheckAutomatically" and "updateSendProfileInfo" preferences. The default is not present; Tunnelblick maintains this preference automatically. This preference is ignored if the "updateCheckAutomatically" and "updateSendProfileInfo" preferences are both forced (to any value).
  • detailsWindowFrame: The size and position of the "OpenVPN Log” window when it was last closed.
  • detailsWindowFrameVersion: The version of Tunnelblick that saved the detailsWindowFrame preference.
  • usePrivateConfigurationsWithDeployedOnes and useSharedConfigurationsWithDeployedOnes are booleans which may be used in a Deployed version of Tunnelblick (see Deploying Tunnelblick) to allow simultaneous display of configurations from the Private (~/Library/Application Support/Tunnelblick/Configurations) and Shared (/Library/Application Support/Tunnelblick/Shared) folders, respectively. These preferences must be forced — they will be ignored if they are not forced.
  • skipWarningAboutIgnoredConfigurations is a boolean which controls display of the warning that one or more configurations are being ignored. Configurations are ignored if there are higher priority configurations with the same name. Priorities are, from highest to lowest:
  1. Deployed .tlbk configurations
  2. Deployed .ovpn and .conf configurations
  3. Shared .tblk configurations
  4. Private .tblk configurations
  5. Private .ovpn and .conf configurations

Per-Configuration Preferences

Per-configuration preferences must each be prefixed by the name of the configuration file without the ".conf" or ".ovpn" extension. For example, if a configuration file is named xyz.conf, the preference would be named xyzautoConnect, "xyz-keychainHasUsernameAndPassword", etc.

A preference can be set for all configurations by using the special configuration name of *, as in *autoConnect.

Here are some commonly-used per-configuration preferences:

  • autoConnect (Boolean): If set, Tunnelblick will connect using the configuration when it Tunnelblick is launched. If cleared or not present, the user must connect manually. The user may specify this using the "Automatically Connect on Launch" check box on the "Details" window tab for the configuration. The default is not present (check box not checked).
  • useDNS (Integer): If zero, Tunnelblick does nothing about DNS or WINS while the VPN is connected. If non-zero, Tunnelblick will use scripts before and after a connection is made to save and restore the computer's DNS and WINS settings and set DNS and WINS according to OpenVPN's instructions. The user may specify this using "Set DNS/WINS" on the "Settings" tab of the "Configurations" panel of the "VPN Details" window tab. The default is "Set nameserver". The value of the preference (1-5) indicates which set of scripts will be used, corresponding to the order they appear in "Set DNS/WINS".
  • -notMonitoringConnection (Boolean): If set, Tunnelblick will monitor the network and restart the connection if changes to the network DNS or WINS configurations are detected. If cleared or not present, no monitoring will be done. The user may specify this using the "Monitor Connection" check box on the "Details" window tab for the configuration. This preference is ignored, and the check box is disabled, if the "useDNS" preference is not set (i.e., the "Set Nameserver" check box is not set). The default is set (check box checked).
  • disableEditConfiguration (Boolean): If set, the "Edit Configuration" button on the "Details" window tab for the configuration will be dimmed and disabled. If cleared or not present, the button will be enabled. The default is not present.
  • -useDownRootPlugin (Boolean): If set, Tunnelblick will use its built-in "openvpn-down-root.so" plugin to allow the configuration file to use the "user" and "group" options to stop running the OpenVPN process as root once a connection has been established (as a security measure). See Using Tunnelblick for details. The default is not present.
  • -keychainHasPrivateKey (Boolean): If set, the user's Keychain contains the connection's private key, and Tunnelblick will use it when needed without interacting with the user. If cleared or not present, the user will be asked for the private key if the connection requires it. This preference is set when the user checks the "Save to Keychain" check box on the dialog which asks for the private key. If this preference is forced, it has a special meaning: the check box is not displayed, the private key is not stored in the user's Keychain, and the user is asked each time the connection requires it. The default is not present.
  • -keychainHasUsernameAndPassword (Boolean): If set, the user's Keychain contains the connection's username and password, and Tunnelblick will use them when needed without interacting with the user. If cleared or not present, the user will be asked for the username and password if the connection requires it. This preference is set when the user checks the "Save to Keychain" check box on the dialog which asks for the username and password. If this preference is forced, it has a special meaning: the check box is not displayed, the username and password are not stored in the user's Keychain, and the user is asked each time the connection requires them. The default is not present.
  • disableShareConfigurationButton is a boolean which may be used to inhibit the display of the "Share configuration" / "Make configuration private" button. If absent or false, the button is displayed for all configurations, but is enabled only for Tunnelblick VPN Connection (.tblk) configurations that are not Deployed; it is disabled (dimmed) for non-.tblk and Deployed configurations.