snapd: github.com/snapcore/snapd/interfaces Index | Files | Directories

package interfaces

import "github.com/snapcore/snapd/interfaces"

Index

Package Files

backend.go core.go json.go naming.go repo.go sorting.go

func InterfaceServiceName Uses

func InterfaceServiceName(snapName, uniqueName string) string

func SecurityTagGlob Uses

func SecurityTagGlob(snapName string) string

SecurityTagGlob returns a pattern that matches all security tags belonging to the same snap as the given app.

func ValidateDBusBusName Uses

func ValidateDBusBusName(busName string) error

ValidateDBusBusName checks if a string conforms to https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names

func ValidateName Uses

func ValidateName(name string) error

ValidateName checks if a string can be used as a plug or slot name.

type BadInterfacesError Uses

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

BadInterfacesError is returned when some snap interfaces could not be registered. Those interfaces not mentioned in the error were successfully registered.

func (*BadInterfacesError) Error Uses

func (e *BadInterfacesError) Error() string

type ConfinementOptions Uses

type ConfinementOptions struct {
    // DevMode flag switches confinement to non-enforcing mode.
    DevMode bool
    // JailMode flag switches confinement to enforcing mode.
    JailMode bool
    // Classic flag switches the core snap "chroot" off.
    Classic bool
}

ConfinementOptions describe confinement configuration.

The confinement system controls the initial layout of the mount namespace as well as the set of actions a process is allowed to perform. Confinement is initially defined by the ConfinementType declared by the snap. It can be either "strict", "devmode" or "classic".

The "strict" type uses mount layout that puts the core snap as the root filesystem and provides strong isolation from the system and from other snaps. Violations cause permission errors or mandatory process termination.

The "devmode" type uses the same mount layout as "strict" but switches confinement to non-enforcing mode whenever possible. Violations that would result in permission error or process termination are instead permitted. A diagnostic message is logged when this occurs.

The "classic" type uses mount layout that is identical to the runtime of the classic system snapd runs in, in other words there is no "chroot". Most of the confinement is lifted, specifically there's no seccomp filter being applied and apparmor is using complain mode by default.

The three types defined above map to some combinations of the three flags defined below.

The DevMode flag attempts to switch all confinement facilities into non-enforcing mode even if the snap requested otherwise.

The JailMode flag attempts to switch all confinement facilities into enforcing mode even if the snap requested otherwise.

The Classic flag switches the layout of the mount namespace so that there's no "chroot" to the core snap.

type ConnRef Uses

type ConnRef struct {
    PlugRef PlugRef
    SlotRef SlotRef
}

ConnRef holds information about plug and slot reference that form a particular connection.

func ParseConnRef Uses

func ParseConnRef(id string) (ConnRef, error)

ParseConnRef parses an ID string

func (*ConnRef) ID Uses

func (conn *ConnRef) ID() string

ID returns a string identifying a given connection.

type Info Uses

type Info struct {
    Name    string
    Summary string
    DocURL  string
    Plugs   []*snap.PlugInfo
    Slots   []*snap.SlotInfo
}

Info holds information about a given interface and its instances.

func (*Info) MarshalJSON Uses

func (info *Info) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of Info.

type InfoOptions Uses

type InfoOptions struct {
    Names     []string
    Doc       bool
    Plugs     bool
    Slots     bool
    Connected bool
}

InfoOptions describes options for Info.

Names: return just this subset if non-empty. Doc: return documentation. Plugs: return information about plugs. Slots: return information about slots. Connected: only consider interfaces with at least one connection.

type Interface Uses

type Interface interface {
    // Unique and public name of this interface.
    Name() string

    // AutoConnect returns whether plug and slot should be
    // implicitly auto-connected assuming they will be an
    // unambiguous connection candidate and declaration-based checks
    // allow.
    AutoConnect(plug *Plug, slot *Slot) bool
}

Interface describes a group of interchangeable capabilities with common features. Interfaces act as a contract between system builders, application developers and end users.

type Interfaces Uses

type Interfaces struct {
    Plugs []*Plug `json:"plugs"`
    Slots []*Slot `json:"slots"`
}

Interfaces holds information about a list of plugs, slots and their connections.

type Plug Uses

type Plug struct {
    *snap.PlugInfo
    Connections []SlotRef `json:"connections,omitempty"`
}

Plug represents the potential of a given snap to connect to a slot.

func (*Plug) MarshalJSON Uses

func (plug *Plug) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of plug.

func (*Plug) Ref Uses

func (plug *Plug) Ref() PlugRef

Ref returns reference to a plug

func (*Plug) Sanitize Uses

func (plug *Plug) Sanitize(iface Interface) error

Sanitize plug with a given snapd interface.

type PlugRef Uses

type PlugRef struct {
    Snap string `json:"snap"`
    Name string `json:"plug"`
}

PlugRef is a reference to a plug.

func (PlugRef) String Uses

func (ref PlugRef) String() string

String returns the "snap:plug" representation of a plug reference.

type PlugSanitizer Uses

type PlugSanitizer interface {
    SanitizePlug(plug *Plug) error
}

PlugSanitizer can be implemented by Interfaces that have reasons to sanitize their plugs.

type Repository Uses

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

Repository stores all known snappy plugs and slots and ifaces.

func NewRepository Uses

func NewRepository() *Repository

NewRepository creates an empty plug repository.

func (*Repository) AddBackend Uses

func (r *Repository) AddBackend(backend SecurityBackend) error

AddBackend adds the provided security backend to the repository.

func (*Repository) AddInterface Uses

func (r *Repository) AddInterface(i Interface) error

AddInterface adds the provided interface to the repository.

func (*Repository) AddPlug Uses

func (r *Repository) AddPlug(plug *Plug) error

AddPlug adds a plug to the repository. Plug names must be valid snap names, as defined by ValidateName. Plug name must be unique within a particular snap.

func (*Repository) AddSlot Uses

func (r *Repository) AddSlot(slot *Slot) error

AddSlot adds a new slot to the repository. Adding a slot with invalid name returns an error. Adding a slot that has the same name and snap name as another slot returns an error.

func (*Repository) AddSnap Uses

func (r *Repository) AddSnap(snapInfo *snap.Info) error

AddSnap adds plugs and slots declared by the given snap to the repository.

This function can be used to implement snap install or, when used along with RemoveSnap, snap upgrade.

AddSnap doesn't change existing plugs/slots. The caller is responsible for ensuring that the snap is not present in the repository in any way prior to calling this function. If this constraint is violated then no changes are made and an error is returned.

Each added plug/slot is validated according to the corresponding interface. Unknown interfaces and plugs/slots that don't validate are not added. Information about those failures are returned to the caller.

func (*Repository) AllPlugs Uses

func (r *Repository) AllPlugs(interfaceName string) []*Plug

AllPlugs returns all plugs of the given interface. If interfaceName is the empty string, all plugs are returned.

func (*Repository) AllSlots Uses

func (r *Repository) AllSlots(interfaceName string) []*Slot

AllSlots returns all slots of the given interface. If interfaceName is the empty string, all slots are returned.

func (*Repository) AutoConnectCandidatePlugs Uses

func (r *Repository) AutoConnectCandidatePlugs(slotSnapName, slotName string, policyCheck func(*Plug, *Slot) bool) []*Plug

AutoConnectCandidatePlugs finds and returns viable auto-connection candidates for a given slot.

func (*Repository) AutoConnectCandidateSlots Uses

func (r *Repository) AutoConnectCandidateSlots(plugSnapName, plugName string, policyCheck func(*Plug, *Slot) bool) []*Slot

AutoConnectCandidateSlots finds and returns viable auto-connection candidates for a given plug.

func (*Repository) Backends Uses

func (r *Repository) Backends() []SecurityBackend

Backends returns all the security backends.

func (*Repository) Connect Uses

func (r *Repository) Connect(ref ConnRef) error

Connect establishes a connection between a plug and a slot. The plug and the slot must have the same interface.

func (*Repository) Connected Uses

func (r *Repository) Connected(snapName, plugOrSlotName string) ([]ConnRef, error)

Connected returns references for all connections that are currently established with the provided plug or slot.

func (*Repository) Disconnect Uses

func (r *Repository) Disconnect(plugSnapName, plugName, slotSnapName, slotName string) error

Disconnect disconnects the named plug from the slot of the given snap.

Disconnect() finds a specific slot and a specific plug and disconnects that plug from that slot. It is an error if plug or slot cannot be found or if the connect does not exist.

func (*Repository) DisconnectAll Uses

func (r *Repository) DisconnectAll(conns []ConnRef)

DisconnectAll disconnects all provided connection references.

func (*Repository) DisconnectSnap Uses

func (r *Repository) DisconnectSnap(snapName string) ([]string, error)

DisconnectSnap disconnects all the connections to and from a given snap.

The return value is a list of names that were affected.

func (*Repository) Info Uses

func (r *Repository) Info(opts *InfoOptions) []*Info

Info returns information about interfaces in the system.

If names is empty then all interfaces are considered. Query options decide which data to return but can also skip interfaces without connections. See the documentation of InfoOptions for details.

func (*Repository) Interface Uses

func (r *Repository) Interface(interfaceName string) Interface

Interface returns an interface with a given name.

func (*Repository) Interfaces Uses

func (r *Repository) Interfaces() *Interfaces

Interfaces returns object holding a lists of all the plugs and slots and their connections.

func (*Repository) Plug Uses

func (r *Repository) Plug(snapName, plugName string) *Plug

Plug returns the specified plug from the named snap.

func (*Repository) Plugs Uses

func (r *Repository) Plugs(snapName string) []*Plug

Plugs returns the plugs offered by the named snap.

func (*Repository) RemovePlug Uses

func (r *Repository) RemovePlug(snapName, plugName string) error

RemovePlug removes the named plug provided by a given snap. The removed plug must exist and must not be used anywhere.

func (*Repository) RemoveSlot Uses

func (r *Repository) RemoveSlot(snapName, slotName string) error

RemoveSlot removes a named slot from the given snap. Removing a slot that doesn't exist returns an error. Removing a slot that is connected to a plug returns an error.

func (*Repository) RemoveSnap Uses

func (r *Repository) RemoveSnap(snapName string) error

RemoveSnap removes all the plugs and slots associated with a given snap.

This function can be used to implement snap removal or, when used along with AddSnap, snap upgrade.

RemoveSnap does not remove connections. The caller is responsible for ensuring that connections are broken before calling this method. If this constraint is violated then no changes are made and an error is returned.

func (*Repository) ResolveConnect Uses

func (r *Repository) ResolveConnect(plugSnapName, plugName, slotSnapName, slotName string) (ConnRef, error)

ResolveConnect resolves potentially missing plug or slot names and returns a fully populated connection reference.

func (*Repository) ResolveDisconnect Uses

func (r *Repository) ResolveDisconnect(plugSnapName, plugName, slotSnapName, slotName string) ([]ConnRef, error)

ResolveDisconnect resolves potentially missing plug or slot names and returns a list of fully populated connection references that can be disconnected.

It can be used in two different ways: 1: snap disconnect <snap>:<plug> <snap>:<slot> 2: snap disconnect <snap>:<plug or slot>

In the first case the referenced plug and slot must be connected. In the second case any matching connection are returned but it is not an error if there are no connections.

In both cases the snap name can be omitted to implicitly refer to the core snap. If there's no core snap it is simply assumed to be called "core" to provide consistent error messages.

func (*Repository) Slot Uses

func (r *Repository) Slot(snapName, slotName string) *Slot

Slot returns the specified slot from the named snap.

func (*Repository) Slots Uses

func (r *Repository) Slots(snapName string) []*Slot

Slots returns the slots offered by the named snap.

func (*Repository) SnapSpecification Uses

func (r *Repository) SnapSpecification(securitySystem SecuritySystem, snapName string) (Specification, error)

SnapSpecification returns the specification of a given snap in a given security system.

type SecurityBackend Uses

type SecurityBackend interface {
    // Name returns the name of the backend.
    // This is intended for diagnostic messages.
    Name() SecuritySystem

    // Setup creates and loads security artefacts specific to a given snap.
    // The snap can be in one of three kids onf confinement (strict mode,
    // developer mode or classic mode). In the last two security violations
    // are non-fatal to the offending application process.
    //
    // This method should be called after changing plug, slots, connections
    // between them or application present in the snap.
    Setup(snapInfo *snap.Info, opts ConfinementOptions, repo *Repository) error

    // Remove removes and unloads security artefacts of a given snap.
    //
    // This method should be called during the process of removing a snap.
    Remove(snapName string) error

    // NewSpecification returns a new specification associated with this backend.
    NewSpecification() Specification
}

SecurityBackend abstracts interactions between the interface system and the needs of a particular security system.

type SecuritySystem Uses

type SecuritySystem string

SecuritySystem is a name of a security system.

const (
    // SecurityAppArmor identifies the apparmor security system.
    SecurityAppArmor SecuritySystem = "apparmor"
    // SecuritySecComp identifies the seccomp security system.
    SecuritySecComp SecuritySystem = "seccomp"
    // SecurityDBus identifies the DBus security system.
    SecurityDBus SecuritySystem = "dbus"
    // SecurityUDev identifies the UDev security system.
    SecurityUDev SecuritySystem = "udev"
    // SecurityMount identifies the mount security system.
    SecurityMount SecuritySystem = "mount"
    // SecurityKMod identifies the kernel modules security system
    SecurityKMod SecuritySystem = "kmod"
    // SecuritySystemd identifies the systemd services security system
    SecuritySystemd SecuritySystem = "systemd"
)

type Slot Uses

type Slot struct {
    *snap.SlotInfo
    Connections []PlugRef `json:"connections,omitempty"`
}

Slot represents a capacity offered by a snap.

func (*Slot) MarshalJSON Uses

func (slot *Slot) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of slot.

func (*Slot) Ref Uses

func (slot *Slot) Ref() SlotRef

Ref returns reference to a slot

func (*Slot) Sanitize Uses

func (slot *Slot) Sanitize(iface Interface) error

Sanitize slot with a given snapd interface.

type SlotRef Uses

type SlotRef struct {
    Snap string `json:"snap"`
    Name string `json:"slot"`
}

SlotRef is a reference to a slot.

func (SlotRef) String Uses

func (ref SlotRef) String() string

String returns the "snap:slot" representation of a slot reference.

type SlotSanitizer Uses

type SlotSanitizer interface {
    SanitizeSlot(slot *Slot) error
}

SlotSanitizer can be implemented by Interfaces that have reasons to sanitize their slots.

type Specification Uses

type Specification interface {
    // AddPermanentSlot records side-effects of having a slot.
    AddPermanentSlot(iface Interface, slot *Slot) error
    // AddPermanentPlug records side-effects of having a plug.
    AddPermanentPlug(iface Interface, plug *Plug) error
    // AddConnectedSlot records side-effects of having a connected slot.
    AddConnectedSlot(iface Interface, plug *Plug, plugAttrs map[string]interface{}, slot *Slot, slotAttrs map[string]interface{}) error
    // AddConnectedPlug records side-effects of having a connected plug.
    AddConnectedPlug(iface Interface, plug *Plug, plugAttrs map[string]interface{}, slot *Slot, slotAttrs map[string]interface{}) error
}

Specification describes interactions between backends and interfaces.

type StaticInfo Uses

type StaticInfo struct {
    Summary string `json:"summary,omitempty"`
    DocURL  string `json:"doc-url,omitempty"`

    // ImplicitOnCore controls if a slot is automatically added to core (non-classic) systems.
    ImplicitOnCore bool `json:"implicit-on-core,omitempty"`
    // ImplicitOnClassic controls if a slot is automatically added to classic systems.
    ImplicitOnClassic bool `json:"implicit-on-classic,omitempty"`

    // BaseDeclarationPlugs defines an optional extension to the base-declaration assertion relevant for this interface.
    BaseDeclarationPlugs string
    // BaseDeclarationSlots defines an optional extension to the base-declaration assertion relevant for this interface.
    BaseDeclarationSlots string
}

StaticInfo describes various static-info of a given interface.

The Summary must be a one-line string of length suitable for listing views. The DocsURL can point to website (e.g. a forum thread) that goes into more depth and documents the interface in detail.

func StaticInfoOf Uses

func StaticInfoOf(iface Interface) (si StaticInfo)

StaticInfoOf returns the static-info of the given interface.

Directories

PathSynopsis
apparmorPackage apparmor contains primitives for working with apparmor.
backends
builtin
dbusPackage dbus implements interaction between snappy and dbus.
ifacetest
kmodPackage kmod implements a backend which loads kernel modules on behalf of interfaces.
mountPackage mount implements mounts that get mapped into the snap
policyPackage policy implements the declaration based policy checks for connecting or permitting installation of snaps based on their slots and plugs.
seccompPackage seccomp implements integration between snappy and ubuntu-core-launcher around seccomp.
systemdPackage systemd implements integration between snappy interfaces and arbitrary systemd units that may be required for "oneshot" style tasks.
udevPackage udev implements integration between snappy, udev and ubuntu-core-laucher around tagging character and block devices so that they can be accessed by applications.

Package interfaces imports 8 packages (graph) and is imported by 103 packages. Updated 2017-09-20. Refresh now. Tools for package owners.