"Interfaces: files, data and snapd's own API"

interface family for users for app developers for Ubuntu Core developers for snapd developers for administrators

Thirty-one interfaces of three kinds. Some read a fixed set of host files (ssh-keys, gpg-keys, system-backup, home). Some share exactly what their attributes declare (personal-files, system-files, shared-memory, content, the driver-libs slots). Some add almost nothing to the sandbox and instead unlock parts of snapd's API (snapd-control, snap-refresh-observe, snap-fde-control, snap-interfaces-requests-control).

On the map: interfaces district, family row

▶ Watch this deck — 8 scenes, ~6 min

01 Three kinds of interface in this family

FILES, DATA AND SNAPD'S API photo-editoron a laptop: 31 interfaces it might ask for, in three kinds read host filesa fixed list; the system holds the slotssh-keysgpg-keyshomesystem-backupnearly all wait for snap connect share, as declaredattributes decide exactly whatpersonal-filessystem-filesshared-memorycontentthe driver-libs interfacespaths, labels and tags unlock snapd's APIalmost nothing in the sandboxsnapd-controlsnap-refresh-observesnap-fde-controlsnap-refresh-controlsnap-interfaces-requests-controlsnapd checks the connectionwhen a snap calls its API
What the photo editor on a laptop might ask for, in three columns: interfaces that read fixed host files, interfaces whose attributes decide what is shared, and marker interfaces that unlock parts of snapd's API

Three kinds: read access to a fixed list of host files, attribute-driven sharing, and markers that unlock parts of snapd's own API. home and content have decks of their own.

You've just installed the photo editor on your laptop. Much of what it might ask for lives in this family of thirty one interfaces, which come in three kinds. The first reads a fixed set of your files: ssh-keys, gpg-keys, home, and system-backup, which reads everything. The system provides those slots, and nearly all of them wait for snap connect. The second shares things, and the attributes a snap declares decide exactly what: personal-files, system-files, shared-memory, content, the driver-libs. The third adds almost nothing to the sandbox. Snapd itself checks the connection when a snap calls its API.

02 personal-files and system-files for app developers for Ubuntu Core developers for snapd developers for administrators

PERSONAL-FILES · SYSTEM-FILES photo-editor, snap.yamlplugs:legacy-presets:interface: personal-filesread: [$HOME/.config/photo-editor]write: [$HOME/.local/share/photo-editor] another snap, snap.yamlplugs:host-config:interface: system-filesread: [/etc/example]write: [/var/log/example] each path starts with $HOME/rules carry owner: only files you owneach path starts with /$HOME is refused read → rk write → rwkl each path covers {,/,/**} both plugs: allow-installation: false · the store reviews the paths personal-files only: snap-update-ns creates missing parent directories for write paths
Two plugs side by side: photo-editor's personal-files plug with $HOME paths and a system-files plug with absolute paths, the path rule of each, the permissions a read or write entry grants, the shared allow-installation false, and the parent directories only personal-files creates

Same code, different path rules: $HOME/ with owner for personal-files, / for system-files. Both plugs have allow-installation: false, so a store snap needs a snap-declaration; a --dangerous install skips that check. Only personal-files creates missing parent directories for write paths.

Say the photo editor wants the presets an older, non-snap version left in your home. Home leaves out hidden files. personal-files will. The plug lists exact paths, each starting with $HOME slash, and the rules cover only files you own. system-files is the same code for absolute paths, and it refuses $HOME. A read entry grants read and lock, a write entry adds write and link, and each path covers everything below it. Both plugs are super-privileged, so the store reviews the list before the snap can be installed from it. For write paths, personal-files also creates missing parent directories.

03 Marker interfaces unlock parts of snapd's API for app developers for Ubuntu Core developers for snapd developers for administrators

MARKERS photo-editorany snap/run/snapd-snap.socket: in every snap's sandboxsnapd: which snap? a connected plug the endpoint lists? snap-refresh-observeread only/v2/changes{,/{id}} /v2/snaps{,/{name}} /v2/icons/{name}/icon/v2/notices: change-update, refresh-inhibit, snap-run-inhibit snap-interfaces-requests-controlread and write/v2/interfaces/requests/prompts{,/{id}} …/rules{,/{id}}/v2/notices: prompt, rule-update /v2/system-info icons snap-fde-controlFDE agent/v2/system-volumes: read; check and change passphrase or PINrecovery keys, some /v2/systems actions: root and polkit snap-refresh-controlnot an endpointsnapctl refresh --proceed from a running appretired: gate-auto-refresh-hook is permanently disabled all four plugs: allow-installation: false · the store decides who may have them
Every snap reaches snapd-snap.socket; snapd identifies the calling snap and requires a connected plug of an interface listed on the endpoint; a table of marker interfaces and the endpoints each unlocks, with snap-refresh-control struck through as retired

On snapd-snap.socket an endpoint accepts a snap only if it has a connected plug of an interface listed on that endpoint. The table shows what each marker unlocks. All four plugs have allow-installation: false.

Every snap can already talk to snapd: the default sandbox allows the snapd-snap.socket. So what stops the photo editor reading your changes, or your disk encryption settings? A short list of interfaces. There, snapd learns which snap is calling from the connection itself, and then looks for a connected plug of an interface that the endpoint names. snap-refresh-observe unlocks reading changes, snaps and refresh notices. snap-interfaces-requests-control unlocks the prompting API. snap-fde-control unlocks the disk encryption endpoints. snap-refresh-control is a leftover: the feature it served is permanently disabled. The store grants each of these, snap by snap.

04 snapd-control is root for snapd for app developers for Ubuntu Core developers for snapd developers for administrators

SNAPD-CONTROL device-agenta management snapplug snapd-control/run/snapd.socket rwthe privileged socket, the one snap usesaccess.go: no interface check here root in the snap has what root running snap on the host has snap.yamlplugs:snapd-control:refresh-schedule: managed CanManageRefreshes → truerefresh.timer=managed acceptedsnapd stops scheduling auto-refreshesthe agent decides when snaps refresh needs a snap-declaration: a --dangerous snap can be connected but cannot take over refreshes
A management snap's snapd-control plug reaching /run/snapd.socket with no interface check, and the refresh-schedule managed attribute letting it set refresh.timer to managed, which stops snapd scheduling auto-refreshes

One AppArmor line, /run/snapd.socket rw, and no interface check on that socket: root in the snap equals root running snap. With refresh-schedule: managed on a snap that has a snap-declaration, refresh.timer=managed (or the older refresh.schedule) is accepted and snapd stops scheduling auto-refreshes.

Could the photo editor ask for snapd-control? It could ask, and the store should say no. The interface adds one rule: read and write on the snapd.socket, the one the snap command uses. Snapd checks no interfaces on that socket, so root inside the snap can do whatever root can do with snap on the host: install, remove, connect. It's meant for management agents on devices. One attribute, refresh-schedule: managed, lets such an agent take over refreshes. Once a store snap has that plug connected, refresh.timer may be set to managed, and snapd stops scheduling auto-refreshes on its own.

05 The driver-libs family puts vendor libraries on the host loader path for app developers for Ubuntu Core developers for snapd developers for administrators

*-DRIVER-LIBS cuda · egl · gbm · nvidia-video · opengl · opengles · vulkan (egl, vulkan also link ICD files) gpu-vendor (a vendor snap)slot: cuda-driver-libslibrary-source: [$SNAP/lib]compatibility: cuda-(9..12)-ubuntu-2404slot plugthe system snapimplicit plug, classic onlyno plug on Ubuntu Coreapp snaps cannot plug it /etc/ld.so.conf.d/snap.system.conf/snap/gpu-vendor/current/libldconfig backend: written on connect,ldconfig runs if the file changed; no AppArmor host with the Nvidia driver loaded: snap-confine can mount the same directories into the snaps it starts slot allow-installation: false · plug-snap-type: [core] · slots-per-plug: * · deny-auto-connection
The seven driver-libs interfaces; a GPU vendor snap's cuda-driver-libs slot connected to the system's implicit plug on classic; the library-source directories written into /etc/ld.so.conf.d/snap.system.conf; snap-confine mounting them into snaps on a host with the Nvidia driver; the slot rules

The ldconfig backend writes a vendor slot's library-source directories to /etc/ld.so.conf.d/snap.system.conf; there is no AppArmor. The plug is implicit on the system snap on classic only, the slot has allow-installation: false, and slots-per-plug: * lets several vendors connect.

Now suppose the laptop's GPU vendor ships its driver libraries as a snap. How do programs find them? Through seven driver-libs interfaces: CUDA, EGL, GBM, Nvidia video, OpenGL, OpenGL ES and Vulkan. The vendor snap's slot lists library directories inside the snap. The plug belongs to the system itself, on classic only. Connect the two, and snapd writes those directories into one file under /etc/ld.so.conf.d, and runs ldconfig if the file changed. On a host with the Nvidia driver loaded, snap-confine can also mount them into the snaps it starts. The slot is super-privileged, and nothing connects automatically.

06 What you will be asked to connect for users

FOR USERS ssh-keysreads your SSH settings and keysincluding the private ones gpg-keysreads your GPG keys and uses the GPG agentincluding the private ones system-backupreads every file on the computerother users' files included; read only personal-filesa short list of specific files in your homechosen by the publisher, checked by the store public keys only: ssh-public-keys and gpg-public-keys are the narrower versions $ snap connections photo-editor$ snap connect photo-editor:ssh-keysnone of these connects on its own; snapd remembers a disconnect
Four interfaces a user may be asked to connect, what each exposes in plain words, and the commands to check and connect

ssh-keys and gpg-keys read your keys, private ones included; system-backup reads every file on the computer; personal-files reaches a store-checked list of files in your home. None connects on its own: snap connections shows what is connected and snap connect grants it.

Some snaps ask for more than your documents, and none of these connects on its own. Here's what you'd agree to. ssh-keys lets the snap read your SSH settings and keys, the private ones included. gpg-keys does the same for GPG, agent included. system-backup lets it read every file on the computer, other people's too, though it can't change them. personal-files reaches a short list of files in your home, chosen by the publisher and checked by the store. Need less? ssh-public-keys and gpg-public-keys are the narrower versions. Snap connect grants one, and snapd remembers a disconnect.

07 Where to go from here

ROADS Files, data and snapd's APIhomecontentmembers with their own decks Interfacesplugs, slots, connections How interfaces are implementedthe mount and ldconfig backends The snapd REST APIthe endpoints markers unlock Who decides when a snap updatesmanaged refreshes and the rest The overlordthe daemon behind snapd-control
Roads from this family to the home and content decks, the interfaces overview, how interfaces are implemented, the snapd REST API, who decides when a snap updates, and the overlord

home and content have their own decks; Interfaces is the overview; How interfaces are implemented covers the mount and ldconfig backends; the REST API, update control and the overlord cover what the marker interfaces and snapd-control reach.

Where next? Home and content are the two members of this family with decks of their own. Interfaces is the overview, if you came here first. How interfaces are implemented shows the backends that did the work in this deck: the mount backend behind personal-files, and the ldconfig backend behind the driver-libs. The snapd REST API covers the endpoints that the markers unlock. Who decides when a snap updates puts the managed refresh schedule next to the other ways to control updates. And the overlord is the daemon behind snapd-control.

08 All 31 interfaces at a glance

ALL 31 INTERFACES AT A GLANCE ros-opt-data confdb content home cuda-driver-libs * dbus egl-driver-libs * gbm-driver-libs * gpg-keys gpg-public-keys juju-client-observe kerberos-tickets nvidia-video-driver-libs * opengl-driver-libs * opengles-driver-libs * personal-files * pkcs11 * shared-memory snap-fde-control * snap-interfaces-requests-control * snap-refresh-control * snap-refresh-observe * snapd-control * ssh-keys ssh-public-keys system-backup system-files * system-packages-doc system-source-code vulkan-driver-libs * posix-mq * auto-connectsconditionalby handstore rule to connect* store rule to install · italic: Ubuntu Touch era
Every interface in the files, data and snapd 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: 1 auto-connect, 3 conditionally, 26 by hand, 1 need a store rule to connect; 16 are super-privileged.

All 31 interfaces of the files, data and snapd family at a glance, sorted by how they get connected. 1 auto-connect on every system: ros-opt-data. 3 auto-connect under conditions: confdb, content, home. 26 connect by hand with snap connect, which is most of the family. 1 need a store rule even to connect: posix-mq. 16, 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 and does not reconnect it on refresh
snap interface personal-files --attrsevery personal-files plug with its read and write lists (the same works for system-files)

snap connections does not show the paths of a personal-files or system-files plug; snap interface <name> --attrs does.

for app developers for Ubuntu Core developers for snapd developers for administrators

personal-files and system-files paths

personal-filessystem-files
Each path muststart with $HOME/ and use $HOME only therestart with / and not contain $HOME
Both refuse~, AppArmor pattern characters, a trailing / or @, paths that change under filepath.Cleanthe same
AppArmor ruleowner "@{HOME}/<path>{,/,/**}""<path>{,/,/**}"
read entryrk (read, lock)rk
write entryrwkl (read, write, lock, link)rwkl
Missing directoriessnap-update-ns creates the parents of each write path below $HOME, not the leafnone created

Both plugs have allow-installation: false and deny-auto-connection: true in the base declaration. A snap from the store needs a snap-declaration that allows the plug. An install with --dangerous runs only the minimal installation check, so a locally built snap with these plugs installs and can be connected by hand.

system-files paths are paths inside the snap's mount namespace. A host directory that the base hides is reached through /var/lib/snapd/hostfs/....

for app developers for Ubuntu Core developers for snapd developers for administrators

What the marker interfaces unlock

Every snap's AppArmor template allows /run/snapd-snap.socket rw. A request on that socket passes an endpoint's check only if snapd can tell which snap is calling and that snap has a connected plug of an interface listed on the endpoint. On /run/snapd.socket no interface is checked.

The catalogue below this deck lists the endpoints and actions each marker interface opens: snap-refresh-observe, snap-interfaces-requests-control, snap-fde-control and snap-refresh-control.

The same mechanism serves interfaces of other families: desktop-launch (snaps and icons), snap-themes-control, ros-snapd-support (changes and apps) and fwupd (secure boot actions, on the slot side).

for app developers for Ubuntu Core developers for snapd developers for administrators

snapd-control and managed refreshes

StepWhat snapd checks
Installthe plug has allow-installation: false: a store snap needs a snap-declaration
Connectdeny-auto-connection: true: by hand, or by a store rule
snap set system refresh.timer=managedat least one installed, unbroken snap with a snap-declaration has a connected snapd-control plug with refresh-schedule: managed; otherwise cannot set schedule to managed. The older refresh.schedule is checked the same way
Auto-refreshwith the value managed, snapd schedules no auto-refresh and logs refresh is managed via the snapd-control interface

The snapd-control reference page says these conditions are rechecked before every refresh attempt. In the code they are checked when the option is set; the auto-refresh code reads the value managed without checking the snap again (overlord/snapstate/autorefresh.go).

snapctl model also accepts a connected snapd-control plug as permission.

for app developers for Ubuntu Core developers for snapd developers for administrators

driver-libs: what a connection writes

BackendFileInterfaces
ldconfig/etc/ld.so.conf.d/snap.system.conf, one line per library-source directory of every connected slot; ldconfig runs when the content changedall seven
configfiles (classic)/var/lib/snapd/export/system_<snap>_<slot>_<interface>.library-sourceall seven
symlinks/etc/glvnd/egl_vendor.d/egl-driver-libs
symlinks/etc/vulkan/icd.d/, implicit_layer.d/, explicit_layer.d/vulkan-driver-libs
symlinks/usr/lib/<triplet>/gbm/<client-driver>gbm-driver-libs

snap-confine reads the .library-source files on classic when the Nvidia kernel driver is loaded, in builds with Nvidia multiarch support, and mounts the listed directories into the snap it starts, together with copies of the EGL and Vulkan vendor files.

Only vulkan-driver-libs compares its compatibility label with something at connect time (the ICD api_version); the others check only that the label is valid.

Further reading

Roads from here

INTERFACES AND CONFINEMENT

RUNNING SNAPS

INSIDE SNAPD · the daemon itself