setting
package
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
- Stable version
When a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Overview¶
Package setting contains types for defining and representing policy settings.It facilitates the registration of setting definitions usingRegister andRegisterDefinition,and the retrieval of registered setting definitions viaDefinitions andDefinitionOf.This package is intended for use primarily within the syspolicy package hierarchy.
Index¶
- Constants
- Variables
- func Register(k pkey.Key, s Scope, t Type, platforms ...string)
- func RegisterDefinition(d *Definition)
- func SetDefaultScope(scope PolicyScope) bool
- func SetDefinitionsForTest(tb testenv.TB, ds ...*Definition) error
- type Definition
- type DefinitionMap
- type ErrorText
- type Origin
- func (s Origin) MarshalJSON() ([]byte, error)
- func (s Origin) MarshalJSONTo(out *jsontext.Encoder) error
- func (s Origin) Name() string
- func (s Origin) Scope() PolicyScope
- func (s Origin) String() string
- func (s *Origin) UnmarshalJSON(b []byte) error
- func (s *Origin) UnmarshalJSONFrom(in *jsontext.Decoder) error
- type PlatformList
- type PolicyScope
- func (s PolicyScope) Contains(s2 PolicyScope) bool
- func (s PolicyScope) IsApplicableSetting(setting *Definition) bool
- func (s PolicyScope) IsConfigurableSetting(setting *Definition) bool
- func (s PolicyScope) Kind() Scope
- func (s PolicyScope) MarshalText() ([]byte, error)
- func (s PolicyScope) StrictlyContains(s2 PolicyScope) bool
- func (s PolicyScope) String() string
- func (s *PolicyScope) UnmarshalText(b []byte) error
- type RawItem
- func (i RawItem) Error() error
- func (i RawItem) MarshalJSON() ([]byte, error)
- func (i RawItem) MarshalJSONTo(out *jsontext.Encoder) error
- func (i RawItem) Origin() *Origin
- func (i RawItem) String() string
- func (i *RawItem) UnmarshalJSON(b []byte) error
- func (i *RawItem) UnmarshalJSONFrom(in *jsontext.Decoder) error
- func (i RawItem) Value() any
- type RawValue
- type RawValueType
- type RawValues
- type Scope
- type Snapshot
- func (s *Snapshot) All() iter.Seq2[pkey.Key, RawItem]
- func (s *Snapshot) Equal(s2 *Snapshot) bool
- func (s *Snapshot) EqualItems(s2 *Snapshot) bool
- func (s *Snapshot) Get(k pkey.Key) any
- func (s *Snapshot) GetErr(k pkey.Key) (any, error)
- func (s *Snapshot) GetSetting(k pkey.Key) (setting RawItem, ok bool)
- func (s *Snapshot) Keys() iter.Seq[pkey.Key]
- func (s *Snapshot) Len() int
- func (s *Snapshot) MarshalJSON() ([]byte, error)
- func (s *Snapshot) MarshalJSONTo(out *jsontext.Encoder) error
- func (s *Snapshot) String() string
- func (s *Snapshot) Summary() Summary
- func (s *Snapshot) UnmarshalJSON(b []byte) error
- func (s *Snapshot) UnmarshalJSONFrom(in *jsontext.Decoder) error
- type Summary
- func (s Summary) IsEmpty() bool
- func (s Summary) MarshalJSON() ([]byte, error)
- func (s Summary) MarshalJSONTo(out *jsontext.Encoder) error
- func (s Summary) Origin() opt.Value[Origin]
- func (s Summary) Scope() opt.Value[PolicyScope]
- func (s Summary) String() string
- func (s *Summary) UnmarshalJSON(b []byte) error
- func (s *Summary) UnmarshalJSONFrom(in *jsontext.Decoder) error
- type SummaryOption
- type Type
- type ValueType
Constants¶
const (// DeviceSetting indicates a policy setting that applies to a device, regardless of// which OS user or Tailscale profile is currently active, if any.// It can only be configured at a [DeviceScope].DeviceSettingScope =iota// ProfileSetting indicates a policy setting that applies to a Tailscale profile.// It can only be configured for a specific profile or at a [DeviceScope],// in which case it applies to all profiles on the device.ProfileSetting// UserSetting indicates a policy setting that applies to users.// It can be configured for a user, profile, or the entire device.UserSetting// NumScopes is the number of possible [Scope] values.NumScopesint =iota// must be the last value in the const block.)
Variables¶
var (// ErrNotConfigured is returned when the requested policy setting is not configured.ErrNotConfigured =errors.New("not configured")// ErrTypeMismatch is returned when there's a type mismatch between the actual type// of the setting value and the expected type.ErrTypeMismatch =errors.New("type mismatch")// ErrNoSuchKey is returned by [DefinitionOf] when no policy setting// has been registered with the specified key.//// Until 2024-08-02, this error was also returned by a [Handler] when the specified// key did 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 =errors.New("no such key"))
var (// DeviceScope indicates a scope containing device-global policies.DeviceScope =PolicyScope{/* contains filtered or unexported fields */}// CurrentProfileScope indicates a scope containing policies that apply to the// currently active Tailscale profile.CurrentProfileScope =PolicyScope{/* contains filtered or unexported fields */}// CurrentUserScope indicates a scope containing policies that apply to the// current user, for whatever that means on the current platform and// in the current application context.CurrentUserScope =PolicyScope{/* contains filtered or unexported fields */})
Functions¶
funcRegister¶
Register registers a policy setting with the specified key, scope, value type,and an optional list of supported platforms. All policy settings must beregistered before any of them can be used. Register panics if called afterinvoking any functions that use the registered policy definitions. Thisincludes callingDefinitions orDefinitionOf directly, or reading anypolicy settings via syspolicy.
funcRegisterDefinition¶
func RegisterDefinition(d *Definition)
RegisterDefinition is likeRegister, but accepts aDefinition.
funcSetDefaultScope¶
func SetDefaultScope(scopePolicyScope)bool
SetDefaultScope attempts to set the specified scope as the default scopeto be used by a program when querying policy settings.It fails and returns false if called more than once, or if theDefaultScopehas already been used.
funcSetDefinitionsForTest¶
func SetDefinitionsForTest(tbtestenv.TB, ds ...*Definition)error
SetDefinitionsForTest allows to register the specified setting definitionsfor the test duration. It is not concurrency-safe, but unlikeRegister,it does not panic and can be called anytime.It returns an error if ds contains two different settings with the same [Key].
Types¶
typeDefinition¶
type Definition struct {// contains filtered or unexported fields}Definition defines policy key, scope and value type.
funcDefinitionOf¶
func DefinitionOf(kpkey.Key) (*Definition,error)
DefinitionOf returns a setting definition by key,orErrNoSuchKey if the specified key does not exist,or an error if there are conflicting policy definitions.
funcDefinitions¶
func Definitions() ([]*Definition,error)
Definitions returns all registered setting definitions,or an error if different policies were registered under the same name.
funcNewDefinition¶
NewDefinition returns a newDefinition with the specifiedkey, scope, type and supported platforms (seePlatformList).
func (*Definition)Equal¶
func (d *Definition) Equal(d2 *Definition)bool
Equal reports whether d and d2 have the same key, type and scope.It does not check whether both s and s2 are supported on the same platforms.
func (*Definition)IsSupported¶
func (d *Definition) IsSupported()bool
IsSupported reports whether the policy setting is supported on the current OS.
func (*Definition)Scope¶
func (d *Definition) Scope()Scope
Scope reports the broadestScope the policy setting may apply to.
func (*Definition)SupportedPlatforms¶
func (d *Definition) SupportedPlatforms()PlatformList
SupportedPlatforms reports platforms on which the policy setting is supported.An emptyPlatformList indicates that s is available on all platforms.
func (*Definition)Type¶
func (d *Definition) Type()Type
Type reports the underlying value type of the policy setting.
typeDefinitionMap¶
type DefinitionMap map[pkey.Key]*Definition
DefinitionMap is a map of settingDefinition by [Key].
funcDefinitionMapOf¶
func DefinitionMapOf(settings []*Definition) (DefinitionMap,error)
DefinitionMapOf returns aDefinitionMap with the specified settings,or an error if any settings have the same key but different type or scope.
typeErrorText¶
type ErrorTextstring
ErrorText represents an error that occurs when reading or parsing a policy setting.This includes errors due to permissions issues, value type and format mismatches,and other platform- or source-specific errors. It does not includeErrNotConfigured andErrNoSuchKey, as those correspond to unconfiguredpolicy settings rather than settings that cannot be read or parseddue to an error.
ErrorText is used to marshal errors when a policy setting is sent over the wire,allowing the error to be logged or displayed. It does not preserve thetype information of the underlying error.
funcMaybeErrorText¶added inv1.74.0
MaybeErrorText returns anErrorText with the text of the specified error,or nil if err is nil,ErrNotConfigured, orErrNoSuchKey.
funcNewErrorText¶
NewErrorText returns aErrorText with the specified error message.
func (ErrorText)MarshalText¶
MarshalText implementsencoding.TextMarshaler.
func (*ErrorText)UnmarshalText¶
UnmarshalText implementsencoding.TextUnmarshaler.
typeOrigin¶
type Origin struct {// contains filtered or unexported fields}Origin describes where a policy or a policy setting is configured.
funcNewNamedOrigin¶
func NewNamedOrigin(namestring, scopePolicyScope) *Origin
NewNamedOrigin returns a newOrigin with the specified scope and name.
funcNewOrigin¶
func NewOrigin(scopePolicyScope) *Origin
NewOrigin returns a newOrigin with the specified scope.
func (Origin)MarshalJSON¶
MarshalJSON implements [json.Marshaler].
func (Origin)MarshalJSONTo¶added inv1.82.0
MarshalJSONTo implementsjsonv2.MarshalerTo.
func (Origin)Name¶
Name returns the name of the policy source where the setting is configured,or "" if not available.
func (Origin)Scope¶
func (sOrigin) Scope()PolicyScope
Scope reports the policyPolicyScope where the setting is configured.
func (*Origin)UnmarshalJSON¶
UnmarshalJSON implements [json.Unmarshaler].
func (*Origin)UnmarshalJSONFrom¶added inv1.82.0
UnmarshalJSONFrom implementsjsonv2.UnmarshalerFrom.
typePlatformList¶
type PlatformList []string
PlatformList is a list of OSes.An empty list indicates that all possible platforms are supported.
func (PlatformList)Has¶
func (lsPlatformList) Has(targetstring)bool
Has reports whether l contains the target platform.
func (PlatformList)HasCurrent¶
func (lsPlatformList) HasCurrent()bool
HasCurrent is like Has, but for the current platform.
typePolicyScope¶
type PolicyScope struct {// contains filtered or unexported fields}PolicyScope is a management scope.
funcDefaultScope¶
func DefaultScope()PolicyScope
DefaultScope returns the defaultPolicyScope to be used by a programwhen querying policy settings.It returnsDeviceScope, unless explicitly changed withSetDefaultScope.
funcUserScopeOf¶
func UserScopeOf(uidstring)PolicyScope
UserScopeOf returns a policyPolicyScope of the user with the specified id.
func (PolicyScope)Contains¶
func (sPolicyScope) Contains(s2PolicyScope)bool
Contains reports whether policy settings that apply to s also apply to s2.For example, policy settings that apply to theDeviceScope also apply totheCurrentUserScope.
func (PolicyScope)IsApplicableSetting¶
func (sPolicyScope) IsApplicableSetting(setting *Definition)bool
IsApplicableSetting reports whether the specified setting applies toand can be retrieved for this scope. Policy settings are applicableto their own scopes as well as more specific scopes. For example,device settings are applicable to device, profile and user scopes,but user settings are only applicable to user scopes.For instance, a menu visibility setting is inherently a user settingand only makes sense in the context of a specific user.
func (PolicyScope)IsConfigurableSetting¶
func (sPolicyScope) IsConfigurableSetting(setting *Definition)bool
IsConfigurableSetting reports whether the specified setting can be configuredby a policy at this scope. Policy settings are configurable at their own scopesas well as broader scopes. For example, [UserSetting]s are configurable inuser, profile, and device scopes, but [DeviceSetting]s are only configurablein theDeviceScope. For instance, the InstallUpdates policy settingcan only be configured in the device scope, as it controls whether updateswill be installed automatically on the device, rather than for specific users.
func (PolicyScope)MarshalText¶
func (sPolicyScope) MarshalText() ([]byte,error)
MarshalText implementsencoding.TextMarshaler.
func (PolicyScope)StrictlyContains¶
func (sPolicyScope) StrictlyContains(s2PolicyScope)bool
StrictlyContains is likePolicyScope.Contains, but returns falsewhen s and s2 is the same scope.
func (*PolicyScope)UnmarshalText¶
func (s *PolicyScope) UnmarshalText(b []byte)error
MarshalText implementsencoding.TextUnmarshaler.
typeRawItem¶
type RawItem struct {// contains filtered or unexported fields}RawItem contains a raw policy setting value as read from a policy store, or anerror if the requested setting could not be read from the store. As a specialcase, it may also hold a value of the [Visibility], [PreferenceOption],ortime.Duration types. While the policy store interface does not supportthese types natively, and the values of these types have to be unmarshalledor converted from strings, these setting types predate the typed policyhierarchies, and must be supported at this layer.
funcRawItemWith¶
RawItemWith returns aRawItem with the specified value, error and origin.
func (RawItem)Error¶
Error returns the error that occurred when reading the policy setting,or nil if no error occurred.
func (RawItem)MarshalJSON¶added inv1.78.0
MarshalJSON implements [json.Marshaler].
func (RawItem)MarshalJSONTo¶added inv1.82.0
MarshalJSONTo implementsjsonv2.MarshalerTo.
func (RawItem)Origin¶
Origin returns an optionalOrigin indicating where the policy setting isconfigured.
func (*RawItem)UnmarshalJSON¶added inv1.78.0
UnmarshalJSON implements [json.Unmarshaler].
func (*RawItem)UnmarshalJSONFrom¶added inv1.82.0
UnmarshalJSONFrom implementsjsonv2.UnmarshalerFrom.
typeRawValue¶added inv1.78.0
RawValue represents a raw policy setting value read from a policy store.It is JSON-marshallable and facilitates unmarshalling of JSON valuesinto corresponding policy setting types, with special handling for JSON numbers(unmarshalled as float64) and JSON string arrays (unmarshalled as []string).See alsoRawValue.UnmarshalJSONFrom.
funcRawValueOf¶added inv1.78.0
func RawValueOf[TRawValueType](v T)RawValue
RawValueOf returns a newRawValue holding the specified value.
func (RawValue)MarshalJSON¶added inv1.78.0
MarshalJSON implements [json.Marshaler].
func (RawValue)MarshalJSONTo¶added inv1.82.0
MarshalJSONTo implementsjsonv2.MarshalerTo.
func (*RawValue)UnmarshalJSON¶added inv1.78.0
UnmarshalJSON implements [json.Unmarshaler].
func (*RawValue)UnmarshalJSONFrom¶added inv1.82.0
UnmarshalJSONFrom implementsjsonv2.UnmarshalerFrom by attempting to unmarshala JSON value as one of the supported policy setting value types (bool, string, uint64, or []string),based on the JSON value type. It fails if the JSON value is an object, if it's a JSON number thatcannot be represented as a uint64, or if a JSON array contains anything other than strings.
typeRawValueType¶added inv1.78.0
RawValueType is a constraint that permits raw setting value types.
typeRawValues¶added inv1.78.0
RawValues is a map of keyed setting values that can be read from a JSON.
typeScope¶
type Scopeint8
Scope indicates the broadest scope at which a policy setting may apply,and the narrowest scope at which it may be configured.
func (Scope)MarshalText¶
MarshalText implementsencoding.TextMarshaler.
func (*Scope)UnmarshalText¶
UnmarshalText implementsencoding.TextUnmarshaler.
typeSnapshot¶
type Snapshot struct {// contains filtered or unexported fields}Snapshot is an immutable collection of ([Key],RawItem) pairs, representinga set of policy settings applied at a specific moment in time.A nil pointer toSnapshot is valid.
funcMergeSnapshots¶
MergeSnapshots returns aSnapshot that contains all [RawItem]sfrom snapshot1 and snapshot2 and theSummary with the narrowerPolicyScope.If there's a conflict between policy settings in the two snapshots,the policy settings from the snapshot with the broader scope take precedence.In other words, policy settings configured for theDeviceScope winover policy settings configured for a user scope.
funcNewSnapshot¶
func NewSnapshot(items map[pkey.Key]RawItem, opts ...SummaryOption) *Snapshot
NewSnapshot returns a newSnapshot with the specified items and options.
func (*Snapshot)All¶
All returns an iterator over policy settings in s. The iteration order is notspecified and is not guaranteed to be the same from one call to the next.
func (*Snapshot)EqualItems¶
EqualItems reports whether items in s and s2 are equal.
func (*Snapshot)Get¶
Get returns the value of the policy setting with the specified keyor nil if it is not configured or has an error.
func (*Snapshot)GetErr¶
GetErr returns the value of the policy setting with the specified key,ErrNotConfigured if it is not configured, or an error returned bythe policy Store if the policy setting could not be read.
func (*Snapshot)GetSetting¶
GetSetting returns the untyped policy setting with the specified key and trueif a policy setting with such key has been configured;otherwise, it returns zero, false.
func (*Snapshot)Keys¶
Keys return an iterator over keys in s. The iteration order is not specifiedand is not guaranteed to be the same from one call to the next.
func (*Snapshot)MarshalJSON¶added inv1.78.0
MarshalJSON implements [json.Marshaler].
func (*Snapshot)MarshalJSONTo¶added inv1.82.0
MarshalJSONTo implementsjsonv2.MarshalerTo.
func (*Snapshot)Summary¶
Summary returns information about s as a whole rather than about specific [RawItem]s in it.
func (*Snapshot)UnmarshalJSON¶added inv1.78.0
UnmarshalJSON implements [json.Unmarshaler].
func (*Snapshot)UnmarshalJSONFrom¶added inv1.82.0
UnmarshalJSONFrom implementsjsonv2.UnmarshalerFrom.
typeSummary¶
type Summary struct {// contains filtered or unexported fields}Summary is an immutablePolicyScope andOrigin.
funcSummaryWith¶
func SummaryWith(opts ...SummaryOption)Summary
SummaryWith returns aSummary with the specified options.
func (Summary)MarshalJSON¶
MarshalJSON implements [json.Marshaler].
func (Summary)MarshalJSONTo¶added inv1.82.0
MarshalJSONTo implementsjsonv2.MarshalerTo.
func (*Summary)UnmarshalJSON¶
UnmarshalJSON implements [json.Unmarshaler].
func (*Summary)UnmarshalJSONFrom¶added inv1.82.0
UnmarshalJSONFrom implementsjsonv2.UnmarshalerFrom.
typeSummaryOption¶
type SummaryOption interface {// contains filtered or unexported methods}SummaryOption is an option that configuresSummaryThe following are allowed options:
typeType¶
type Typeint
Type is a policy setting value type.Except forInvalidValue, which represents an invalid policy setting type,andPreferenceOptionValue,VisibilityValue, andDurationValue,which have special handling due to their legacy status in the package,SettingTypes represent the raw value types readable from policy stores.
const (// InvalidValue indicates an invalid policy setting value type.InvalidValueType =iota// BooleanValue indicates a policy setting whose underlying type is a bool.BooleanValue// IntegerValue indicates a policy setting whose underlying type is a uint64.IntegerValue// StringValue indicates a policy setting whose underlying type is a string.StringValue// StringListValue indicates a policy setting whose underlying type is a []string.StringListValue// PreferenceOptionValue indicates a three-state policy setting whose// underlying type is a string, but the actual value is a [PreferenceOption].PreferenceOptionValue// VisibilityValue indicates a two-state boolean-like policy setting whose// underlying type is a string, but the actual value is a [Visibility].VisibilityValue// DurationValue indicates an interval/period/duration policy setting whose// underlying type is a string, but the actual value is a [time.Duration].DurationValue)
Source Files