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 GetString(key Key, defaultValue string) (string, error)
• func GetStringArray(key Key, defaultValue []string) ([]string, error)
• func GetUint64(key Key, defaultValue uint64) (uint64, error)
• func RegisterHandler(h Handler)
• func SelectControlURL(reg, disk string) string
• func SetHandlerForTest(tb testing.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 PreferenceOption
  • func GetPreferenceOption(name Key) (PreferenceOption, error)
  • func (p PreferenceOption) ShouldEnable(userChoice bool) bool
  • func (p PreferenceOption) Show() bool
  • func (p PreferenceOption) WillOverride(userChoice bool) bool
• type Visibility
  • func GetVisibility(name Key) (Visibility, error)
  • func (p Visibility) Show() bool

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 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 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 testing.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 string

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"

	// 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"

	// 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 PreferenceOption

type PreferenceOption int

PreferenceOption is a policy that governs whether a boolean variable is forcibly assigned an administrator-defined value, or allowed to receive a user-defined value.

func GetPreferenceOption

func GetPreferenceOption(name Key) (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 (PreferenceOption) ShouldEnable

func (p PreferenceOption) ShouldEnable(userChoice bool) bool

ShouldEnable checks if the choice administered by this policy should be enabled. If the administrator has chosen a setting, the administrator's setting is returned, otherwise userChoice is returned.

func (PreferenceOption) Show

func (p PreferenceOption) Show() bool

Show returns if the UI option that controls the choice administered by this policy should be shown. Currently this is true if and only if the policy is showChoiceByPolicy.

func (PreferenceOption) WillOverride

func (p PreferenceOption) WillOverride(userChoice bool) bool

WillOverride checks if the choice administered by the policy is different from the user's choice.

type Visibility

type Visibility byte

Visibility is a policy that controls whether or not a particular component of a user interface is to be shown.

func GetVisibility

func GetVisibility(name Key) (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 (Visibility) Show

func (p Visibility) Show() bool

Show reports whether the UI option administered by this policy should be shown. Currently this is true if and only if the policy is visibleByPolicy.