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
01 A copy before you experiment
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
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
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
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
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
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
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 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
| Command | Effect | Output |
|---|---|---|
snap save [--users=a,b] [<snap>...] | save the named snaps, or all active snaps, as one set | the snap saved rows of the new set |
snap saved [--id=<set>] [<snap>...] | list sets | columns Set, Snap, Age, Version, Rev, Size, Notes; or No snapshots found. |
snap check-snapshot <set> [<snap>...] [--users=a,b] | verify sizes and hashes | Snapshot #<set> verified successfully. |
snap restore <set> [<snap>...] [--users=a,b] | replace current data and configuration | Restored snapshot #<set>. |
snap forget <set> [<snap>...] | delete a set, or one snap's part of it | Snapshot #<set> forgotten. |
snap export-snapshot <set> <filename> | write the set to a file | Exported snapshot #<set> into "<filename>" |
snap import-snapshot <filename> | store an exported set | Imported 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
| Part | Content |
|---|---|
| System data | the current revision's data directory and the common data directory |
| User data | for each user, the current revision's directory and the common directory under that user's home |
| Configuration | the snap's options, as snap get shows them |
| Not included | the 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
| Item | Value |
|---|---|
| Taken when | snap remove without --purge, of an app snap, removing all revisions |
| Option | snap set system snapshots.automatic.retention=<duration> or =no |
| Smallest duration | 24 hours |
| Default on classic | 31 days |
| Default on Ubuntu Core | off |
| Expiry check | at most once every 24 hours |
| Manual snapshots | no expiry; kept until snap forget |
Importing a set that is identical to an automatic one removes its expiry.
Restore checks and messages
| Message | Meaning |
|---|---|
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 progress | another change is using the set |
cannot operate on snapshot set #<n> while operation <op> is in progress | an export or import is using the set |
cannot snapshot user data directories in NFS mounts: use --purge to skip taking a snapshot | remove with snap data on NFS |
no export.json file in uploaded data | the 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.
| Entry | Content |
|---|---|
archive.tgz | system data: the revision directory and common |
user/<username>.tgz | one per user: the revision directory and common |
meta.json | set id, snap, snap-id, revision, version, epoch, time, SHA3-384 per entry, size, options, configuration |
meta.sha3_384 | hash 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_DATAor$SNAP_USER_COMMON. - A single
*is allowed;[,],{,},?and**are not. - The REST API accepts further exclusions per request in
snapshot-options;snap savehas no flag for them. - Active mount points under the data directories are excluded at save time.
for snapd developers
Tasks and state
| Task kind | Undo | Notes |
|---|---|---|
save-snapshot | deletes the file | one per snap; summary Save data of snap "<name>" in automatic snapshot set #<n> for automatic ones |
restore-snapshot | moves the replaced data back and restores the configuration | one per snap |
cleanup-after-restore | none | one per change, after all restore tasks; removes the replaced data |
check-snapshot | none | |
forget-snapshot | none |
- Change summaries for save:
Snapshot all snapsorSnapshot snaps <names>. - Set ids: one more than the larger of
last-snapshot-set-idin 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-opsin the state cache.
Further reading
- Create data snapshots: every snapshot command with examples. It describes an export as a zip; the file is a tar archive.
- Data locations: which directories are per revision and which are common.
- System options:
snapshots.automatic.retention. - Disk space awareness: the space check before the automatic snapshot on remove.
- snapd REST API: the snapshot action and
snapshot-options.
Roads from here
GETTING SNAPS
- Snap packaging — the data directories a snapshot copies
- Epochs: when new code cannot read old data — why restored data may need an epoch
RUNNING SNAPS
- Remove and revert — the remove that takes an automatic snapshot
- Configuration — the configuration a snapshot carries
- The overlord — save and restore are changes that can conflict
- Refresh — the refresh you may want a snapshot before