SNAPPER(8)

📦
version 0.13.2 · 8 versions
, in arch rolling

💅 SNAPPER — the snapper(8) manual, but make it make sense

okay so bestie, welcome to snapper(8) — yes, the section-8 one, the filesystem snapshot management girlie 💖. This is the command-line program for managing filesystem snapshots, and honestly? She's iconic. Let's get into it.

✨ SYNOPSIS ✨

snapper [--global-opts] command [--command-opts] [command-arguments]

snapper {--help}

like, that's the whole shape of it. global opts first, then the command, then the command's own opts, then whatever arguments that command wants. and --help exists if you're just vibing and wanna know more 🫶

🌸 DESCRIPTION 🌸

So Snapper is a command-line program for filesystem snapshot management. She can create, delete and compare snapshots, and even undo changes done between snapshots. Main character energy, fr fr 👑

The way that Snapper never modifies the content of snapshots — never ever, no cap. That's why snapper creates read-only snapshots if supported by the kernel. Obsessed with the safety of it all.

Supported filesystems are btrfs and ext4 (discontinued) as well as snapshots of LVM logical volumes with thin-provisioning. Some filesystems might not be supported depending on your installation, so don't come for her if your exotic setup isn't on the list 🙈

🧠 CONCEPTS 🧠

Configurations

For each filesystem or subvolume that should be snapshotted by snapper, a configuration file is required — see snapper-configs(5). And the setup can be done with the create-config command. Slay, easy.

Snapshots

Snapper distinguishes three types of snapshots. Three! A little trio 🎀

  • pre — Pre snapshots should always have a corresponding post snapshot. The intention of pre/post snapshot pairs is to snapshot the filesystem before and after a modification.
  • post — See pre type. (yes, they're a package deal, iykyk)
  • single — These snapshots have no special relationship to other snapshots. Independent queen 💅
Note that filesystem-wise all three types are the same. The differences are in the vibes (and the metadata), not the fs.

Snapshot Description and Userdata

With each snapshot a description and some userdata can be associated. The description is a string. The userdata is a list of key-value pairs where the keys and values are strings.

⚠️ real talk: do not use non-ASCII characters for the snapshot description, userdata or any other strings, unless you always use the UTF-8 character encoding. Like, always. Not sometimes. Always 😭

Automatic Snapshot Creation

Next to manual snapshot creation, snapshots are also created automatically ✨

  • A cronjob or systemd timer creates hourly snapshots, if TIMELINE_CREATE is enabled for a config.
  • Certain programs like YaST and zypper create pre/post snapshot pairs when modifying the system.

Cleanup Algorithms

Snapper provides several algorithms to clean up old snapshots. The algorithms are executed in an hourly cronjob or systemd timer. This can be configured in the corresponding configurations files along with parameters for every algorithm.

  • number — Deletes old snapshots when a certain number of snapshots is reached.
  • timeline — Deletes old snapshots but keeps a number of hourly, daily, weekly, monthly, quarterly and yearly snapshots.
  • empty-pre-post — Deletes pre/post snapshot pairs with empty diffs.

The number and timeline cleanup algorithms can also try to keep the space used by snapshots below a limit and the free space of the filesystem above a limit. For the first condition quota must be setup — see command setup-quota. Additionally the NUMBER_LIMIT and TIMELINE_LIMIT variables in the config file must have ranges (min- and max-value). The algorithms will then make two passes:

  1. Delete snapshots above the max-value independent of the snapshot and filesystem space.
  2. Delete snapshots above the min-value until the limits for the snapshot and filesystem are reached.

The limit for the used space can be configured via the SPACE_LIMIT variable.

💀 Note: only snapshots that have a cleanup algorithm set are taken into account when calculating the space used by snapshots. So if you didn't give it a cleanup algorithm, she's not counting it, periodt.

The limit for the free space can be configured via the FREE_LIMIT variable.

⚠️ Note: since the cleanup is performed asynchronously from creating snapshots, the observed snapshots can differ from the expected snapshots according to the limits. Also btrfs stale qgroups can exist temporarily. Not a bug, just asynchronous behavior being asynchronous 🙈

Filters

Some files keep state information of the system, e.g. /etc/mtab. Such files should never be reverted. To help users, snapper allows one to ignore these files 🫶

Filters are read from the files /etc/snapper/filters/*.txt and /usr/share/snapper/filters/*.txt, where for files with the same name the former location has precedence. Each line in those files specifies a pattern. When snapper computes the difference between two snapshots it ignores all files and directories matching any of those patterns by using fnmatch(3) with the flag FNM_LEADING_DIR.

🚨 Note that filters do not exclude files or directories from being snapshotted. For that, use subvolumes or mount points. Filters are for diffing, not for snapshotting, bestie. Different thing entirely.

🌈 GLOBAL OPTIONS 🌈

these work on every command, so learn them once and you're set 💜

  • -q, --quiet — Suppress normal output. Error messages will still be printed, though. (she's quiet, not silent 💅)
  • -v, --verbose — Increase verbosity. wanna know everything? this is your girl.
  • --logger-type type — Set the logger type. Possible values are none, stdout, logfile and syslog.
  • --debug — Turn on debugging. 🐛
  • --utc — Display dates and times in UTC. By default, local time is used.
  • --iso — Display dates and times in ISO format. ISO format is always used for machine-readable outputs.
  • -t, --table-style style — Specifies table style. Table style is identified by an integer number.
  • --abbreviate — Try to abbreviate texts in some columns so that tables fit the width of the screen. tiny screen girlies rise 🫶
  • --machine-readable format — Specifies a machine-readable output format. Possible options are csv and json.
  • --csvout — Sets CSV output format. See RFC 4180 for the details, except lines end with a LF, not CR+LF. okay customize 💅
  • --jsonout — Sets JSON output format.
  • --separator character — Specifies the character separator for CSV output format.
  • --no-headers — Suppress headers for CSV output format.
  • -c, --config name — Use specified configuration instead of the default configuration. The default configuration is named "root".
  • --no-dbus — Operate without a DBus connection.
⚠️ Use with caution since a running snapperd will not know about modifications made to the system. like, she's offline and blissfully unaware 😭
  • -r, --root path — Operate on target root. Only works together with no-dbus and only for some commands. conditional queen.
  • -a, --ambit ambit — Operate in the specified ambit. Can be used to override the ambit detection. Allowed ambits are auto, classic and transactional.
  • --version — Print version and exit. bye bestie 👋

💅 COMMANDS 💅

okay bestie, so snapper comes with a whole bunch of commands and you're gonna meet all of them 💖 Each command accepts the options from the GLOBAL OPTIONS section — but heads up, those have to go before the command name. And like, lots of commands also have their own special options, listed right here in this section. Those command-specific ones go after the command name but before any of the command arguments. Order matters, no cap 🫶

help

Shows a short help text. That's it, that's the whole vibe ✨

list-configs [options]

Lists the available configurations. 🎀

  • --columns columns — pick which columns to show, separated by comma.

Possible columns are: config, subvolume.

create-config [options] subvolume

Makes a brand new configuration for a filesystem or subvolume 🌸 for this one you'll most likely need the global option --config — go peek at GLOBAL OPTIONS and CONCEPTS.

  • -f, --fstype fstype — manually set the filesystem type. Supported values are btrfs, ext4 (discontinued 😭) and lvm. For lvm, snapper uses LVM thin-provisioned snapshots, and the filesystem type sitting on top of LVM must be provided in parentheses, like lvm(xfs).

Without this option snapper tries to detect the filesystem on its own.

  • -t, --template name — name of the template for the new configuration file.

delete-config

Deletes a configuration for a filesystem or subvolume, including all snapshots 💀 for this one you'll likely need the global option --config — see GLOBAL OPTIONS and CONCEPTS.

bestie this one is permanent, the snapshots go poof too 🙈

get-config [options]

Displays the settings of the configuration. 💜

  • --columns columns — pick which columns to show, separated by comma.

Possible columns are: key, value.

Columns are not selected when JSON format is used.

set-config configdata

Changes the settings of the configuration. The settings configdata are a list of key-value-pairs separated by spaces, and the key and the value must be separated by an equal sign, like this:

"NUMBER_CLEANUP=yes NUMBER_LIMIT=10"

The value of SUBVOLUME and FSTYPE cannot be changed 🚫

list (ls) [options]

Lists snapshots 🦋

  • -t, --type type — selects the type of snapshots to list. Possible values are all, single and pre-post.
  • --disable-used-space — disables the display of used space.

Calculating used space takes a minute, so this option speeds up the listing. ⚡

  • -a, --all-configs — lists snapshots from all configs accessible by the user.
  • --columns columns — pick which columns to show, separated by comma.

Possible columns are: config, subvolume, number, default, active, date, user, used-space, cleanup, description, userdata, pre-number, post-number, post-date, read-only.

For each snapshot the output consists of several columns. A few of them need explaining, so buckle up:

#, Pre # and Post #

The number of the snapshot.

For btrfs the number can be followed by a sign 👀 A - means the snapshot is the currently mounted snapshot, and a + means the snapshot will be mounted next time (it's the btrfs default subvolume). If both conditions apply, a * is displayed.

Used Space

For btrfs, this is the exclusive space of the btrfs quota group corresponding to the snapshot.

Display of used space is automatically disabled if it's not available — like when quota isn't enabled on btrfs 🥲

create [options]

Creates a new snapshot ✨

  • -t, --type type — specifies the type of the new snapshot. Possible values are single, pre and post.
  • --pre-number number — for post snapshots, the number of the pre snapshot must be provided.
  • -p, --print-number — prints the number of the created snapshot.
  • -d, --description description — description for the snapshot.
  • -c, --cleanup-algorithm cleanup-algorithm — sets the cleanup algorithm for the snapshot.
  • -u, --userdata userdata — sets userdata for the snapshot. The key-value pairs must be separated by comma, and the key and value must be separated by an equal sign, like requestid=42,user=arthur.
  • --command command — creates a pre and post snapshot and runs command in between. If snapper is unable to execute the command at all, it does not take the post snapshot. If the command exits with a non-zero exit code, snapper takes the post snapshot and exits with that same exit code. 🏃‍♀️
  • --read-only — creates a read-only snapshot. This is the default.
  • --read-write — creates a read-write snapshot.
  • --from number — creates a snapshot from the snapshot with the provided number instead of snapshot 0.
  • --empty — creates an empty snapshot. Only supported on btrfs and with --no-dbus.

modify [options] number

Modifies a snapshot 🎀

  • -d, --description description — new description for the snapshot.
  • -c, --cleanup-algorithm cleanup-algorithm — sets the cleanup algorithm for the snapshot.
  • -u, --userdata userdata — sets userdata for the snapshot. The key-value pairs must be separated by comma, and the key and value must be separated by an equal sign, like requestid=42,user=arthur.
  • --read-only — sets the snapshot read-only.
  • --read-write — sets the snapshot read-write.
  • --default — sets the snapshot as the default snapshot. Only for btrfs.

delete (remove|rm) number | number1-number2

Deletes a snapshot — or a whole range of snapshots 😭

  • -s, --sync — syncs the filesystem after deleting the snapshots. The details depend on the filesystem type.

Btrfs normally frees space asynchronously after deleting snapshots. With this option snapper waits until the space once used by the deleted snapshots is actually available again. ⏳

Snapshot 0 cannot be deleted. For btrfs, the currently mounted snapshot and the snapshot that will be mounted next time (the btrfs default subvolume) can also not be deleted. Like, at all. 🚫

mount number

Mounts a snapshot. Not required for all filesystem types.

umount number

Unmounts a snapshot. Not required for all filesystem types.

status [options] number1..number2

Compares the snapshots number1 and number2. This shows a list of files and directories that have been created, modified or deleted in the time between the two snapshots being made. 🔍

  • -o, --output file — writes output to the file file.

The output consists of a string encoding the status, followed by the filename. The characters of the status string are, in order:

  1. A + means the file was created, a - means the file was deleted. A c means the content of the file has changed, and a t means the type of the file has changed (e.g. from regular file to directory).
  2. A p means the permissions have changed.
  3. A u means the user ownership has changed.
  4. A g means the group ownership has changed.
  5. A x means the extended attribute information has changed.
  6. An a means the ACL information has changed.

If there is no change, a . is outputted. ✨

diff [options] number1..number2 [files]

Compares the snapshots number1 and number2. This shows a diff of the content of files and directories that have been created, modified or deleted in the time between the two snapshots being made. 🦋

  • -i, --input file — read files to diff from the file file.
  • --diff-cmd command — the command used for comparing files. The default is /usr/bin/diff --new-file --unified. The two files to compare are passed as parameters to the command.
  • -x, --extensions options — extra options passed to the diff command.

undochange [options] number1..number2 [files]

Undoes the changes done between snapshot number1 and number2. 🧚 time travel but make it filesystem

  • -i, --input file — read files for which to undo changes from the file file.

rollback [options] [number]

Creates two new snapshots and sets the default subvolume. By default the system boots from the default subvolume of the root filesystem. The exact actions depend on whether a number is provided or not:

  • Without a number, a first read-only snapshot of the default subvolume is created. A second read-write snapshot of the current system is created. The system is set to boot from the second snapshot.
  • With a number, a first read-only snapshot of the current system is created. A second read-write snapshot is created of number. The system is set to boot from the second snapshot.

Rollback is only supported with btrfs and requires a properly configured system. 👑

  • -p, --print-number — prints the number of the second created snapshot.
  • -d, --description description — description for the snapshot.
  • -c, --cleanup-algorithm cleanup-algorithm — sets the cleanup algorithm for the snapshot.
  • -u, --userdata userdata — sets userdata for the snapshot. The key-value pairs must be separated by comma, and the key and value must be separated by an equal sign, like requestid=42,user=arthur.

The rollback command also sets the description, the cleanup algorithm and some userdata — unless the values are specified on the command line. This automates cleanup of snapshots created by rollbacks. 🧹

In other ambits than classic, the rollback command does what's required to do a rollback. Anyway, it's recommended to use specific programs in that case.

setup-quota

Sets up quota. Currently only supported with btrfs. 🌈

cleanup [options] cleanup-algorithm

Runs the cleanup algorithm cleanup-algorithm. Currently implemented cleanup algorithms are number, timeline and empty-pre-post. To run all cleanup algorithms, all can be provided as cleanup-algorithm. 💅

  • --path path — cleanup all configs affecting path. Only useful for btrfs.
  • --free-space free-space — try to make free-space available. Only useful for btrfs.

xadiff number1..number2 [files]

Compares the extended attributes between snapshot number1 and number2. See the examples below: 🍓

  • +:user.foo for created attributes
  • -:user.bar for removed attributes
  • -+:security.selinux for modified attributes

🌸 PERMISSIONS 🌸

Non-root users can be allowed to use a configuration by setting ALLOW_USERS or ALLOW_GROUPS in the config file, bestie. For all operations to work, the user must also be able to read and access the .snapshots directory inside the subvolume. And heads up: the .snapshots directory must be owned by root and must not be writable by anybody else. Periodt. 🫶

Here are some methods how to achieve that:

  • Make the directory accessible for everyone: chmod a+rx .snapshots
  • Make the directory accessible for a group the user belongs to, e.g.: chown :users .snapshots
  • Make the directory accessible for the user using ACLs, e.g.: setfacl -m u:tux:rx .snapshots

The last method can be performed by snapper — see the SYNC_ACL setting in snapper-configs(5). iykyk ✨

🧚 PLUGINS 🧚

snapper can execute external scripts after certain actions, and honestly? main character energy. Scripts have to be placed in /usr/lib/snapper/plugins. The name has to start with a digit, and execution order is alphabetical. No cap, alphabet supremacy. 🔥

The first argument of a script is the action snapper executed. The following actions are defined:

  • create-config-pre subvolume fstype — executed before a new config is created
  • create-config-post subvolume fstype — executed after a new config was created
  • delete-config-pre subvolume fstype — executed before a config is deleted
  • delete-config-post subvolume fstype — executed after a config was deleted
  • create-snapshot-pre subvolume fstype snapshot-number — executed before a new snapshot is created
  • create-snapshot-post subvolume fstype snapshot-number — executed after a new snapshot was created
  • modify-snapshot-pre subvolume fstype snapshot-number — executed before a snapshot is modified
  • modify-snapshot-post subvolume fstype snapshot-number — executed after a snapshot was modified
  • delete-snapshot-pre subvolume fstype snapshot-number — executed before a snapshot is removed
  • delete-snapshot-post subvolume fstype snapshot-number — executed after a snapshot was removed
  • set-read-only-pre subvolume fstype snapshot-number — executed before a snapshot is set read-only or read-write
  • set-read-only-post subvolume fstype snapshot-number — executed after a snapshot is set read-only or read-write
  • set-default-snapshot-pre subvolume fstype snapshot-number — executed before the default snapshot is changed
  • set-default-snapshot-post subvolume fstype snapshot-number — executed after the default snapshot was changed
  • rollback-post subvolume fstype old-snapshot-number new-snapshot-number — executed after a rollback was done

More actions and arguments can be added any time. Using snapper in the plugins is not allowed. 🙈

Ensure plugins execute within a few seconds. Slow-running plugins block the primary interface and degrade user experience and can even cause timeouts (e.g. causing zypper to kill the snapper plugin). Not the vibe. 💀

It is undefined whether the plugins are called from the client (snapper) or server (snapperd). Schrödinger’s plugin caller, lowkey. 🦋

🎀 FILES 🎀

  • /etc/conf.d/snapper — Global configuration file.
  • /etc/snapper/configs — Directory containing configuration files.
  • /etc/snapper/config-templates — Directory containing configuration templates.
  • /usr/share/snapper/config-templates — Fallback directory containing configuration templates.
  • /etc/snapper/filters/*.txt — Filter files.
  • /usr/share/snapper/filters/*.txt — Fallback filter files.
  • /var/log/snapper.log — Logfile. Please include this file in bug reports.

Bestie, please actually include the logfile in bug reports. It’s giving helpful, fr fr. 🍓

✨ EXIT STATUS ✨

Normally the exit status is 0. If an error occurred the exit status is 1. It is also an error if the exit status of a plugin is not 0. Simple, iconic, no notes. 💅

💜 NOTES 💜

There is no mechanism to ensure consistency of the files while a snapshot is made. E.g. the files of a database can be inconsistent while the database is running. No cap — running databases and snapshots are not automatically giving “perfectly consistent files.” 😭

Consistency after undochange is not guaranteed. E.g. when the creation of a user is undone, there might still exist files from that user. Undo is powerful, but not a magical little time machine, bestie. 🎀

Support for individual filesystems, rollback and extended attributes are compile-time options and may not be available. Compile-time choices are the main characters here. 🌈

🌸 HOMEPAGE 🌸

http://snapper.io/

👑 AUTHORS 👑

Arvin Schnell <aschnell@suse.com>

🔥 SEE ALSO 🔥

snapper-configs(5), snapper-zypp-plugin(8), snbk(8), pam_snapper(8), btrfs(8), lvm(8), attr(5), acl(5)

📎 NOTES 📎

  1. RFC 4180 — https://tools.ietf.org/html/rfc4180

That’s the whole page, bestie! 💖 SNAPPER(8) is version 0.13.2, dated 2026-01-02 — slay, bye! 🎀

📦 where this page comes from