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
Modifying Preferences
Commonly-used Program Preferences
Commonly-used Per-Configuration Preferences
List of All Preferences
All Program Preferences
All Per-Configuration Preferences
Debugging 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.
Modifying Preferences
-
Most preferences are set using the Tunnelblick user interface, but all preferences can be modified by a non-admin user with the macOS defaults command, e.g. defaults write net.tunnelblick.tunnelblick updateCheckAutomatically -bool yes . They may also be modified by specifying values for them in the Info.plist of a Tunnelblick VPN Configuration, or using Tunnelblick's import/export mechanism. Note that some preferences are ignored unless they are forced.
-
Forced preferences can only be changed by a computer administrator and always override corresponding normal preferences. They are contained in /Library/Application Support/Tunnelblick/forced-preferences.plist , which must be owned by root:wheel and have permissions of 0644.
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.
Commonly-used Program Preferences
Here are some commonly-used program preferences:
-
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.
-
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.
-
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).
-
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.
-
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.
-
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.
-
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:
- Deployed .tlbk configurations
- Deployed .ovpn and .conf configurations
- Shared .tblk configurations
- Private .tblk configurations
- Private .ovpn and .conf configurations
-
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.
Commonly-used 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.
List of All Preferences
Note that many preferences are used internally by Tunnelblick and should not be modified. Preferences whose name is followed by (must be forced) will be ignored unless they are being forced.
All Program Preferences
The following preferences affect the operation of the Tunnelblick application.
- AdvancedWindowTabIdentifier
- allow64BitIntelOpenvpnOnTigerOrLeopard
- allowNonAdminSafeConfigurationReplacement (must be forced)
- ApplicationCrashedAfterRelaunch
- buildExpirationTimestamp
- chooseSameOpenvpnOverSameSsl
- connectionLogEntrySizeLimit
- connectionLogInitialLoadMultiplier
- connectionLogTickInterval
- connectionWindowDisplayCriteria
- dateLastRequestedEmailCrashReports
- daysBeforeFirstWarningOfOldBuild
- daysToDeferWarningOfOldBuild
- delayBeforeComplainingAboutFailedUpdateCheckBecauseInternetIsOffline,
- delayBeforeConnectingAfterReenablingNetworkServices
- delayBeforeIPAddressCheckAfterConnection
- delayBeforePopupHelp
- delayBeforeReconnectingAfterSleep
- delayBeforeReconnectingAfterSleepAndIpaFetchError
- delayBeforeRetryingUpdateCheckBecauseInternetIsOffline,
- delayBeforeSlowDisconnectDialog
- delayToHideStatistics
- delayToShowStatistics
- detailsWindowConfigurationsTabIdentifier
- detailsWindowFrame
- detailsWindowFrameVersion
- detailsWindowLeftFrame
- detailsWindowViewIndex
- disableAddConfigurationButton
- disableAdvancedButton
- disableCheckNowButton
- disableCopyConfigurationsIntoNewFolderMenuItem
- disableCopyLogToClipboardButton
- disableDeleteConfigurationCredentialsInKeychainMenuItem
- disableDuplicateConfigurationMenuItem
- disableExamineOpenVpnConfigurationFileMenuItem
- disableMakeConfigurationPublicOrPrivateMenuItem
- disableMoveConfigurationsIntoNewFolderMenuItem
- disableRemoveConfigurationButton
- disableRenameConfigurationMenuItem
- disableResetDisabledWarningsButton
- disableRevertToShadowMenuItem
- disableShowHideOnTbMenuItem
- disableShowOpenVpnLogInFinderMenuItem
- disableWorkOnConfigurationButton
- displayUpdateInterval
- doNotCheckForNetworkReachabilityWhenConnecting
- doNotCheckThatOpenvpnVersionIsCompatibleWithConfiguration
- doNotCreateLaunchTunnelblickLinkinConfigurations
- doNotDisconnectForCertificateProblems
- doNotEjectTunnelblickVolume
- doNotIgnoreSignal13
- doNotLaunchOnLogin, /* DISABLE the ability to launch on login provided by launchAtNextLogin */
- doNotMonitorConfigurationFolder
- doNotRedisplayLoginOrPassphraseWindowAtScreenChangeOrWakeFromSleep
- doNotShowAddConfigurationMenuItem
- doNotShowConnectionSubmenus
- doNotShowDisconnectedNotificationWindows
- doNotShowHaveNoConfigurationsGuide
- doNotShowNotificationWindowBelowIconOnMouseover
- doNotShowNotificationWindowOnMouseover
- doNotShowOutlineViewOfConfigurations
- doNotShowSplashScreen
- doNotShowSuggestionOrBugReportMenuItem
- doNotShowVpnDetailsMenuItem
- doNotShowWelcomeDoNotShowAgainCheckbox
- doNotUnrebrandLicenseDescription
- easy-rsaPath
- haveDealtWithAfterDisconnect
- haveDealtWithAlwaysShowLoginWindow
- haveDealtWithOldLoginItem
- haveDealtWithOldTunTapPreferences
- haveStartedAnUpdateOfTheApp
- hookupTimeout
- inhibitOutboundTunneblickTraffic
- IPAddressCheckURL (must be forced)
- keyboardShortcutIndex
- lastConnectedDisplayName
- lastLanguageAtLaunchWasRTL
- lastLaunchTime
- launchAtNextLogin
- leftNavOutlineViewExpandedDisplayNames
- leftNavSelectedDisplayName
- maxConfigurationsForUncachedMenu
- maximumNumberOfTabs
- maximumOpenvpnLogSize
- maxLogDisplaySize
- menuIconSet
- namedCredentialsNames
- namedCredentialsThatAllConfigurationsUse
- notOKToCheckThatIPAddressDidNotChangeAfterConnection
- NSWindow Frame ConnectingWindow
- NSWindow Frame ListingWindow
- NSWindow Frame NSFindPanel
- NSWindow Frame SettingsSheetWindow
- NSWindow Frame SUStatusFrame
- NSWindow Frame SUUpdateAlert
- onlyAdminCanUpdate
- openvpnAllowsDynamicChallengeRegardlessOfAuthRetrySetting
- openvpnVersion
- placeIconInStandardPositionInStatusBar
- showConnectedDurations
- showTooltips
- skipWarningAbout64BitVersionOnNonSnowLeopardPointEight
- skipWarningAbout64BitVersionOnSnowLeopardPointEight
- skipWarningAbout64BitVersionWithTap
- skipWarningAbout64BitVersionWithTunOnSnowLeopardPointEight
- skipWarningAboutAlwaysLoadTunAndOrTapOnFutureMacOS
- skipWarningAboutBigSur1
- skipWarningAboutBigSur1m
- skipWarningAboutBigSur2
- skipWarningAboutBigSur2m
- skipWarningAboutConfigFileProtectedAndAlwaysExamineIt
- skipWarningAboutConvertingToTblks
- skipWarningAboutDevNodeTunOnFutureMacOS
- skipWarningAboutDnsProblems
- skipWarningAboutErrorGettingDnsServers
- skipWarningAboutErrorGettingKnownPublicDnsServers
- skipWarningAboutIgnoredConfigurations
- skipWarningAboutInstallsWithCommands
- skipWarningAboutInvalidSignature
- skipWarningAboutNonAdminUpdatingTunnelblick
- skipWarningAboutNoSignature
- skipWarningAboutNotCheckingIPAddressChanges
- skipWarningAboutOnComputerStartAndTblkScripts
- skipWarningAboutOpenSSL_1_1_1
- skipWarningAboutPlacingIconNearTheSpotlightIcon
- skipWarningAboutPreAuthorizedActivity
- skipWarningAboutReenablingInternetAccessOnConnect
- skipWarningAboutReenablingInternetAccessOnLaunch
- skipWarningAboutReenablingInternetAccessOnQuit
- skipWarningAboutReprotectingConfigurationFile
- skipWarningAboutRosetta
- skipWarningAboutSimultaneousConnections
- skipWarningAboutSystemClock
- skipWarningAboutTapConnectionOnFutureMacOS
- skipWarningAboutUnavailableOpenvpnVersions
- skipWarningAboutUnknownOpenVpnProcesses
- skipWarningAboutWhenSystemStartsConfigurationsThatAreNotConnected
- skipWarningThatCannotModifyConfigurationFile
- skipWarningThatDNSIsNotWorking
- skipWarningThatInternetIsNotReachable
- skipWarningThatIPAddressDidNotChangeAfterConnection
- skipWarningThatIPANotFetchedBeforeConnection
- skipWarningThatNameChangeDisabledUpdates
- skipWarningThatTunnelblickLauncherIsDisabled
- skipWelcomeScreen
- statisticsRateTimeInterval
- statusDisplayNumber
- SUAutomaticallyUpdate
- SUEnableAutomaticChecks
- SUFeedURL
- SUHasLaunchedBefore
- SULastCheckTime
- SULastProfileSubmissionDate
- SUPublicDSAKey (must be forced)
- SUScheduledCheckInterval
- SUSendProfileInfo
- SUSkippedVersion
- TBUpdaterAllowNonAdminToUpdateTunnelblick (must be forced)
- TBUpdaterCheckOnlyWhenConnectedToVPN
- TBUpdaterDownloadUpdateWhenAvailable
- TBUpdateTunnelblickLauncherLastEnabledTime
- TBUpdateVersionStringForDownloadedAppUpdate
- timeoutForDisconnectingConfigurations,
- timeoutForIPAddressCheckAfterConnection
- timeoutForIPAddressCheckAfterSleeping
- timeoutForIPAddressCheckBeforeConnection
- timeoutForOpenvpnToTerminateAfterDisconnectBeforeAssumingItIsReconnecting
- tryToLoadKextsOnThisVersionOfMacOS,
- tunnelblickVersionHistory
- updateCheckAutomatically
- updateCheckBetas
- updateCheckInterval
- updateFeedURL
- usePrivateConfigurationsWithDeployedOnes (must be forced)
- useRtlLayout
- useSharedConfigurationsWithDeployedOnes (must be forced)
- WebKitDefaultFontSize
- WebKitStandardFont
- welcomeHeight
- welcomeURL (must be forced)
- welcomeWidth
All Per-Configuration Preferences
The following preferences affect the operation of the Tunnelblick application for particular configurations. Most, but not all, begin with a hyphen ("-").
-
To affect all configurations, prefix the preference name with an asterisk ("*").
-
To affect only the configuration named XYZ, prefix the preference name with XYZ. (For example, "XYZ-skipWarningAboutDownroot". or "USA/CT/Hartford/tcp-allowChangesToManuallySetNetworkSettings".)
Note that preferences for specific configurations override the "*" preference.
- -allowChangesToManuallySetNetworkSettings
- -authenticateOnConnect (must be forced)
- -changeDNSServersAction
- -changeDomainAction
- -changeNetBIOSNameAction
- -changeOtherDNSServersAction
- -changeOtherDomainAction
- -changeOtherNetBIOSNameAction
- -changeOtherSearchDomainAction
- -changeOtherWINSServersAction
- -changeOtherWorkgroupAction
- -changeSearchDomainAction
- -changeWINSServersAction
- -changeWorkgroupAction
- -consecutiveSuccessfulIPAddressChanges
- -credentialsGroup
- -disableConnectButton
- -disableDisconnectButton
- -disableEditConfiguration
- -disableNetworkAccessAfterDisconnect
- -disableNetworkAccessAfterUnexpectedDisconnect
- -disableSecondaryNetworkServices
- -doNotDisableIpv6onTun
- -doNotDisconnectOnFastUserSwitch
- -doNotDisconnectOnSleep
- -doNotDisconnectWhenTunnelblickQuits
- -doNotFlushCache
- -doNotLoadTapKext
- -doNotLoadTunKext
- -doNotParseConfigurationFile
- -doNotReconnectOnFastUserSwitch
- -doNotReconnectOnUnexpectedDisconnect
- -doNotReconnectOnWakeFromSleep
- -doNotRestoreOnDnsReset
- -doNotRestoreOnWinsReset
- -doNotShowOnTunnelblickMenu
- -doNotUseDefaultDomain
- -doNotWaitForInternetAtBoot
- -enableIpv6OnTap
- -keepConnected
- -keychainHasPrivateKey (must be forced; if forced to any value inhibit saving in the Keychain)
- -keychainHasUsername (must be forced; if forced to any value inhibit saving in the Keychain)
- -keychainHasUsernameAndPassword (must be forced; if forced to any value inhibit saving in the Keychain)
- -lastConnectionSucceeded
- -leasewatchOptions
- -loadTap
- -loadTapKext
- -loadTun
- -loadTunKext
- -loggingLevel
- -loginWindowSecurityTokenCheckboxIsChecked
- -loginWindowSecurityTokenIsHidden
- -notMonitoringConnection
- -notOKToCheckThatIPAddressDidNotChangeAfterConnection
- -onSystemStart
- -openvpnVersion
- -prependDomainNameToSearchDomains
- -resetPrimaryInterfaceAfterDisconnect
- -resetPrimaryInterfaceAfterUnexpectedDisconnect
- -routeAllTrafficThroughVpn
- -runMtuTest
- -skipWarningAboutDownroot
- -skipWarningAboutNoTunOrTap
- -skipWarningThatCannotConnectBecauseOfOpenVPNOptionConflicts
- -skipWarningThatCannotConnectBecauseOfOpenVPNOptions
- -skipWarningThatNotUsingSpecifiedOpenVPN
- -skipWarningUnableToToEstablishOpenVPNLink
- -tunnelDownSoundName
- -tunnelUpSoundName
- -useDownRootPlugin
- -useUpInsteadOfRouteUp
- -waitForDHCPInfoIfTap
- autoConnect
- useDNS
Debugging Preferences
The following preferences will cause extra entries to be made in the macOS log for Tunnelblick – not in the Tunnelblick/OpenVPN log shown in the VPN Details window.
They affect all Tunnelblick operations for all configurations.
- DB-ALL (Boolean): All extra logging
- DB-AA (Boolean): Extra logging for system authorization
- DB-AU (Boolean): Extra logging for VPN authorization
- DB-CD (Boolean): Extra logging for connect/disconnect
- DB-DD (Boolean): Extra logging for drag/drop onto VPN Details window
- DB-D2 (Boolean): Extra logging for drag/drop within the left navigation of the VPN Details window
- DB-HU (Boolean): Extra logging for hookup
- DB-IC (Boolean): Extra logging for IP address checking
- DB-IT (Boolean): Extra logging for IP address check threading
- DB-MC (Boolean): Extra logging for menu cache creation and use
- DB-MO (Boolean): Extra logging for mouseover (of icon and status windows)
- DB-PM (Boolean): Extra logging for password manipulation (password-replace.user.sh, etc.)
- DB-PO (Boolean): Extra logging for populating the NSOutlineView showing configurations
- DB-PU (Boolean): Extra logging for information popups
- DB-SD (Boolean): Extra logging for shutdown
- DB-SI (Boolean): Extra logging for status item creation/deletion/move
- DB-SU (Boolean): Extra logging for startup
- DB-SW (Boolean): Extra logging for sleep/wake and inactive user/active user
- DB-TD (Boolean): Extra logging for tunnelblickd interactions,
- DB-TO (Boolean): Extra logging for terminating OpenVPN processes (via kill, killall, or socket)
- DB-UA (Boolean): Extra logging for updating the application
- DB-UC (Boolean): Extra logging for updating configurations
- DB-UP (Boolean): Extra logging for the up and down scripts
- DB-UU (Boolean): Extra logging for UI updates
|