"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

▶ Watch this deck — 8 scenes, ~6 min

01 None of these connect on their own

THE PATTERN system slotmost on classic and Coreacme-agentthe plug no auto-connection27 interfacesobserve or control the host seventeen: snap connect by an administratorsystem-observe · log-observe · time-control · cpu-control … ten: a store declaration to install at allshutdown · polkit · kernel-module-* · auditd-support … kernel-module-observe ↔ kernel-module-controllogin-session-observe ↔ login-session-controlobserve reads; control adds the writers
A system slot and an app plug with no automatic connection; seventeen interfaces an admin can connect, ten that need a store declaration to install; observe and control pairs

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

WHAT YOU GRANT system-observeevery process and the kernel's state, as ps and top see it log-observethe journal, the system logs, the kernel's messages time-controlsets the system clock and the hardware clock shutdownreboot, power off, suspend, hibernate · store-gated $ snap connections acme-agent$ snap connect acme-agent:system-observe$ snap disconnect acme-agent:system-observe a disconnect is remembered across refreshes
Four interfaces and what connecting each lets a snap do on the machine, then the commands to check, connect and disconnect

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

TWO LEVELS OF GATING base-declaration, slots:system-observe:allow-installation:slot-snap-type: [core]deny-auto-connection: true installs freely · snap connect by an admin base-declaration, plugs:shutdown:allow-installation: falsedeny-auto-connection: true# a snap-declaration rule replaces it needs a snap-declaration to install the ten: auditd-support · kernel-firmware-control · kernel-module-control · kernel-module-load · kernel-sched-ext-controlpackagekit-control · polkit · polkit-agent · shutdown · ubuntu-pro-control kernel-module-load's slot says deny-connection: true, but snapd checks the base plug rule first: the slot rule is not reached
The slot-only rule of system-observe next to the plug rule of shutdown with allow-installation false, the list of ten super-privileged interfaces, and the inert slot deny of kernel-module-load

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

OBSERVE VERSUS CONTROL kernel-module-observe/{,usr/}bin/kmod ixr,@{PROC}/modules r,/sys/module/{,**} r,/etc/modprobe.d/{,**} r,/{,usr/}lib/modprobe.d/{,**} r,capability syslog,# seccomp: no init_module, delete_module lsmod and modinfo work · modprobe fails kernel-module-controlthe same six rules, plus:capability sys_module,/dev/mem r, # left overseccomp:init_modulefinit_moduledelete_module super-privileged: declaration to install observe is not always read-only: log-observe writes printk_ratelimit and the AppArmor audit parameter
The AppArmor rules of kernel-module-observe next to kernel-module-control, which repeats them and adds capability sys_module, three syscalls and /dev/mem

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

SYSTEMD'S BUS DAEMONS logindlogin-session-observe · login-session-control · shutdown timedatedtime-control · timezone-control hostnamedsystem-observe · reads properties localedlocale-control polkitdpolkit · polkit-agent an interface lists the D-Bus members it allows: time-control has SetTime and SetLocalRTC, not SetTimezone
Five systemd bus daemons on the left, each linked to the interfaces that talk to it on the right

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

KERNEL-MODULE-LOAD acme-agent, snap.yamlplugs:kmod:interface: kernel-module-loadmodules:- name: pcspkrload: denied- name: acme-drvload: on-bootoptions: debug=1- name: acme-radioload: dynamic /etc/modprobe.d/snap.acme-agent.confblacklist pcspkroptions acme-drv debug=1 /etc/modules-load.d/snap.acme-agent.confacme-drvand modprobe runs now $ snapctl kmod insert acme-radiofrom inside the snap, later;snapd runs modprobe on the host no sys_module for the snap · the list is checked at connect time
A kernel-module-load modules list in acme-agent's snap.yaml on the left, the modprobe.d and modules-load.d files snapd writes from it on the right, and a dynamic entry loaded later through snapctl kmod

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 system control and observenothing connects by itself Interfacesinterfaces in general How interfaces are implementedrule evaluation and profiles Interfaces: networkmore observe and control pairs Confinementcapabilities and seccomp, enforced Configurationsystem.timezone · system.hostname snapctl: device and systemsnapctl kmod, later
The family in the middle with roads to interfaces, how interfaces are implemented, the network family, confinement, configuration and the snapctl device commands

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

ALL 27 INTERFACES AT A GLANCE account-control apparmor-observe auditd-support * cpu-control daemon-notify hugepages-control kernel-firmware-control * kernel-module-control * kernel-module-observe kernel-sched-ext-control * locale-control log-observe login-session-control login-session-observe packagekit-control * polkit * polkit-agent * power-control process-control shutdown * system-observe system-trace time-control timezone-control ubuntu-drivers-observe ubuntu-pro-control * kernel-module-load * auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the system control and observe family, sorted and coloured by how it gets connected: auto-connect, conditional, by hand, or store rule needed

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

CommandEffect
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

SlotInterfaces
classic and Ubuntu Corethe 21 not named below
classic onlypackagekit-control, ubuntu-drivers-observe, ubuntu-pro-control
classic; Ubuntu Core Desktoplocale-control
classic; Ubuntu Core when polkitd is present and snapd can add polkit policy or rulespolkit
Ubuntu Core only, when the polkit agent helper is installedpolkit-agent

for app developers for snapd developers for administrators

Two rule shapes in the base declaration

17 interfaces10 interfaces
Examplesystem-observeshutdown
Slot ruleallow-installation: slot-snap-type: [core], deny-auto-connection: truethe same
Plug rulenoneallow-installation: false, deny-auto-connection: true
Store snap with the pluginstallsrefused unless a snap-declaration allows the plug
Connectionsnap connect by an administratorsnap connect, once installed
Auto-connectiononly with a snap-declaration ruleonly 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

ServiceInterfaceAllowed
logind (org.freedesktop.login1)shutdownPowerOff, Reboot, RebootWithFlags, Suspend, Hibernate, SuspendThenHibernate, HybridSleep, the matching Can... queries, Inhibit, ListInhibitors, ScheduleShutdown, CancelScheduledShutdown, SetWallMessage, SetRebootParameter
systemd (org.freedesktop.systemd1)shutdownReboot, PowerOff, Halt
logindlogin-session-observe, login-session-controlsession queries; control adds session actions
timedated (org.freedesktop.timedate1)time-controlSetTime, SetLocalRTC, properties
timedatedtimezone-controlthe timezone
hostnamed (org.freedesktop.hostname1)system-observeGet and GetAll on properties, introspection
localed (org.freedesktop.locale1)locale-controlthe locale
polkitd (org.freedesktop.PolicyKit1)polkit, polkit-agentauthorisation checks; registering as the agent

time-control also grants /dev/rtc* and /sys/class/rtc/*.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

  • Configuration — configuration sets the timezone and hostname without an interface

SNAPCTL · the snap's API into snapd

INTERFACE FAMILIES · every interface, grouped by what it touches