"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
01 Three kinds of interface in this family
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
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
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
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
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
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
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
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
| 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 and does not reconnect it on refresh |
snap interface personal-files --attrs | every 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-files | system-files | |
|---|---|---|
| Each path must | start with $HOME/ and use $HOME only there | start with / and not contain $HOME |
| Both refuse | ~, AppArmor pattern characters, a trailing / or @, paths that change under filepath.Clean | the same |
| AppArmor rule | owner "@{HOME}/<path>{,/,/**}" | "<path>{,/,/**}" |
read entry | rk (read, lock) | rk |
write entry | rwkl (read, write, lock, link) | rwkl |
| Missing directories | snap-update-ns creates the parents of each write path below $HOME, not the leaf | none 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
| Step | What snapd checks |
|---|---|
| Install | the plug has allow-installation: false: a store snap needs a snap-declaration |
| Connect | deny-auto-connection: true: by hand, or by a store rule |
snap set system refresh.timer=managed | at 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-refresh | with 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
| Backend | File | Interfaces |
|---|---|---|
| ldconfig | /etc/ld.so.conf.d/snap.system.conf, one line per library-source directory of every connected slot; ldconfig runs when the content changed | all seven |
| configfiles (classic) | /var/lib/snapd/export/system_<snap>_<slot>_<interface>.library-source | all 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
- personal-files interface: attributes and an example of importing a configuration from the home directory.
- system-files interface: attributes and the store review requirement.
- snapd-control interface: the three steps to a managed refresh schedule. It says the conditions are rechecked before each refresh, which the code does not do.
- Super-privileged interfaces: why some interfaces need a snap-declaration to install.
- Connect interfaces:
snap connections,snap connectandsnap disconnectfrom the user's side. - cuda-driver-libs interface: the slot attributes of the driver-libs pattern.
Roads from here
INTERFACES AND CONFINEMENT
- The home interface — the one member that auto-connects on desktops; its own deck
- The content interface — the sharing interface with the most attributes; its own deck
- Interfaces — back to the interfaces overview
- How interfaces are implemented — the mount and ldconfig backends and the policy checks
RUNNING SNAPS
- Who decides when a snap updates — a managed refresh schedule beside the other ways to control updates
- The overlord — the daemon behind snapd-control
INSIDE SNAPD · the daemon itself
- The snapd REST API — the endpoints that the marker interfaces unlock