The store
store client for users for app developers for snapd developers for administrators
snapd asks one store a small set of questions. Search and info describe snaps. A channel name of track and risk and branch says which release to follow. One request reports every installed snap and returns the revisions to install or refresh. The file is then downloaded from the cache or as a delta or in full and checked by its SHA3-384 digest.
On the map: the harbour
01 One address, a few questions
snapd talks to one store, by default api.snapcraft.io. It searches, describes a snap, asks what to install or refresh, and then downloads the file and its signatures.
You type snap install, wait a few seconds, and the photo editor is there. What did your machine and the store actually say to each other? The snap command doesn't talk to the store itself. It asks snapd, and snapd does the talking, to one address by default. There are only a few kinds of question. Search. Describe one snap. And the main one: what should I install or refresh? The answer names a revision and where to download it. Then the file comes, and with it the signatures that let snapd trust it. The rest of this deck takes them one at a time.
02 Looking before you install
snap find searches every channel unless you add --narrow, and asks only for confinement the system can run. snap info lists each channel of one snap with its version, date, revision and size. With no search term, snap find lists featured snaps.
Before you install anything, you can look. Two commands do the looking, and they ask the store two different questions. Snap find sends your words and prints a line per match: name, version, publisher, notes and a summary. It searches every channel, unless you add the --narrow option, which keeps it to stable. And it asks only for snaps your system can run, so on Ubuntu Core you'll see strictly confined ones only. Snap info asks about one snap by name. You get a line per channel, with its version, release date, revision and size. If it's installed, you also see what you're tracking and the revision you have.
03 A channel has three parts
A channel is track/risk/branch. The risks are stable, candidate, beta and edge. A missing track means latest and a missing risk means stable, so edge is latest/edge and 1.x is 1.x/stable.
The photo editor has a stable release, a test release, and an older version 1 that some still want. One short name picks between them: the channel. It has up to three parts. The risk is the one you meet first: stable, candidate, beta, edge. You can leave parts out. Just edge means edge on latest, the track you get by default. 1.x isn't a risk name, so it's a track: a line of releases the publisher keeps side by side. A missing risk means stable. Add a branch, a short-lived line for one fix, and you've used all three. Plain stable and latest stable are the same channel.
04 Changing risk keeps the track
A new channel that names only a risk keeps the current track: tracking 1.x/stable, asking for edge gives 1.x/edge. snap switch changes the tracked channel without a refresh; snap refresh --channel does both.
You're on the version 1 track and you'd like to try its edge build. Say edge, and snapd keeps the track you're on, so you end up on 1.x/edge. Snap switch only changes what you follow. Nothing is downloaded; the new revision comes with the next refresh. Snap refresh with the --channel option does both at once. And if your channel has nothing released on it, the store may hand you a revision from another risk of the same track. snapd tells you it's forwarding, and you keep tracking what you asked for. Snap info marks a closed channel like that with an up arrow.
05 Here is what I have, here is what I want for app developers for snapd developers for administrators
Install, refresh and download share one request to v2/snaps/refresh: a context entry for every installed store snap and a list of actions. The result for each action becomes the download-snap and validate-snap tasks.
The gateway wants to know if there's a newer acme-agent. It doesn't ask about just that snap. It tells the store what it has, in two halves. The context lists every snap installed from the store: its revision, the channel it tracks, its epoch and cohort, and whether it's held. The actions say what's wanted: refresh acme-agent. Install, refresh and download all use it. Headers say which device is asking, and for which store. Each action gets an answer: a revision, its digest and where to fetch it, or an error such as no updates available. snapd turns that into two tasks: download-snap and validate-snap.
06 Cache, delta, or the whole file
The file comes from the download cache, from a delta applied to the installed revision, or as a full download that can resume. A download, or a file rebuilt from a delta, must match the store's SHA3-384 digest. Every file, cached ones included, is then hashed again, and that digest is the key of the snap-revision assertion that is fetched next.
Revision 42 is big and the gateway's link is slow. So snapd avoids fetching all of it. First, the cache: a file with the same digest may already be there. Next, a delta, if the store offered one: the difference from revision 41, applied to the copy of 41 on disk. If anything about the delta fails, snapd falls back to the whole file, and a full download that's cut off resumes where it stopped. A full download must match the store's SHA3-384 digest, or it's fetched again from the start. Whatever the route, snapd hashes the file once more, and that digest has to find its signed statement.
07 A different store, a proxy, or no store for administrators for snapd developers
proxy.http and proxy.https route requests through an HTTP proxy. proxy.store redirects them to the store whose assertion carries a url. store.access=offline makes every store request fail and skips auto-refresh.
Your gateways sit on a factory network with no direct route to the internet. Three settings help. The proxy options send every store request through an ordinary HTTP proxy. proxy.store goes further. It names another store by its id, and snapd builds every address from the URL in that store's assertion, so the assertion has to be acknowledged before the option is accepted. Changing it also drops the device's session, and the next request signs in to the new store. And store.access=offline stops snapd asking at all. Requests fail at once with a message saying how to go back online, and automatic refreshes are skipped.
08 Where to go from here
Roads: packaging, assertions and the download check, refresh, the overlord, the store and device assertions, and the overview.
So that's the conversation: a few questions, one file, and a digest that has to match. Here's where the file goes next. Packaging opens it up and shows where it's mounted. The assertions decks cover the signed statements and the check that follows the download. Refresh shows when snapd asks the store without being told to. The overlord shows the change that the download was one task of. The identity and device decks cover the store assertion and the serial behind the device session. And the overview takes you back to the whole of snapd.
Read more
What snapd asks the store
| Question | Endpoint | Asked by |
|---|---|---|
| search | v2/snaps/find | snap find |
| describe one snap | v2/snaps/info/<name> | snap info, snap debug connectivity |
| install, refresh, download, fetch assertions | v2/snaps/refresh | snap install, snap refresh, snap download, auto-refresh; snap download sends it from the command itself, not through snapd |
| sections | api/v1/snaps/sections | snap find --section, and snapd's periodic catalog refresh |
| categories | v2/snaps/categories | the /v2/categories API of snapd; no snap command |
| create a cohort | v2/cohorts | snap create-cohort |
| device session | api/v1/snaps/auth/nonces, api/v1/snaps/auth/sessions | snapd, once the device has a serial |
The default base address is https://api.snapcraft.io/. A request times out after 10 seconds. A failed request is retried up to 6 times within 38 seconds when the answer is a 5xx status or a transient network error; "no such host" is not retried.
Channel names
| You write | snapd reads |
|---|---|
stable | latest/stable |
edge | latest/edge |
1.x | 1.x/stable |
1.x/beta | track 1.x, risk beta |
beta/fix-crash | risk beta, branch fix-crash, track latest |
1.x/beta/fix-crash | track, risk and branch |
| four or more parts | error: channel name has too many components |
Risks in order: stable, candidate, beta, edge. Changing to a channel that names only a risk, or a risk and a branch, keeps the current track. A snap with no tracking channel is reported to the store as tracking stable. When the store answers an install with a redirect channel, for a snap whose publisher set a default track, snapd tracks that channel.
In snap info, ↑ (or ^) marks a closed channel in a track that has an open channel at a lower risk, and – (or --) one in a track with none.
for administrators for snapd developers
Pinned tracks on Ubuntu Core
When the model gives a track for the kernel or the gadget, a channel change may alter the risk but not the track. The error is cannot switch from kernel track "<track>" as specified for the (device) model to "<channel>" (or gadget track).
for app developers for snapd developers for administrators
The snap-action request
| Part | Fields |
|---|---|
context, one entry per installed store snap | snap-id, instance-key, revision, tracking-channel, epoch, refreshed-date, ignore-validation, cohort-key, validation-sets, held |
actions, one entry per wanted operation | action (install, refresh, download, fetch-assertions), instance-key, name, snap-id, channel, revision, cohort-key, ignore-validation, epoch, validation-sets |
| request headers | Snap-Device-Series, Snap-Device-Architecture, Snap-Classic, Snap-Device-Capabilities: default-tracks, Snap-Device-Store when the device has a store id, Snap-Accept-Delta-Format, Snap-Refresh-Managed, and Snap-Refresh-Reason: scheduled for an auto-refresh |
| result, one per action | result (install, refresh, download, fetch-assertions, error), the snap's revision data, effective-channel, redirect-channel |
A parallel instance is reported under a key derived from the snap id and a random salt kept on the device, so local instance names are not sent to the store. A requested revision equal to the installed one is not sent. A refresh result equal to what is installed becomes snap has no updates available.
The download
| Step | Detail |
|---|---|
| cache | /var/lib/snapd/cache, keyed by SHA3-384; a hit must also have the right size |
| delta | formats xdelta3, and snap-1-1-xdelta3 first when experimental.snap-delta-format is on; applied to the installed revision's file in /var/lib/snapd/snaps; the rebuilt file must have the target's digest |
| full file | written to <target>.partial, renamed at the end; resumes with a range request, or restarts when the server does not support it |
| digest | sha3-384 mismatch for "<name>": got <a> but expected <b>; after one mismatch the file is downloaded once more from the start |
| retries | up to 7 attempts within 90 seconds |
| stalled transfer | cancelled when the average stays under 4096 bytes per second for 5 minutes |
| rate limit | refresh.rate-limit applies to auto-refresh downloads only |
| cache size | at most 5 unreferenced files and 30 days; on Ubuntu Core also a 1 GiB target |
A failed delta is logged as Cannot download or apply deltas for <snap>: <error> and the full download follows.
for app developers for snapd developers for administrators
What is fetched after the download
The validate-snap task computes the SHA3-384 digest and the size of the file and fetches the snap-revision assertion with that digest. Fetching it brings the snap-declaration, the publisher's and developer's account and the signing account-key chain. When the model names a store, the store assertion is fetched too. Components get snap-resource-revision and snap-resource-pair in validate-component. See Assertions and Snaps and validation.
A local file installed with snap install ./file.snap is not downloaded. snapd looks for assertions it already has for that file; snap ack adds them, and --dangerous installs without them.
for administrators for snapd developers
Who is asking
| Credential | Comes from | Sent as |
|---|---|---|
| device session | the device signs a device-session-request with its device key and sends it with its serial and model assertions | Snap-Device-Authorization |
| user | snap login: e-mail, password and an optional one-time code | Authorization |
A device with no serial yet sends requests without device authorization. On an HTTP 401 snapd renews the expired credential and retries, up to 4 times per request. The store id in Snap-Device-Store is the store header of the model assertion; on a classic system with the generic model it is the UBUNTU_STORE_ID environment variable.
for administrators for snapd developers
Proxy, proxy store and offline
| Option | Effect |
|---|---|
proxy.http, proxy.https, proxy.ftp, proxy.no-proxy | read for every store request, with the process environment as fallback; also written to /etc/environment |
proxy.store=<store id> | every endpoint is built on the url of that store assertion; setting it needs the assertion in the database; changing it resets the device session |
store.access=offline | every request and download fails; auto-refresh is skipped; the only other accepted value is unset |
snap debug connectivity asks for the information of the snapd snap and then checks that the download host answers, and reports each host.
for administrators for snapd developers
Cohorts
snap create-cohort <snap> returns a cohort key. snap install --cohort=<key>, snap refresh --cohort=<key> and snap switch --cohort=<key> store it for the snap, and --leave-cohort clears it. The key is sent with every snap-action request, and snap info shows in-cohort. A cohort and a revision cannot be combined: cannot specify revision and cohort. What the key selects is decided by the store.
Messages you may meet
| Situation | Message |
|---|---|
| no such snap | snap not found |
| nothing on that channel | no snap revision on specified channel |
| nothing for this architecture | no snap revision on specified architecture |
| already up to date | snap has no updates available |
| refresh of a snap installed from a local file | cannot perform operation on local snap |
search with --private while logged out | you need to log in first |
| too many requests | too many requests |
| damaged download | sha3-384 mismatch for ... |
| offline | store is marked offline, use 'snap unset system store.access' to go online |
| no signatures | cannot verify snap "<name>", no matching signatures found |
| paid snap | please buy <name> before installing it |
| search term with special characters | bad query |
Further reading
- Channels and tracks: what each risk level means, closed channels and
snap switch. - Revisions: what a revision is and how to ask for one with
--revision. - Snap deltas: download deltas and the fallback to a full download.
- Network requirements: the hosts and ports snapd needs to reach.
- Assertions: the signed documents that come with a snap.
- Store overview: the global store, dedicated stores and how a device is bound to one.
Roads from here
START HERE
- snapd — back to the overview
GETTING SNAPS
- Snap packaging — what is inside the file that was downloaded
- A store of your own — a store of your own
- Epochs: when new code cannot read old data — why some revisions are offered in steps
RUNNING SNAPS
- Refresh — when snapd asks the store for refreshes by itself
- The overlord — the change and tasks that carry a download
ASSERTIONS · signed statements snapd trusts
- Assertions: how they work — the signed statements that come with every snap
- Assertions: snaps and validation — what the check after the download compares
- Assertions: identity and store — the store assertion behind proxy.store
- Assertions: devices — the serial and device key behind the device session