Documentation ¶
Index ¶
- Variables
- func AppSecurityTag(snapName, appName string) string
- func BadInterfacesSummary(snapInfo *Info) string
- func BaseDataDir(name string) string
- func BaseDir(name string) string
- func CommonDataDir(name string) string
- func DataDir(name string, revision Revision) string
- func DefaultContentProviders(plugs []*PlugInfo) (providerSnapsToContentTag map[string][]string)
- func GuessAppsForBroken(info *Info) map[string]*AppInfo
- func HookSecurityTag(snapName, hookName string) string
- func HooksDir(name string, revision Revision) string
- func InstallDate(name string) time.Time
- func InstanceName(snapName, instanceKey string) string
- func InstanceSnap(instanceName string) string
- func IsHookSupported(hookName string) bool
- func IsSnapd(snapID string) bool
- func JoinSnapApp(snap, app string) string
- func MockAppendSupportedHookTypes(hookTypes []*HookType) (restore func())
- func MockSanitizePlugsSlots(f func(snapInfo *Info)) (restore func())
- func MockSupportedHookTypes(hookTypes []*HookType) (restore func())
- func MountDir(name string, revision Revision) string
- func MountFile(name string, revision Revision) string
- func NeededDefaultProviders(info *Info) (providerSnapsToContentTag map[string][]string)
- func NoneSecurityTag(snapName, uniqueName string) string
- func ScopedSecurityTag(snapName, scopeName, suffix string) string
- func SecurityTag(snapName string) string
- func SplitInstanceName(instanceName string) (snapName, instanceKey string)
- func SplitSnapApp(snapApp string) (snap, app string)
- func UserCommonDataDir(home string, name string) string
- func UserDataDir(home string, name string, revision Revision) string
- func UserSnapDir(home string, name string) string
- func UserXdgRuntimeDir(euid sys.UserID, name string) string
- func ValidAppName(n string) bool
- func Validate(info *Info) error
- func ValidateAlias(alias string) error
- func ValidateApp(app *AppInfo) error
- func ValidateBase(info *Info) error
- func ValidateBasesAndProviders(snapInfos []*Info) []error
- func ValidateCommonIDs(info *Info) error
- func ValidateContainer(c Container, s *Info, logf func(format string, v ...interface{})) error
- func ValidateDesktopPrefix(prefix string) bool
- func ValidateHook(hook *HookInfo) error
- func ValidateInstanceName(instanceName string) error
- func ValidateInterfaceName(name string) error
- func ValidateLayout(layout *Layout, constraints []LayoutConstraint) error
- func ValidateLayoutAll(info *Info) error
- func ValidateLicense(license string) error
- func ValidateLinks(links map[string][]string) error
- func ValidateName(name string) error
- func ValidatePathVariables(path string) error
- func ValidatePlugName(name string) error
- func ValidateSlotName(name string) error
- func ValidateSystemUsernames(info *Info) error
- func ValidateVersion(version string) error
- type AlreadyInstalledError
- type AppInfo
- func (app *AppInfo) CompleterPath() string
- func (app *AppInfo) DesktopFile() string
- func (app *AppInfo) EnvChain() []osutil.ExpandableEnv
- func (app *AppInfo) IsService() bool
- func (app *AppInfo) LauncherCommand() string
- func (app *AppInfo) LauncherPostStopCommand() string
- func (app *AppInfo) LauncherReloadCommand() string
- func (app *AppInfo) LauncherStopCommand() string
- func (app *AppInfo) SecurityTag() string
- func (app *AppInfo) ServiceFile() string
- func (app *AppInfo) ServiceName() string
- func (app *AppInfo) String() string
- func (app *AppInfo) WrapperPath() string
- type AppInfoBySnapApp
- type BrokenSnapError
- type ByType
- type ChannelSnapInfo
- type ConfinementType
- type Container
- type DaemonScope
- type DeltaInfo
- type DownloadInfo
- type Epoch
- func (e *Epoch) CanRead(other Epoch) bool
- func (e *Epoch) Equal(other *Epoch) bool
- func (e *Epoch) IsZero() bool
- func (e Epoch) MarshalJSON() ([]byte, error)
- func (Epoch) MarshalYAML() (interface{}, error)
- func (e Epoch) String() string
- func (e *Epoch) UnmarshalJSON(bs []byte) error
- func (e *Epoch) UnmarshalYAML(unmarshal func(interface{}) error) error
- func (e *Epoch) Validate() error
- type EpochError
- type HookInfo
- type HookType
- type HotplugKey
- type Info
- func (s *Info) CommonDataDir() string
- func (s *Info) CommonDataHomeDir() string
- func (s *Info) Contact() string
- func (s *Info) DataDir() string
- func (s *Info) DataHomeDir() string
- func (s *Info) Description() string
- func (s *Info) DesktopPrefix() string
- func (s *Info) ExpandSnapVariables(path string) string
- func (s *Info) Filename() string
- func (s *Info) HooksDir() string
- func (s *Info) ID() string
- func (s *Info) InstallDate() time.Time
- func (s *Info) InstanceName() string
- func (s *Info) IsActive() bool
- func (s *Info) Links() map[string][]string
- func (s *Info) MountDir() string
- func (s *Info) MountFile() string
- func (s *Info) NeedsClassic() bool
- func (s *Info) NeedsDevMode() bool
- func (s *Info) Services() []*AppInfo
- func (s *Info) SnapName() string
- func (s *Info) SnapRevision() Revision
- func (s *Info) Summary() string
- func (s *Info) Title() string
- func (s *Info) Type() Type
- func (s *Info) UserCommonDataDir(home string) string
- func (s *Info) UserDataDir(home string) string
- func (s *Info) UserXdgRuntimeDir(euid sys.UserID) string
- func (s *Info) XdgRuntimeDirs() string
- type InstallOptions
- type Layout
- type LayoutConstraint
- type MediaInfo
- type MediaInfos
- type NotFoundError
- type NotInstalledError
- type NotSnapError
- type PlaceInfo
- type PlugInfo
- type RestartCondition
- type Revision
- func (r Revision) Local() bool
- func (r Revision) MarshalJSON() ([]byte, error)
- func (r Revision) MarshalYAML() (interface{}, error)
- func (r Revision) Store() bool
- func (r Revision) String() string
- func (r *Revision) UnmarshalJSON(data []byte) error
- func (r *Revision) UnmarshalYAML(unmarshal func(interface{}) error) error
- func (r Revision) Unset() bool
- type ScreenshotInfo
- type ServiceStopReason
- type SideInfo
- type SlotInfo
- type SocketInfo
- type StopModeType
- type StoreAccount
- type SystemUsernameInfo
- type TimerInfo
- type Type
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrBadModes is returned by ValidateContainer when the container has files with the wrong file modes for their role ErrBadModes = errors.New("snap is unusable due to bad permissions") // ErrMissingPaths is returned by ValidateContainer when the container is missing required files or directories ErrMissingPaths = errors.New("snap is unusable due to missing files") )
var ErrUnknownRestartCondition = errors.New("invalid restart condition")
ErrUnknownRestartCondition is returned when trying to unmarshal an unknown restart condition
var RestartMap = map[string]RestartCondition{ "no": RestartNever, "never": RestartNever, "on-success": RestartOnSuccess, "on-failure": RestartOnFailure, "on-abnormal": RestartOnAbnormal, "on-abort": RestartOnAbort, "on-watchdog": RestartOnWatchdog, "always": RestartAlways, }
var SanitizePlugsSlots = func(snapInfo *Info) { panic("SanitizePlugsSlots function not set") }
var SupportedSystemUsernames = map[string]systemUsername{ "snap_daemon": {Id: 584788}, "snap_microk8s": {Id: 584789, AllowedSnapIds: []string{ "EaXqgt1lyCaxKaQCU349mlodBkDCXRcg", }}, }
SupportedSystemUsernames for now contains the hardcoded list of system users (and implied system group of same name) that snaps may specify. This will eventually be moved out of here into the store.
Since the snap is mounted read-only and to avoid problems associated with different systems using different uids and gids for the same user name and group name, snapd will create system-usernames where 'scope' is not 'external' (currently snapd only supports 'scope: shared') with the following characteristics:
- uid and gid shall match for the specified system-username
- a snapd-allocated [ug]id for a user/group name shall never change
- snapd should avoid [ug]ids that are known to overlap with uid ranges of common use cases and user namespace container managers so that DAC and AppArmor owner match work as intended.
- [ug]id shall be < 2^31 to avoid (at least) broken devpts kernel code
- [ug]id shall be >= 524288 (0x00080000) to give plenty of room for large sites, default uid/gid ranges for docker (231072-296608), LXD installs that setup a default /etc/sub{uid,gid} (100000-165536) and podman whose tutorials reference setting up a specific default user and range (100000-165536)
- [ug]id shall be < 1,000,000 and > 1,001,000,000 (ie, 1,000,000 subordinate uid with 1,000,000,000 range) to avoid overlapping with LXD's minimum and maximum id ranges. LXD allows for any id range >= 65536 and doesn't perform any [ug]id overlap detection with current users
- [ug]ids assigned by snapd initially will fall within a 65536 (2^16) range (see below) where the first [ug]id in the range has the 16 lower bits all set to zero. This allows snapd to conveniently be bitwise aligned, follows sensible conventions (see https://systemd.io/UIDS-GIDS.html) but also potentially discoverable by systemd-nspawn (it assigns a different 65536 range to each container. Its allocation algorithm is not sequential and may choose anything within its range that isn't already allocated. It's detection algorithm includes (effectively) performing a getpwent() operation on CANDIDATE_UID & 0XFFFF0000 and selecting another range if it is assigned).
What [ug]id range(s) should snapd use?
While snapd does not employ user namespaces, it will operate on systems with container managers that do and will assign from a range of [ug]ids. It is desirable that snapd assigns [ug]ids that minimally conflict with the system and other software (potential conflicts with admin-assigned ranges in /etc/subuid and /etc/subgid cannot be avoided, but can be documented as well as detected/logged). Overlapping with container managers is non-fatal for snapd and the container, but introduces the possibility that a uid in the container matches a uid a snap is using, which is undesirable in terms of security (eg, DoS via ulimit, same ownership of files between container and snap (even if the other's files are otherwise inaccessible), etc).
snapd shall assign [ug]ids from range(s) of 65536 where the lowest value in the range has the 16 lower bits all set to zero (initially just one range, but snapd can add more as needed).
To avoid [ug]id overlaps, snapd shall only assign [ug]ids >= 524288 (0x00080000) and <= 983040 (0x000F0000, ie the first 65536 range under LXD's minimum where the lower 16 bits are all zeroes). While [ug]ids >= 1001062400 (0x3BAB0000, the first 65536 range above LXD's maximum where the lower 16 bits are all zeroes) would also avoid overlap, considering nested containers (eg, LXD snap runs a container that runs a container that runs snapd), choosing >= 1001062400 would mean that the admin would need to increase the LXD id range for these containers for snapd to be allowed to create its [ug]ids in the deeply nested containers. The requirements would both be an administrative burden and artificially limit the number of deeply nested containers the host could have.
Looking at the LSB and distribution defaults for login.defs, we can observe uids and gids in the system's initial 65536 range (ie, 0-65536):
- 0-99 LSB-suggested statically assigned range (eg, root, daemon, etc)
- 0 mandatory 'root' user
- 100-499 LSB-suggested dynamically assigned range for system users (distributions often prefer a higher range, see below)
- 500-999 typical distribution default for dynamically assigned range for system users (some distributions use a smaller SYS_[GU]ID_MIN)
- 1000-60000 typical distribution default for dynamically assigned range for regular users
- 65535 (-1) should not be assigned since '-1' might be evaluated as this with set[ug]id* and chown families of functions
- 65534 (-2) nobody/nogroup user for NFS/etc [ug]id anonymous squashing
- 65519-65533 systemd recommended reserved range for site-local anonymous additions, etc
To facilitate potential future use cases within the 65536 range snapd will assign from, snapd will only assign from the following subset of ranges relative to the range minimum (ie, its 'base' which has the lower 16 bits all set to zero):
- 60500-60999 'scope: shared' system-usernames - 61000-65519 'scope: private' system-usernames
Since the first [ug]id range must be >= 524288 and <= 983040 (see above) and following the above guide for system-usernames [ug]ids within this 65536 range, the lowest 'scope: shared' user in this range is 584788 (0x0008EC54).
Since this number is within systemd-nspawn's range of 524288-1879048191 (0x00080000-0x6FFFFFFF), the number's lower 16 bits are not all zeroes so systemd-nspawn won't detect this allocation and could potentially assign the 65536 range starting at 0x00080000 to a container. snapd will therefore also create the 'snapd-range-524288-root' user and group with [ug]id 524288 to work within systemd-nspawn's collision detection. This user/group will not be assigned to snaps at this time.
In short (phew!), use the following:
$ snappy-debug.id-range 524288 # 0x00080000 Host range: 524288-589823 (00080000-0008ffff; 0-65535) LSB static range: 524288-524387 (00080000-00080063; 0-99) Useradd system range: 524788-525287 (000801f4-000803e7; 500-999) Useradd regular range: 525288-584288 (000803e8-0008ea60; 1000-60000) Snapd system range: 584788-585287 (0008ec54-0008ee47; 60500-60999) Snapd private range: 585288-589807 (0008ee48-0008ffef; 61000-65519)
Snapd is of course free to add more ranges (eg, 589824 (0x00090000)) with new snapd-range-<base>-root users, or to allocate differently within its 65536 range in the future (sequentially assigned [ug]ids are not required), but for now start very regimented to avoid as many problems as possible.
References: https://forum.snapcraft.io/t/multiple-users-and-groups-in-snaps/ https://systemd.io/UIDS-GIDS.html https://docs.docker.com/engine/security/userns-remap/ https://github.com/lxc/lxd/blob/master/doc/userns-idmap.md
Functions ¶
func AppSecurityTag ¶
AppSecurityTag returns the application-specific security tag.
func BadInterfacesSummary ¶
BadInterfacesSummary returns a summary of the problems of bad plugs and slots in the snap.
func BaseDataDir ¶
BaseDataDir returns the base directory for snap data locations.
func CommonDataDir ¶
CommonDataDir returns the common data directory for given snap name. The name can be either a snap name or snap instance name.
func DataDir ¶
DataDir returns the data directory for given snap name and revision. The name can be either a snap name or snap instance name.
func DefaultContentProviders ¶
DefaultContentProviders returns the set of default provider snaps requested by the given plugs, mapped to their content tags.
func GuessAppsForBroken ¶
GuessAppsForBroken guesses what apps and services a broken snap has on the system by searching for matches based on the snap name in the snap binaries and service file directories. It returns a mapping from app names to partial AppInfo.
func HookSecurityTag ¶
HookSecurityTag returns the hook-specific security tag.
func HooksDir ¶
HooksDir returns the directory containing the snap's hooks for given snap name. The name can be either a snap name or snap instance name.
func InstallDate ¶
InstallDate returns the "install date" of the snap.
If the snap is not active, it'll return a zero time; otherwise it'll return the modtime of the "current" symlink.
func InstanceName ¶
InstanceName takes the snap name and the instance key and returns an instance name of the snap.
func InstanceSnap ¶
InstanceSnap splits the instance name and returns the name of the snap.
func IsHookSupported ¶
IsHookSupported returns true if the given hook name matches one of the supported hooks.
func JoinSnapApp ¶
JoinSnapApp produces a full application wrapper name from the `snap` and the `app` part. It also deals with the special case of snapName == appName.
func MockAppendSupportedHookTypes ¶
func MockAppendSupportedHookTypes(hookTypes []*HookType) (restore func())
func MockSanitizePlugsSlots ¶
func MockSanitizePlugsSlots(f func(snapInfo *Info)) (restore func())
func MockSupportedHookTypes ¶
func MockSupportedHookTypes(hookTypes []*HookType) (restore func())
func MountDir ¶
MountDir returns the base directory where it gets mounted of the snap with the given name and revision.
func NeededDefaultProviders ¶
NeededDefaultProviders returns a map keyed by the names of all default-providers for the content plugs that the given snap.Info needs. The map values are the corresponding content tags.
func NoneSecurityTag ¶
NoneSecurityTag returns the security tag for interfaces that are not associated to an app or hook in the snap.
func ScopedSecurityTag ¶
ScopedSecurityTag returns the snap-specific, scope specific, security tag.
func SecurityTag ¶
SecurityTag returns the snap-specific security tag.
func SplitInstanceName ¶
SplitInstanceName splits the instance name and returns the snap name and the instance key.
func SplitSnapApp ¶
SplitSnapApp will split a string of the form `snap.app` into the `snap` and the `app` part. It also deals with the special case of snapName == appName.
Example ¶
fmt.Println(snap.SplitSnapApp("hello-world.env"))
Output: hello-world env
Example (Short) ¶
fmt.Println(snap.SplitSnapApp("hello-world"))
Output: hello-world hello-world
func UserCommonDataDir ¶
UserCommonDataDir returns the user-specific common data directory for given snap name. The name can be either a snap name or snap instance name.
func UserDataDir ¶
UserDataDir returns the user-specific data directory for given snap name. The name can be either a snap name or snap instance name.
func UserSnapDir ¶
UserSnapDir returns the user-specific directory for given snap name. The name can be either a snap name or snap instance name.
func UserXdgRuntimeDir ¶
UserXdgRuntimeDir returns the user-specific XDG_RUNTIME_DIR directory for given snap name. The name can be either a snap name or snap instance name.
func ValidAppName ¶
ValidAppName tells whether a string is a valid application name.
func ValidateAlias ¶
ValidateAlias checks if a string can be used as an alias name.
func ValidateApp ¶
ValidateApp verifies the content in the app info.
func ValidateBasesAndProviders ¶
ValidateBasesAndProviders checks that all bases/default-providers are part of the seed
func ValidateCommonIDs ¶
func ValidateContainer ¶
ValidateContainer does a minimal sanity check on the container.
func ValidateDesktopPrefix ¶
ValidateDesktopPrefix checks if a string can be used as a desktop file prefix. A desktop prefix should be of the form 'snapname' or 'snapname+instance'.
func ValidateHook ¶
ValidateHook validates the content of the given HookInfo
func ValidateInstanceName ¶
ValidateInstanceName checks if a string can be used as a snap instance name.
func ValidateInterfaceName ¶
ValidateInterfaceName checks if a string can be used as an interface name.
func ValidateLayout ¶
func ValidateLayout(layout *Layout, constraints []LayoutConstraint) error
ValidateLayout ensures that the given layout contains only valid subset of constructs.
func ValidateLayoutAll ¶
ValidateLayoutAll validates the consistency of all the layout elements in a snap.
func ValidateLicense ¶
ValidateLicense checks if a string is a valid SPDX expression.
func ValidateLinks ¶
ValidateLinks checks that links entries have valid keys and values that can be parsed as URLs or are email addresses possibly prefixed with mailto:.
func ValidateName ¶
ValidateName checks if a string can be used as a snap name.
func ValidatePathVariables ¶
ValidatePathVariables ensures that given path contains only $SNAP, $SNAP_DATA or $SNAP_COMMON.
func ValidatePlugName ¶
ValidatePlugName checks if a string can be used as a slot name.
Slot names and plug names within one snap must have unique names. This is not enforced by this function but is enforced by snap-level validation.
func ValidateSlotName ¶
ValidateSlotName checks if a string can be used as a slot name.
Slot names and plug names within one snap must have unique names. This is not enforced by this function but is enforced by snap-level validation.
func ValidateSystemUsernames ¶
func ValidateVersion ¶
ValidateVersion checks if a string is a valid snap version.
Types ¶
type AlreadyInstalledError ¶
type AlreadyInstalledError struct {
Snap string
}
func (AlreadyInstalledError) Error ¶
func (e AlreadyInstalledError) Error() string
type AppInfo ¶
type AppInfo struct { Snap *Info Name string LegacyAliases []string // FIXME: eventually drop this Command string CommandChain []string CommonID string Daemon string DaemonScope DaemonScope StopTimeout timeout.Timeout StartTimeout timeout.Timeout WatchdogTimeout timeout.Timeout StopCommand string ReloadCommand string PostStopCommand string RestartCond RestartCondition RestartDelay timeout.Timeout Completer string RefreshMode string StopMode StopModeType InstallMode string // TODO: this should go away once we have more plumbing and can change // things vs refactor // https://github.com/snapcore/snapd/pull/794#discussion_r58688496 BusName string ActivatesOn []*SlotInfo Plugs map[string]*PlugInfo Slots map[string]*SlotInfo Sockets map[string]*SocketInfo Environment strutil.OrderedMap // list of other service names that this service will start after or // before After []string Before []string Timer *TimerInfo Autostart string }
AppInfo provides information about an app.
func SortServices ¶
SortServices sorts the apps based on their Before and After specs, such that starting the services in the returned ordering will satisfy all specs.
func (*AppInfo) CompleterPath ¶
CompleterPath returns the path to the completer snippet for the app binary.
func (*AppInfo) DesktopFile ¶
DesktopFile returns the path to the installed optional desktop file for the application.
func (*AppInfo) EnvChain ¶
func (app *AppInfo) EnvChain() []osutil.ExpandableEnv
EnvChain returns the chain of environment overrides, possibly with expandable $ vars, specific for the app.
func (*AppInfo) LauncherCommand ¶
LauncherCommand returns the launcher command line to use when invoking the app binary.
func (*AppInfo) LauncherPostStopCommand ¶
LauncherPostStopCommand returns the launcher command line to use when invoking the app post-stop command binary.
func (*AppInfo) LauncherReloadCommand ¶
LauncherReloadCommand returns the launcher command line to use when invoking the app stop command binary.
func (*AppInfo) LauncherStopCommand ¶
LauncherStopCommand returns the launcher command line to use when invoking the app stop command binary.
func (*AppInfo) SecurityTag ¶
SecurityTag returns application-specific security tag.
Security tags are used by various security subsystems as "profile names" and sometimes also as a part of the file name.
func (*AppInfo) ServiceFile ¶
ServiceFile returns the systemd service file path for the daemon app.
func (*AppInfo) ServiceName ¶
ServiceName returns the systemd service name for the daemon app.
func (*AppInfo) WrapperPath ¶
WrapperPath returns the path to wrapper invoking the app binary.
type AppInfoBySnapApp ¶
type AppInfoBySnapApp []*AppInfo
AppInfoBySnapApp supports sorting the given slice of app infos by (instance name, app name).
func (AppInfoBySnapApp) Len ¶
func (a AppInfoBySnapApp) Len() int
func (AppInfoBySnapApp) Less ¶
func (a AppInfoBySnapApp) Less(i, j int) bool
func (AppInfoBySnapApp) Swap ¶
func (a AppInfoBySnapApp) Swap(i, j int)
type BrokenSnapError ¶
BrokenSnapError describes an error that refers to a snap that warrants the "broken" note.
type ByType ¶
type ByType []*Info
ByType supports sorting the given slice of snap info by types. The most important types will come first.
type ChannelSnapInfo ¶
type ChannelSnapInfo struct { Revision Revision `json:"revision"` Confinement ConfinementType `json:"confinement"` Version string `json:"version"` Channel string `json:"channel"` Epoch Epoch `json:"epoch"` Size int64 `json:"size"` ReleasedAt time.Time `json:"released-at"` }
ChannelSnapInfo is the minimum information that can be used to clearly distinguish different revisions of the same snap.
type ConfinementType ¶
type ConfinementType string
ConfinementType represents the kind of confinement supported by the snap (devmode only, or strict confinement)
const ( DevModeConfinement ConfinementType = "devmode" ClassicConfinement ConfinementType = "classic" StrictConfinement ConfinementType = "strict" )
The various confinement types we support
func (*ConfinementType) UnmarshalJSON ¶
func (confinementType *ConfinementType) UnmarshalJSON(data []byte) error
UnmarshalJSON sets *confinementType to a copy of data, assuming validation passes
func (*ConfinementType) UnmarshalYAML ¶
func (confinementType *ConfinementType) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML so ConfinementType implements yaml's Unmarshaler interface
type Container ¶
type Container interface { // Size returns the size of the snap in bytes. Size() (int64, error) // RandomAccessFile returns an implementation to read at any // given location for a single file inside the snap plus // information about the file size. RandomAccessFile(relative string) (interface { io.ReaderAt io.Closer Size() int64 }, error) // ReadFile returns the content of a single file from the snap. ReadFile(relative string) ([]byte, error) // Walk is like filepath.Walk, without the ordering guarantee. Walk(relative string, walkFn filepath.WalkFunc) error // ListDir returns the content of a single directory inside the snap. ListDir(path string) ([]string, error) // Install copies the snap file to targetPath (and possibly unpacks it to mountDir). // The bool return value indicates if the backend had nothing to do on install. Install(targetPath, mountDir string, opts *InstallOptions) (bool, error) // Unpack unpacks the src parts to the dst directory Unpack(src, dst string) error }
Container is the interface to interact with the low-level snap files.
type DaemonScope ¶
type DaemonScope string
DaemonScope represents the scope of the daemon running under systemd
const ( SystemDaemon DaemonScope = "system" UserDaemon DaemonScope = "user" )
func (*DaemonScope) UnmarshalJSON ¶
func (daemonScope *DaemonScope) UnmarshalJSON(data []byte) error
UnmarshalJSON sets *daemonScope to a copy of data, assuming validation passes
func (*DaemonScope) UnmarshalYAML ¶
func (daemonScope *DaemonScope) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML so DaemonScope implements yaml's Unmarshaler interface
type DeltaInfo ¶
type DeltaInfo struct { FromRevision int `json:"from-revision,omitempty"` ToRevision int `json:"to-revision,omitempty"` Format string `json:"format,omitempty"` AnonDownloadURL string `json:"anon-download-url,omitempty"` DownloadURL string `json:"download-url,omitempty"` Size int64 `json:"size,omitempty"` Sha3_384 string `json:"sha3-384,omitempty"` }
DeltaInfo contains the information to download a delta from one revision to another.
type DownloadInfo ¶
type DownloadInfo struct { AnonDownloadURL string `json:"anon-download-url,omitempty"` DownloadURL string `json:"download-url,omitempty"` Size int64 `json:"size,omitempty"` Sha3_384 string `json:"sha3-384,omitempty"` // The server can include information about available deltas for a given // snap at a specific revision during refresh. Currently during refresh the // server will provide single matching deltas only, from the clients // revision to the target revision when available, per requested format. Deltas []DeltaInfo `json:"deltas,omitempty"` }
DownloadInfo contains the information to download a snap. It can be marshalled.
type Epoch ¶
An Epoch represents the ability of the snap to read and write its data. Most developers need not worry about it, and snaps default to the 0th epoch, and users are only offered refreshes to epoch 0 snaps. Once an epoch bump is in order, there's a simplified expression they can use which should cover the majority of the cases:
epoch: N
means a snap can read/write exactly the Nth epoch's data, and
epoch: N*
means a snap can additionally read (N-1)th epoch's data, which means it's a snap that can migrate epochs (so a user on epoch 0 can get offered a refresh to a snap on epoch 1*).
If the above is not enough, a developer can explicitly describe what epochs a snap can read and write:
epoch: read: [1, 2, 3] write: [1, 3]
the read attribute defaults to the value of the write attribute, and the write attribute defaults to the last item in the read attribute. If both are unset, it's the same as not specifying an epoch at all (i.e. epoch: 0). The lists must not have more than 10 elements, they must be strictly increasing, and there must be a non-empty intersection between them.
Epoch numbers must be written in base 10, with no zero padding.
func E ¶
E returns the epoch represented by the expression s. It's meant for use in testing, as it panics at the first sign of trouble.
func (*Epoch) CanRead ¶
CanRead checks whether this epoch can read the data written by the other one.
func (*Epoch) IsZero ¶
IsZero checks whether a snap's epoch is not set (or is set to the default value of "0"). Also zero are some epochs that would be normalized to "0", such as {"read": 0}, as well as some invalid ones like {"read": []}.
func (Epoch) MarshalJSON ¶
func (Epoch) MarshalYAML ¶
func (*Epoch) UnmarshalJSON ¶
func (*Epoch) UnmarshalYAML ¶
type EpochError ¶
type EpochError struct {
Message string
}
EpochError tracks the details of a failed epoch parse or validation.
func (EpochError) Error ¶
func (e EpochError) Error() string
type HookInfo ¶
type HookInfo struct { Snap *Info Name string Plugs map[string]*PlugInfo Slots map[string]*SlotInfo Environment strutil.OrderedMap CommandChain []string Explicit bool }
HookInfo provides information about a hook.
func (*HookInfo) EnvChain ¶
func (hook *HookInfo) EnvChain() []osutil.ExpandableEnv
EnvChain returns the chain of environment overrides, possibly with expandable $ vars, specific for the hook.
func (*HookInfo) SecurityTag ¶
SecurityTag returns the hook-specific security tag.
Security tags are used by various security subsystems as "profile names" and sometimes also as a part of the file name.
type HookType ¶
type HookType struct {
// contains filtered or unexported fields
}
HookType represents a pattern of supported hook names.
func NewHookType ¶
NewHookType returns a new HookType with the given pattern.
type HotplugKey ¶
type HotplugKey string
HotplugKey is a string key of a hotplugged device
func (HotplugKey) ShortString ¶
func (h HotplugKey) ShortString() string
ShortString returns a truncated string representation of the hotplug key
type Info ¶
type Info struct { SuggestedName string InstanceKey string Version string SnapType Type Architectures []string Assumes []string OriginalTitle string OriginalSummary string OriginalDescription string Environment strutil.OrderedMap LicenseAgreement string LicenseVersion string License string Epoch Epoch Base string Confinement ConfinementType Apps map[string]*AppInfo LegacyAliases map[string]*AppInfo // FIXME: eventually drop this Hooks map[string]*HookInfo Plugs map[string]*PlugInfo Slots map[string]*SlotInfo // Plugs or slots with issues (they are not included in Plugs or Slots) BadInterfaces map[string]string // slot or plug => message // The information in all the remaining fields is not sourced from the snap // blob itself. SideInfo // Broken marks whether the snap is broken and the reason. Broken string // The information in these fields is ephemeral, available only from the // store. DownloadInfo Prices map[string]float64 MustBuy bool Publisher StoreAccount Media MediaInfos Website string StoreURL string // The flattended channel map with $track/$risk Channels map[string]*ChannelSnapInfo // The ordered list of tracks that contain channels Tracks []string Layout map[string]*Layout // The list of common-ids from all apps of the snap CommonIDs []string // List of system users (usernames) this snap may use. The group of the same // name must also exist. SystemUsernames map[string]*SystemUsernameInfo // OriginalLinks is a map links keys to link lists OriginalLinks map[string][]string }
Info provides information about snaps.
func InfoFromSnapYaml ¶
InfoFromSnapYaml creates a new info based on the given snap.yaml data
func ReadCurrentInfo ¶
ReadCurrentInfo reads the snap information from the installed snap in 'current' revision
func ReadInfo ¶
ReadInfo reads the snap information for the installed snap with the given name and given side-info.
func ReadInfoFromSnapFile ¶
ReadInfoFromSnapFile reads the snap information from the given Container and completes it with the given side-info if this is not nil.
func (*Info) CommonDataDir ¶
CommonDataDir returns the data directory common across revisions of the snap.
func (*Info) CommonDataHomeDir ¶
CommonDataHomeDir returns the per user data directory common across revisions of the snap.
func (*Info) DataHomeDir ¶
DataHomeDir returns the per user data directory of the snap.
func (*Info) Description ¶
Description returns the blessed description for the snap.
func (*Info) DesktopPrefix ¶
DesktopPrefix returns the prefix string for the desktop files that belongs to the given snapInstance. We need to do something custom here because a) we need to be compatible with the world before we had parallel installs b) we can't just use the usual "_" parallel installs separator because that is already used as the separator between snap and desktop filename.
func (*Info) ExpandSnapVariables ¶
ExpandSnapVariables resolves $SNAP, $SNAP_DATA and $SNAP_COMMON inside the snap's mount namespace.
func (*Info) Filename ¶
Filename returns the name of the snap with the revision number, as used on the filesystem. This is the equivalent of filepath.Base(s.MountFile()).
func (*Info) InstallDate ¶
InstallDate returns the "install date" of the snap.
If the snap is not active, it'll return a zero time; otherwise it'll return the modtime of the "current" symlink. Sneaky.
func (*Info) InstanceName ¶
InstanceName returns the blessed name of the snap decorated with instance key, if any.
func (*Info) MountFile ¶
MountFile returns the path where the snap file that is mounted is installed.
func (*Info) NeedsClassic ¶
NeedsClassic returns whether the snap needs classic confinement consent.
func (*Info) NeedsDevMode ¶
NeedsDevMode returns whether the snap needs devmode.
func (*Info) SnapRevision ¶
SnapRevision returns the revision of the snap.
func (*Info) Type ¶
Type returns the type of the snap, including additional snap ID check for the legacy snapd snap definitions.
func (*Info) UserCommonDataDir ¶
UserCommonDataDir returns the user-specific data directory common across revision of the snap.
func (*Info) UserDataDir ¶
UserDataDir returns the user-specific data directory of the snap.
func (*Info) UserXdgRuntimeDir ¶
UserXdgRuntimeDir returns the XDG_RUNTIME_DIR directory of the snap for a particular user.
func (*Info) XdgRuntimeDirs ¶
XdgRuntimeDirs returns the XDG_RUNTIME_DIR directories for all users of the snap.
type InstallOptions ¶
type InstallOptions struct { // MustNotCrossDevices indicates that the snap file when installed to the // target must not cross devices. For example, installing a snap file from // the ubuntu-seed partition onto the ubuntu-data partition must result in // an installation on ubuntu-data that does not depend or reference // ubuntu-seed at all. MustNotCrossDevices bool }
InstallOptions is for customizing the behavior of Install() from a higher level function, i.e. from overlord customizing how a snap file is installed on a system with tmpfs mounted as writable or with full disk encryption and graded secured on UC20.
type Layout ¶
type Layout struct { Snap *Info Path string `json:"path"` Bind string `json:"bind,omitempty"` BindFile string `json:"bind-file,omitempty"` Type string `json:"type,omitempty"` User string `json:"user,omitempty"` Group string `json:"group,omitempty"` Mode os.FileMode `json:"mode,omitempty"` Symlink string `json:"symlink,omitempty"` }
Layout describes a single element of the layout section.
type LayoutConstraint ¶
LayoutConstraint abstracts validation of conflicting layout elements.
type MediaInfos ¶
type MediaInfos []MediaInfo
func (MediaInfos) IconURL ¶
func (mis MediaInfos) IconURL() string
type NotFoundError ¶
type NotFoundError struct { Snap string Revision Revision // Path encodes the path that triggered the not-found error. It may refer to // a file inside the snap or to the snap file itself. Path string }
func (NotFoundError) Broken ¶
func (e NotFoundError) Broken() string
func (NotFoundError) Error ¶
func (e NotFoundError) Error() string
type NotInstalledError ¶
func (NotInstalledError) Error ¶
func (e NotInstalledError) Error() string
type NotSnapError ¶
type NotSnapError struct {
Path string
}
func (NotSnapError) Error ¶
func (e NotSnapError) Error() string
type PlaceInfo ¶
type PlaceInfo interface { // InstanceName returns the name of the snap decorated with instance // key, if any. InstanceName() string // SnapName returns the name of the snap. SnapName() string // SnapRevision returns the revision of the snap. SnapRevision() Revision // Filename returns the name of the snap with the revision // number, as used on the filesystem. Filename() string // MountDir returns the base directory of the snap. MountDir() string // MountFile returns the path where the snap file that is mounted is // installed. MountFile() string // HooksDir returns the directory containing the snap's hooks. HooksDir() string // DataDir returns the data directory of the snap. DataDir() string // UserDataDir returns the per user data directory of the snap. UserDataDir(home string) string // CommonDataDir returns the data directory common across revisions of the // snap. CommonDataDir() string // UserCommonDataDir returns the per user data directory common across // revisions of the snap. UserCommonDataDir(home string) string // UserXdgRuntimeDir returns the per user XDG_RUNTIME_DIR directory UserXdgRuntimeDir(userID sys.UserID) string // DataHomeDir returns the a glob that matches all per user data directories // of a snap. DataHomeDir() string // CommonDataHomeDir returns a glob that matches all per user data // directories common across revisions of the snap. CommonDataHomeDir() string // XdgRuntimeDirs returns a glob that matches all XDG_RUNTIME_DIR // directories for all users of the snap. XdgRuntimeDirs() string }
PlaceInfo offers all the information about where a snap and its data are located and exposed in the filesystem.
func MinimalPlaceInfo ¶
MinimalPlaceInfo returns a PlaceInfo with just the location information for a snap of the given name and revision.
func ParsePlaceInfoFromSnapFileName ¶
ParsePlaceInfoFromSnapFileName returns a PlaceInfo with just the location information for a snap of file name, failing if the snap file name is invalid This explicitly does not support filenames with instance names in them
type PlugInfo ¶
type PlugInfo struct { Snap *Info Name string Interface string Attrs map[string]interface{} Label string Apps map[string]*AppInfo Hooks map[string]*HookInfo }
PlugInfo provides information about a plug.
func (*PlugInfo) SecurityTags ¶
SecurityTags returns security tags associated with a given plug.
type RestartCondition ¶
type RestartCondition string
RestartCondition encapsulates the different systemd 'restart' options
const ( RestartNever RestartCondition = "never" RestartOnSuccess RestartCondition = "on-success" RestartOnFailure RestartCondition = "on-failure" RestartOnAbnormal RestartCondition = "on-abnormal" RestartOnAbort RestartCondition = "on-abort" RestartOnWatchdog RestartCondition = "on-watchdog" RestartAlways RestartCondition = "always" )
These are the supported restart conditions
func (RestartCondition) String ¶
func (rc RestartCondition) String() string
func (*RestartCondition) UnmarshalYAML ¶
func (rc *RestartCondition) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML so RestartCondition implements yaml's Unmarshaler interface
type Revision ¶
type Revision struct {
N int
}
func ParseRevision ¶
ParseRevisions returns the representation in r as a revision. See R for a function more suitable for hardcoded revisions.
func R ¶
func R(r interface{}) Revision
R returns a Revision given an int or a string. Providing an invalid revision type or value causes a runtime panic. See ParseRevision for a polite function that does not panic.
func (Revision) MarshalJSON ¶
func (Revision) MarshalYAML ¶
func (*Revision) UnmarshalJSON ¶
func (*Revision) UnmarshalYAML ¶
type ScreenshotInfo ¶
type ScreenshotInfo struct { URL string `json:"url,omitempty"` Width int64 `json:"width,omitempty"` Height int64 `json:"height,omitempty"` Note string `json:"note,omitempty"` }
ScreenshotInfo provides information about a screenshot.
type ServiceStopReason ¶
type ServiceStopReason string
const ( StopReasonRefresh ServiceStopReason = "refresh" StopReasonRemove ServiceStopReason = "remove" StopReasonDisable ServiceStopReason = "disable" StopReasonOther ServiceStopReason = "" )
type SideInfo ¶
type SideInfo struct { RealName string `yaml:"name,omitempty" json:"name,omitempty"` SnapID string `yaml:"snap-id" json:"snap-id"` Revision Revision `yaml:"revision" json:"revision"` Channel string `yaml:"channel,omitempty" json:"channel,omitempty"` EditedLinks map[string][]string `yaml:"links,omitempty" json:"links,omitempty"` EditedContact string `yaml:"contact,omitempty" json:"contact,omitempty"` EditedTitle string `yaml:"title,omitempty" json:"title,omitempty"` EditedSummary string `yaml:"summary,omitempty" json:"summary,omitempty"` EditedDescription string `yaml:"description,omitempty" json:"description,omitempty"` Private bool `yaml:"private,omitempty" json:"private,omitempty"` Paid bool `yaml:"paid,omitempty" json:"paid,omitempty"` }
SideInfo holds snap metadata that is crucial for the tracking of snaps and for the working of the system offline and which is not included in snap.yaml or for which the store is the canonical source overriding snap.yaml content.
It can be marshalled and will be stored in the system state for each currently installed snap revision so it needs to be evolved carefully.
Information that can be taken directly from snap.yaml or that comes from the store but is not required for working offline should not end up in SideInfo.
type SlotInfo ¶
type SlotInfo struct { Snap *Info Name string Interface string Attrs map[string]interface{} Label string Apps map[string]*AppInfo Hooks map[string]*HookInfo // HotplugKey is a unique key built by the slot's interface // using properties of a hotplugged device so that the same // slot may be made available if the device is reinserted. // It's empty for regular slots. HotplugKey HotplugKey }
SlotInfo provides information about a slot.
func (*SlotInfo) SecurityTags ¶
SecurityTags returns security tags associated with a given slot.
type SocketInfo ¶
SocketInfo provides information on application sockets.
func (*SocketInfo) File ¶
func (socket *SocketInfo) File() string
File returns the path to the *.socket file
type StopModeType ¶
type StopModeType string
StopModeType is the type for the "stop-mode:" of a snap app
func (StopModeType) KillAll ¶
func (st StopModeType) KillAll() bool
KillAll returns if the stop-mode means all processes should be killed when the service is stopped or just the main process.
func (StopModeType) KillSignal ¶
func (st StopModeType) KillSignal() string
KillSignal returns the signal that should be used to kill the process (or an empty string if no signal is needed).
func (StopModeType) Validate ¶
func (st StopModeType) Validate() error
Validate ensures that the StopModeType has an valid value.
type StoreAccount ¶
type StoreAccount struct { ID string `json:"id"` Username string `json:"username"` DisplayName string `json:"display-name"` Validation string `json:"validation,omitempty"` }
StoreAccount holds information about a store account, for example of snap publisher.
type SystemUsernameInfo ¶
SystemUsernameInfo provides information about a system username (ie, a UNIX user and group with the same name). The scope defines visibility of the username wrt the snap and the system. Defined scopes:
- shared static, snapd-managed user/group shared between host and all snaps
- private static, snapd-managed user/group private to a particular snap (currently not implemented)
- external dynamic user/group shared between host and all snaps (currently not implented)
type Type ¶
type Type string
Type represents the kind of snap (app, core, gadget, os, kernel, snapd)
const ( TypeApp Type = "app" TypeGadget Type = "gadget" TypeKernel Type = "kernel" TypeBase Type = "base" TypeSnapd Type = "snapd" // FIXME: this really should be TypeCore TypeOS Type = "os" )
The various types of snap parts we support
func (Type) SortsBefore ¶
func (*Type) UnmarshalJSON ¶
UnmarshalJSON sets *m to a copy of data.
func (*Type) UnmarshalYAML ¶
UnmarshalYAML so Type implements yaml's Unmarshaler interface
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package naming implements naming constraints and concepts for snaps and their elements.
|
Package naming implements naming constraints and concepts for snaps and their elements. |
Package quota defines state structures for resource quota groups for snaps.
|
Package quota defines state structures for resource quota groups for snaps. |
Package snaptest contains helper functions for mocking snaps.
|
Package snaptest contains helper functions for mocking snaps. |