openSUSE/snapper
1
0
Fork 0
mirror of https://github.com/openSUSE/snapper.git synced 2026-02-05 06:46:08 +01:00
Code Issues Releases Wiki Activity
Files
master
snapper/doc/snapper.xml.in
Arvin Schnell 2205701a9c Merge pull request #1076 from epg/create-command-error 
Report failure of 'create --command' command
2026-01-05 08:14:06 +00:00

1091 lines
41 KiB
XML
Raw Permalink Blame History

<?xml version="1.0" encoding="utf-8"?>
<refentry id='snapper8' xmlns:xlink="http://www.w3.org/1999/xlink">
<refentryinfo>
<date>2026-01-02</date>
</refentryinfo>
<refmeta>
<refentrytitle>snapper</refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo class='date'>2026-01-02</refmiscinfo>
<refmiscinfo class='version'>@VERSION@</refmiscinfo>
<refmiscinfo class='manual'>Filesystem Snapshot Management</refmiscinfo>
</refmeta>
<refnamediv>
<refname>snapper</refname>
<refpurpose>Command-line program for filesystem snapshot management</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
<command>snapper</command>
<arg choice='opt'><replaceable>--global-opts</replaceable></arg>
<arg choice='plain'><replaceable>command</replaceable></arg>
<arg choice='opt'><replaceable>--command-opts</replaceable></arg>
<arg choice='opt'><replaceable>command-arguments</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>snapper</command>
<arg choice='req'>--help</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id='description'>
<title>DESCRIPTION</title>
<para>Snapper is a command-line program for filesystem snapshot management. It can
create, delete and compare snapshots and undo changes done between snapshots.</para>
<para>Snapper never modifies the content of snapshots. Thus snapper creates
read-only snapshots if supported by the kernel. Supported filesystems are
btrfs and ext4 (discontinued) as well as snapshots of LVM logical volumes with
thin-provisioning. Some filesystems might not be supported depending on your
installation.</para>
</refsect1>
<refsect1 id='concepts'>
<title>CONCEPTS</title>
<refsect2 id='configurations'>
<title>Configurations</title>
<para>For each filesystem or subvolume that should be snapshotted by
snapper, a configuration file is required, see
<citerefentry><refentrytitle>snapper-configs</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
setup can be done with the create-config command.</para>
</refsect2>
<refsect2 id='snapshots'>
<title>Snapshots</title>
<para>Snapper distinguishes three types of snapshots.</para>
<glosslist>
<glossentry>
<glossterm>pre</glossterm>
<glossdef>
<para>Pre snapshots should always have a corresponding post
snapshot. The intention of pre/post snapshot pairs is to snapshot the
filesystem before and after a modification.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>post</glossterm>
<glossdef>
<para>See pre type.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>single</glossterm>
<glossdef>
<para>These snapshots have no special relationship to other snapshots.</para>
</glossdef>
</glossentry>
</glosslist>
<para>Note that filesystem-wise all three types are the same.</para>
</refsect2>
<refsect2 id='snapshot_description_and_userdata'>
<title>Snapshot Description and Userdata</title>
<para>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.</para>
<para>Do not use non-ASCII characters for the snapshot description, userdata or
any other strings, unless you always use the UTF-8 character encoding.</para>
</refsect2>
<refsect2 id='automatic_snapshot_creation'>
<title>Automatic Snapshot Creation</title>
<para>Next to manual snapshot creation, snapshots are also created automatically.</para>
<itemizedlist>
<listitem>
<para>A cronjob or systemd timer creates hourly snapshots, if TIMELINE_CREATE is enabled for a config.</para>
</listitem>
<listitem>
<para>Certain programs like YaST and zypper create pre/post
snapshot pairs when modifying the system.</para>
</listitem>
</itemizedlist>
</refsect2>
<refsect2 id='cleanup_algorithms'>
<title>Cleanup Algorithms</title>
<para>Snapper provides several algorithms to clean up old snapshots. The
algorithms are executed in an hourly cronjob or systemd timer. This can be configured in the
corresponding configurations files along with parameters for every
algorithm.</para>
<glosslist>
<glossentry>
<glossterm>number</glossterm>
<glossdef>
<para>Deletes old snapshots when a certain number of snapshots is
reached.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>timeline</glossterm>
<glossdef>
<para>Deletes old snapshots but keeps a number of hourly, daily,
weekly, monthly, quarterly and yearly snapshots.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>empty-pre-post</glossterm>
<glossdef>
<para>Deletes pre/post snapshot pairs with empty diffs.</para>
</glossdef>
</glossentry>
</glosslist>
<para>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:</para>
<orderedlist>
<listitem>
<para>Delete snapshots above the max-value independent of
the snapshot and filesystem space.</para>
</listitem>
<listitem>
<para>Delete snapshots above the min-value until the limits for
the snapshot and filesystem are reached.</para>
</listitem>
</orderedlist>
<para>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.</para>
<para>The limit for the free space can be configured via the
FREE_LIMIT variable.</para>
<para>Note: Since the cleanup is performed asynchronous from
creating snapshots the observed snapshots can differ from the
expected snapshots according to the limits. Also btrfs stale
qgroups can exist temporarily.</para>
</refsect2>
<refsect2 id='filters'>
<title>Filters</title>
<para>Some files keep state information of the system,
e.g. <filename>/etc/mtab</filename>. Such files should never be
reverted. To help users, snapper allows one to ignore these files.</para>
<para>Filters are read from the files
<filename>/etc/snapper/filters/*.txt</filename> and
<filename>/usr/share/snapper/filters/*.txt</filename>, where
for files with the same name the former location has precedence.
Each line in those files specifies a pattern. When snapper
computes the difference between two snapshots it ignores all
files and directories matching any of those patterns by using
<citerefentry role="nolink"><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>
with the flag FNM_LEADING_DIR.</para>
<para>Note that filters do not exclude files or directories from being
snapshotted. For that, use subvolumes or mount points.</para>
</refsect2>
</refsect1>
<refsect1 id='global_options'>
<title>GLOBAL OPTIONS</title>
<variablelist>
<varlistentry>
<term><option>-q, --quiet</option></term>
<listitem>
<para>Suppress normal output. Error messages will still be printed, though.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-v, --verbose</option></term>
<listitem>
<para>Increase verbosity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--logger-type <replaceable>type</replaceable></option></term>
<listitem>
<para>Set the logger type. Possible values are none, stdout,
logfile and syslog.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--debug</option></term>
<listitem>
<para>Turn on debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--utc</option></term>
<listitem>
<para>Display dates and times in UTC. By default, local time is used.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--iso</option></term>
<listitem>
<para>Display dates and times in ISO format. ISO format is always used for machine-readable
outputs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t, --table-style <replaceable>style</replaceable></option></term>
<listitem>
<para>Specifies table style. Table style is identified by an integer number.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--abbreviate</option></term>
<listitem>
<para>Try to abbreviate texts in some columns so that tables fit the width of the screen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--machine-readable <replaceable>format</replaceable></option></term>
<listitem>
<para>Specifies a machine-readable output format. Possible options are csv and json.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--csvout</option></term>
<listitem>
<para>Sets CSV output format. See
<link xlink:href="https://tools.ietf.org/html/rfc4180">RFC 4180</link>
for the details, except lines end with a LF, not CR+LF.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--jsonout</option></term>
<listitem>
<para>Sets JSON output format.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--separator <replaceable>character</replaceable></option></term>
<listitem>
<para>Specifies the character separator for CSV output format.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-headers</option></term>
<listitem>
<para>Suppress headers for CSV output format.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c, --config <replaceable>name</replaceable></option></term>
<listitem>
<para>Use specified configuration instead of the default configuration. The default
configuration is named "root".</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-dbus</option></term>
<listitem>
<para>Operate without a DBus connection.</para>
<para>Use with caution since a running snapperd will not know about
modifications made to the system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-r, --root <replaceable>path</replaceable></option></term>
<listitem>
<para>Operate on target root. Only works together with no-dbus and only for some commands.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-a, --ambit <replaceable>ambit</replaceable></option></term>
<listitem>
<para>Operate in the specified ambit. Can be used to override the ambit detection.
Allowed ambits are auto, classic and transactional.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem>
<para>Print version and exit.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id='commands'>
<title>COMMANDS</title>
<para>Snapper provides a number of <emphasis>commands</emphasis>. Each
command accepts the options listed in the <link
linkend='global_options'>GLOBAL OPTIONS</link> section. These options must
be specified <emphasis>before</emphasis> the command name. In addition,
many commands have specific options, which are listed in this
section. These command-specific options must be specified
<emphasis>after</emphasis> the name of the command and
<emphasis>before</emphasis> any of the command arguments.</para>
<variablelist>
<varlistentry>
<term><option>help</option></term>
<listitem>
<para>Show short help text.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list-configs [options]</option></term>
<listitem>
<para>List available configurations.</para>
<variablelist>
<varlistentry>
<term><option>--columns</option> <replaceable>columns</replaceable></term>
<listitem>
<para>Select columns to show separated by comma.</para>
<para>Possible columns are: config, subvolume.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>create-config [options] <replaceable>subvolume</replaceable></option></term>
<listitem>
<para>Create a new configuration for a filesystem or subvolume. For this command you
will likely need the global option <option>--config</option>, see
<link linkend='global_options'>GLOBAL OPTIONS</link> and
<link linkend="concepts">CONCEPTS.</link></para>
<variablelist>
<varlistentry>
<term><option>-f, --fstype</option> <replaceable>fstype</replaceable></term>
<listitem>
<para>Manually set filesystem type. Supported values are btrfs, ext4
(discontinued) 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).</para>
<para>Without this option snapper tries to detect the filesystem.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-t, --template</option> <replaceable>name</replaceable></term>
<listitem>
<para>Name of template for the new configuration file.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete-config</option></term>
<listitem>
<para>Delete a configuration for a filesystem or subvolume
including all snapshots. For this command you will likely need to
global option <option>--config</option>, see <link
linkend='global_options'>GLOBAL OPTIONS</link> and <link
linkend="concepts">CONCEPTS.</link></para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>get-config [options]</option></term>
<listitem>
<para>Displays the settings of the configuration.</para>
<variablelist>
<varlistentry>
<term><option>--columns</option> <replaceable>columns</replaceable></term>
<listitem>
<para>Select columns to show separated by comma.</para>
<para>Possible columns are: key, value.</para>
<para>Columns are not selected when JSON format is used.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set-config</option> <replaceable>configdata</replaceable></term>
<listitem>
<para>Changes the settings of the configuration. The settings
<replaceable>configdata</replaceable> 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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>list (ls) [options]</option></term>
<listitem>
<para>List snapshots.</para>
<variablelist>
<varlistentry>
<term><option>-t, --type</option> <replaceable>type</replaceable></term>
<listitem>
<para>Selects type of snapshots to list. Possible values are
all, single and pre-post.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--disable-used-space</option></term>
<listitem>
<para>Disable display of used space.</para>
<para>Calculating the used space needs some time. Thus
this option can speedup the listing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-a, --all-configs</option></term>
<listitem>
<para>List snapshots from all configs accessible by the user.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--columns</option> <replaceable>columns</replaceable></term>
<listitem>
<para>Select columns to show separated by comma.</para>
<para>Possible columns are: config, subvolume, number, default, active,
date, user, used-space, cleanup, description, userdata, pre-number, post-number,
post-date, read-only.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For each snapshot the output consists of several
columns. Some need explanation:</para>
<glosslist>
<glossentry>
<glossterm>#, Pre # and Post #</glossterm>
<glossdef>
<para>The number of the snapshot.</para>
<para>For btrfs the number can be followed by a sign.
A "<computeroutput>-</computeroutput>" indicates that the snapshot is
the currently mounted snapshot and a
"<computeroutput>+</computeroutput>" indicates that the snapshot will
be mounted next time (It is the btrfs default subvolume). If both
conditions apply a
"<computeroutput>*</computeroutput>" is displayed.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>Used Space</glossterm>
<glossdef>
<para>For btrfs the exclusive space of the btrfs quota
group corresponding to the snapshot.</para>
<para>Display of used space is automatically disabled
if not available, e.g. quota not enabled on btrfs.</para>
</glossdef>
</glossentry>
</glosslist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>create [options]</option></term>
<listitem>
<para>Create a new snapshot.</para>
<variablelist>
<varlistentry>
<term><option>-t, --type</option> <replaceable>type</replaceable></term>
<listitem>
<para>Specifies the type of the new snapshot. Possible values
are single, pre and post.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--pre-number</option> <replaceable>number</replaceable></term>
<listitem>
<para>For post snapshots the number of the pre snapshot must
be provided.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-p, --print-number</option></term>
<listitem>
<para>Print number of the created snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d, --description</option> <replaceable>description</replaceable></term>
<listitem>
<para>Description for the snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c, --cleanup-algorithm</option> <replaceable>cleanup-algorithm</replaceable></term>
<listitem>
<para>Set the cleanup algorithm for the snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-u, --userdata</option> <replaceable>userdata</replaceable></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--command</option> <replaceable>command</replaceable></term>
<listitem>
<para>Create a pre and post snapshot and run command in between. If snapper is
unable to execute the command at all, it does not take the post snapshot. If the
command exits with a non-zero exit code, snapper takes the post snapshot and exits
with that same exit code.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
<listitem>
<para>Create a read-only snapshot. This is the default.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read-write</option></term>
<listitem>
<para>Create a read-write snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--from</option> <replaceable>number</replaceable></term>
<listitem>
<para>Create a snapshot from the snapshot with the
provided number instead of snapshot 0.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--empty</option></term>
<listitem>
<para>Create an empty snapshot. Only supported on
btrfs and with --no-dbus.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>modify [options] <replaceable>number</replaceable></option></term>
<listitem>
<para>Modify a snapshot.</para>
<variablelist>
<varlistentry>
<term><option>-d, --description</option> <replaceable>description</replaceable></term>
<listitem>
<para>New description for snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c, --cleanup-algorithm</option> <replaceable>cleanup-algorithm</replaceable></term>
<listitem>
<para>Set the cleanup algorithm for the snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-u, --userdata</option> <replaceable>userdata</replaceable></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read-only</option></term>
<listitem>
<para>Set the snapshot read-only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--read-write</option></term>
<listitem>
<para>Set the snapshot read-write.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--default</option></term>
<listitem>
<para>Set the snapshot as default snapshot. Only for btrfs.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete (remove|rm) <replaceable>number</replaceable> |
<replaceable>number1-number2</replaceable></option></term>
<listitem>
<para>Delete a snapshot or a range of snapshots.</para>
<variablelist>
<varlistentry>
<term><option>-s, --sync</option></term>
<listitem>
<para>Sync the filesystem after deleting the snapshots. The
details depend on the filesystem type.</para>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>mount <replaceable>number</replaceable></option></term>
<listitem>
<para>Mount a snapshot. Not required for all filesystem types.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>umount <replaceable>number</replaceable></option></term>
<listitem>
<para>Unmount a snapshot. Not required for all filesystem types.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>status [options] <replaceable>number1</replaceable>..<replaceable>number2</replaceable></option></term>
<listitem>
<para>Compare the snapshots <replaceable>number1</replaceable> and
<replaceable>number2</replaceable>. 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.</para>
<variablelist>
<varlistentry>
<term><option>-o, --output</option> <replaceable>file</replaceable></term>
<listitem>
<para>Write output to file <replaceable>file</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The output consists of a string encoding the status followed by
the filename. The characters of the status string are:</para>
<orderedlist>
<listitem>
<para>A "<computeroutput>+</computeroutput>" means the file was
created, a "<computeroutput>-</computeroutput>" means the file was deleted. A
"<computeroutput>c</computeroutput>" means the content of the file has changed
and a "<computeroutput>t</computeroutput>" means the type of the file has
changed (e.g. from regular file to directory).</para>
</listitem>
<listitem>
<para>A "<computeroutput>p</computeroutput>" means the permissions
are have changed.</para>
</listitem>
<listitem>
<para>An "<computeroutput>u</computeroutput>" means the user
ownership has changed.</para>
</listitem>
<listitem>
<para>A "<computeroutput>g</computeroutput>" means the group
ownership has changed.</para>
</listitem>
<listitem>
<para>A "<computeroutput>x</computeroutput>" means the extended
attribute information has changed.</para>
</listitem>
<listitem>
<para>An "<computeroutput>a</computeroutput>" means the ACL
information has changed.</para>
</listitem>
</orderedlist>
<para>If there is no change a "." is outputted.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>diff [options] <replaceable>number1</replaceable>..<replaceable>number2</replaceable> [files]</option></term>
<listitem>
<para>Compare the snapshots <replaceable>number1</replaceable> and
<replaceable>number2</replaceable>. 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.</para>
<variablelist>
<varlistentry>
<term><option>-i, --input</option> <replaceable>file</replaceable></term>
<listitem>
<para>Read files to diff from file <replaceable>file</replaceable>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--diff-cmd</option> <replaceable>command</replaceable></term>
<listitem>
<para>Command used for comparing files. The default is
<filename>/usr/bin/diff --new-file --unified</filename>. The two files to
compare are passed as parameters to the command.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-x, --extensions</option> <replaceable>options</replaceable></term>
<listitem>
<para>Extra options passed to the diff command.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>undochange [options] <replaceable>number1</replaceable>..<replaceable>number2</replaceable> [files]</option></term>
<listitem>
<para>Undo changes done between snapshot <replaceable>number1</replaceable> and <replaceable>number2</replaceable>.</para>
<variablelist>
<varlistentry>
<term><option>-i, --input</option> <replaceable>file</replaceable></term>
<listitem>
<para>Read files for which to undo changes from file <replaceable>file</replaceable>.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>rollback [options] [<replaceable>number</replaceable>]</option></term>
<listitem>
<para>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:</para>
<itemizedlist>
<listitem>
<para>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.</para>
</listitem>
<listitem>
<para>With a number, a first read-only snapshot of the current
system is created. A second read-write snapshot is created of
<replaceable>number</replaceable>. The system is set to boot from the second
snapshot.</para>
</listitem>
</itemizedlist>
<para>Rollback is only supported with btrfs and requires a properly
configured system.</para>
<variablelist>
<varlistentry>
<term><option>-p, --print-number</option></term>
<listitem>
<para>Print number of the second created snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-d, --description</option> <replaceable>description</replaceable></term>
<listitem>
<para>Description for the snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-c, --cleanup-algorithm</option> <replaceable>cleanup-algorithm</replaceable></term>
<listitem>
<para>Set the cleanup algorithm for the snapshot.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-u, --userdata</option> <replaceable>userdata</replaceable></term>
<listitem>
<para>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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>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.</para>
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>setup-quota</option></term>
<listitem>
<para>Sets up quota. Currently only supported with btrfs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>cleanup [options] <replaceable>cleanup-algorithm</replaceable></option></term>
<listitem>
<para>Run the cleanup algorithm
<replaceable>cleanup-algorithm</replaceable>. Currently implemented cleanup algorithms
are number, timeline and empty-pre-post. To run all cleanup algorithms, all can be
provided as cleanup-algorithm.</para>
<variablelist>
<varlistentry>
<term><option>--path</option> <replaceable>path</replaceable></term>
<listitem>
<para>Cleanup all configs affecting path. Only useful for btrfs.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--free-space</option> <replaceable>free-space</replaceable></term>
<listitem>
<para>Try to make free-space available. Only useful for btrfs.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><option>xadiff <replaceable>number1</replaceable>..<replaceable>number2</replaceable> [files]</option></term>
<listitem>
<para>Compare the extended attributes between snapshot
<replaceable>number1</replaceable> and
<replaceable>number2</replaceable>. See examples below:</para>
<itemizedlist>
<listitem>
<para><computeroutput> +:user.foo</computeroutput> for created attributes</para>
</listitem>
<listitem>
<para><computeroutput> -:user.bar</computeroutput> for removed attributes</para>
</listitem>
<listitem>
<para><computeroutput>-+:security.selinux</computeroutput> for modified attributes</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id='permissions'>
<title>PERMISSIONS</title>
<para>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 <filename>.snapshots</filename>
directory inside the subvolume. The <filename>.snapshots</filename> directory
must be owned by root and must not be writable by anybody else.</para>
<para>Here are some methods how to achieve that:</para>
<itemizedlist>
<listitem>
<para>Make the directory accessible for everyone:</para>
<para><command>chmod a+rx .snapshots</command></para>
</listitem>
<listitem>
<para>Make the directory accessible for a group the user belongs to, e.g.:</para>
<para><command>chown :users .snapshots</command></para>
</listitem>
<listitem>
<para>Make the directory accessible for the user using ACLs, e.g.:</para>
<para><command>setfacl -m u:tux:rx .snapshots</command></para>
</listitem>
</itemizedlist>
<para>The last method can be performed by snapper, see the SYNC_ACL setting in
<citerefentry><refentrytitle>snapper-configs</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1 id='plugins'>
<title>PLUGINS</title>
<para>snapper can execute external scripts after certain actions. Scripts
have to be placed in <filename>/usr/lib/snapper/plugins</filename>.
The name has to start with a digit, execution order is alphabetical.</para>
<para>The first argument of a script is the action snapper executed. The
following actions are defined:</para>
<variablelist>
<varlistentry>
<term><option>create-config-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable></option></term>
<listitem>
<para>Executed before a new config is created</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>create-config-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable></option></term>
<listitem>
<para>Executed after a new config was created</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete-config-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable></option></term>
<listitem>
<para>Executed before a config is deleted</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete-config-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable></option></term>
<listitem>
<para>Executed after a config was deleted</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>create-snapshot-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed before a new snapshot is created</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>create-snapshot-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after a new snapshot was created</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>modify-snapshot-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed before a snapshot is modified</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>modify-snapshot-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after a snapshot was modified</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete-snapshot-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed before a snapshot is removed</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>delete-snapshot-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after a snapshot was removed</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set-read-only-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed before a snapshot is set read-only or read-write</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set-read-only-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after a snapshot is set read-only or read-write</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set-default-snapshot-pre <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed before the default snapshot is changed</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>set-default-snapshot-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after the default snapshot was changed</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>rollback-post <replaceable>subvolume</replaceable> <replaceable>fstype</replaceable> <replaceable>old-snapshot-number</replaceable> <replaceable>new-snapshot-number</replaceable></option></term>
<listitem>
<para>Executed after a rollback was done</para>
</listitem>
</varlistentry>
</variablelist>
<para>More actions and arguments can be added any time. Using snapper in
the plugins is not allowed.</para>
<para>It is undefined whether the plugins are called from the
client (snapper) or server (snapperd).</para>
</refsect1>
<refsect1 id='files'>
<title>FILES</title>
<variablelist>
<varlistentry>
<term><filename>@SYSCONFIG@/snapper</filename></term>
<listitem>
<para>Global configuration file.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/snapper/configs</filename></term>
<listitem>
<para>Directory containing configuration files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/snapper/config-templates</filename></term>
<listitem>
<para>Directory containing configuration templates.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/usr/share/snapper/config-templates</filename></term>
<listitem>
<para>Fallback directory containing configuration templates.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/etc/snapper/filters/*.txt</filename></term>
<listitem>
<para>Filter files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/usr/share/snapper/filters/*.txt</filename></term>
<listitem>
<para>Fallback filter files.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/var/log/snapper.log</filename></term>
<listitem>
<para>Logfile. Please include this file in bug reports.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id='exit_status'>
<title>EXIT STATUS</title>
<para>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.</para>
</refsect1>
<refsect1 id='notes'>
<title>NOTES</title>
<para>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.</para>
<para>Consistency after undochange is not guaranteed. E.g. when the
creation of a user is undone, there might still exist files from that
user.</para>
<para>Support for individual filesystems, rollback and extended attributes
are compile-time options and may not be available.</para>
</refsect1>
<refsect1 id='homepage'>
<title>HOMEPAGE</title>
<para><ulink url='http://snapper.io/'>http://snapper.io/</ulink></para>
</refsect1>
<refsect1 id='authors'>
<title>AUTHORS</title>
<para>Arvin Schnell <email>aschnell@suse.com</email></para>
</refsect1>
<refsect1 id='see_also'>
<title>SEE ALSO</title>
<para>
<citerefentry><refentrytitle>snapper-configs</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>snapper-zypp-plugin</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>snbk</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>pam_snapper</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry role="nolink"><refentrytitle>btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry role="nolink"><refentrytitle>lvm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry role="nolink"><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry role="nolink"><refentrytitle>acl</refentrytitle><manvolnum>5</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
View Git Blame Copy Permalink