Layouts

a snap.yaml feature for app developers for snapd developers

A layout makes a path outside the snap such as a directory under /etc or /opt appear inside the snap's own mount namespace. It is backed by a directory or file of the snap or its data and nothing changes on the host. There are four kinds - bind and bind-file and symlink and tmpfs. snapd turns each into a mount entry that snap-update-ns applies and into AppArmor rules.

On the map: developing snaps district

▶ Watch this deck — 8 scenes, ~6 min

01 A program that insists on its paths

LAYOUTS the host what acme-agent sees vendor librarylooks for its plug-ins in a fixed system folder without help: not foundthe snap's files are somewhere else the fixed folderthe snap's own filesa layout found, at the same path the fixed folderon the host: still not there one snap's view changes; nothing else does
Two panels: the host, and what acme-agent sees. Inside the snap a vendor library looks for its plug-ins in a fixed system folder and does not find it; a layout makes the fixed folder show the snap's own files and the library finds it; on the host the folder still does not exist

A layout makes a path outside the snap appear inside that snap's own view of the filesystem, backed by the snap's files or its data. The host and other snaps do not see it.

The agent starts, and the vendor library inside it goes looking for its plug-ins in a folder that isn't there. You can't change the library. You may not even have its source. So what can you change? The library has its folders compiled in, and inside a snap those folders are missing or belong to the base. A layout is the other answer. You tell snapd that, for this snap only, that folder should exist and should show the snap's own files. The library opens the path it always opened and finds what it needs. On the host, nothing changed: the folder still isn't there.

02 Four kinds of layout for app developers for snapd developers

THE LAYOUT KEY layout:/opt/acme:bind: $SNAP/opt/acme/etc/acme/agent.conf:bind-file: $SNAP_DATA/agent.conf/usr/share/acme:symlink: $SNAP/share/var/cache/acme:type: tmpfsinside the snap /opt/acme$SNAP/opt/acmebind: a directory, with everything below it /etc/acme/agent.conf$SNAP_DATA/agent.confbind-file: one file /usr/share/acme→ $SNAP/sharesymlink: shows up as a link /var/cache/acmetype: tmpfs: empty, in memory typo detected: use singular "layout" insteadof plural "layouts"exactly one kind per entry · mode defaults to 0755user and group accept only root
The layout key of acme-agent's snap.yaml with four entries, and what each makes inside the snap: /opt/acme bound from $SNAP/opt/acme, /etc/acme/agent.conf bound as one file from $SNAP_DATA/agent.conf, /usr/share/acme as a symlink to $SNAP/share, and /var/cache/acme as an empty tmpfs. Writing layouts instead of layout is reported as a typo

bind for a directory, bind-file for one file, symlink for a link, type: tmpfs for an empty directory. One kind per path; mode defaults to 0755 and user and group accept only root.

Four things the library wants: a folder of plug-ins, one settings file, a data folder and some scratch space. A layout has a kind for each. Under the layout key, each path you want to exist is a key, and its value says how to fill it. Bind mounts a directory, with everything below it. bind-file does the same for one file. Symlink makes a symbolic link, and a program that checks will see that it's a link. type: tmpfs gives an empty directory in memory, the only filesystem type allowed. One kind per entry. And the key is layout, singular: write layouts and snapd reports a typo.

03 The source comes from the snap for app developers

WHERE A LAYOUT POINTS FROM the source must start with one of three variables$SNAP$SNAP_DATA$SNAP_COMMONthe layout path the snap itself: read-only/opt/acme writable, per revision/etc/acme/agent.conf writable, shared by all revisions/var/lib/acme (an example) /etc/ssl on the hostuses invalid bind mount source "/etc/ssl":must start with $SNAP, $SNAP_DATA or $SNAP_COMMONa layout cannot bring host files into the snap; interfaces are the way to reach those $ snap packbases other than core to core24 onlylayout "/opt/acme" source "$SNAP/opt/acme" must exist and be a directory, ...
Three allowed sources for a layout: $SNAP, read-only, behind /opt/acme; $SNAP_DATA, writable per revision, behind /etc/acme/agent.conf; $SNAP_COMMON, writable and shared by all revisions, behind an example /var/lib/acme. A source on the host such as /etc/ssl is refused because it must start with one of the three. snap pack also requires a source under $SNAP to exist, for bases other than core to core24

Sources and symlink targets must start with $SNAP, $SNAP_DATA or $SNAP_COMMON; only the last two are writable. For bases other than core to core24, snap pack also requires that sources under $SNAP exist in the snap.

The library writes to its settings file. So what's really behind a layout, and can the program write there? The source of a bind, a bind-file or a symlink has to start with one of three variables. Plug-ins that ship with the snap come from $SNAP, which is read-only. A settings file the configure hook rewrites belongs in $SNAP_DATA, kept per revision. State shared by every revision goes in $SNAP_COMMON. A source on the host is refused, so a snap can't slip outside files into its own view. And for bases other than core to core24, snap pack checks that sources under $SNAP exist.

04 Where a layout may not go for app developers for snapd developers

THE PATH IS CHECKED TOO /dev/acme/home/acme? checked by snap pack, by snap try and on every install/opt/acmeaccepted: opt is an allowed top-level directory /acme/pluginslayout "/acme/plugins" defines a new top-level directory "/acme"it would need a writable copy of / itselfallowed first components: bin etc lib lib64 meta mnt opt root sbin snap srv usr var writable layout "/dev/acme" defines a new top-level directory "/dev"the same for /home, /run, /tmp, /proc, /sys and /boot /lib/modules/acmelayout "/lib/modules/acme" in an off-limits areaalso /lib/firmware, /var/lib/snapd, /var/snap, /var/run and the /usr/lib twins /opt/acme/pluginslayout "/opt/acme/plugins" underneath prior layout item "/opt/acme"one layout cannot sit inside another
Candidate layout paths checked by snap pack, snap try and every install: /opt/acme is accepted; /acme/plugins defines a new top-level directory; /dev/acme and /home/acme are refused for the same reason; /lib/modules/acme is in an off-limits area; /opt/acme/plugins is underneath the prior layout /opt/acme. The allowed first components are bin, etc, lib, lib64, meta, mnt, opt, root, sbin, snap, srv, usr, var and writable

The first path component must be one of fourteen top-level directories, which already rules out /dev, /run, /tmp and /home. Sixteen off-limits areas such as /lib/modules and /var/lib/snapd are refused, and a layout cannot be nested under another.

If a layout can make any folder appear, can it make /dev appear? Or /home? No, and here's why. The same checks run in snap pack, in snap try and on every install. /opt/acme is fine. The first part of the path has to be one of fourteen top-level directories, like opt or var. A new one would need a writable copy of the root itself, and snapd doesn't do that. That alone keeps out dev, run, tmp and home. Deeper down, some areas are off limits: the kernel loads modules and firmware, so a snap can't replace those. And one layout can't sit underneath another.

05 From snap.yaml to a mount entry for app developers for snapd developers

WHAT SNAPD MAKES OF IT /opt/acme:bind: $SNAP/opt/acme mount backend/snap/acme-agent/42/opt/acme /opt/acme nonerbind,rw,x-snapd.origin=layout 0 0/var/lib/snapd/mount/snap.acme-agent.fstabthe wanted profile: variables expanded, sorted by path bind-filebind,rw,x-snapd.kind=filesymlinkx-snapd.kind=symlink,x-snapd.symlink=<target>tmpfstmpfs <path> tmpfsevery kind ends in x-snapd.origin=layout snap-update-ns/run/snapd/ns/snap.acme-agent.fstabwhat is mounted now AppArmorbackend"/opt/acme{,/**}" mrwklix,in every app and hook profile of the snap; nothing extra for a symlink
The layout entry /opt/acme bind $SNAP/opt/acme becomes, through the mount backend, the fstab line /snap/acme-agent/42/opt/acme /opt/acme none rbind,rw,x-snapd.origin=layout 0 0 in /var/lib/snapd/mount/snap.acme-agent.fstab. The other kinds get x-snapd.kind=file, x-snapd.kind=symlink with x-snapd.symlink, or type tmpfs. snap-update-ns applies the profile and records it in /run/snapd/ns/snap.acme-agent.fstab. The AppArmor backend adds the rule /opt/acme{,/**} mrwklix to every app and hook profile

Each layout becomes one line in /var/lib/snapd/mount/snap.<name>.fstab tagged x-snapd.origin=layout; snap-update-ns applies it and records the result in /run/snapd/ns/snap.<name>.fstab. The AppArmor profiles of every app and hook get "<path>{,/**}" mrwklix,, or nothing extra for a symlink.

You've written four entries in snap.yaml. Nothing in the kernel knows what a layout is. So what does snapd turn them into? Lines in the same mount profile that the content interface writes to. The mount backend expands the variables and writes source, mount point and options, sorted by path, ahead of what interfaces add. One option marks a line as a layout: x-snapd.origin=layout. snap-update-ns applies the profile to the snap's namespace and records the result under slash run. That's half of it. The program also needs permission, so every app and hook profile gets an AppArmor rule for the path.

06 When the mount point is missing for app developers for snapd developers

THE WRITABLE MIMIC 1 · from the base/optread-onlyexisting entries, if any/opt/acmemissing, and cannot be created 2 · a writable mimic/opt tmpfssame mode, same owner existing entriesmounted back in place 3 · the layout mounted/opt tmpfsexisting entries/opt/acme$SNAP/opt/acme only for entries with x-snapd.origin=layout;a content mount does not get this $ snap run --shell acme-agent.agent$ stat -f /opt -c '%T'tmpfs
/opt inside acme-agent in three states: from the base, read-only, where /opt/acme does not exist and cannot be created; replaced by a tmpfs with the same mode and owner and with its existing entries mounted back; then /opt/acme created in the tmpfs and $SNAP/opt/acme mounted on it. In a shell inside the snap, stat -f /opt reports tmpfs. Only entries with x-snapd.origin=layout get this

When a layout path is missing under a read-only directory, snap-update-ns replaces the parent with a tmpfs that mirrors it, a writable mimic, and creates the path there. It does so only for entries with x-snapd.origin=layout. From inside, the parent's filesystem type is tmpfs.

There's a catch. To mount something at /opt/acme, it has to exist first, and the base snap is read-only. Who creates it? snap-update-ns does. Inside this snap only, it replaces /opt with an in-memory filesystem that looks the same: same mode, same owner, and whatever was in it mounted back in place. Now there's somewhere to create the missing folder, and the layout is mounted on it. Only layout entries get this, not content sharing, because only this namespace sees the result. From a shell inside the snap, /opt reports tmpfs.

07 A refresh changes the layout for app developers for snapd developers

REVISION 42 TO 43 42 · /opt/acme: bind: $SNAP/opt/acme43 · /opt/acme: symlink: $SNAP/opt/acme the mount profile changedsnap-update-ns updates it at once worked: whatever runs insidesees the new layout faileddiscard the namespacethe next start builds a fresh one failed, buta daemon with refresh-mode: endurecannot update mount namespace of snap "acme-agent", and cannot discard itbecause it contains an enduring daemon: ...snapd checks that the snap has such a daemon, not whether it is running
Revision 42 of acme-agent binds /opt/acme and revision 43 makes it a symlink. The mount profile changed, so snap-update-ns updates the existing namespace at once. If that works, what runs inside sees the new layout. If it fails, the namespace is discarded and the next start builds a fresh one, unless the snap has a daemon with refresh-mode: endure, in which case snapd reports that it cannot update the mount namespace and cannot discard it

A changed mount profile is applied to the existing namespace at once. If that fails, the namespace is discarded and rebuilt on the next start, unless the snap has a daemon with refresh-mode: endure; then snapd returns an error instead.

Revision 43 of the agent turns the bind mount at /opt/acme into a symlink. The namespace from 42 is still there. What happens to it? When the mount profile changes, snapd asks snap-update-ns to bring the existing namespace in line at once: unmount what's gone, mount what's new. Some changes don't apply cleanly, and a bind mount that became a symlink is the classic one. Then snapd throws the namespace away, and the next start builds a fresh one. Unless the snap has a daemon with refresh-mode: endure. That daemon may still be running inside, so snapd reports that it can neither update nor discard.

08 Where to go from here

ROADS Layouts snap-update-nsapplying entries, the mimic The mount namespacewhere layouts live The content interfaceanother snap's directory Confinementthe AppArmor profile Run and debuga shell inside the snapTry and packwhere layouts are checkedSnap packagingOverview
Roads from Layouts: snap-update-ns, the mount namespace, the content interface, confinement, run and debug, try and pack, snap packaging and the overview

Roads: snap-update-ns and the mount namespace, the content interface, confinement, run and debug, try and pack, snap packaging and the overview.

That's a layout: a snap's own files, shown at the address a program expects. A few roads lead on from here. To see how the entries are applied and how a writable mimic is built, take the road to snap-update-ns. The namespace deck has the larger picture that layouts live in. If what you need is another snap's directory, that's the content interface, not a layout. Confinement covers the AppArmor profile the layout rules join. And when a layout doesn't behave, run and debug shows how to open a shell inside the snap and look, while try and pack covers where layouts are checked.

Read more

Keys of one layout entry

KeyValueNotes
binda directoryrecursive bind mount, read-write
bind-filea filebind mount of one file
symlinka patha symbolic link at the layout path
typetmpfsan empty tmpfs; no other type is accepted
modeoctal, default 0755must fit in 01777
user, grouprootonly root is accepted

Exactly one of bind, bind-file, symlink and type per entry, otherwise layout "<path>" must define a bind mount, a filesystem mount or a symlink. The key is layout, not layouts: the plural is reported as typo detected: use singular "layout" instead of plural "layouts". No feature flag is needed; layouts has graduated.

Rules for the path

The same checks run in snap pack, snap try and every install.

RuleError
not emptylayout cannot use an empty path
no AppArmor pattern charactersinvalid layout path: ...
absolutelayout "<path>" is a relative filename
first component is bin, etc, lib, lib64, meta, mnt, opt, root, sbin, snap, srv, usr, var or writablelayout "<path>" defines a new top-level directory "<dir>"
under /snap only in the snap's own directorylayout "<path>" defines a layout in space belonging to another snap
only $SNAP, $SNAP_DATA, $SNAP_COMMON as variableslayout "<path>" uses invalid mount point: reference to unknown variable "<var>"
clean: no .., // or trailing /layout "<path>" uses invalid mount point: must be absolute and clean
not in an off-limits arealayout "<path>" in an off-limits area
not at or under an earlier layout pathlayout "<path>" underneath prior layout item "<other>"

The top-level check runs first, so a path under /dev, /run or /home is reported as a new top-level directory, not as an off-limits area.

The check for another snap's space compares name prefixes without a path separator: for a snap foo, a path under /snap/foobar/ is accepted. Keep layouts out of /snap unless they are under your own snap's directory. This is a snapd defect (findings/expansion/SUSPECTED-BUGS.md V1).

Off-limits areas

/dev, /proc, /sys, /media, /run, /var/run, /tmp, /var/lib/snapd, /lib/firmware, /usr/lib/firmware, /lib/modules, /usr/lib/modules, /var/snap, /home, /boot, /lost+found. A path at or under any of these is refused. Of these, /var/run, /var/lib/snapd, /var/snap and the firmware and module directories are the ones that pass the top-level check and are caught here.

RuleError
starts with $SNAP, $SNAP_DATA or $SNAP_COMMONlayout "<path>" uses invalid bind mount source "<src>": must start with $SNAP, $SNAP_DATA or $SNAP_COMMON
the same for a symlinklayout "<path>" uses invalid symlink old name "<target>": must start with $SNAP, $SNAP_DATA or $SNAP_COMMON
one source is not both a directory and a filelayout "<path>" refers to directory "<src>" but another layout treats it as file

The source in these messages is shown with the variables expanded. The test compares the expanded path with the expanded variables as a string prefix, without a path separator, so a sibling such as /var/snap/<snap>/commonx also passes. It does not give access to another snap's files. This is a snapd defect (findings/expansion/SUSPECTED-BUGS.md V2).

Checks only snap pack makes

For bases other than core, core18, core20, core22 and core24:

KindRequirementError
bind from $SNAPthe source is a directory in the treelayout "<path>" source "<src>" must exist and be a directory, ensure it is present in the snap or created before packing
bind-file from $SNAPthe source is a regular filelayout "<path>" source "<src>" must exist and be a file, ...
type: tmpfs at a path under $SNAPthe path is a directory in the treelayout "<path>" must exist as a directory in the snap, ensure it is present or created before packing

Sources under $SNAP_DATA and $SNAP_COMMON and symlink targets are not checked. These checks do not run at install.

for snapd developers for app developers

From a layout to a mount entry

KindSourceTypeOptions
bindthe expanded sourcenonerbind,rw,x-snapd.origin=layout
bind-filethe expanded sourcenonebind,rw,x-snapd.kind=file,x-snapd.origin=layout
type: tmpfstmpfstmpfsx-snapd.origin=layout
symlinknonenonex-snapd.kind=symlink,x-snapd.symlink=<target>,x-snapd.origin=layout

Each line ends with 0 0. A mode other than 0755 adds x-snapd.mode=<octal> before the origin. Order in the profile: entries for a parallel instance's name mapping, then layouts sorted by path, then entries from interfaces. Layouts declared by the base snap are not applied.

FileContent
/var/lib/snapd/mount/snap.<instance>.fstabthe wanted mount profile
/run/snapd/ns/snap.<instance>.fstabthe profile snap-update-ns last applied

When snap-update-ns has to create a missing mount point under a read-only directory, it builds a writable mimic only for entries with x-snapd.origin=layout; see snap-update-ns.

for snapd developers for app developers

AppArmor rules

WhereRule
app and hook profiles, bind and tmpfs"<path>{,/**}" mrwklix,
app and hook profiles, bind-file"<path>" mrwklix,
app and hook profiles, symlinknothing extra
the snap's snap-update-ns profilemount options=(rbind, rw) "<src>/" -> "<path>/",, mount options=(rprivate) -> "<path>/",, umount "<path>/", and the rules for a mimic at the path and at the source

When the profile changes

Outcome of the updateWhat snapd does
the namespace is updatednothing more; processes inside see the new layout
the update failsdiscards the namespace; the next start builds a new one
the update fails and the snap has an app with a daemon and refresh-mode: endurereturns cannot update mount namespace of snap "<snap>", and cannot discard it because it contains an enduring daemon: ...

The check is for such an app in the snap, not for a running daemon.

Looking at a layout

CommandShows
snap run --shell <snap>.<app>a shell inside the snap's namespace, where the layout paths exist
cat /run/snapd/ns/snap.<instance>.fstabthe entries applied now (as root)

Quota groups with a journal quota add entries of their own through the same path; see quota groups. Whether a layout has any effect for a snap with classic confinement was not determined: no validation rule refuses the combination.

Further reading

The snapd documentation has no page on how layouts work; this deck is the description.

Roads from here

START HERE

  • snapd — back to the overview

GETTING SNAPS

  • Snap packaging — what $SNAP and $SNAP_DATA and $SNAP_COMMON point at

INTERFACES AND CONFINEMENT

DEVELOPING SNAPS · try, pack, run, debug

SANDBOX INTERNALS · the mount namespace