"Interfaces: system control and observe"
interface family for administrators for users for app developers for snapd developers
Twenty-seven interfaces that let a snap observe or control the host. The system provides the slot (a few only on classic or only on Ubuntu Core) and none auto-connects. Seventeen can be connected by an administrator with snap connect; ten need a snap-declaration even to install.
On the map: interfaces district, family row
01 None of these connect on their own
27 interfaces with a system slot (a few on classic only or Ubuntu Core only), none of which auto-connects. 17 can be connected by an administrator with snap connect; 10 need a snap-declaration to install. Most come in observe and control pairs.
The acme-agent reports on the gateway's health, and now and then it needs to reboot it. Both kinds of request land in this family: twenty seven interfaces that let a snap observe or control the machine itself. For most of them the system provides the slot, on classic and Ubuntu Core alike, and the snap carries the plug. Not one connects on its own. Seventeen can be connected by whoever administers the machine, with snap connect. The other ten can't even be installed from the store unless a declaration allows them. And most come in pairs: observe reads, and control adds the writers.
02 What a connection lets a snap do for users for administrators
system-observe: every process and the kernel's state, no tracing. log-observe: the journal, the system logs and the kernel's messages. time-control: the system and hardware clocks. shutdown: reboot, power off, suspend, hibernate. Review with snap connections, grant with snap connect, revoke with snap disconnect.
Connecting one of these is a decision about the whole machine. Here's what four of them grant. system-observe lets the acme-agent see every process and the kernel's state, the way ps and top do, without tracing anything. log-observe lets it read the journal, the system's log files and the kernel's messages. time-control lets it set the system clock and the hardware clock. Shutdown lets it reboot, power off, suspend and hibernate, and a snap from the store can't carry that plug unless the store allowed it. Check with snap connections, grant with snap connect, revoke with snap disconnect. Snapd remembers a disconnect across refreshes.
03 Who can even install this for app developers for snapd developers
A slot-only rule (system-observe) installs freely and connects by hand. A plug rule with allow-installation: false (shutdown and nine others) needs a snap-declaration to install, and a declaration rule that does not deny auto-connection also auto-connects. kernel-module-load's slot deny-connection is not reached, because snapd checks the base plug rule first.
Why can the acme-agent install with system-observe, but not with shutdown? system-observe has only a slot rule: the slot must be on the system, and auto-connection is denied. Nothing restricts the plug, so any snap can carry it and an administrator can connect it. Shutdown adds a plug rule: allow-installation: false, and deny-auto-connection. Snapd refuses to install a store snap with that plug unless its snap-declaration replaces the rule, and unless the new rule denies auto-connection again, the plug then connects by itself. Ten interfaces carry this plug rule. One oddity: kernel-module-load's slot rule is never reached.
04 Observe versus control for app developers for snapd developers
kernel-module-observe: kmod, /proc/modules, /sys/module and modprobe.d read-only, plus capability syslog; lsmod works, modprobe fails in seccomp. kernel-module-control adds capability sys_module, the init_module, finit_module and delete_module system calls, and /dev/mem r. Only the control side is super-privileged.
Say the acme-agent needs a driver loaded. kernel-module-observe won't do. The pairs share a read-only core, and the control side adds the writers. Observe grants the kmod tool, /proc/modules, the module tree in sysfs and the modprobe settings, all read-only, plus the syslog capability. So lsmod and modinfo work, and modprobe fails, because seccomp has no init_module or delete_module. Control grants the same reads, then the sys_module capability, three module system calls, and read access to /dev/mem, left over from an older policy. Only control is super-privileged. And observe isn't always read-only: log-observe writes two kernel settings.
05 One D-Bus daemon, one interface
logind: login-session-observe, login-session-control, shutdown (which also reaches systemd's Reboot, PowerOff and Halt). timedated: time-control and timezone-control. hostnamed: system-observe, reading only. localed: locale-control. polkitd: polkit and polkit-agent. Each interface names the D-Bus members it allows.
When the acme-agent asks for a reboot, who actually does it? Usually a small systemd daemon on the system bus, and this family gives each one its own interfaces. Logind serves login-session-observe, login-session-control and shutdown, and shutdown may also ask systemd itself to reboot or power off. Timedated is split in two: time-control sets the time and the hardware clock, timezone-control sets the timezone. system-observe may read hostnamed's properties. Localed serves locale-control. Polkitd serves polkit and polkit-agent. Each interface names the D-Bus methods it allows, so time-control can't set the timezone.
06 Declarative modules for app developers for snapd developers
The modules attribute becomes host files: load: denied a blacklist line and options an options line in /etc/modprobe.d/snap.<snap>.conf, load: on-boot an entry in /etc/modules-load.d/snap.<snap>.conf, loaded at once. load: dynamic modules are loaded on request with snapctl kmod insert. No sys_module for the snap.
So how should the acme-agent get its driver loaded, without the sys_module capability? kernel-module-load lets the snap declare what it wants, and snapd does the work. The plug lists modules, each with a name and a load mode or options. load: denied becomes a blacklist line in a modprobe file named after the snap. Load on-boot lists the module in a modules load file, and snapd loads it at once. Options become an options line, with $SNAP_COMMON expanded to the snap's common directory. load: dynamic lets the snap ask for the module later, with snapctl kmod. Snapd checks the list at connect time.
07 Where to go next
Roads: interfaces, how interfaces are implemented, the network family, confinement, configuration (system.timezone, system.hostname) and the snapctl device commands (snapctl kmod).
This family is the least automatic in snapd: nothing connects by itself, and the decision sits with an administrator or a store declaration. Where next? Interfaces covers plugs, slots and connections in general. How interfaces are implemented shows how the rules you saw are evaluated and the profiles written. The network family has more observe and control pairs. Confinement explains what a capability or a seccomp line means once the app runs. Configuration shows how a device sets its timezone and hostname with snap set, no interface needed. And snapctl's device commands load a declared module later.
08 All 27 interfaces at a glance
Every interface in the family by connection class: 0 auto-connect, 0 conditionally, 26 by hand, 1 need a store rule to connect; 10 are super-privileged.
All 27 interfaces of the system control and observe family at a glance, sorted by how they get connected. 26 connect by hand with snap connect, which is most of the family. 1 need a store rule even to connect: kernel-module-load. 10, marked with a star, are super-privileged and need a store rule to install. Every one of them is in the catalogue below this deck, with what it grants and its rule.
Read more
The catalogue below this deck lists every interface of the family with its grants, attributes and rules. This page collects what cuts across them.
Commands
| Command | Effect |
|---|---|
snap connections <snap> | the snap's plugs and what each is connected to |
snap connect <snap>:<plug> | connect a plug to the system slot of the same name |
snap disconnect <snap>:<plug> | disconnect it; snapd remembers this across refreshes |
snap set system system.timezone=<zone>, system.hostname=<name> | change the timezone or hostname without any interface |
Where the slot exists
| Slot | Interfaces |
|---|---|
| classic and Ubuntu Core | the 21 not named below |
| classic only | packagekit-control, ubuntu-drivers-observe, ubuntu-pro-control |
| classic; Ubuntu Core Desktop | locale-control |
| classic; Ubuntu Core when polkitd is present and snapd can add polkit policy or rules | polkit |
| Ubuntu Core only, when the polkit agent helper is installed | polkit-agent |
for app developers for snapd developers for administrators
Two rule shapes in the base declaration
| 17 interfaces | 10 interfaces | |
|---|---|---|
| Example | system-observe | shutdown |
| Slot rule | allow-installation: slot-snap-type: [core], deny-auto-connection: true | the same |
| Plug rule | none | allow-installation: false, deny-auto-connection: true |
| Store snap with the plug | installs | refused unless a snap-declaration allows the plug |
| Connection | snap connect by an administrator | snap connect, once installed |
| Auto-connection | only with a snap-declaration rule | only with a snap-declaration rule |
The ten with a plug rule: auditd-support, kernel-firmware-control, kernel-module-control, kernel-module-load, kernel-sched-ext-control, packagekit-control, polkit, polkit-agent, shutdown, ubuntu-pro-control.
snapd evaluates one rule per connection, the first it finds in this order: the plug snap's declaration, the slot snap's declaration, the base declaration's plug rule, its slot rule. A snap-declaration rule replaces the base rule entirely, so a rule that only allows installation also allows auto-connection. kernel-module-load's slot rule (deny-connection: true) is never reached, because the base plug rule comes first.
A snap installed with --dangerous skips the installation rules and can be connected by hand.
for app developers for snapd developers for administrators
D-Bus services and what each interface may call
| Service | Interface | Allowed |
|---|---|---|
logind (org.freedesktop.login1) | shutdown | PowerOff, Reboot, RebootWithFlags, Suspend, Hibernate, SuspendThenHibernate, HybridSleep, the matching Can... queries, Inhibit, ListInhibitors, ScheduleShutdown, CancelScheduledShutdown, SetWallMessage, SetRebootParameter |
systemd (org.freedesktop.systemd1) | shutdown | Reboot, PowerOff, Halt |
| logind | login-session-observe, login-session-control | session queries; control adds session actions |
timedated (org.freedesktop.timedate1) | time-control | SetTime, SetLocalRTC, properties |
| timedated | timezone-control | the timezone |
hostnamed (org.freedesktop.hostname1) | system-observe | Get and GetAll on properties, introspection |
localed (org.freedesktop.locale1) | locale-control | the locale |
polkitd (org.freedesktop.PolicyKit1) | polkit, polkit-agent | authorisation checks; registering as the agent |
time-control also grants /dev/rtc* and /sys/class/rtc/*.
Further reading
- system-observe interface: what an observing snap can read.
- shutdown interface: the power actions.
- kernel-module-load interface: the
modulesattribute with examples. - Super-privileged interfaces: why ten of these need a snap-declaration.
- Connect interfaces:
snap connections,snap connectandsnap disconnect.
Roads from here
INTERFACES AND CONFINEMENT
- Interfaces — interfaces in general
- How interfaces are implemented — how the rules are evaluated and the profiles written
- Confinement — what a capability or a seccomp line means inside the sandbox
RUNNING SNAPS
- Configuration — configuration sets the timezone and hostname without an interface
SNAPCTL · the snap's API into snapd
- snapctl: device and system — snapctl kmod loads a declared module later
INTERFACE FAMILIES · every interface, grouped by what it touches
- "Interfaces: network" — the other family of observe and control pairs