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

▶ Watch this deck — 8 scenes, ~6 min

01 One file, mounted, not unpacked

THE SNAP FILE acme-agentrevision 42one file unpacked, copied around mountedwhat the apps seethe snap's files,exactly as packed compressed · read-onlyone digest covers all of it the snap's datawritable,kept outside the file revision 41still there, whole
acme-agent revision 42 is one compressed read-only file; it is mounted so the apps see its files exactly as packed, it is not unpacked and copied around, its writable data is kept in a separate place, and revision 41 is still there as its own file

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

INSIDE acme-agent_2.1_all.snapsquashfs: the file starts with hsqs meta/snap.yamlmeta/hooks/configurebin/agentbin/report name: acme-agentversion: '2.1'summary: Reports gateway readingsbase: core24apps:agent:command: bin/agentdaemon: simple if you leave them out:type: app confinement: strictarchitectures: [all] epoch: 0 snap is unusable due to missing filesno readable meta/snap.yaml or a missing app command; "due to bad permissions" if a command is not executable $ snap pack ./acme-agentbuilt: acme-agent_2.1_all.snap
The file acme-agent_2.1_all.snap is a squashfs image starting with hsqs and holds meta/snap.yaml, meta/hooks/configure, bin/agent and bin/report. Its snap.yaml names acme-agent, version 2.1, a summary, base core24 and one app; type app, confinement strict, architectures all and epoch 0 are the defaults when left out. A file without a readable snap.yaml or with a missing app command is unusable. snap pack builds the file

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

REVISIONS $ snap list --all acme-agentName Version Rev Tracking Publisher Notesacme-agent 2.0 41 latest/stable acme disabledacme-agent 2.1 42 latest/stable acme - version: any textthe publisher likes revision: given by the store,one per uploaded file on your laptop$ sudo snap install --dangerous ./acme-agent_2.1_all.snapacme-agent 2.1 installed$ snap list acme-agentName Version Rev Tracking Publisher Notes acme-agent 2.1 x1 - - -← a local revision next local file: x2, then x3
snap list --all acme-agent on the gateway shows version 2.0 at revision 41, disabled, and version 2.1 at revision 42. The version is any text the publisher likes; the revision is given by the store, one per uploaded file. On a laptop, acme-agent built locally and installed with --dangerous gets the local revision x1, and the next local file gets x2

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 /var/lib/snapd/snaps/acme-agent_42.snapthe file, kept whole /snap/acme-agent/42starts as an empty directory snap-acme\x2dagent-42.mountWhat=/var/lib/snapd/snaps/acme-agent_42.snapWhere=/snap/acme-agent/42Type=squashfsOptions=nodev,ro,x-gdu.hide,x-gvfs-hide meta/ bin/mounted read-only a kernel snap: its boot assets are extracted here toosnap try: a directory instead of a file, with a bind mount
mount-snap keeps the file as /var/lib/snapd/snaps/acme-agent_42.snap, creates the empty directory /snap/acme-agent/42, and writes the systemd unit snap-acme\x2dagent-42.mount with What, Where, Type=squashfs and Options=nodev,ro,x-gdu.hide,x-gvfs-hide, which mounts the file read-only on the directory. snap try bind-mounts a directory instead

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

ON DISK currentin /snap/acme-agent, read-only/snap/acme-agent/41/snap/acme-agent/42 currentin /var/snap/acme-agent, writable/var/snap/acme-agent/41/var/snap/acme-agent/42/var/snap/acme-agent/common /var/snap/acme-agent/42unlink-current-snap removes both;link-snap points them at 42an undo points them back at 41 41, 42: one per revisioncommon: shared by every revision $SNAP$SNAP_DATA$SNAP_COMMON per user, the same split:~/snap/acme-agent/42 $SNAP_USER_DATA~/snap/acme-agent/common $SNAP_USER_COMMON
Under /snap/acme-agent revisions 41 and 42 are mounted and a current symlink points at 41; under /var/snap/acme-agent there are directories 41, 42 and common with their own current symlink. On a refresh unlink-current-snap removes both current symlinks and link-snap re-creates them pointing at 42; an undo points them back at 41. The numbered directories are one per revision and common is shared. Apps read $SNAP, $SNAP_DATA and $SNAP_COMMON, and per user $SNAP_USER_DATA and $SNAP_USER_COMMON

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

BASES acme-agentbase: core24 core24 (type: base)the root filesystem the apps see; only /snap/acme-agent/42 comes from the snap prerequisitesinstall core24 from stableand snapd, if it is missing download-snapvalidate-snapprerequisitesmount-snapwait until they are there no base: in an app snap → the core snap base: none → no base, and then no apps and no hookssnapd, os, base and gadget snaps skip prerequisites
acme-agent says base: core24; core24, a snap of type base, is the root filesystem its apps see, and only /snap/acme-agent/42 comes from the snap itself. The install starts with prerequisites, which installs core24 from stable, then download-snap, validate-snap, a second prerequisites that waits for them, and mount-snap. With no base an app snap gets core; base: none allows no apps or hooks; snapd, os, base and gadget snaps skip prerequisites

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

COMPONENTS acme-agent_42.snap $ sudo snap install acme-agent+diagnostics acme-agent+diagnostics_7.compits own squashfs, its own revision: 7meta/component.yaml /snap/acme-agent/components/mnt/diagnostics/7mounted here /snap/acme-agent/components/42/diagnosticsa symlink per snap revision SNAP_COMPONENTS=/snap/acme-agent/components/42types: standard, kernel-modules · signed for by snap-resource-revision and snap-resource-pair
Next to acme-agent_42.snap, snap install acme-agent+diagnostics brings acme-agent+diagnostics_7.comp, its own squashfs with meta/component.yaml and revision 7. It is mounted at /snap/acme-agent/components/mnt/diagnostics/7, and /snap/acme-agent/components/42/diagnostics is a symlink to it for snap revision 42. SNAP_COMPONENTS is /snap/acme-agent/components/42. Component types are standard and kernel-modules, and the store signs for them with snap-resource-revision and snap-resource-pair

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 Snap packaging The storehow the file arrivesSnaps and validationwho vouches for the file the rest of what a snap declaresFor snap developersplugs and slotsServicesapps that become servicesHooksrun at set moments Confinementhow an app sees the base Remove and revertthe older revisions on disksnapdback to the overview
Roads from snap packaging: the store and snap assertions; plugs and slots, services and hooks; confinement, remove and revert, and back to the snapd overview

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

PathWhat it is
/var/lib/snapd/snaps/<name>_<rev>.snapthe snap file
/snap/<name>/<rev>the file, mounted read-only
/snap/<name>/currentsymlink to the active revision
/var/snap/<name>/<rev>system data of that revision
/var/snap/<name>/commonsystem data shared by all revisions
/var/snap/<name>/currentsymlink to the active revision's data
~/snap/<name>/<rev>a user's data for that revision
~/snap/<name>/commona user's data shared by all revisions
~/snap/<name>/currentsymlink, 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>.jsonthe list of revisions snapd has for the snap
/etc/systemd/system/<escaped mount path>.mountthe 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

VariableValue
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_HOMEthe user's home directory
SNAP_SAVE_DATAthe save directory, only when it exists
SNAP_NAME, SNAP_INSTANCE_NAME, SNAP_INSTANCE_KEYnames
SNAP_VERSION, SNAP_REVISION, SNAP_ARCHfrom 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

KeyDefault when absentNotes
namerequired2 to 40 characters of a-z, 0-9 and -, with at least one letter
versionprintable ASCII without spaces, at most 32 characters
typeappapp, gadget, kernel, base, snapd, os
confinementstrictstrict, devmode, classic
architecturesall
epoch0see below
basecore for an app snapnone 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

TypeWhat it isOrder when handled together
snapdsnapd itselffirst
osthe legacy core snap
kernelthe kernel of an Ubuntu Core system
basea root filesystem for other snaps
gadgetthe device's boot and partition definition
app (also written application)everything elselast

Any other value is invalid snap type. The published snap format page lists four types; the code also accepts snapd and os.

Revisions

Written asMeaning
42a store revision
x1, x2a 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.yamlRoot filesystem
base: core24the core24 snap
no basethe core snap
base: nonenone; 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.yamlReadsWrites
epoch: 111
epoch: 1*0 and 11
epoch: {read: [1, 2], write: [2]}1 and 22

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

WhatWhere
declared in snap.yamlcomponents: with type, summary, description
the file/var/lib/snapd/snaps/<snap>+<component>_<rev>.comp
its metadatameta/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>
typesstandard, kernel-modules (and test, for tests)
hook variablesSNAP_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

Roads from here

START HERE

  • snapd — back to the overview

GETTING SNAPS

INTERFACES AND CONFINEMENT

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

HOOKS · code snapd runs inside a snap

ADMINISTRATION · managing a system of snaps