SNAPPER(8) | Filesystem Snapshot Management | SNAPPER(8) |
snapper - Command-line program for filesystem snapshot management
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. Supported filesystems are btrfs and ext4 as well as snapshots of LVM logical volumes with thin-provisioning. Some filesystems might not be supported depending on your installation.
For each filesystem or subvolume that should be snapshotted by snapper, a configuration file is required, see snapper-configs(5). The setup can be done with the create-config command.
Snapper distinguishes three types of snapshots.
pre
post
single
Note that filesystem-wise all three types are the same.
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.
Do not use non-ASCII characters for the snapshot description, userdata or any other strings, unless you always use the UTF-8 character encoding.
Next to manual snapshot creation, snapshots are also created automatically.
Snapper provides several algorithms to clean up old snapshots. The algorithms are executed in a daily cron-job. This can be configured in the corresponding configurations files along with parameters for every algorithm.
number
timeline
empty-pre-post
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. Additional 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:
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. The limit for the free space can be configured via the FREE_LIMIT variable.
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.
Each line in all files /etc/snapper/filters/*.txt 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.
-q, --quiet
-v, --verbose
--utc
--iso
-t, --table-style
-c, --config name
--no-dbus
Use with caution since a running snapperd will not know about modifications made to the system.
-r, --root path
--version
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
list-configs
create-config [options] subvolume
-f, --fstype fstype
Without this option snapper tries to detect the filesystem.
-t, --template name
delete-config
get-config
set-config configdata
list (ls) [options]
-t, --type type
--disable-used-space
Calculating the used space needs some time. Thus this option can speedup the listing.
-a, --all-configs
For each snapshot the output consists of several columns. Some need explanation:
#, Pre # and Post #
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
Display of used space is automatically disabled if not available, e.g. quota not enabled on btrfs.
create [options]
-t, --type type
--pre-number number
-p, --print-number
-d, --description description
-c, --cleanup-algorithm cleanup-algorithm
-u, --userdata userdata
--command command
modify [options] number
-d, --description description
-c, --cleanup-algorithm cleanup-algorithm
-u, --userdata userdata
delete (remove|rm) number | number1-number2
-s, --sync
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
umount number
status [options] number1..number2
-o, --output file
The output consists of a string encoding the status followed by the filename. The characters of the status string are:
If there is no change a "." is outputted.
diff [options] number1..number2 [files]
-i, --input file
--diff-cmd command
-x, --extensions options
undochange [options] number1..number2 [files]
-i, --input file
rollback [options] [number]
Rollback is only supported with btrfs and requires a properly configured system.
-p, --print-number
-d, --description description
-c, --cleanup-algorithm cleanup-algorithm
-u, --userdata userdata
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.
setup-quota
cleanup cleanup-algorithm
xadiff number1..number2 [files]
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:
chmod a+rx .snapshots
chown :users .snapshots
setfacl -m u:tux:rx .snapshots
The last method can be performed by snapper, see the SYNC_ACL setting in snapper-configs(5).
/etc/default/snapper
/etc/snapper/configs
/etc/snapper/config-templates
/etc/snapper/filters/*.txt
/var/log/snapper.log
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), pam_snapper(8), btrfs(8), lvm(8), attr(5), acl(5)
2018-10-29 | 0.8.2 |