snapper - Man Page

• List snapshot configs: snapper list-configs
• Create snapper config: snapper [-c|--config] config create-config path/to/directory
• Create a snapshot with a description: snapper [-c|--config] config create [-d|--description] "snapshot_description"
• List snapshots for a config: snapper [-c|--config] config list
• Delete a snapshot: snapper [-c|--config] config delete snapshot_number
• Delete a range of snapshots: snapper [-c|--config] config delete snapshot1-snapshot2

tldr.sh

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

snapper {--help}

Snapper is a command-line program for filesystem snapshot management​. It can create, delete and compare snapshots and undo changes done between snapshots​.

Snapper never modifies the content of snapshots​. Thus snapper creates read-only snapshots if supported by the kernel​. Btrfs and thin-provisioned LVM logical volumes are supported​. Some filesystems might not be supported depending on your installation​.

-q,  --quiet

Suppress normal output​. Error messages will still be printed, though​.

-v,  --verbose

Increase verbosity​.

--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​.

--machine-readable format

Specifies a machine-readable output format​. Possible options are csv and json​.

--csvout

Sets CSV output format​. See RFC 4180​^[1] for the details, except lines end with a LF, not CR+LF​.

--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​.

-r,  --root path

Operate on target root​. Only works together with no-dbus and only for some commands​.

-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​.

Snapper provides a number of commands​. Each command accepts the options listed in the Global Options section​. These options must be specified before the command name​. In addition, many commands have specific options, which are listed in this section​. These command-specific options must be specified after the name of the command and before any of the command arguments​.

help

Show short help text​.

list-configs [options]

List available configurations​.

--columns columns

Select columns to show separated by comma​.

Possible columns are: config, subvolume​.

create-config [options] subvolume

Create a new configuration for a filesystem or subvolume​. For this command you will likely need the global option --config, see Global Options and Concepts​.

-f, --fstype fstype

Manually set filesystem type​. Supported values are btrfs and lvm​. For lvm, snapper uses LVM thin-provisioned snapshots​. The filesystem type on top of LVM must be provided in parentheses, e​.g​. lvm(xfs)​.

Without this option snapper tries to detect the filesystem​.

-t, --template name

Name of template for the new configuration file​.

delete-config

Delete a configuration for a filesystem or subvolume​. For this command you will likely need to global option --config, see Global Options and Concepts​.

get-config [options]

Displays the settings of the configuration​.

--columns columns

Select 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 value must be separated by an equal sign, e​.g​. "NUMBER_CLEANUP=yes NUMBER_LIMIT=10"​. The value of SUBVOLUME and FSTYPE cannot be changed​.

list (ls) [options]

List snapshots​.

-t, --type type

Selects type of snapshots to list​. Possible values are all, single and pre-post​.

--disable-used-space

Disable display of used space​.

Calculating the used space needs some time​. Thus this option can speedup the listing​.

-a, --all-configs

List snapshots from all configs accessible by the user​.

--columns columns

Select 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​. Some need explanation:

#, Pre # and Post #

The number of the snapshot​.

For btrfs the number can be followed by a sign​. A "-" indicates that the snapshot is the currently mounted snapshot and a "+" indicates that the snapshot will be mounted next time (It is the btrfs default subvolume)​. If both conditions apply a "*" is displayed​.

Used Space

For btrfs the exclusive space of the btrfs quota group corresponding to the snapshot​.

Display of used space is automatically disabled if not available, e​.g​. quota not enabled on btrfs​.

create [options]

Create 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

Print number of the created snapshot​.

-d, --description description

Description for the snapshot​.

-c, --cleanup-algorithm cleanup-algorithm

Set the cleanup algorithm for the snapshot​.

-u, --userdata userdata

Set 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, e​.g​. requestid=42,user=arthur​.

--command command

Create a pre and post snapshot and run command in between​.

--read-only

Create a read-only snapshot​. This is the default​.

--read-write

Create a read-write snapshot​.

--from number

Create a snapshot from the snapshot with the provided number instead of snapshot 0​.

--empty

Create an empty snapshot​. Only supported on btrfs and with --no-dbus​.

modify [options] number

Modify a snapshot​.

-d, --description description

New description for snapshot​.

-c, --cleanup-algorithm cleanup-algorithm

Set the cleanup algorithm for the snapshot​.

-u, --userdata userdata

Set 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, e​.g​. requestid=42,user=arthur​.

--read-only

Set the snapshot read-only​.

--read-write

Set the snapshot read-write​.

--default

Set the snapshot as default snapshot​. Only for btrfs​.

delete (remove|rm) number | number1-number2

Delete a snapshot or a range of snapshots​.

-s, --sync

Sync the filesystem after deleting the snapshots​. The details depend on the filesystem type​.

Btrfs normally asynchronously frees space after deleting snapshots​. With this option snapper will wait 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​.

mount number

Mount a snapshot​. Not required for all filesystem types​.

umount number

Unmount a snapshot​. Not required for all filesystem types​.

status [options] number1​.​.number2

Compare the snapshots number1 and number2​. This will show a list of files and directories that have been created, modified or deleted in the time between the two snapshots have been made​.

-o, --output file

Write output to file file​.

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

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 are have changed​.
3. An "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]

Compare the snapshots number1 and number2​. This will show a diff of the content of files and directories that have been created, modified or deleted in the time between the two snapshots have been made​.

-i, --input file

Read files to diff from file file​.

--diff-cmd command

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]

Undo changes done between snapshot number1 and number2​.

-i, --input file

Read files for which to undo changes from file file​.

rollback [options] [number]

Creates two new snapshots and sets the default subvolume​. Per 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

Print number of the second created snapshot​.

-d, --description description

Description for the snapshot​.

-c, --cleanup-algorithm cleanup-algorithm

Set the cleanup algorithm for the snapshot​.

-u, --userdata userdata

Set 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, e​.g​. 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 will automate cleanup of snapshots created by rollbacks​.

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

setup-quota

Sets up quota​. Currently only supported with btrfs​.

cleanup [options] cleanup-algorithm

Run 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]

Compare the extended attributes between snapshot number1 and number2​. See examples below:

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

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

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)​.

snapper can execute external scripts after certain actions​. Scripts have to be placed in /usr/libexec/snapper/plugins​. The name has to start with a digit, execution order is alphabetical​.

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​.

It is undefined whether the plugins are called from the client (snapper) or server (snapperd)​.

/etc/sysconfig/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​.

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​.

There is no mechanism to ensure consistency of the files while a snapshot it made​. E​.g​. the files of a database can be inconsistent while the database is running​.

Consistency after undochange is not guaranteed​. E​.g​. when the creation of a user is undone, there might still exist files from that user​.

Support for individual filesystems, rollback and extended attributes are compile-time options and may not be available​.

http://snapper​.io/

Arvin Schnell <aschnell@suse​.com>

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

1.

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