From Gentoo Wiki
Jump to:navigation Jump to:search
This article is a stub. Please help out by expanding it - how to get started.

Snapper is a command-line program to create and manage filesystem snapshots, allowing viewing or reversion of changes.

Snapper has the ability to create, delete, compare, and undo changes between snapshots. Snapper never modifies the content of snapshots, creating read-only snapshots (if supported by the system's kernel). It can work with root and non-root users.

Snapper mainly targets btrfs , but also supports snapshots of LVM volumes with thin-provisioning (some filesystems might not be supported depending on the installation [1]).

ext4 used to be supported . ext4 does not support snapshotting, and probably never will. snapper/ext4 required kernel patches that never got merged in Linus Kernel[2].

Snapper was initially developed by SUSE Linux but is now in use across many Linux distributions.


USE flags

USE flags for app-backup/snapper Command-line program for btrfs and lvm snapshot management

lvm Enable LVM thinprovisioned snapshots support sys-fs/lvm2
pam Add support for PAM (Pluggable Authentication Modules) - DANGEROUS to arbitrarily flip
systemd Enable use of systemd-specific libraries and features like socket activation or session tracking
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
xattr Add support for getting and setting POSIX extended attributes, through sys-apps/attr.


After USE flags have been set, emerge snapper:

root #emerge --ask app-backup/snapper


Configuration files for snapper are found in the /etc/snapper/ directory. According to snapper's man page, each filesystem or subvolume that should be snapshotted by snapper requires a configuration file.

A create-config sub-command exists to aid in configuration file generation:

root #snapper create-config <subvolume>

To create a configuration for the root filesystem, run:

root #snapper create-config /

This presumes the root filesystem has been formatted with btrfs or some other snapper compatible filesystem. The create-config command will attempt to guess the underlying filesystem type. If the filesystem type is known (in this case btrfs), then it can be specified using the --fstype <fstype> option. See the snapper man page for more information.

Create new snapper configuration named home for the Btrfs volume at /home.

root #snapper --config home create-config /home

Verify the snapper configuration files have been created.

root #snapper list-configs

Allow the regular user to list snapshots. Add user name in the snapper's root and home configurations.

user $sudo snapper -c root set-config ALLOW_USERS=${LOGNAME} SYNC_ACL=yes
user $sudo snapper -c home set-config ALLOW_USERS=${LOGNAME} SYNC_ACL=yes

Change the group permissions of the /.snapshots and /home/.snapshots directories to user name.

user $sudo chown -R :${LOGNAME} /.snapshots
user $sudo chown -R :${LOGNAME} /home/.snapshots


user $snapper --help
usage: snapper [--global-options] <command> [--command-options] [command-arguments]

    Global options:
	--quiet, -q			Suppress normal output.
	--verbose, -v			Increase verbosity.
	--utc				Display dates and times in UTC.
	--iso				Display dates and times in ISO format.
	--table-style, -t <style>	Table style (integer).
	--config, -c <name>		Set name of config to use.
	--no-dbus			Operate without DBus.
	--root, -r <path>		Operate on target root (works only without DBus).
	--version			Print version and exit.

  List configs:
	snapper list-configs

  Create config:
	snapper create-config <subvolume>

    Options for 'create-config' command:
	--fstype, -f <fstype>		Manually set filesystem type.
	--template, -t <name>		Name of config template to use.

  Delete config:
	snapper delete-config

  Get config:
	snapper get-config

  Set config:
	snapper set-config <configdata>

  List snapshots:
	snapper list

    Options for 'list' command:
	--type, -t <type>		Type of snapshots to list.
	--all-configs, -a		List snapshots from all accessible configs.

  Create snapshot:
	snapper create

    Options for 'create' command:
	--type, -t <type>		Type for snapshot.
	--pre-number <number>		Number of corresponding pre snapshot.
	--print-number, -p		Print number of created snapshot.
	--description, -d <description>	Description for snapshot.
	--cleanup-algorithm, -c <algo>	Cleanup algorithm for snapshot.
	--userdata, -u <userdata>	Userdata for snapshot.
	--command <command>	Run command and create pre and post snapshots.

  Modify snapshot:
	snapper modify <number>

    Options for 'modify' command:
	--description, -d <description>	Description for snapshot.
	--cleanup-algorithm, -c <algo>	Cleanup algorithm for snapshot.
	--userdata, -u <userdata>	Userdata for snapshot.

  Delete snapshot:
	snapper delete <number>

    Options for 'delete' command:
	--sync, -s			Sync after deletion.

  Mount snapshot:
	snapper mount <number>

  Umount snapshot:
	snapper umount <number>

  Comparing snapshots:
	snapper status <number1>..<number2>

    Options for 'status' command:
	--output, -o <file>		Save status to file.

  Comparing snapshots:
	snapper diff <number1>..<number2> [files]

    Options for 'diff' command:
	--input, -i <file>		Read files to diff from file.
	--diff-cmd <command>		Command used for comparing files.
	--extensions, -x <options>	Extra options passed to the diff command.

  Comparing snapshots extended attributes:
	snapper xadiff <number1>..<number2> [files]

  Undo changes:
	snapper undochange <number1>..<number2> [files]

    Options for 'undochange' command:
	--input, -i <file>		Read files for which to undo changes from file.

	snapper rollback [number]

    Options for 'rollback' command:
	--print-number, -p		Print number of second created snapshot.
	--description, -d <description>	Description for snapshots.
	--cleanup-algorithm, -c <algo>	Cleanup algorithm for snapshots.
	--userdata, -u <userdata>	Userdata for snapshots.

  Cleanup snapshots:
	snapper cleanup <cleanup-algorithm>


Snapper has function called 'rollback' to switch the current mounted btrfs subvolume to an older subvolume. This feature requires a btrfs file system.

To work properly the rollback feature needs an entry in the fstab to mount the subvolume .snapshots to the directory /.snapshots. If the .snapshots subvolume is not mounted, snapper will fail to create a subvolume after the first rollback and give an input/output error. It will also fail to find any snapshot after the first rollback.

For this example, presume that /dev/sda1 contains the btrfs filesystem snapper will manage. Add the following to /etc/fstab:

FILE /etc/fstabSnapper fstab example
/dev/sda1            /.snapshots     btrfs           subvol=.snapshots       0 0

When snapper is initialized, this fstab entry is not needed, because the /.snapshots subvolume is created in the root subvolume and from there accessible. After the first rollback to a snapshot subvolume (e.g. /.snapshots/432), and upon a reboot into the snapshot subvolume the root subvolume will be left. In the snapshot subvolume, the /.snapshots directory is empty (e.g /.snapshots/432/.snapshots). Snapper cannot find older snapshots or create new ones in the empty directory.

This seems to be a tradeoff between ease of configuration and possible errors in this configuration. It might be a good setup for a Suse system but the btrfs devs propose another setup.[3] With this flat hierarchy the original subvolume can even be deleted and if need be replaced by one of the snapshots. On the other hand the subvolume has to be mounted manually inside. This mount point has to be chmod 750 /.snapshots and needs to be on the same volume. This is always the case in the way snapper works by default, so it cannot be mixed up. Subvolumes can also be moved like regular folders, so nothing is lost when starting with the default way snapper works and change it later on.

Tips and tricks


Installations by portage may be all automatically snapshotted with the number cleanup algorithm using the following configuration:[4]

FILE /etc/portage/bashrc
case "${EBUILD_PHASE}" in
                if [ -z "${REPLACING_VERSIONS}" ]; then
                        DESC="Installing ${CATEGORY}/${PF}"
                        DESC="Upgrading to ${CATEGORY}/${PF} replacing version(s) ${REPLACING_VERSIONS}"
                NUMBER=`snapper create -t pre -p -d "${DESC}" -c number`
                snapper create -t post --pre-number $NUMBER -d "${DESC}" -c number


Fatal exceptions

dbus not running

If seeing dbus error messages such as the following:

terminate called after throwing an instance of 'DBus::FatalException'
  what():  dbus fatal exception


Failure (dbus fatal exception).

dbus is probably not running. To start dbus, on OpenRC, issue:

root #rc-service dbus start
root #rc-update add dbus default

Furthermore, if dbus refuses to start, check that lvm is running:

root #rc-service lvm start

See also

  • Btrfs — a copy-on-write (CoW) filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, self-healing properties, and easy administration.
  • Ext4 — an open source disk filesystem and most recent version of the extended series of filesystems.
  • LVM — allows administrators to create meta devices that provide an abstraction layer between a file system and the physical storage that is used underneath.