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
01 A program that insists on its paths
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
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
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 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
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
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
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: 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
| Key | Value | Notes |
|---|---|---|
bind | a directory | recursive bind mount, read-write |
bind-file | a file | bind mount of one file |
symlink | a path | a symbolic link at the layout path |
type | tmpfs | an empty tmpfs; no other type is accepted |
mode | octal, default 0755 | must fit in 01777 |
user, group | root | only 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.
| Rule | Error |
|---|---|
| not empty | layout cannot use an empty path |
| no AppArmor pattern characters | invalid layout path: ... |
| absolute | layout "<path>" is a relative filename |
first component is bin, etc, lib, lib64, meta, mnt, opt, root, sbin, snap, srv, usr, var or writable | layout "<path>" defines a new top-level directory "<dir>" |
under /snap only in the snap's own directory | layout "<path>" defines a layout in space belonging to another snap |
only $SNAP, $SNAP_DATA, $SNAP_COMMON as variables | layout "<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 area | layout "<path>" in an off-limits area |
| not at or under an earlier layout path | layout "<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.
Rules for the source and the symlink target
| Rule | Error |
|---|---|
starts with $SNAP, $SNAP_DATA or $SNAP_COMMON | layout "<path>" uses invalid bind mount source "<src>": must start with $SNAP, $SNAP_DATA or $SNAP_COMMON |
| the same for a symlink | layout "<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 file | layout "<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:
| Kind | Requirement | Error |
|---|---|---|
bind from $SNAP | the source is a directory in the tree | layout "<path>" source "<src>" must exist and be a directory, ensure it is present in the snap or created before packing |
bind-file from $SNAP | the source is a regular file | layout "<path>" source "<src>" must exist and be a file, ... |
type: tmpfs at a path under $SNAP | the path is a directory in the tree | layout "<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
| Kind | Source | Type | Options |
|---|---|---|---|
bind | the expanded source | none | rbind,rw,x-snapd.origin=layout |
bind-file | the expanded source | none | bind,rw,x-snapd.kind=file,x-snapd.origin=layout |
type: tmpfs | tmpfs | tmpfs | x-snapd.origin=layout |
symlink | none | none | x-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.
| File | Content |
|---|---|
/var/lib/snapd/mount/snap.<instance>.fstab | the wanted mount profile |
/run/snapd/ns/snap.<instance>.fstab | the 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
| Where | Rule |
|---|---|
app and hook profiles, bind and tmpfs | "<path>{,/**}" mrwklix, |
app and hook profiles, bind-file | "<path>" mrwklix, |
app and hook profiles, symlink | nothing extra |
| the snap's snap-update-ns profile | mount 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 update | What snapd does |
|---|---|
| the namespace is updated | nothing more; processes inside see the new layout |
| the update fails | discards the namespace; the next start builds a new one |
the update fails and the snap has an app with a daemon and refresh-mode: endure | returns 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
| Command | Shows |
|---|---|
snap run --shell <snap>.<app> | a shell inside the snap's namespace, where the layout paths exist |
cat /run/snapd/ns/snap.<instance>.fstab | the 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
- Use layouts: the Snapcraft how-to, the only published guide; it redirects to ubuntu.com/docs/snapcraft.
- The snap format: a short "Layouts" section in the snap.yaml reference.
- Glossary: the definition of a layout.
- Test snaps with snap try: layout changes need a reinstall under
snap try. - Experimental features: where the
layoutsflag is listed as graduated.
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
- The content interface — sharing a directory with another snap which a layout cannot do
- Confinement — the AppArmor profile that the layout rules are added to
DEVELOPING SNAPS · try, pack, run, debug
- Running and debugging an app — snap run --shell to look at a layout from inside
- Trying and packing a snap — snap pack and snap try which both validate layouts
SANDBOX INTERNALS · the mount namespace
- snap-update-ns and the mount profiles — how the mount entries are applied and how a writable mimic is built
- The per-snap mount namespace — the per-snap mount namespace that layouts live in