content interface¶

The content interface allows sharing code and data from a slot on a producer snap to one or more plugs on consumer snaps. It’s often used to share common themes and icons from a producer snap, for example, to many snapped applications.

Sharing happens at the filesystem level, which means anything that can be expressed as a file can be shared. This includes executables, libraries and data files, but also sockets.

Example¶

The Yaru MATE Icons snap is a good producer snap example, letting other applications access the wonderful MATE icon theme. But there are many other producer snaps too, including several for GTK Common Themes, KDE Frameworks for better application integration with the desktop, and Mesa for a graphical libraries stack.

Developer details¶

Auto-connect: no, unless connecting to snaps from the same publisher.

Attributes:

source (slot): allows multiple directories to be exposed separately rather than grouped together
read (slot): read-only paths to be exposed to a consuming snap
write (slot): read and write paths to be exposed to a consuming snap
target (plug): path in consuming snap to find producer snap’s files
default-provider (plug): name of preferred producer snap (<SNAP>)
content (slot and plug): an arbitrary identifier for content type. Defaults to either local slot name or local plug name for slot/plug definitions respectively.
interface (slot and plug): snapd interface name (must be interface: content)

Sharing content¶

By default, when multiple directories are shared from a producer snap, or when multiple slots are connected to a single plug, the shared content is merged under the target path of the consuming path’s plug definition. This behaviour can be modified with the source attribute.

Read, write and target should start with either $SNAP, $SNAP_DATA or $SNAP_COMMON to refer to the designated directory. See Environment variables for details on where these point to on the filesystem.

Paths declared in a slot’s source attribute can also reference $SNAP_INSTANCE_NAME, but only within a path that starts with $SNAP_DATA or $SNAP_COMMON. This is useful for sharing a separate, per-instance directory with consumers of a parallel-installed producer snap. See the Parallel installed content providers section below. Requires snapd 2.79+.

The content identifier specified by the consuming snap (plug) must match the content attribute of the producer snap (slot).

At a very basic level, the content interface enables one directory, file or socket to appear in a place where another snap can access it.

Each example below involve two snaps: the first provides some content (using a content slot) while the second consumes that content (using a content plug).

In all of the cases we see a small set of attributes defined on the particular interface:

the producer declares which path can be read, using either the read attribute for read-only, or the write attribute for both read and write permissions
the consumer uses the target attribute to define where the content should become available at runtime.
both the producer and consumer use an arbitrary content attribute to describe the content. This attribute must match on both sides for the connection to happen.

Using `source`¶

The source attribute presents one or more sub-directories, shared from a slot to a plug, beneath the plug’s target path. Adding the source attribute ensures that sub-directories, shared from one or more producer snaps, are presented separately to the consumer snap beneath its target path.

When multiple slots are connected to the same plug and they share directories with the same name, those directories are given unique names with the following pattern: <directory>, <directory>-2, <directory>-3, <directory>-x. The first connection keeps the original directory name from the slot; subsequent connections with the same name get the suffixed form.

With the following example, directories from the producer snap are shared in corresponding directories beneath the consumer snap’s target path:

producer/snapcraft.yaml:

slots:
  <slot_name>:
    interface: content
    content: my-binaries
    source:
      read:
        - $SNAP/bin   # binaries to share
        - $SNAP/libs  # libraries to share

consumer/snapcraft.yaml:

plugs:
  <plug_name>:
    interface: content
    content: my-binaries
    target: $SNAP/connected-content

Using the above configuration, the consumer snap could implement a part to run an executable from the following path:

$SNAP/connected-content/bin/<executable-name>

While the libraries are accessible at:

$SNAP/connected-content/libs/<library-name>

When more than one slot, providing similarly named sources, is connected to the same plug, the plug directory for the new connection will be incremented:

$SNAP/connected-content/bin-2/<executable-name>

Directory names are preserved after a reboot.

Parallel installed content providers¶

Requires snapd 2.79+.

When a slot’s source attribute declares paths starting with $SNAP_DATA or $SNAP_COMMON and with $SNAP_INSTANCE_NAME as the final path element, it allows a consumer snap to get a separate directory for each instance of the parallel-installed producer snap.

producer/snapcraft.yaml:

slots:
  <slot_name>:
    interface: content
    content: assets
    source:
      read:
        - $SNAP_DATA/assets/$SNAP_INSTANCE_NAME

consumer/snapcraft.yaml:

plugs:
  <plug_name>:
    interface: content
    content: assets
    target: $SNAP_DATA/assets

If multiple instances of producer snap such as my-producer, my-producer_inst1 and my-producer_inst2 are all connected to the consumer’s plug, the consumer sees each producer’s content under its own instance name:

$SNAP_DATA/assets/my-producer/...
$SNAP_DATA/assets/my-producer_inst1/...
$SNAP_DATA/assets/my-producer_inst2/...

Since $SNAP_INSTANCE_NAME is only known at content provider snap installation time, it can only be used when sharing data from writable locations, such as $SNAP_DATA or $SNAP_COMMON.

Using the `read` and `write` attributes¶

Without the source attribute, content from the producer snap is mounted at the exact path indicated in the consumer snap:

producer/snapcraft.yaml:

slots:
  <slot_name>:
    interface: content
    content: my-binaries
    read:
      - $SNAP/bin

consumer/snapcraft.yaml:

plugs:
  <plug_name>:
    interface: content
    content: my-binaries
    target: $SNAP/usr/local/bin

Using the above configuration, the consumer snap can access executables using the following path:

$SNAP/usr/local/bin/<executable-name>

When more than one slot is connected to the same plug, the plug directory for the new connection will be incremented using the same mechanism as with the source attribute described above (<directory>, <directory>-2, <directory>-3, <directory>-x).

It is recommended to only expose a single read path using this configuration.

Read-only content sharing¶

Read-only content sharing is ideal for executables, libraries and files related to global graphical themes or images.

Content identifier obligations¶

The content identifier attribute identifies a mostly-immutable compatibility contract (API/ABI or similar) between the snap providing the corresponding content and the snaps consuming it.

The providing snap must preserve backward compatibility for the content provided under a given identifier.

Equally, updates to consuming snaps cannot strongly depend on changes of the identified content from updates to the providing snaps.

There is no support in snapd to synchronise updates between consuming and providing snaps. Compatibility breaking changes need to happen under a different content identifier.

Default provider¶

The optional default-provider attribute can be used to set to the name of a snap offering a corresponding content slot:

consumer/snapcraft.yaml

plugs:
  lib0-1604:
    interface: content
    content: lib0-1604
    target: $SNAP/extra-libs
    default-provider: lib01604

If the system does not contain a snap providing a matching slot, installing a consumer snap with a default-provider will trigger the automatic installation of the named provider snap. If the named snap is already installed, the absence of a matching slot will instead trigger an update of the named provider snap. The plug and slot will be auto-connected assuming the auto-connection mechanism is configured properly for this.

For example, a snap consuming the GNOME content snap for GNOME 3.26 can set default-provider to gnome-3-26-1604.

Technical details¶

The content interface is implemented via an interplay between two systems: AppArmor and bind mounts.

By default, the AppArmor sandbox allows writes to $SNAP_DATA and reads from $SNAP (see Environment variables for details).

The content interface takes advantage of this feature to map data from other locations to either $SNAP or $SNAP_DATA.

A bind mount is then created to link $SNAP in one snap (e.g. from /snap/my-snap/1234/content) to an empty directory in the other snap (e.g., to /snap/my-other-snap/4321/incoming-content). Locations need to be selected carefully because a bind mount could potentially permit mounts over important locations, such as $SNAP_DATA, preventing access to a snap’s own writable space.

The same can be done for particular files, if desired, but it requires a pair of interfaces for each file and is more cumbersome.

Code examples¶

The previously mentioned Yaru MATE Icons snap is a good example of how this interface can be used to share media with other snaps. Its snapcraft.yaml can be found here: https://github.com/ubuntu-mate/icon-theme-yaru-mate-snap/blob/main/snap/snapcraft.yaml

The source code for this interface is in the snapd repository: https://github.com/canonical/snapd/blob/master/interfaces/builtin/content.go

content interface¶

Example¶

Developer details¶

Sharing content¶

Using source¶

Parallel installed content providers¶

Using the read and write attributes¶

Read-only content sharing¶

Sharing an executable¶

Sharing a C-level library¶

Sharing icons or themes¶

Content identifier obligations¶

Default provider¶

Sharing writable data¶

Technical details¶

Code examples¶

Using `source`¶

Using the `read` and `write` attributes¶