The content interface

one interface for app developers

Shares directories between snaps. A provider slot names source paths and a consumer plug names a target and a content label. snapd bind-mounts each source onto the target or with a source section into a subdirectory beneath it. Connection needs matching labels and auto-connection also needs the same publisher.

On the map: a postern in the south-west wall

▶ Watch this deck — 6 scenes, ~4 min

01 What content does

CONTENT a snap can't see another snap's files filter-pack (provider)$SNAP/blurslot photo-editor (consumer)plug$SNAP/filters/blur bind mount how platform snaps share themes, libraries and runtimes with many apps
filter-pack's blur directory bind-mounted beneath photo-editor's filters target through a content connection

A provider slot names source directories, a consumer plug names a target, and on connection snapd bind-mounts each source onto the target or beneath it. Platform snaps share themes, libraries and runtimes this way. filter-pack is an invented example.

photo-editor's filters come in a separate snap, filter-pack, so they can be updated on their own. But a snap can't see another snap's files. The content interface is how one snap shares them with another. The provider, filter-pack, offers a slot that names directories of its own. The consumer, photo-editor, has a plug that names a target directory in its own snap. When the two are connected, snapd bind mounts each provider directory onto the target, or into a folder beneath it, inside photo-editor's sandbox. Platform snaps share themes, libraries and whole desktop runtimes with many apps the same way.

02 Both sides in snap.yaml for app developers for Ubuntu Core developers for snapd developers

BOTH SIDES filter-pack snap.yamlslots:filters:interface: contentcontent: photo-filterssource:read: [$SNAP/blur] photo-editor snap.yamlplugs:filters:interface: contentcontent: photo-filterstarget: $SNAP/filtersdefault-provider: filter-pack mounted at $SNAP/filters/blur (target + last element) default-provider: snapd installs filter-pack if it is missing the content labels must match
filter-pack's and photo-editor's snap.yaml for the content interface, with matching content labels, a source section, the resulting path beneath the target, and a default-provider

The slot lists its paths under source; the plug has the same content label and a target. Each source lands at target/<basename>, here $SNAP/filters/blur. A default-provider is installed when missing. Labels must match.

Here are the two halves. In filter-pack's snap.yaml, the slot uses the content interface, gives a content label, photo-filters, and lists one path under source: the blur directory in its own snap. In photo-editor's snap.yaml, the plug carries the same label and a target, a filters directory in its own snap. Because the path sits under source, it lands in a subdirectory named after its last element, so photo-editor finds blur inside filters. The plug can also name a default-provider. If filter-pack is missing, snapd installs it along with photo-editor. And if the labels don't match, the connection is refused.

03 Onto the target or beneath it for app developers for Ubuntu Core developers for snapd developers

TWO FORMS read on the slot (older)slots:filters:read: [$SNAP/blur]plugs:filters:target: $SNAP/filters /snap/filter-pack/5/blur→ /snap/photo-editor/42/filtersmounted on the target itself, which it hides read under sourceslots:filters:source:read:- $SNAP/blur- $SNAP/sharpenplugs:filters: {target: $SNAP/filters} /snap/photo-editor/42/filters/blur/snap/photo-editor/42/filters/sharpenone subdirectory per path, named by its last element read paths are mounted read-only, write paths read-write; one slot uses one form
Side by side: a slot with read directly on it is mounted onto photo-editor's filters target; a slot with read under source is mounted into subdirectories blur and sharpen inside filters

Top-level read/write: each source is mounted on the target itself. Under source: each source is mounted at target/<basename>. Read entries are mounted bind,ro, write entries bind. A slot with both forms is rejected.

There are two ways to write the slot's paths, and they land differently. Put read or write directly on the slot, the older form, and each path is mounted onto the target itself. filter-pack's blur directory would become photo-editor's filters directory, and whatever filters held before is hidden. Put them under source, and each one goes beneath the target, in a subdirectory named after its last element, so blur and sharpen sit side by side inside filters. Either way, read paths are mounted read-only and write paths read-write. One slot can't mix the two forms.

04 Several providers on one target for app developers for Ubuntu Core developers for snapd developers

SEVERAL PROVIDERS a second snap also ships blur · a mount point already taken is renamed: -2, -3 … under sourceread: [$SNAP/blur] target: $SNAP/filters$SNAP/filters/blur$SNAP/filters/blur-2two snaps, same last element-2 lands inside the target older formread: [$SNAP/blur] target: $SNAP/filters$SNAP/filters$SNAP/filters-2-2 is a sibling of the targetthe order of the entries decides who gets it under sourceread: [$SNAP_DATA/presets/$SNAP_INSTANCE_NAME]$SNAP/filters/filter-pack$SNAP/filters/filter-pack_betatwo instancesone name per instance $SNAP_INSTANCE_NAME: only under source, only below $SNAP_DATA or $SNAP_COMMON
Several slots on one plug: under source a second blur lands as blur-2 inside filters; with the older form the second mount becomes filters-2 beside the target; $SNAP_INSTANCE_NAME gives each instance its own directory

A clashing mount point gets a -2, -3 suffix: inside the target under source:, beside the target with the older form. $SNAP_INSTANCE_NAME, allowed only under source: in paths that start with $SNAP_DATA or $SNAP_COMMON, gives each provider instance a distinct name.

One plug can connect to several slots. Say a second pack, from another snap, also ships a blur directory. Now two mount entries want the same mount point, so snapd renames the later one with a -2 suffix, then -3, and so on. Under source, the second blur lands beside the first, inside filters. With the older form the suffix goes on the target itself, next to filters. Which provider gets the suffix depends on the order snapd adds the entries. To give each instance of a provider its own directory, end a source path under $SNAP_DATA or $SNAP_COMMON with $SNAP_INSTANCE_NAME.

05 What the target directory must look like for app developers for Ubuntu Core developers for snapd developers

THE TARGET DIRECTORY snap-update-ns sees only mount entries: source, mount point, options $SNAP_DATA, $SNAP_COMMONwritable: the missing directoryis simply created $SNAP (read-only)writable mimic: a tmpfs over the parent,existing entries bound back in older form$SNAP/filters/filter-pack's blur (the mount)# photo-editor's own filters# are hidden by the mount under source$SNAP/filters/blur/ (mount)sharpen/ (mount)built-in filters (kept)# mimic over filters/ to add them
snap-update-ns creates missing mount points with mkdir in writable directories and with a writable mimic in read-only $SNAP; the older form hides the target's contents, a source section keeps them

snap-update-ns creates missing mount points: a directory in $SNAP_DATA or $SNAP_COMMON, a writable mimic (a tmpfs with bind mounts of what was there) in $SNAP. The older form hides the target's contents; source: keeps them and adds subdirectories.

Does the target have to exist? No. snap-update-ns makes it when it applies the mounts, and it only sees mount entries, not which form produced them. Under $SNAP_DATA or $SNAP_COMMON a missing directory is simply created. $SNAP is read-only, so there it builds a writable mimic: a tmpfs over the parent directory, with everything that was there bound back in, and then it adds the new directory. With the older form, the mount covers the target, so anything photo-editor ships there is hidden. Under source, the target keeps its own files, so photo-editor's built-in filters stay next to blur.

06 The rule for app developers for Ubuntu Core developers for snapd developers

THE RULE base-declaration, slots:content:allow-installation:slot-snap-type: [app, gadget, kernel] allow-connection:plug-attributes:content: $SLOT(content)labels match: may connect allow-auto-connection:plug-publisher-id: [$SLOT_PUBLISHER_ID]plug-attributes:content: $SLOT(content) same publisher: auto-connects other publisher: snap connect,or a snap declaration rule
The base-declaration rule for content: slots on app, gadget and kernel snaps; connection when labels match; auto-connection only within one publisher

Slots on app, gadget and kernel snaps. Connection when the content labels match. Auto-connection only when the publishers match too; otherwise snap connect by hand or a snap declaration rule.

So who may connect to what? The base declaration lets a content slot live on app, gadget and kernel snaps. A connection is allowed when the plug's content label equals the slot's. Auto-connection adds one more condition: both snaps must come from the same publisher. filter-pack and photo-editor do, so they connect at install. A filter pack from someone else matches the label but stays disconnected until you run snap connect. For it to connect by itself, a snap-declaration from the store has to allow it.

Read more

Attributes

The deck's example: photo-editor consumes filters from filter-pack, an invented provider by the same publisher.

SideAttributeMeaning
slotcontentthe label; defaults to the slot name when neither content nor compatibility is given
slotread, writepaths mounted directly on the plug's target (the older form)
slotsource: {read: [...], write: [...]}paths mounted beneath the target, one subdirectory each; cannot be combined with top-level read or write (move the "read" attribute into the "source" section)
slotcompatibilitya compatibility label instead of content; evaluated only with the experimental content-compatibility-label feature
plugcontentthe label to match
plugtargetwhere the content appears; required
plugdefault-provider<snap> or <snap>:<slot>; the slot part is ignored. Installing the consumer installs this snap when it is missing

At least one read or write path is required.

Paths

RuleDetail
Prefixes$SNAP, $SNAP_DATA, $SNAP_COMMON; a path without one is taken as below $SNAP
Cleanunchanged by path cleaning, not starting with ../, no AppArmor pattern characters
$SNAP_INSTANCE_NAMEonly in slot paths under source: that start with $SNAP_DATA or $SNAP_COMMON
Componentsread paths may be $SNAP_COMPONENT(<name>) or $SNAP_COMPONENT(<name>)/<sub>; a component that is not installed is skipped. Write paths may not name a component

Under source: the subdirectory is the last element of the resolved path: $SNAP/blur lands at <target>/blur, $SNAP itself at <target>/<revision>, and $SNAP_COMPONENT(bar) at <target>/bar.

Mounts

Slot entryMount optionsMount point
read, older formbind,ro<target>
write, older formbind<target>
read under source:bind,ro<target>/<last element>
write under source:bind<target>/<last element>
  • Two entries for the same mount point from different sources: the later one is renamed <dir>-2, <dir>-3 and so on, and snapd logs renaming mount entry for directory ... to avoid a clash. Two entries with the same source are merged, read-write winning over read-only.
  • A missing mount point is created by snap-update-ns: a directory in a writable place, a writable mimic in $SNAP. See snap-update-ns.
  • When the provider is refreshed, the consumer's mount namespace is updated too.
  • The published reference says that several directories on one target are merged under it. snapd mounts each on its own mount point, renaming clashes as above.

AppArmor

The plug side gets read, map and run access (mrkix) to read sources, and write access as well (mrwklix) to write sources, which covers Unix sockets in them. With a write source the slot side also gets access to the consumer's target.

The rule

KeyValue
allow-installationslot-snap-type: [app, gadget, kernel]
allow-connectionplug content equals the slot's, or matching compatibility labels
allow-auto-connectionthe same, and plug-publisher-id: [$SLOT_PUBLISHER_ID]

The same rule holds on classic and on Ubuntu Core. A consumer from another publisher connects with snap connect <consumer>:<plug> <provider>:<slot> or through a rule in a snap declaration.

Further reading

Roads from here

GETTING SNAPS

  • The store — default-provider pulls a snap from the store

INTERFACES AND CONFINEMENT

ADMINISTRATION · managing a system of snaps

SANDBOX INTERNALS · the mount namespace