Customize Tailscale using system policies
This page contains a list of policies observed by the Tailscale client. You might find these policies useful if you are a system administrator deploying Tailscale in a corporate environment, using a solution like mobile device management (MDM).
Setting these policies can improve the user experience for your users. For instance, you can hide UI items that might be confusing to less tech-savvy individuals in your organization. You can also enforce settings to improve your security posture.
If you need help using any of the settings listed in this document, or would like to suggest any new policies, contact our support or sales teams.
Available settings
Category | Policy key | Supported operating systems |
---|---|---|
UI visibility | AdminConsole | Windows |
UI visibility | ExitNodesPicker | macOS, iOS, Windows |
UI visibility | HiddenNetworkDevices | macOS, iOS |
UI visibility | ManageTailnetLock | macOS, iOS |
UI visibility | NetworkDevices | Windows |
UI visibility | PreferencesMenu | Windows |
UI visibility | ResetToDefaults | macOS |
UI visibility | RunExitNode | macOS, tvOS, Windows |
UI visibility | StartOnLoginMenuItem | macOS |
UI visibility | TestMenu | macOS, Windows |
UI visibility | UpdateMenu | macOS (Standalone variant only), Windows |
UI visibility | VPNOnDemandSettings | macOS, iOS |
Organization customization | ManagedByOrganizationName | macOS, iOS, Windows |
Organization customization | ManagedByCaption | macOS, iOS, Windows |
Organization customization | ManagedByURL | macOS, iOS, Windows |
Auto update functionality | SUEnableAutomaticChecks | macOS (Standalone variant only) |
Auto update functionality | SUAutomaticallyUpdate | macOS (Standalone variant only) |
Auto update functionality | ApplyUpdates | macOS (Standalone variant only) |
Auto update functionality | CheckUpdates | Windows |
Auto update functionality | InstallUpdates | Windows |
Auto update functionality | UnstableUpdates | macOS (Standalone variant only) |
Exit node configuration | ExitNodeID | macOS, iOS, Windows |
Exit node configuration | ExitNodeAllowLANAccess | macOS, iOS, Windows |
Runtime configuration | TailscaleStartOnLogin | macOS |
Runtime configuration | PostureChecking | macOS, Windows |
Runtime configuration | ForceEnabled | macOS, iOS |
Runtime configuration | LoginURL | macOS, iOS, tvOS, Windows |
Runtime configuration | MachineCertificateSubject | Windows |
Runtime configuration | Tailnet | macOS, iOS, tvOS, Windows |
Runtime configuration | KeyExpirationNotice | macOS, iOS, Windows |
Runtime configuration | UnattendedMode | Windows |
Runtime configuration | IPAddressCopiedAlertSuppressed | macOS |
Runtime configuration | TailscaleOnboardingSeen | macOS |
Runtime configuration | UseTailscaleDNSSettings | macOS, iOS, tvOS, Windows |
Runtime configuration | UseTailscaleSubnets | macOS, iOS, tvOS, Windows |
Runtime configuration | AllowIncomingConnections | macOS, iOS, tvOS, Windows |
How to apply system policies
The Tailscale client reads and applies the values of all system policies upon launch, and changing a policy value while Tailscale is running is not supported. Restart the Tailscale client every time you make a modification to a system policy in order to fully apply your changes.
While many of the configuration keys listed on this page are shared between platforms, different steps are required to configure these policies on each.
Windows
The Tailscale client for Windows reads and applies system policies stored in the Windows registry. These can be deployed using MDM solutions such as Microsoft Intune.
For more information, refer to the platform-specific documentation for Windows.
macOS and iOS / tvOS
The Tailscale clients for macOS, iOS, and tvOS read and apply system policies stored in the system user defaults. You can impose these policies by deploying a configuration profile using MDM solutions like Microsoft Intune, Kandji, or SimpleMDM. If you are not using server-based MDM, you can also manually install a configuration profile on target devices using Apple Configurator.
For more information, refer to the platform-specific documentation for macOS or iOS/tvOS.
Available system policies
The following is a list of the system policies observed by the Tailscale clients.
Change the visibility of UI items
Hide the Admin Console menu item
The AdminConsole
policy can be used to show or hide the Admin Console item in the Tailscale menu.
- Supported platforms: Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the exit node picker
The ExitNodesPicker
policy can be used to show or hide all UI items to choose an exit node in the Tailscale client.
- Supported platforms: macOS, iOS, Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide network devices
The HiddenNetworkDevices
policy can be used to hides one or more categories of network devices normally displayed in the Tailscale client. Administrators can choose to hide:
- devices owned by the current user
- devices owned by other users
- tagged devices
If all three options are chosen, the Network Devices menu item disappears entirely and users aren't able to see any device on the tailnet.
- Supported platforms: macOS, iOS
- Possible values: String Array. Use one or more of:
current-user
,other-users
,tagged-devices
. - Added in Tailscale: 1.52
Hide the tailnet lock settings
The ManageTailnetLock
policy can be used to show or hide the Manage Tailnet lock menu item.
- Supported platforms: macOS, iOS
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the Network Devices menu
The NetworkDevices
policy can be used to show or hide the Network Devices menu item from the Tailscale client.
- Deprecated: prefer using "HiddenNetworkDevices" instead, which works on other platforms too.
- Supported platforms: Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the Preferences Menu
The PreferencesMenu
policy can be used to show or hide the Preferences menu item from the Tailscale client.
- Supported platforms: Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the Reset To Defaults menu item
The ResetToDefaults
policy can be used to show or hide the Reset to Defaults menu item in the Tailscale client.
- Supported platforms: macOS
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the Run as Exit Node menu item
The RunExitNode
policy can be used to show or hide the Run as Exit Node menu item.
- Supported platforms: macOS, tvOS, Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the Start on Login menu item
The StartOnLoginMenuItem
policy can be used to show or hide the Start on Login menu item.
- Supported platforms: macOS
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the debug menu
The TestMenu
policy can be used to show or hide the debug menu in the Tailscale client. On macOS, this system policy will also hide any information displayed when holding down the Option key while clicking on the Tailscale menubar item.
- Supported platforms: macOS, Windows
- Possible values:
show
,hide
- Added in Tailscale: 1.50
Hide the update menu
The UpdateMenu
policy can be used to show or hide the Update Tailscale menu option on Windows, and Update Available options on macOS and iOS.
- Supported platforms: Windows, macOS, iOS
- Possible values:
show
,hide
- Added in Tailscale: 1.50 (Windows), 1.56 (macOS, iOS)
Hide the VPN On-Demand menu item
The VPNOnDemandSettings
policy can be used to show or hide the VPN On-Demand menu item. You might want to use this setting if you're deploying your own VPN configuration profile for Tailscale, and you don't want your users to interact with the on-demand VPN configuration you set up for them.
- Supported platforms: iOS
- Possible values:
show
,hide
- Added in Tailscale: 1.52
Show contact information for your organization
Set your organization name
Use the ManagedByOrganizationName
policy to specify the name of the organization managing Tailscale, for instance "XYZ Corp, Inc.".
The value will be displayed in the Tailscale client, so that users can easily reach your internal support resources.
- Supported platforms: macOS, iOS, Windows
- Possible values: any String
- Added in Tailscale: 1.52, 1.62 (Windows)
Set an info message
Use the ManagedByCaption
policy to specify a caption to be displayed in the Managed By view in the Tailscale client. Use this string value to provide your users with information on how to reach support resources for Tailscale in your organization.
- Supported platforms: macOS, iOS, Windows
- Possible values: any String
- Added in Tailscale: 1.52, 1.62 (Windows)
Set a support URL
Use the ManagedByURL
policy to specify a URL pointing to a help desk webpage, or other helpful resources for users in the organization. Clicking the Support button in the Tailscale UI will open this webpage.
- Supported platforms: macOS, iOS, Windows
- Possible values: a valid URL
- Added in Tailscale: 1.52, 1.62 (Windows)
Configure the auto-update settings
Check for updates automatically (macOS)
This system policy exclusively applies to the Standalone variant of Tailscale for macOS. When you download Tailscale from the Mac App Store, the system automatically updates it for you, provided that automatic app updates are enabled.
If you are using the Standalone version of Tailscale for macOS, the client will periodically check for updates automatically and notify the user that a new version is available, using the Sparkle framework. We recommend that you leave this feature on, in order to ensure your users receive any security updates in a timely manner.
However, you might prefer to manually deploy updates and disable notifications of new available versions. To do so, use the boolean policy with key SUEnableAutomaticChecks
. When it is set to true
, the standalone variant of Tailscale for macOS will automatically check for updates. Set this value to false
to disable automatically checking for updates.
- Supported platforms: macOS (Standalone variant only)
- Possible values: Boolean
- Added in Tailscale: 1.46
Install updates automatically (macOS)
This system policy exclusively applies to the Standalone variant of Tailscale for macOS. When you download Tailscale from the Mac App Store, the system automatically updates it for you, provided that automatic app updates are enabled.
If you are using the Standalone version of Tailscale for macOS, the client can also install updates automatically. This feature also relies on the Sparkle framework. We recommend that you always turn this feature on, in order to ensure your users receive any security updates in a timely manner.
However, if you manually manage updates, or prefer your users to be notified but to manually update, you can disable the automatic installation. To do so, use the boolean policy with key SUAutomaticallyUpdate
. When it is set to false
, the standalone variant of Tailscale for macOS will require user input before updates are installed.
- Supported platforms: macOS (Standalone variant only)
- Possible values: Boolean
- Added in Tailscale: 1.52
Hide the auto-update settings (macOS)
This system policy exclusively applies to the Standalone variant of Tailscale for macOS. When you download Tailscale from the Mac App Store, this setting is always hidden in Tailscale. Update settings should instead be managed in the Mac App Store.
If you do not want to allow the user to turn the automatic installation of updates on or off, you can use the ApplyUpdates
policy. When this setting is set to hide
, the Automatically install updates menu item won't be shown to the user, and the user won't be able to configure automatic updates.
- Supported platforms: macOS (Standalone variant only)
- Possible values:
show
,hide
- Added in Tailscale: 1.52
Check for updates automatically (Windows)
The Tailscale client for Windows will periodically check for updates and notify the user that a new version is available. We recommend that you leave this feature on, in order to ensure your users receive any security updates in a timely manner.
However, you might prefer to manually deploy updates and disable notifications of new available versions, or enable auto-updates on all devices. To do so, use the policy with key CheckUpdates
. The default user-decides
value will enable update checks, but allow the user to manually disable them. Set this value to never
to disable automatically checking for updates. Set this value to always
to disallow users to opt-out of update checks.
- Supported platforms: Windows
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Install updates automatically (Windows)
The Tailscale client for Windows can also install updates automatically. We recommend that you always turn this feature on, in order to ensure your users receive any security updates in a timely manner.
To control auto-updates on all devices you can set the key InstallUpdates
in your policy. Setting it to always
enables auto-updates in the client, setting it to never
disables them. The default value user-decides
will use the value set in the Admin panel under Settings > Device management > Auto-update Tailscale, and let the user locally override that value in Tailscale app settings.
- Supported platforms: Windows
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Manage unstable versions availability
Starting in Tailscale v1.60, the Standalone variant of Tailscale for macOS allows a user to opt into receiving unstable releases of the client, with a toggle presented in the Settings user interface:
You can set a value for the UnstableUpdates
policy to force a specific value for this setting. For example, setting UnstableUpdates
to never
means that your users won't be able to update to unstable versions of the client. You can deploy this policy to prevent non-tech-savvy users from enrolling in pre-release builds of the client, which might be more prone to issues.
- Supported platforms: macOS (Standalone variant only)
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.60
Configure the exit node settings
Force an exit node to always be used
The ExitNodeID
policy forces the Tailscale client to always use the given exit node. This can be useful if you wish to route all Internet traffic through a node for inspection or logging purposes. Users won't be able to disable or choose another exit node when this policy is active. A message will be displayed in the client UI informing users about this restriction.
The value for this key should be the ID of an exit node device. You can find the ID for any device in your tailnet by looking at the Machines page of the admin console, or by using the Tailscale API.
Note that if a forced exit node goes offline, Internet connectivity will be unavailable on client devices until the exit node comes back online.
- Supported platforms: Windows, macOS, iOS
- Possible values: String, an exit node ID
- Added in Tailscale: 1.56
Toggle Local Network Access when an exit node is in use
The Allow Local Network Access menu item allows your users to control whether they can still access devices on the local network while using an exit node. If you desire to control this setting on behalf of your users, the ExitNodeAllowLANAccess
policy can be used to do so. For more information about this feature, refer to the Exit Nodes topic.
- Supported platforms: Windows, macOS, iOS
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Other settings
Automatically start Tailscale when the user logs in
The first time the application is opened on a Mac, Tailscale installs a macOS login helper. This allows Tailscale to start automatically when the user logs into their account. The TailscaleStartOnLogin
boolean policy controls whether the login helper should start Tailscale at login time.
- Supported platforms: macOS
- Possible values: Boolean
- Added in Tailscale: 1.46
Enable gathering device posture data
The PostureChecking
policy enables gathering of device posture data.
- Supported platforms: macOS, Windows
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.52
Force Tailscale to always be running
When set to true, the ForceEnabled
boolean policy instructs Tailscale to always be connected and actively monitor the tunnel state for disconnections. The Disconnect toggle will be disabled, to prevent users from disabling the VPN themselves. An attempt to disconnect will present a banner informing the user the organization's policy prevents Tailscale from being disconnected. If the client detects the VPN tunnel is down because the Tailscale VPN process was terminated, Tailscale will automatically restart it and reconnect.
This policy should always be used together with an always-on VPN configuration profile (available on supervised iOS devices). You might also want to set VPNOnDemandSettings
to hide
, to prevent the user from interacting with your on-demand VPN configuration.
- Supported platforms: macOS, iOS
- Possible values: Boolean
- Added in Tailscale: 1.52
Set a custom control server URL
The LoginURL
policy can be used to specify a custom control server URL. This should not be changed unless you are not using the standard Tailscale server. Use this policy if you're deploying your own server, such as Headscale.
- Supported platforms: macOS, iOS, tvOS, Windows
- Possible values:
https://controlplane.tailscale.com
or another Tailscale server instance - Added in Tailscale: 1.4 (Windows), 1.38.1 (macOS, iOS)
- The now-deprecated key
ControlURL
was used in early versions of Tailscale for macOS and iOS
Set a machine certificate subject
The MachineCertificateSubject
policy enables signed registration requests with an externally-provisioned machine certificate. This policy is only applicable to particular enterprise customers and they receive further documentation on how to correctly configure this option.
- Supported platforms: Windows
- Possible values: consult customer-specific documentation
- Added in Tailscale: 1.52
Set a suggested or required tailnet
The Tailnet
policy allows the organization to specify a tailnet, its identity provider will be used on the login page. If the policy value is prefixed with required:
, Tailscale will force that identity provider to be used and won’t allow logging in with anything else.
- Supported platforms: macOS, iOS, tvOS, Windows
- Possible values: a tailnet name, for example:
example.com
orrequired:example.com
- Added in Tailscale: 1.52
Set the key expiration notice period
The KeyExpirationNotice
policy controls how long before key expiry should a notice be displayed. The default is 24 hours.
- Supported platforms: Windows, macOS, iOS
- Possible values: Go-style Duration, for example,
24h
or5h25m30s
- Added in Tailscale: 1.50 (Windows), 1.58 (macOS, iOS)
Set unattended mode
The UnattendedMode
policy sets the Unattended Mode option.
- Supported platforms: Windows
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.52
Set whether the device accepts Tailscale subnets
The UseTailscaleSubnets
policy instructs Tailscale whether to accept subnets advertised by other nodes in your tailnet. This is the equivalent of tailscale up --accept-routes
. If this is off, the device won't reach other devices behind a subnet router. When no value is specified for this policy, Tailscale defaults to true
on Windows, macOS, Android, and iOS and false
on Linux/BSD.
- Supported platforms: Windows, macOS, iOS, tvOS
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Set whether the device uses Tailscale DNS settings
The UseTailscaleDNSSettings
policy instructs Tailscale whether to apply its DNS configuration when the tunnel is connected. This policy is the equivalent to tailscale up --accept-dns
and allows administrators to override the DNS preference chosen by the user when necessary.
- Supported platforms: Windows, macOS, iOS, tvOS
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Set whether to allow incoming connections
The AllowIncomingConnections
policy decides whether Tailscale should allow incoming connections to the device. This blocks any incoming connections over Tailscale by overriding the ACLs to deny access to the device.
- Supported platforms: Windows, macOS, iOS, tvOS
- Possible values:
always
,never
,user-decides
- Added in Tailscale: 1.56
Suppress IP Address Copied notifications
When you use the Tailscale menu bar item to copy to the Clipboard the IP address of a device, a notification displaying the IP address is presented. The IPAddressCopiedAlertSuppressed
policy can be used to suppress this Copied IP address to clipboard notification.
- Supported platforms: macOS
- Possible values: Boolean
- Added in Tailscale: 1.50
Suppress the first launch onboarding flow
When you start Tailscale on your Mac for the first time, an onboarding flow is presented. It explains the Tailscale privacy policy, and guides the user in setting up the VPN configuration on their Mac. You might want to disable this onboarding flow if you are going to automatically set up the VPN configuration on the system by using a configuration profile. In order to do so, the TailscaleOnboardingSeen
boolean policy suppresses the onboarding flow when Tailscale launches for the first time and the value is set to true
.
- Supported platforms: macOS
- Possible values: Boolean
- Added in Tailscale: 1.46