Snapshots

snap data for users for administrators for snapd developers

A snapshot is a copy of a snap's system data and user data for the current revision together with its configuration. snap save makes one and snap restore puts it back. snap remove makes one automatically and on classic it expires after 31 days. A snapshot can be checked and exported to a file and imported on another machine.

On the map: the archive

▶ Watch this deck — 8 scenes, ~6 min

01 A copy before you experiment

SNAPSHOTS photo-editorits datasaved snapshots $ snap save photo-editor 7Set Snap Age Version Rev Size Notes7 photo-editor 1.20s 2.4 42 18.5MB - snap savedlist themsnap restore 7put it backsnap forget 7delete it the number is the set: one snap save of several snaps, or of all of them, makes one set 8automade by snap remove
The photo-editor snap and its data; snap save photo-editor copies the data into set 7 on a shelf of saved snapshots; snap saved lists sets, snap restore 7 puts one back, snap forget 7 deletes it; a second set 8 marked auto was made by snap remove

snap save stores a copy of a snap's data as a numbered set. snap saved lists sets, snap restore puts one back and snap forget deletes it.

You're about to let the photo editor convert your whole catalogue to a new format. Wouldn't it be nice to have a copy of your data from five minutes ago? That's what snap save makes. It copies the snap's data and prints a line with a set number, here seven. That number is how you refer to it from now on. Snap saved lists what you have, snap restore seven puts it back, and snap forget seven deletes it. Save several snaps at once, or name none for all, and they share one set. And you've met one kind already without asking: the one snap remove makes.

02 What goes into a snapshot general version

WHAT GOES IN this revision (42)all revisionssystemeach userset 7 revision 42 datacommon data revision 42 datacommon dataalice, and every other user who has used the snap settings, as snap get photo-editor shows them the program itselfdata of revision 41not included snap save --users=alice photo-editorsaves only alice's part, plus the system part
A grid of the snap's data: rows system and each user, columns this revision 42 and all revisions; all four cells and the settings go into set 7; the program itself and the data of revision 41 are not included

A snapshot holds the current revision's data and the data shared across revisions, for the system and for each user, plus the snap's configuration. The snap itself and the data of older revisions are not included.

Set seven is on the shelf. But what's actually inside? A snap keeps its data in four places: for the system and for each user, each with a part for the current revision and a part shared by all revisions. A snapshot takes all four, for alice and every other user who has used the snap. It also records the snap's settings, the ones snap get shows you. The program isn't in there; the store or a revert gives you that. Neither is the data older revisions keep on disk. With the users option, you can save just some users.

03 On disk, one zip file per snap for administrators for snapd developers in place of the general version

ON DISK /var/lib/snapd/snapshots/ 7_photo-editor_2.4_42.zipset · snap · version · revisiondirectory mode 0700, readable by root only archive.tgzsystem data: revision 42 and common user/alice.tgzalice's data: revision 42 and common meta.jsonset, snap, snap-id, revision, epoch, time,sizes, a SHA3-384 per archive, the configurationmeta.sha3_384the hash of meta.jsonsnap check-snapshot verifies against these files mode 0600 · each archive is made with tar, run as the user who owns the data
The snapshots directory holds 7_photo-editor_2.4_42.zip, named by set, snap, version and revision; it contains archive.tgz with system data, user/alice.tgz with alice's data, meta.json with hashes and the configuration, and meta.sha3_384 with the hash of meta.json

A set is one file per snap, <set>_<snap>_<version>_<revision>.zip, in /var/lib/snapd/snapshots. It holds archive.tgz, user/<name>.tgz, meta.json with SHA3-384 hashes and the configuration, and meta.sha3_384.

Go looking for set seven on disk and you won't find one file called seven. Snapshots live in a directory only root can read, as one zip file per snap, named by set, snap, version and revision. Inside, the data for the system is a compressed tar archive of the current revision's directory and common. Each user gets an archive of the same shape under user. meta.json describes the snapshot, carries the snap's configuration and a hash of every archive. A small file holds the hash of meta.json itself. snap check-snapshot checks against these. And tar runs as the user who owns the data.

04 Putting it back

RESTORE $ snap restore 7 snapshotbesidein useset 7today's datasame snap? can this revision read that epoch? unpacked copy✓ size and hash match, one archive at a time after the swaptoday's datakept until the change is donedata from set 7Restored snapshot #7. settingsreplaced too the app is not stopped:close it first
snap restore 7: set 7 is checked for the same snap and a readable epoch, unpacked archive by archive into a copy beside today's data, each checked for size and hash and then swapped in; today's data is kept aside until the change is done and then removed; the settings are replaced too; the app is not stopped

snap restore checks snap id and epoch, unpacks each archive beside the live data, verifies its size and hash, then swaps each part in and replaces the configuration. The replaced data is removed when the change completes, or put back if it fails. The snapshot's data becomes the data of the installed revision.

The conversion went wrong and the catalogue is a mess. Time to bring set seven back, and watch the order. First it checks that the snapshot belongs to this snap, and that the installed revision can read data that old: the snap's epoch. Then, one archive at a time, it unpacks beside the real data, checks size and hash, and only then swaps it in. Today's data is moved aside, deleted at the end, or moved back if anything fails. The settings are replaced too. Whatever you changed since the snapshot is gone. And snapd doesn't stop the app for you, so it's wise to close it first.

05 The snapshot you did not ask for

AUTOMATIC $ snap remove photo-editorphoto-editor removed (snap data snapshot saved) $ snap savedSet Snap Age Version Rev Size Notes7 photo-editor 7d01h 2.4 42 18.5MB -8 photo-editor 4.10s 2.4 42 18.6MB auto set 8deletedremoved31 days later (classic) set 7kept until snap forget 7 $ snap set system snapshots.automatic.retention=72h$ snap set system snapshots.automatic.retention=noat least 24 hours,or no to switch it off Ubuntu Coreoff unless a retention is setsnap remove --purgetakes no snapshot
snap remove photo-editor prints that a snap data snapshot was saved; snap saved lists set 7 and set 8 marked auto; on a time line set 8 is deleted 31 days after the removal while set 7 is kept until snap forget 7; snapshots.automatic.retention sets the time or switches it off; on Ubuntu Core it is off unless set

snap remove saves an automatic snapshot, marked auto in snap saved. It expires after snapshots.automatic.retention: 31 days by default on classic, off by default on Ubuntu Core. Manual snapshots do not expire.

A week later you remove the photo editor anyway. Look at what remove printed: it saved a snapshot. Snap saved lists it as set eight, with the note auto. An automatic snapshot is an ordinary one with an expiry date. On a classic system, snapd deletes it 31 days after it was made. Yours don't expire; set seven stays until you forget it. Reinstall within the month and snap restore eight brings your data back. The retention is a system option: a day or more, or no to switch it off. On Ubuntu Core it's off until you set one. And snap remove --purge skips the snapshot.

06 Taking a snapshot to another machine

EXPORT AND IMPORT laptop7new laptop12 $ snap check-snapshot 7Snapshot #7 verified successfully. $ snap export-snapshot 7 editor.snapshotExported snapshot #7 into "editor.snapshot"editor.snapshot a tar archivethe set's zip filesexport.jsoncontent.json $ snap import-snapshot editor.snapshotImported snapshot as #33set ids are local counters $ snap import-snapshot editor.snapshotImported snapshot as #3the same file again: the same set, not a copy
On the laptop snap check-snapshot 7 verifies set 7 and snap export-snapshot 7 writes editor.snapshot, a tar archive of the set's zip files, export.json and content.json; on the new laptop snap import-snapshot stores it as set 3; importing the same file again gives set 3 again

snap check-snapshot verifies a set against its hashes. snap export-snapshot writes a set to one tar file and snap import-snapshot stores it under a new set id on the importing system; importing the same file again prints the existing id.

New laptop. You'd like the photo editor's catalogue to come with you, and set seven has it. First, snap check-snapshot seven re-reads every archive and compares sizes and hashes. A cheap way to know it's intact. Then snap export-snapshot writes the whole set into one file that you name: a tar archive holding the set's zip files and two small JSON files that describe them. On the new laptop, snap import-snapshot stores it and tells you its number. Set numbers are local counters, so seven here became three there. Import the same file again and you get set three back, not a copy.

07 Snapshots do not stop the snap, and they are changes for administrators for snapd developers

AS A CHANGE acme-agent.agentnot stopped: data may change while it is copied advice: snap stop acme-agent, save,then snap start acme-agentactive mount points inside the data are left out · export and import are not tasks change: Snapshot snaps "photo-editor", "acme-agent"save-snapshotsave-snapshotphoto-editoracme-agentno lanes: the set succeeds or fails as a whole restore-snapshotcleanup-after-restoreundo moves the old data back refresh photo-editorconflict while the snapshot runs,and the other way round forget 7cannot operate on snapshot set #7while change "..." is in progress
The running acme-agent service is not stopped by snap save, so stopping it first is advised. A save change for photo-editor and acme-agent holds one save-snapshot task per snap and succeeds or fails as a whole; a restore is restore-snapshot then cleanup-after-restore; a refresh of photo-editor conflicts with it; forget of set 7 conflicts with work on set 7

Save is one save-snapshot task per snap with no lanes; restore is restore-snapshot per snap followed by cleanup-after-restore. They conflict with a refresh or remove of the same snap. Apps and services are not stopped; the handlers expect them not to be running, so stopping a service first with snap stop is advisable.

On the gateway you'd put snap save in a script before anything risky. Know this first: snap save doesn't stop the agent. The handlers expect apps and services to be stopped already, and nothing stops them, so the data can change while it's copied. For a busy daemon, stopping it yourself first is the careful choice. The save itself is a change with one save-snapshot task per snap. Restore adds a clean-up task and can be undone. While either runs, a refresh or removal of that snap is a conflict, and the other way round. Forget conflicts with other work on the same set.

08 Where to go from here

ROADS Snapshots Remove and revertthe remove that saves one Configurationthe settings a snapshot carries Snap packagingthe data directories The overlordchanges and conflicts Refreshwhat you might save before
Roads from snapshots: remove and revert, configuration, snap packaging, the overlord and refresh

Roads to remove and revert, configuration, snap packaging, the overlord and refresh.

Save, check, restore, forget, and a file you can carry. Here's where the neighbouring pieces live. The remove and revert deck shows the remove that saved set eight for you. The configuration deck covers the settings a snapshot carries back. Snap packaging lays out the data directories a snapshot copies. The overlord deck explains changes, tasks and the conflicts you just met. And the refresh deck is the one to read before deciding what's worth saving first.

Read more

Commands

CommandEffectOutput
snap save [--users=a,b] [<snap>...]save the named snaps, or all active snaps, as one setthe snap saved rows of the new set
snap saved [--id=<set>] [<snap>...]list setscolumns Set, Snap, Age, Version, Rev, Size, Notes; or No snapshots found.
snap check-snapshot <set> [<snap>...] [--users=a,b]verify sizes and hashesSnapshot #<set> verified successfully.
snap restore <set> [<snap>...] [--users=a,b]replace current data and configurationRestored snapshot #<set>.
snap forget <set> [<snap>...]delete a set, or one snap's part of itSnapshot #<set> forgotten.
snap export-snapshot <set> <filename>write the set to a fileExported snapshot #<set> into "<filename>"
snap import-snapshot <filename>store an exported setImported snapshot as #<set>, then the snap saved rows of that set

Notes column: auto for an automatic snapshot, broken: <reason> for one that cannot be read. snap saved has no --users option.

Importing a file whose content is identical to a set already on the system prints the id of that existing set; no copy is made.

What a snapshot holds

PartContent
System datathe current revision's data directory and the common data directory
User datafor each user, the current revision's directory and the common directory under that user's home
Configurationthe snap's options, as snap get shows them
Not includedthe snap itself; data of other revisions on disk; active mount points inside the data directories; paths the snap excludes

With --users, only those users' data is saved; the system data is always saved. Disabled snaps are skipped when no snap is named. Naming a snap that is not installed is an error.

Automatic snapshots

ItemValue
Taken whensnap remove without --purge, of an app snap, removing all revisions
Optionsnap set system snapshots.automatic.retention=<duration> or =no
Smallest duration24 hours
Default on classic31 days
Default on Ubuntu Coreoff
Expiry checkat most once every 24 hours
Manual snapshotsno expiry; kept until snap forget

Importing a set that is identical to an automatic one removes its expiry.

Restore checks and messages

MessageMeaning
cannot restore snapshot for "<snap>": current snap (epoch <a>) cannot read snapshot data (epoch <b>)the installed revision cannot read data of the snapshot's epoch
cannot restore snapshot for "<snap>": current snap (ID ...) does not match snapshot (ID ...)a different snap with the same name
cannot operate on snapshot set #<n> while change "<id>" is in progressanother change is using the set
cannot operate on snapshot set #<n> while operation <op> is in progressan export or import is using the set
cannot snapshot user data directories in NFS mounts: use --purge to skip taking a snapshotremove with snap data on NFS
no export.json file in uploaded datathe imported file is not a snapshot export

Each archive, the system's and each user's, is checked and swapped in turn; if a later one fails, the earlier ones are put back.

The snapshot's revision data is restored as the data of the installed revision, even when that revision is newer than the saved one; the epoch check guards this. The configure hook is not run after a restore.

Running apps

Save and restore do not stop the snap's apps or services. The task handlers are documented as expecting that they are not running, and the code carries a to-do to add tasks that stop them. Stopping a service with snap stop before snap save or snap restore, and starting it again afterwards, is advice that follows from this; it is not a documented procedure.

for administrators for snapd developers

Files

Directory: /var/lib/snapd/snapshots, mode 0700. One file per snap and set, mode 0600: <set>_<snap>_<version>_<revision>.zip.

EntryContent
archive.tgzsystem data: the revision directory and common
user/<username>.tgzone per user: the revision directory and common
meta.jsonset id, snap, snap-id, revision, version, epoch, time, SHA3-384 per entry, size, options, configuration
meta.sha3_384hash of meta.json

Archives are written by tar --create --sparse --gzip --format gnu --anchored --no-wildcards-match-slash, run as the owning user.

An export is a tar stream of content.json, the set's zip files and export.json (format: 1, date, files).

for administrators for snapd developers

Exclusions

A snap can ship meta/snapshots.yaml:

exclude:
  - $SNAP_COMMON/cache
  - $SNAP_USER_DATA/*.tmp
  • Each path starts with $SNAP_DATA, $SNAP_COMMON, $SNAP_USER_DATA or $SNAP_USER_COMMON.
  • A single * is allowed; [, ], {, }, ? and ** are not.
  • The REST API accepts further exclusions per request in snapshot-options; snap save has no flag for them.
  • Active mount points under the data directories are excluded at save time.

for snapd developers

Tasks and state

Task kindUndoNotes
save-snapshotdeletes the fileone per snap; summary Save data of snap "<name>" in automatic snapshot set #<n> for automatic ones
restore-snapshotmoves the replaced data back and restores the configurationone per snap
cleanup-after-restorenoneone per change, after all restore tasks; removes the replaced data
check-snapshotnone
forget-snapshotnone
  • Change summaries for save: Snapshot all snaps or Snapshot snaps <names>.
  • Set ids: one more than the larger of last-snapshot-set-id in state and the highest id in file names on disk. An id is allocated when the task is created.
  • Expiry records live under the state key snapshots.
  • Export and import are not tasks; a running one is recorded under snapshot-ops in the state cache.

Further reading

Roads from here

GETTING SNAPS

RUNNING SNAPS