This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Snapper
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.
Installation
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. |
Emerge
After USE flags have been set, emerge snapper:
root #emerge --ask app-backup/snapperConfiguration
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.
Usage
user $snapper --helpusage: 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.
Rollback:
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>
Rollback
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:
/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
Portage
You can have all installations by portage automatically snapshotted with the following configuration:[3]
/etc/portage/bashrccase "${EBUILD_PHASE}" in
preinst)
DESC="${CATEGORY}/${PF}"
NUMBER=`snapper create -t pre -p -d "${DESC}"`
;;
postinst)
snapper create -t post --pre-number $NUMBER -d "${DESC}"
;;
esac
Troubleshooting
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 Aborted
or
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.