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
01 What content does
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
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
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
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
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
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.
| Side | Attribute | Meaning |
|---|---|---|
| slot | content | the label; defaults to the slot name when neither content nor compatibility is given |
| slot | read, write | paths mounted directly on the plug's target (the older form) |
| slot | source: {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) |
| slot | compatibility | a compatibility label instead of content; evaluated only with the experimental content-compatibility-label feature |
| plug | content | the label to match |
| plug | target | where the content appears; required |
| plug | default-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
| Rule | Detail |
|---|---|
| Prefixes | $SNAP, $SNAP_DATA, $SNAP_COMMON; a path without one is taken as below $SNAP |
| Clean | unchanged by path cleaning, not starting with ../, no AppArmor pattern characters |
$SNAP_INSTANCE_NAME | only in slot paths under source: that start with $SNAP_DATA or $SNAP_COMMON |
| Components | read 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 entry | Mount options | Mount point |
|---|---|---|
| read, older form | bind,ro | <target> |
| write, older form | bind | <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>-3and so on, and snapd logsrenaming 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
| Key | Value |
|---|---|
allow-installation | slot-snap-type: [app, gadget, kernel] |
allow-connection | plug content equals the slot's, or matching compatibility labels |
allow-auto-connection | the 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
- The content interface: attributes, examples with and without
source, parallel-installed providers. - Interface auto-connection: when a store rule is needed.
- Connect interfaces: connecting a plug to a named slot.
Roads from here
GETTING SNAPS
- The store — default-provider pulls a snap from the store
INTERFACES AND CONFINEMENT
- Interfaces — back to interfaces
- Interfaces for snap developers — where plugs and slots are declared
- How interfaces are implemented — the mount backend that does the work
- The home interface — another single interface
- The network interface — another single interface
ADMINISTRATION · managing a system of snaps
- Parallel installs — instances of one provider snap
SANDBOX INTERNALS · the mount namespace
- snap-update-ns and the mount profiles — how the mounts are applied and the writable mimic made