syspolicy

Documentation

Overview

Package syspolicy facilitates retrieval of the current policy settings applied to the device or user and receiving notifications when the policy changes.

It provides functions that return specific policy settings by their unique [setting.Key]s, such as GetBoolean, GetUint64, GetString, GetStringArray, GetPreferenceOption, GetVisibility and GetDuration.

Index

• Variables
• func GetBoolean(key Key, defaultValue bool) (bool, error)
• func GetDuration(name Key, defaultValue time.Duration) (time.Duration, error)
• func GetPreferenceOption(name Key) (setting.PreferenceOption, error)
• func GetString(key Key, defaultValue string) (string, error)
• func GetStringArray(key Key, defaultValue []string) ([]string, error)
• func GetUint64(key Key, defaultValue uint64) (uint64, error)
• func GetVisibility(name Key) (setting.Visibility, error)
• func MustRegisterStoreForTest(tb TB, name string, scope setting.PolicyScope, store source.Store) *rsop.StoreRegistration
• func RegisterChangeCallback(cb rsop.PolicyChangeCallback) (unregister func(), err error)
• func RegisterHandler(h Handler)
• func RegisterStore(name string, scope setting.PolicyScope, store source.Store) (*rsop.StoreRegistration, error)
• func RegisterWellKnownSettingsForTest(tb TB)
• func SelectControlURL(reg, disk string) string
• func SetDebugLoggingEnabled(v bool)
• func SetHandlerForTest(tb TB, h Handler)
• func WellKnownSettingDefinition(k Key) (*setting.Definition, error)
• func WrapHandler(h Handler) source.Store
• type Handler
• type Key
• type TB

Variables

var (
	// ErrNotConfigured is returned when the requested policy setting is not configured.
	ErrNotConfigured = setting.ErrNotConfigured
	// ErrTypeMismatch is returned when there's a type mismatch between the actual type
	// of the setting value and the expected type.
	ErrTypeMismatch = setting.ErrTypeMismatch
	// ErrNoSuchKey is returned by [setting.DefinitionOf] when no policy setting
	// has been registered with the specified key.
	//
	// This error is also returned by a (now deprecated) [Handler] when the specified
	// key does not have a value set. While the package maintains compatibility with this
	// usage of ErrNoSuchKey, it is recommended to return [ErrNotConfigured] from newer
	// [source.Store] implementations.
	ErrNoSuchKey = setting.ErrNoSuchKey
)

Functions

func GetBoolean

func GetBoolean(key Key, defaultValue bool) (bool, error)

GetBoolean returns a boolean policy setting with the specified key, or defaultValue if it does not exist.

func GetDuration

func GetDuration(name Key, defaultValue time.Duration) (time.Duration, error)

GetDuration loads a policy from the registry that can be managed by an enterprise policy management system and describes a duration for some action. The registry value should be a string that time.ParseDuration understands. If the registry value is "" or can not be processed, defaultValue is returned instead.

func GetPreferenceOption

func GetPreferenceOption(name Key) (setting.PreferenceOption, error)

GetPreferenceOption loads a policy from the registry that can be managed by an enterprise policy management system and allows administrative overrides of users' choices in a way that we do not want tailcontrol to have the authority to set. It describes user-decides/always/never options, where "always" and "never" remove the user's ability to make a selection. If not present or set to a different value, "user-decides" is the default.

func GetString

func GetString(key Key, defaultValue string) (string, error)

GetString returns a string policy setting with the specified key, or defaultValue if it does not exist.

func GetStringArray

func GetStringArray(key Key, defaultValue []string) ([]string, error)

GetStringArray returns a multi-string policy setting with the specified key, or defaultValue if it does not exist.

func GetUint64

func GetUint64(key Key, defaultValue uint64) (uint64, error)

GetUint64 returns a numeric policy setting with the specified key, or defaultValue if it does not exist.

func GetVisibility

func GetVisibility(name Key) (setting.Visibility, error)

GetVisibility loads a policy from the registry that can be managed by an enterprise policy management system and describes show/hide decisions for UI elements. The registry value should be a string set to "show" (return true) or "hide" (return true). If not present or set to a different value, "show" (return false) is the default.

func MustRegisterStoreForTest

func MustRegisterStoreForTest(tb TB, name string, scope setting.PolicyScope, store source.Store) *rsop.StoreRegistration

MustRegisterStoreForTest is like rsop.RegisterStoreForTest, but it fails the test if the store could not be registered.

func RegisterChangeCallback

func RegisterChangeCallback(cb rsop.PolicyChangeCallback) (unregister func(), err error)

RegisterChangeCallback adds a function that will be called whenever the effective policy for the default scope changes. The returned function can be used to unregister the callback.

func RegisterHandler

func RegisterHandler(h Handler)

RegisterHandler wraps and registers the specified handler as the device's policy source.Store for the program's lifetime.

Deprecated: using RegisterStore should be preferred.

func RegisterStore

func RegisterStore(name string, scope setting.PolicyScope, store source.Store) (*rsop.StoreRegistration, error)

RegisterStore registers a new policy source.Store with the specified name and setting.PolicyScope.

It is a shorthand for rsop.RegisterStore.

func RegisterWellKnownSettingsForTest

func RegisterWellKnownSettingsForTest(tb TB)

RegisterWellKnownSettingsForTest registers all implicit setting definitions for the duration of the test.

func SelectControlURL

func SelectControlURL(reg, disk string) string

SelectControlURL returns the ControlURL to use based on a value in the registry (LoginURL) and the one on disk (in the GUI's prefs.conf). If both are empty, it returns a default value. (It always return a non-empty value)

See https://github.com/tailscale/tailscale/issues/2798 for some background.

func SetDebugLoggingEnabled

func SetDebugLoggingEnabled(v bool)

SetDebugLoggingEnabled controls whether spammy debug logging is enabled.

func SetHandlerForTest

func SetHandlerForTest(tb TB, h Handler)

SetHandlerForTest wraps and sets the specified handler as the device's policy source.Store for the duration of tb.

Deprecated: using MustRegisterStoreForTest should be preferred.

func WellKnownSettingDefinition

func WellKnownSettingDefinition(k Key) (*setting.Definition, error)

WellKnownSettingDefinition returns a well-known, implicit setting definition by its key, or an ErrNoSuchKey if a policy setting with the specified key does not exist among implicit policy definitions.

func WrapHandler

func WrapHandler(h Handler) source.Store

WrapHandler returns a source.Store that wraps the specified Handler.

Types

type Handler

type Handler interface {
	// ReadString reads the policy setting's string value for the given key.
	// It should return ErrNoSuchKey if the key does not have a value set.
	ReadString(key string) (string, error)
	// ReadUInt64 reads the policy setting's uint64 value for the given key.
	// It should return ErrNoSuchKey if the key does not have a value set.
	ReadUInt64(key string) (uint64, error)
	// ReadBool reads the policy setting's boolean value for the given key.
	// It should return ErrNoSuchKey if the key does not have a value set.
	ReadBoolean(key string) (bool, error)
	// ReadStringArray reads the policy setting's string array value for the given key.
	// It should return ErrNoSuchKey if the key does not have a value set.
	ReadStringArray(key string) ([]string, error)
}

Handler reads system policies from OS-specific storage.

Deprecated: implementing a source.Store should be preferred.

type Key

type Key = setting.Key

Key is a string that uniquely identifies a policy and must remain unchanged once established and documented for a given policy setting. It may contain alphanumeric characters and zero or more [KeyPathSeparator]s to group individual policy settings into categories.

const (
	// Keys with a string value
	ControlURL Key = "LoginURL"  // default ""; if blank, ipn uses ipn.DefaultControlURL.
	LogTarget  Key = "LogTarget" // default ""; if blank logging uses logtail.DefaultHost.
	Tailnet    Key = "Tailnet"   // default ""; if blank, no tailnet name is sent to the server.
	// ExitNodeID is the exit node's node id. default ""; if blank, no exit node is forced.
	// Exit node ID takes precedence over exit node IP.
	// To find the node ID, go to /api.md#device.
	ExitNodeID Key = "ExitNodeID"
	ExitNodeIP Key = "ExitNodeIP" // default ""; if blank, no exit node is forced. Value is exit node IP.

	// Keys with a string value that specifies an option: "always", "never", "user-decides".
	// The default is "user-decides" unless otherwise stated. Enforcement of
	// these policies is typically performed in ipnlocal.applySysPolicy(). GUIs
	// typically hide menu items related to policies that are enforced.
	EnableIncomingConnections Key = "AllowIncomingConnections"
	EnableServerMode          Key = "UnattendedMode"
	ExitNodeAllowLANAccess    Key = "ExitNodeAllowLANAccess"
	EnableTailscaleDNS        Key = "UseTailscaleDNSSettings"
	EnableTailscaleSubnets    Key = "UseTailscaleSubnets"
	// CheckUpdates is the key to signal if the updater should periodically
	// check for updates.
	CheckUpdates Key = "CheckUpdates"
	// ApplyUpdates is the key to signal if updates should be automatically
	// installed. Its value is "InstallUpdates" because of an awkwardly-named
	// visibility option "ApplyUpdates" on MacOS.
	ApplyUpdates Key = "InstallUpdates"
	// EnableRunExitNode controls if the device acts as an exit node. Even when
	// running as an exit node, the device must be approved by a tailnet
	// administrator. Its name is slightly awkward because RunExitNodeVisibility
	// predates this option but is preserved for backwards compatibility.
	EnableRunExitNode Key = "AdvertiseExitNode"

	// Keys with a string value that controls visibility: "show", "hide".
	// The default is "show" unless otherwise stated. Enforcement of these
	// policies is typically performed by the UI code for the relevant operating
	// system.
	AdminConsoleVisibility    Key = "AdminConsole"
	NetworkDevicesVisibility  Key = "NetworkDevices"
	TestMenuVisibility        Key = "TestMenu"
	UpdateMenuVisibility      Key = "UpdateMenu"
	ResetToDefaultsVisibility Key = "ResetToDefaults"
	// RunExitNodeVisibility controls if the "run as exit node" menu item is
	// visible, without controlling the setting itself. This is preserved for
	// backwards compatibility but prefer EnableRunExitNode in new deployments.
	RunExitNodeVisibility     Key = "RunExitNode"
	PreferencesMenuVisibility Key = "PreferencesMenu"
	ExitNodeMenuVisibility    Key = "ExitNodesPicker"
	// AutoUpdateVisibility is the key to signal if the menu item for automatic
	// installation of updates should be visible. It is only used by macsys
	// installations and uses the Sparkle naming convention, even though it does
	// not actually control updates, merely the UI for that setting.
	AutoUpdateVisibility Key = "ApplyUpdates"
	// SuggestedExitNodeVisibility controls the visibility of suggested exit nodes in the client GUI.
	// When this system policy is set to 'hide', an exit node suggestion won't be presented to the user as part of the exit nodes picker.
	SuggestedExitNodeVisibility Key = "SuggestedExitNode"
	// OnboardingFlowVisibility controls the visibility of the onboarding flow in the client GUI.
	// When this system policy is set to 'hide', the onboarding flow is never shown to the user.
	OnboardingFlowVisibility Key = "OnboardingFlow"

	// Keys with a string value formatted for use with time.ParseDuration().
	KeyExpirationNoticeTime Key = "KeyExpirationNotice" // default 24 hours

	// Boolean Keys that are only applicable on Windows. Booleans are stored in the registry as
	// DWORD or QWORD (either is acceptable). 0 means false, and anything else means true.
	// The default is 0 unless otherwise stated.
	LogSCMInteractions      Key = "LogSCMInteractions"
	FlushDNSOnSessionUnlock Key = "FlushDNSOnSessionUnlock"

	// PostureChecking indicates if posture checking is enabled and the client shall gather
	// posture data.
	// Key is a string value that specifies an option: "always", "never", "user-decides".
	// The default is "user-decides" unless otherwise stated.
	PostureChecking Key = "PostureChecking"
	// DeviceSerialNumber is the serial number of the device that is running Tailscale.
	// This is used on iOS/tvOS to allow IT administrators to manually give us a serial number via MDM.
	// We are unable to programmatically get the serial number from IOKit due to sandboxing restrictions.
	DeviceSerialNumber Key = "DeviceSerialNumber"

	// ManagedByOrganizationName indicates the name of the organization managing the Tailscale
	// install. It is displayed inside the client UI in a prominent location.
	ManagedByOrganizationName Key = "ManagedByOrganizationName"
	// ManagedByCaption is an info message displayed inside the client UI as a caption when
	// ManagedByOrganizationName is set. It can be used to provide a pointer to support resources
	// for Tailscale within the organization.
	ManagedByCaption Key = "ManagedByCaption"
	// ManagedByURL is a valid URL pointing to a support help desk for Tailscale within the
	// organization. A button in the client UI provides easy access to this URL.
	ManagedByURL Key = "ManagedByURL"

	// AuthKey is an auth key that will be used to login whenever the backend starts. This can be used to
	// automatically authenticate managed devices, without requiring user interaction.
	AuthKey Key = "AuthKey"

	// MachineCertificateSubject is the exact name of a Subject that needs
	// to be present in an identity's certificate chain to sign a RegisterRequest,
	// formatted as per pkix.Name.String(). The Subject may be that of the identity
	// itself, an intermediate CA or the root CA.
	//
	// Example: "CN=Tailscale Inc Test Root CA,OU=Tailscale Inc Test Certificate Authority,O=Tailscale Inc,ST=ON,C=CA"
	MachineCertificateSubject Key = "MachineCertificateSubject"

	// Keys with a string array value.
	// AllowedSuggestedExitNodes's string array value is a list of exit node IDs that restricts which exit nodes are considered when generating suggestions for exit nodes.
	AllowedSuggestedExitNodes Key = "AllowedSuggestedExitNodes"
)

type TB

type TB = internal.TB

TB is a subset of testing.TB that we use to set up test helpers. It's defined here to avoid pulling in the testing package.