syspolicy

Documentation

Overview

Package syspolicy provides functions to retrieve system settings of a device.

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 RegisterHandler(h Handler)
• func SelectControlURL(reg, disk string) string
• func SetHandlerForTest(tb TB, h Handler)
• type CachingHandler
  • func NewCachingHandler(handler Handler) *CachingHandler
  • func (ch *CachingHandler) ReadBoolean(key string) (bool, error)
  • func (ch *CachingHandler) ReadString(key string) (string, error)
  • func (ch *CachingHandler) ReadStringArray(key string) ([]string, error)
  • func (ch *CachingHandler) ReadUInt64(key string) (uint64, error)
• type Handler
• type Key
• type TB

Variables

var ErrNoSuchKey = errors.New("no such key")

ErrNoSuchKey is returned by a Handler when the specified key does not have a value set.

Functions

func GetBoolean

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

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)

func GetStringArray

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

func GetUint64

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

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 RegisterHandler

func RegisterHandler(h Handler)

RegisterHandler initializes the policy handler and ensures registration will happen once.

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 SetHandlerForTest

func SetHandlerForTest(tb TB, h Handler)

Types

type CachingHandler

type CachingHandler struct {
	// contains filtered or unexported fields
}

CachingHandler is a handler that reads policies from an underlying handler the first time each key is requested and permanently caches the result unless there is an error. If there is an ErrNoSuchKey error, that result is cached, otherwise the actual error is returned and the next read for that key will retry using the handler.

func NewCachingHandler

func NewCachingHandler(handler Handler) *CachingHandler

NewCachingHandler creates a CachingHandler given a handler.

func (*CachingHandler) ReadBoolean

func (ch *CachingHandler) ReadBoolean(key string) (bool, error)

ReadBoolean reads the policy settings boolean value given the key. ReadBoolean first reads from the handler's cache before resorting to using the handler.

func (*CachingHandler) ReadString

func (ch *CachingHandler) ReadString(key string) (string, error)

ReadString reads the policy settings value string given the key. ReadString first reads from the handler's cache before resorting to using the handler.

func (*CachingHandler) ReadStringArray

func (ch *CachingHandler) ReadStringArray(key string) ([]string, error)

ReadBoolean reads the policy settings boolean value given the key. ReadBoolean first reads from the handler's cache before resorting to using the handler.

func (*CachingHandler) ReadUInt64

func (ch *CachingHandler) ReadUInt64(key string) (uint64, error)

ReadUInt64 reads the policy settings uint64 value given the key. ReadUInt64 first reads from the handler's cache before resorting to using the handler.

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.

type Key

type Key = setting.Key

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"

	// 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 interface {
	Helper()
	Cleanup(func())
}

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.