Snap packaging
the snap file for app developers for Ubuntu Core developers for snapd developers
A snap is one squashfs file with meta/snap.yaml inside. snapd keeps the file whole and mounts it read-only under /snap at its revision. A current symlink selects the active revision and the writable data lives in separate directories. The base snap supplies the root filesystem and components are further files mounted beside the snap.
On the map: the granary
01 One file, mounted, not unpacked
A snap is one compressed, read-only file. The system mounts it instead of unpacking it, the snap's writable data is kept outside it, and each revision is a separate file.
When you install acme-agent, where do its files go? Mostly, nowhere. Most packages get unpacked, and their files end up spread: all over the system. A snap arrives as one compressed file and stays one file. The system mounts it, so the apps can read what's inside exactly as it was packed. Nothing in it can be changed, not by the snap and not by anything else, and that's what lets one digest stand for all of its content. Anything the snap writes goes to separate data directories. And since each revision is its own file, revision 41 sits right next to 42, untouched.
02 Inside the file for app developers for Ubuntu Core developers for snapd developers
A snap is a squashfs image. meta/snap.yaml must be readable and app commands must be executable. Absent keys default to type: app, confinement: strict, architectures: [all] and epoch: 0.
Let's open the file. Inside there's a plain directory tree, and one path that snapd insists on. The file is a squashfs image, and snapd recognises it by its first four bytes. The path is snap.yaml, in a directory called meta, and it says what the snap is. Hooks sit next to it, in meta/hooks. The yaml can be short, because missing keys have defaults: type app, strict confinement, all architectures, epoch 0. snapd refuses a file whose snap.yaml can't be read, or whose app commands are missing or not executable. Snap pack builds the file from a directory and runs the same checks.
03 Revision is not version
The version is free text from the publisher. The revision is assigned by the store to each uploaded file. A file installed without store signatures gets a local revision: x1, then x2; installed without --dangerous, a file whose signatures snapd already has keeps its store revision.
Two numbers follow every snap around, and people mix them up all the time. One is a label. The other is an identity. The version is whatever the publisher wrote, and two different files can carry the same one. The revision names one exact file. The store hands it out when a file is uploaded, and the signed statement about that file repeats it. So when you ask what's installed, the revision is the precise answer. Now build acme-agent yourself and install it with --dangerous. There's no store revision, so it gets a local one: x1. The next local file gets x2.
04 From a file to a directory for app developers for Ubuntu Core developers for snapd developers for administrators
mount-snap keeps the file as /var/lib/snapd/snaps/acme-agent_42.snap, creates /snap/acme-agent/42 and writes a systemd mount unit of type squashfs with ro and nodev that joins them. The unit is named after the escaped mount path.
The file has arrived and its digest checks out. Now it has to become something a program can run. The task called mount-snap does three things. It keeps the file in snapd's own directory, named after the snap and the revision. It makes an empty directory for that revision. And it writes a systemd mount unit that joins the two, then starts it. From then on the mount is systemd's job, which is why it's back after every boot without snapd doing a thing. The options say read-only. A kernel snap also gets its boot assets extracted here. And snap try mounts a directory instead of a file.
05 current, and where the data lives for app developers for Ubuntu Core developers for snapd developers for administrators
current is a relative symlink to the active revision, under /snap/acme-agent and under /var/snap/acme-agent; on a refresh both are removed by unlink-current-snap and re-created by link-snap. Data in a numbered directory belongs to one revision; data in common is shared.
Revision 41 and revision 42 are both sitting there, mounted. Which one runs? One tiny symlink decides. It's called current, and it holds nothing but a revision number. There's a matching one on the data side. On a refresh both are removed when 41 is unlinked; link-snap points them at 42, and an undo points them back. The data side has two kinds of directory: one per revision, so each revision keeps the data it wrote, and common, which every revision shares. The apps don't hard-code any of this. They read $SNAP, $SNAP_DATA and $SNAP_COMMON, and per user, $SNAP_USER_DATA and $SNAP_USER_COMMON.
06 The base is the root filesystem for app developers for Ubuntu Core developers for snapd developers
base: names the snap whose content is the root filesystem for the snap's apps. The prerequisites task installs a missing base from stable, and snapd, before the snap is mounted. No base means core; base: none forbids apps and hooks. Snaps of type snapd, os, base and gadget skip the step.
acme-agent brings its own program, but no C library and no shell. Those come from the base: another snap, of type base, whose content is what the app sees as the root of the filesystem. One line in snap.yaml names it. snapd makes sure it's there. The first task of an install, prerequisites, installs a missing base from the stable channel, and snapd too if it's missing. A second prerequisites task waits for them, before the mount. An app snap with no base line gets the old core snap. And a base of none means no base at all, so no apps and no hooks.
07 A component is a second file for app developers for Ubuntu Core developers for snapd developers
A component is a separate squashfs file, acme-agent+diagnostics_7.comp, with meta/component.yaml and its own revision. It is mounted under /snap/acme-agent/components/mnt and linked from components/42, the directory in SNAP_COMPONENTS.
Suppose acme-agent has a diagnostics kit that only a few gateways need. Why should every gateway download it? That's what a component is for: a second file of the snap, installed only where you ask for it, by the snap name, a plus sign and the component name. It's a squashfs like the snap, with its own metadata file and its own revision. snapd mounts it under the snap's components directory, then adds a link for the snap-revision that uses it, so each snap-revision sees the component revision that goes with it. The snap finds it through $SNAP_COMPONENTS. And the store signs for the pairing.
08 Where to go from here
Roads: the store, the assertions about a file, what else a snap declares (plugs and slots, services, hooks), confinement, and remove and revert.
So a snap is a file, a number, a mount and a handful of directories. Here's where each of those leads. The store deck shows how the file arrives and how its digest is checked, and the assertions deck shows who vouches for it. The rest of what a snap declares is spread over three decks: plugs and slots, services, and hooks. Confinement shows how the base and the snap are put together into what a running app sees. And remove and revert covers the older revisions that are still on disk.
Read more
Where one snap lives
| Path | What it is |
|---|---|
/var/lib/snapd/snaps/<name>_<rev>.snap | the snap file |
/snap/<name>/<rev> | the file, mounted read-only |
/snap/<name>/current | symlink to the active revision |
/var/snap/<name>/<rev> | system data of that revision |
/var/snap/<name>/common | system data shared by all revisions |
/var/snap/<name>/current | symlink to the active revision's data |
~/snap/<name>/<rev> | a user's data for that revision |
~/snap/<name>/common | a user's data shared by all revisions |
~/snap/<name>/current | symlink, made when the user runs the snap |
/var/lib/snapd/save/snap/<name> | data on the save partition, when that directory exists |
/var/lib/snapd/sequence/<name>.json | the list of revisions snapd has for the snap |
/etc/systemd/system/<escaped mount path>.mount | the mount unit, for example snap-acme\x2dagent-42.mount |
<name> is the instance name, for example acme-agent or acme-agent_test for a parallel instance. On distributions that use the alternative location, /snap is /var/lib/snapd/snap. With the hidden-directory option the per-user root is ~/.snap/data instead of ~/snap.
Variables that name these places
| Variable | Value |
|---|---|
SNAP | /snap/<snap name>/<rev> |
SNAP_DATA | /var/snap/<snap name>/<rev> |
SNAP_COMMON | /var/snap/<snap name>/common |
SNAP_USER_DATA | ~/snap/<name>/<rev> |
SNAP_USER_COMMON | ~/snap/<name>/common |
SNAP_REAL_HOME | the user's home directory |
SNAP_SAVE_DATA | the save directory, only when it exists |
SNAP_NAME, SNAP_INSTANCE_NAME, SNAP_INSTANCE_KEY | names |
SNAP_VERSION, SNAP_REVISION, SNAP_ARCH | from snap.yaml, the revision and the architecture |
SNAP_COMPONENTS | /snap/<snap name>/components/<rev>, for a snap that declares components |
SNAP, SNAP_DATA and SNAP_COMMON use the snap name without the instance key: inside its own mount namespace a parallel instance sees its directories at the plain name. For strict and devmode snaps HOME is set to SNAP_USER_DATA; classic snaps keep their HOME.
The mount unit
[Mount] What=/var/lib/snapd/snaps/acme-agent_42.snap Where=/snap/acme-agent/42 Type=squashfs Options=nodev,ro,x-gdu.hide,x-gvfs-hide LazyUnmount=yes [Install] WantedBy=snapd.mounts.target WantedBy=multi-user.target
The unit's name is the mount path escaped the way systemd-escape --path does it: slashes become dashes and a dash in the snap name becomes \x2d. Where the kernel cannot mount squashfs the type is fuse.squashfuse or fuse.snapfuse with allow_other. A snap try directory is bind-mounted. The file in /var/lib/snapd/snaps is a hard link to the download when possible, a symlink for files in the seed, otherwise a copy.
snap.yaml: top-level keys and defaults
| Key | Default when absent | Notes |
|---|---|---|
name | required | 2 to 40 characters of a-z, 0-9 and -, with at least one letter |
version | printable ASCII without spaces, at most 32 characters | |
type | app | app, gadget, kernel, base, snapd, os |
confinement | strict | strict, devmode, classic |
architectures | all | |
epoch | 0 | see below |
base | core for an app snap | none means no base |
Other top-level keys: summary, description, title, license, grade, assumes, provenance, environment, plugs, slots, apps, hooks, layout, system-usernames, links, components, snapd-info, ubuntu-core-tracks. See Interfaces for snap developers for plugs and slots, Services for apps and Hooks for hooks.
Snap types
| Type | What it is | Order when handled together |
|---|---|---|
snapd | snapd itself | first |
os | the legacy core snap | |
kernel | the kernel of an Ubuntu Core system | |
base | a root filesystem for other snaps | |
gadget | the device's boot and partition definition | |
app (also written application) | everything else | last |
Any other value is invalid snap type. The published snap format page lists four types; the code also accepts snapd and os.
Revisions
| Written as | Meaning |
|---|---|
42 | a store revision |
x1, x2 | a local revision, given to a file installed without store signatures or with snap try |
The first local revision of a snap is x1; each later one takes the next number. A local file whose assertions are already known keeps its store revision, unless it is installed with --dangerous, which always gives a local revision.
Building and checking a file
snap pack <dir> runs mksquashfs with -noappend -comp xz -no-fragments -no-progress and, for app, gadget and kernel snaps, -all-root -no-xattrs; for os, core, base and snapd it keeps extended attributes. The default file name is <name>_<version>_<architecture>.snap, where the architecture is all when snap.yaml lists none and multi when it lists several. snap pack --check-skeleton validates the metadata only. A file is refused with snap is unusable due to missing files or snap is unusable due to bad permissions.
Bases and prerequisites
| In snap.yaml | Root filesystem |
|---|---|
base: core24 | the core24 snap |
no base | the core snap |
base: none | none; the snap cannot have apps or hooks |
The prerequisites task installs, in order, the default providers of the snap's content plugs, the base from the stable channel, and snapd. Snaps of type snapd, os, base and gadget skip it. A snap of type os or base cannot name a base other than none. See the content interface for default providers.
Epochs
An epoch says which data formats a revision can read and write.
| In snap.yaml | Reads | Writes |
|---|---|---|
epoch: 1 | 1 | 1 |
epoch: 1* | 0 and 1 | 1 |
epoch: {read: [1, 2], write: [2]} | 1 and 2 | 2 |
A revision may replace the installed one only if it can read an epoch that the installed one writes. The store is told the installed epoch and offers a revision that can read it, so crossing several epochs can take several refreshes. A local file that cannot is refused with cannot refresh "<snap>" to <rev> with epoch <e>, because it can't read the current epoch of <c>. 0* is not a valid epoch, and a list has at most 10 entries.
Components
| What | Where |
|---|---|
| declared in snap.yaml | components: with type, summary, description |
| the file | /var/lib/snapd/snaps/<snap>+<component>_<rev>.comp |
| its metadata | meta/component.yaml: component: <snap>+<component>, type, version, summary, description |
| mounted at | /snap/<snap>/components/mnt/<component>/<component rev> |
| linked from | /snap/<snap>/components/<snap rev>/<component> |
| types | standard, kernel-modules (and test, for tests) |
| hook variables | SNAP_COMPONENT, SNAP_COMPONENT_NAME, SNAP_COMPONENT_VERSION, SNAP_COMPONENT_REVISION |
Install with snap install <snap>+<component>. See Snaps and validation for snap-resource-revision and snap-resource-pair.
Further reading
- The snap format: the annotated
meta/snap.yamland the other files undermeta/. - System snap directory: what is under
/snap, including thecurrentsymlink. - Data locations: the data variables and which directories are per revision.
- Snap components: what a component is and where it is mounted.
- Snaps in Ubuntu Core: the kernel, gadget, base, snapd and app types from the system's side.
- Glossary: short definitions of base, epoch, revision, channel and track.
Roads from here
START HERE
- snapd — back to the overview
GETTING SNAPS
- The store — how the file arrives and how its digest is checked
- Epochs: when new code cannot read old data — when new code cannot read old data
INTERFACES AND CONFINEMENT
- Interfaces for snap developers — plugs and slots in snap.yaml
- Confinement — how the base becomes the root filesystem an app sees
RUNNING SNAPS
- Services — the apps in snap.yaml that become services
- Remove and revert — how many revisions stay on disk and how to go back to one
ASSERTIONS · signed statements snapd trusts
- Assertions: snaps and validation — the snap-revision that vouches for a file and the pair for a component
HOOKS · code snapd runs inside a snap
- Hooks: how they work — the hooks packed under meta/hooks
ADMINISTRATION · managing a system of snaps
- Components — installing and removing components