Trying and packing a snap

the edit and test loop for app developers

Three routes take a snap from a build directory onto a system. snap try bind-mounts the directory itself so file edits are live at once. snap pack validates the directory and builds one squashfs file. snap install --dangerous installs a file that has no signatures and gives it a local revision. The flags --devmode and --jailmode and --classic must agree with the confinement the snap declares.

On the map: developing snaps district

▶ Watch this deck — 8 scenes, ~6 min

01 Three routes from a directory to an installed snap

FROM A DIRECTORY TO A SNAP your build directoryacme-agent 2.1 installed onthis system the storeupload, review, signatures: not this deckstore revision: 42 snap tryno file is built; the directory itself is used snap packone .snap filesnap install--dangerous local revision: x1the rest of this deck: the two local routes, the checks on the way, and the confinement flags
A build directory for acme-agent 2.1 on the left and the installed system on the right, joined by three routes: snap try uses the directory with no file built; snap pack builds one .snap file and snap install --dangerous installs it; the store route, the slow one for testing, of upload, review and signatures is not covered here. The two local routes give revision x1, the store gives revision 42

snap try <dir> installs the directory in place. snap pack <dir> builds a file and snap install --dangerous <file> installs it without signatures. Both give the snap a local revision such as x1.

You've just built acme-agent. It's a directory on your laptop, version 2.1. How do you get from there to a snap you can actually run? The store is one way, but uploading and waiting for review is slow when you're testing a fix. There are two quicker routes. Snap try uses the directory as it is; nothing gets built. Snap pack turns the directory into one file, and installing that file needs --dangerous, because nobody signed it. Both leave a snap with a local revision, x1, that the store knows nothing about. The rest of this deck walks those two routes.

02 snap try mounts the directory itself for app developers for snapd developers

SNAP TRY $ snap try ~/acme-agent/primeacme-agent 2.1 mounted from /home/dev/acme-agent/prime /home/dev/acme-agent/primeyour files, writable by you/var/lib/snapd/snaps/acme-agent_x1.snapa symlink, not a file /snap/acme-agent/x1a bind mount, not squashfsmount unit: Type=none, Options=bind then an ordinary local install, change kind try-snap: profiles, services, commands on your path Name Version Rev Tracking Publisher Notesacme-agent 2.1 x1 - - try
snap try ~/acme-agent/prime prints acme-agent 2.1 mounted from /home/dev/acme-agent/prime. The file /var/lib/snapd/snaps/acme-agent_x1.snap is a symlink to the directory, and /snap/acme-agent/x1 is a bind mount of it. The change kind is try-snap, and snap list shows try in Notes

The "file" acme-agent_x1.snap is a symlink to the directory and /snap/acme-agent/x1 is a bind mount of it. snap list shows try in Notes. The docs call the directory an unpacked snap.

A normal install mounts a file. But with snap try there's no file. So what does snapd mount? Your directory. Where the snap file would sit, snapd puts a symlink to your directory. And the mount unit for revision x1 is a bind mount of that directory, not a squashfs mount. From there on it's an ordinary local install, in a change of kind try-snap: profiles, services, commands on your path. Snap list marks it with try in Notes.

03 What is live, and what needs another try for app developers

EDIT, RUN, REPEAT prime/acme-agent x1mounted from prime/ edit bin/agentlive at once: run it again edit meta/snap.yaml: add daemon: simpleread when the snap was installed: no effect yet $ snap try ~/acme-agent/primeacme-agent x2 install tasks run again: the service unit is written and started known issue: add a pre-refresh hook to a tried directory and the next snap try failsboth revisions are the same directory; snapd keeps this as a test (tests/main/try-with-hooks)
Two lanes from the prime directory to the tried snap acme-agent x1. Editing bin/agent is live at once. Editing meta/snap.yaml to add a daemon has no effect until snap try runs again, which makes x2 and runs the install tasks again. A known issue: after adding a pre-refresh hook to a tried directory, the next snap try fails

Changes to files are live at once. Changes to meta/snap.yaml need another snap try, which creates the next local revision. A second try after adding a pre-refresh hook fails; snapd records this as a known issue in a test.

You fix a bug in the agent's binary and rebuild. Do you need to tell snapd? No, and that's the whole point of try. Revision x1 is your directory, so whatever's in it now is what runs next. snap.yaml is different. Snapd read it once, when it wrote the profiles, the units and the commands. So when you add a daemon line, a plug or an app, run snap try again. That makes x2, and the install tasks run again; that's when the service unit appears. One rough edge: both revisions are the same directory, so after you add a pre-refresh hook the next try fails.

04 snap pack checks before it builds for app developers for Ubuntu Core developers

SNAP PACK $ snap pack ~/acme-agent/prime 1 · parseread snap.yaml,add hooks frommeta/hooksplugs and slots: the real interface checks, while parsinga bad one is set aside and does not stop the build 2 · validatethe same rulesas an install3 · filescommands thereand executable;completer readableerror: cannot pack "…/prime": snap is unusable due to missing files 4 · snap typegadget.yaml andits content;kernel checks acme-agent_2.1_amd64.snapbuilt: acme-agent_2.1_amd64.snap<name>_<version>_<arch>.snap $ snap pack --check-skeleton ~/acme-agent/primethe same checks, a list of bad plugs and slots, no file
snap pack ~/acme-agent/prime runs four checks in order: parse snap.yaml and add hooks from meta/hooks, with plugs and slots checked against the real interfaces but only set aside when bad; validate as an install does; the commands it names exist and are executable, or the pack stops with cannot pack; gadget and kernel snaps get their own validation. Then it builds acme-agent_2.1_amd64.snap and prints built:. --check-skeleton runs the checks and builds no file

snap pack parses and validates snap.yaml, checks that commands exist and are executable and that completers are readable, validates gadget and kernel snaps, then builds <name>_<version>_<arch>.snap and prints built:. Bad plugs and slots do not stop the build; --check-skeleton runs the checks only and lists them.

Try is quick, but you can't hand a directory to a colleague. Snap pack makes a file, and it checks a few things first, so a broken snap fails on your laptop, not at install. First it reads snap.yaml and adds any hooks it finds in meta/hooks. Plugs and slots get the real interface checks here, though a bad one is only set aside. Then the validation an install runs. Then every app's command must be there and executable. A gadget or kernel snap gets its own checks. Only then is the squashfs file built and named. The --check-skeleton option runs the checks and builds nothing.

05 Installing a file nobody signed

INSTALLING A LOCAL FILE $ snap install ./acme-agent_2.1_amd64.snap error: cannot find signatures with metadata forsnap/component "acme-agent_2.1_amd64.snap"snapd looks for a signed statementfrom the store for this exact file:a download has one; this has none $ snap install --dangerous ./acme-agent_2.1_amd64.snapacme-agent 2.1 installedname, version and everything else are taken from the file itself acme-agent 2.1revision x1 the storenot asked about this snap at refresh time$ snap refresh --amend acme-agentmoves it to the store once acme-agent is published there dangerous: nobody vouched for this file
snap install ./acme-agent_2.1_amd64.snap fails with cannot find signatures with metadata for snap/component. snap install --dangerous on the same file prints acme-agent 2.1 installed. The snap gets revision x1, its name and version are taken from the file, and the store is not asked about it at refresh time; snap refresh --amend moves it to the store

Without --dangerous snapd needs a signed snap-revision assertion for the file. With it, the file's own metadata is trusted, the revision is local, and refreshes skip the snap until snap refresh --amend. --devmode implies --dangerous.

A colleague sends you acme-agent as a file, and snap install refuses it. Why? When snapd installs a file, it looks for a signed statement from the store that matches the file's hash. A store download comes with one. A file packed a minute ago has none. --dangerous tells snapd to go ahead and take the name, the version and everything else from the file itself. The snap gets revision x1. The store has no record of it, so refreshes leave it alone; snap refresh --amend moves it to the store later. Dangerous is the right word: nobody vouched for this file.

06 Three flags that must agree with the snap for app developers for snapd developers

THE CONFINEMENT FLAGS the snap declaresyou passseccomp starts withAppArmor profileconfinement: strictno flagenforcedenforced confinement: strict--devmode@complaincomplainlogged only confinement: devmodeno flagsnap "acme-agent" requires devmode or confinement override confinement: classic--classic@unrestrictedcomplainconfinement: classicno flagsnap "acme-agent" requires classic confinementon Ubuntu Core a classic snap is refused with any flag strict or devmode--jailmodeenforcedenforcedconfinement: classic--classic --jailmodeenforcedenforced--devmode with --jailmode or --classic is refused; so is --jailmode where snapd forces devmode snap list, Notes column: devmode jailmode classic try
A table of what the snap declares, the flag passed, the first seccomp directive and the AppArmor profile flag. strict with no flag: enforced. strict with --devmode: @complain and complain. devmode with no flag: refused, requires devmode or confinement override. classic with --classic: @unrestricted and complain; without it: refused, requires classic confinement. A strict or devmode snap with --jailmode, or a classic snap with --classic --jailmode: enforced. --devmode with --jailmode or --classic is refused, and so is --jailmode where snapd forces devmode. snap list Notes shows devmode, jailmode, classic and try

seccomp starts with @complain when devmode is on and jailmode is off, and with @unrestricted for classic without jailmode. AppArmor gets the complain flag for devmode or classic without jailmode. A snap declaring devmode or classic is refused without the matching flag. --jailmode overrides both; a classic snap needs it with --classic. The docs call devmode "developer mode".

The agent works under snap try with the --devmode flag and fails without it. What did that flag change? A strict snap installed with it keeps its profiles, but seccomp starts with @complain and AppArmor gets the complain flag. Denials are logged, not blocked, so you can find the plugs it needs. A snap that declares devmode needs that flag on every install, or the --jailmode flag to force enforcement. A classic snap needs the --classic flag and gets @unrestricted; on Ubuntu Core it's refused. Jail mode wins over both; a classic snap takes it alongside the --classic flag. Whichever you used shows in Notes.

07 The directory went away for app developers for administrators

WHEN THE DIRECTORY IS GONE ~/acme-agent/primebind mountacme-agent x1 $ rm -rf ~/acme-agent/primenothing behind revision x1 $ snap list acme-agentName Version Rev Tracking Publisher Notesacme-agent - x1 - - try,broken $ snap remove acme-agentremoved, with its commands in /snap/binand its unit files try in Notes: someone developed on this machine; broken: snapd can't read the snap's filesthe fix: remove it, then snap try or install again
The directory ~/acme-agent/prime is bind-mounted as acme-agent x1. After rm -rf of the directory, snap list still answers and shows acme-agent with version -, revision x1 and Notes try,broken. snap remove acme-agent still works and removes its commands and unit files

A tried snap whose directory is gone shows broken in Notes and - as its version. It can be removed, and its /snap/bin entries and unit files go with it.

You clean your build tree and forget a snap was mounted from it. What does snapd do with a snap whose files just vanished? With a packed snap, snapd holds the file. With try, it holds a symlink to something of yours. Delete prime and revision x1 has nothing behind it. Nothing crashes. Snap list still answers, shows a dash for the version and marks the snap broken. You can still remove it, and its commands and unit files go with it. Try in Notes means someone developed on this machine; broken means snapd can't read the snap's files. Remove it, then try or install again.

08 Where to go from here

ROADS Trying and packingtry · pack · --dangerous Run and debugstart it, look insideApps and environmentthe entries pack checked Layoutsfixed paths in the snapSystem usernamesa user for a daemon Snap packagingthe file, x1 and x2Confinementwhat devmode relaxes When snapd askssnaps without a snap-id ComponentsOverview
Roads from Trying and packing a snap: run and debug, apps and environment, layouts and system usernames in the developing snaps district; snap packaging and confinement; interface policy for local snaps and components

Roads to the other developing snaps topics, to snap packaging, confinement, interface policy for local snaps, and components.

So acme-agent is installed, one way or the other. Where next depends on what it does when you run it. Run and debug shows how it starts and how to look inside its sandbox. Apps and environment covers the entries pack just checked. Layouts and system usernames are the two snap.yaml features you're likely to need next. Snap packaging has the file format and how local revisions are numbered. Confinement says what devmode relaxes. When snapd asks explains why a snap without a snap-id is judged differently for interfaces. And components have their own pack and install.

Read more

Commands

CommandWhat it does
snap try [<snap-dir>]installs the directory in place; flags --devmode, --jailmode, --classic; prints <name> <version> mounted from <path>
snap pack [<snap-dir>] [<target-dir>]validates and builds a snap file; both default to .; prints built: <path>
snap pack --check-skeleton <snap-dir>validation only; prints a summary of bad plugs and slots; a result of only missing commands exits 0
snap pack --filename=<name>sets the file name; an absolute name cannot be combined with a target directory
snap pack --compression=<xz or lzo>chooses the squashfs compression
snap install --dangerous <file>installs a file without signatures
snap install --devmode <file>uses signatures when present and accepts their absence
snap refresh --amend <snap>refreshes a local snap, one unknown to the store, from the store

snap try without an argument uses prime when snap/snapcraft.yaml, snapcraft.yaml or .snapcraft.yaml exists and prime is a directory; otherwise the current directory when it has meta/snap.yaml; otherwise it fails with "error: the <snap-dir> argument was not provided and couldn't be inferred".

Without --dangerous (or --devmode) an install of a file fails with cannot find signatures with metadata for snap/component "<file name>" unless snapd has a snap-revision assertion for the file's hash.

What snap pack checks, in order

1. meta/snap.yaml parses. While parsing, plugs and slots are checked against the real interfaces; a bad one is recorded and dropped, and does not stop the build. Hooks found in meta/hooks/ are added. 2. The snap validates: cannot validate snap "<name>": .... 3. . and meta are readable and searchable, meta/snap.yaml is readable, every app command exists and is executable, every completer is readable. A missing command is snap is unusable due to missing files: path "<path>" does not exist. 4. For bases other than core, core18, core20, core22 and core24: content plug targets and layout sources under $SNAP exist in the tree. See layouts. 5. meta/snapshots.yaml parses, if present. 6. Gadget snaps: gadget.yaml and the gadget content. Kernel snaps: the kernel validation.

A failure is printed as cannot pack "<snap-dir>": <reason>. Unreadable files stop the build with "cannot access the following locations in the snap source directory:" and one line per path with its owner and mode.

Files left out of the snap

WhereNames
top levelDEBIAN, .git, .gitignore, .bzr, .hg, .svn, CVS, .snapignore and similar
anywhere*.snap, *.click, .*.sw?, *~, ,,*, .[#~]*

File names

InputDefault name
a snap, no architectures<name>_<version>_all.snap
a snap, one architecture<name>_<version>_<arch>.snap
a snap, several architectures<name>_<version>_multi.snap
a directory with meta/component.yaml and no meta/snap.yaml<snap>+<comp>_<version>.comp or <snap>+<comp>.comp; see components

The confinement flags

Snap declaresFlagResult
strictnoneenforced
strict--devmodeseccomp @complain, AppArmor complain
strict--classicsnap "<name>" is not a classic confined snap
devmodenonesnap "<name>" requires devmode or confinement override
devmode--devmodeseccomp @complain, AppArmor complain
devmode--jailmodeenforced
classicnonesnap "<name>" requires classic confinement
classic--classicseccomp @unrestricted, AppArmor complain
classic--classic --jailmoderegular, non-classic confinement, enforced
classic, on Ubuntu Coreanysnap "<name>" requires classic confinement which is only available on classic systems

Refused combinations: cannot use devmode and jailmode flags together, cannot use classic and devmode flags together, and this system cannot honour the jailmode flag on a system that forces devmode.

AppArmor complain is the flag complain added to the profile's flag list, after attach_disconnected and mediate_deleted. seccomp @complain and @unrestricted are the first directives of the profile, after its version comment.

Notes in snap list

NoteMeaning
tryinstalled with snap try
brokenthe snap cannot be read, for example the tried directory is gone; its version then shows as -
devmode, jailmode, classicthe flag the snap was installed with

A tried snap and a snap installed with --dangerous show - for Tracking and Publisher.

for snapd developers

In the code

WhatWhere
snap try in the daemon, change kind try-snapdaemon/api_sideload_n_try.go:971-1002
snapstate.TryPath sets TryModeoverlord/snapstate/snapstate.go:851-856
the symlink in place of the snap filesnap/snapdir/snapdir.go:68-72
the bind mount unitsystemd/systemd.go:1587-1591
TryMode kept across undo as old-trymodeoverlord/snapstate/handlers.go:1915-1916, 2117, 2530-2531, 2634
pack validationsnap/pack/pack.go:244-293
real plug and slot sanitization in snap packcmd/snapd/cli/cmd_pack.go:87-89, snap/info_snap_yaml.go:284
flags against confinementoverlord/snapstate/check_snap.go:93-129
try-mode and id-less snaps left out of refreshoverlord/snapstate/storehelpers.go:331-347
a broken snap's info, built from its side infooverlord/snapstate/snapmgr.go:632-650

A known limitation, kept as a test: adding meta/hooks/pre-refresh to a directory that is already tried makes the next snap try fail, because both revisions are the same directory (tests/main/try-with-hooks).

Further reading

No published page explains snap pack as a topic; this deck and snap pack --help are the description.

Roads from here

START HERE

  • snapd — back to the overview

GETTING SNAPS

  • Snap packaging — what is inside the file and how local revisions x1 and x2 are numbered

INTERFACES AND CONFINEMENT

  • Confinement — what strict and devmode and classic mean for a running process

POLICY · who may install and connect what

ADMINISTRATION · managing a system of snaps

  • Components — packing and installing a component file

DEVELOPING SNAPS · try, pack, run, debug