From Gentoo Wiki
Jump to: navigation, search
This article is a stub. You can help by expanding it.

Snapper is a command-line program capable of managing filesystem snapshots. It has provisions for root and non-root users to review older versions of files and restore them. It also has the ability to create, delete, compare, and undo changes between snapshots. Snapper never modifies the content of snapshots. Thus it will create read-only snapshots (if supported by the system's kernel). Supported filesystems are btrfs and ext4 as well as snapshots of LVM volumes with thin-provisioning. Some filesystems might not be supported depending on the installation.[1] Snapper was initially developed by SUSE Linux but is now in use across many Linux distributions.


USE flags

Cannot load package information. Is the atom app-backup/snapper correct?


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.


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.[2] 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 chown 750 /.snapshots and needs to be on the same volume. This is always the case in the way snapper works by default, so you cannot mix it up. Subvolumes can also be moved like regular folders, so you lose nothing when you start with the default way snapper works and change it later on.

Tips and tricks


You can have all installations by portage automatically snapshotted with the following configuration:[3]

FILE /etc/portage/bashrc
case "${EBUILD_PHASE}" in
                NUMBER=`snapper create -t pre -p -d "${DESC}"`
                snapper create -t post --pre-number $NUMBER -d "${DESC}"


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 #service dbus start
root #rc-update add dbus default

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

root #service lvm start

See also

  • btrfs - A B-tree file system fully capable of running underneath snapper.
  • ext4 - The most commonly used filesystem in Linux.
  • LVM - A utility that virtualizes storage which enables storage to be easily spread across disks/volumes.