1SNAPPER(8)              Filesystem Snapshot Management              SNAPPER(8)
2
3
4

NAME

6       snapper - Command-line program for filesystem snapshot management
7

SYNOPSIS

9       snapper [--global-opts] command [--command-opts] [command-arguments]
10
11       snapper {--help}
12

DESCRIPTION

14       Snapper is a command-line program for filesystem snapshot management.
15       It can create, delete and compare snapshots and undo changes done
16       between snapshots.
17
18       Snapper never modifies the content of snapshots. Thus snapper creates
19       read-only snapshots if supported by the kernel. Supported filesystems
20       are btrfs as well as snapshots of LVM logical volumes with
21       thin-provisioning.
22

CONCEPTS

24   Configurations
25       For each filesystem or subvolume that should be snapshotted by snapper,
26       a configuration file is required, see snapper-configs(5). The setup can
27       be done with the create-config command.
28
29   Snapshots
30       Snapper distinguishes three types of snapshots.
31
32       pre
33           Pre snapshots should always have a corresponding post snapshot. The
34           intention of pre/post snapshot pairs is to snapshot the filesystem
35           before and after a modification.
36
37       post
38           See pre type.
39
40       single
41           These snapshots have no special relationship to other snapshots.
42
43       Note that filesystem-wise all three types are the same.
44
45   Snapshot Description and Userdata
46       With each snapshot a description and some userdata can be associated.
47       The description is a string. The userdata is a list of key-value pairs
48       where the keys and values are strings.
49
50       Do not use non-ASCII characters for the snapshot description, userdata
51       or any other strings, unless you always use the UTF-8 character
52       encoding.
53
54   Automatic Snapshot Creation
55       Next to manual snapshot creation, snapshots are also created
56       automatically.
57
58       ·   A cron-job creates hourly snapshots.
59
60       ·   Certain programs like YaST and zypper create pre/post snapshot
61           pairs when modifying the system.
62
63   Cleanup Algorithms
64       Snapper provides several algorithms to clean up old snapshots. The
65       algorithms are executed in a daily cron-job. This can be configured in
66       the corresponding configurations files along with parameters for every
67       algorithm.
68
69       number
70           Deletes old snapshots when a certain number of snapshots is
71           reached.
72
73       timeline
74           Deletes old snapshots but keeps a number of hourly, daily, weekly,
75           monthly and yearly snapshots.
76
77       empty-pre-post
78           Deletes pre/post snapshot pairs with empty diffs.
79
80       The number and timeline cleanup algorithms can also try to keep the
81       space used by snapshots below a limit and the free space of the
82       filesystem above a limit. For the first condition quota must be setup,
83       see command setup-quota. Additional the NUMBER_LIMIT and TIMELINE_LIMIT
84       variables in the config file must have ranges (min- and max-value). The
85       algorithms will then make two passes:
86
87        1. Delete snapshots above the max-value independent of the snapshot
88           and filesystem space.
89
90        2. Delete snapshots above the min-value until the limits for the
91           snapshot and filesystem are reached.
92
93       The limit for the used space can be configured via the SPACE_LIMIT
94       variable. Note: Only snapshots that have a cleanup algorithm set are
95       taken into account when calculating the space used by snapshots. The
96       limit for the free space can be configured via the FREE_LIMIT variable.
97
98   Filters
99       Some files keep state information of the system, e.g.  /etc/mtab. Such
100       files should never be reverted. To help users, snapper allows one to
101       ignore these files.
102
103       Each line in all files /etc/snapper/filters/*.txt specifies a pattern.
104       When snapper computes the difference between two snapshots it ignores
105       all files and directories matching any of those patterns by using
106       fnmatch(3) with the flag FNM_LEADING_DIR.
107
108       Note that filters do not exclude files or directories from being
109       snapshotted. For that, use subvolumes or mount points.
110

GLOBAL OPTIONS

112       -q, --quiet
113           Suppress normal output. Error messages will still be printed,
114           though.
115
116       -v, --verbose
117           Increase verbosity.
118
119       --utc
120           Display dates and times in UTC.
121
122       --iso
123           Display dates and times in ISO format.
124
125       -t, --table-style
126           Specifies table style. Table style is identified by an integer
127           number.
128
129       -c, --config name
130           Use specified configuration instead of the default configuration.
131           The default configuration is named "root".
132
133       --no-dbus
134           Operate without a DBus connection.
135
136           Use with caution since a running snapperd will not know about
137           modifications made to the system.
138
139       -r, --root path
140           Operate on target root. Only works together with no-dbus and only
141           for some commands.
142
143       --version
144           Print version and exit.
145

COMMANDS

147       Snapper provides a number of commands. Each command accepts the options
148       listed in the GLOBAL OPTIONS section. These options must be specified
149       before the command name. In addition, many commands have specific
150       options, which are listed in this section. These command-specific
151       options must be specified after the name of the command and before any
152       of the command arguments.
153
154       help
155           Show short help text.
156
157       list-configs
158           List available configurations.
159
160       create-config [options] subvolume
161           Create a new configuration for a filesystem or subvolume. For this
162           command you will likely need the global option --config, see GLOBAL
163           OPTIONS and CONCEPTS.
164
165           -f, --fstype fstype
166               Manually set filesystem type. Supported values are btrfs and
167               lvm. For lvm, snapper uses LVM thin-provisioned snapshots. The
168               filesystem type on top of LVM must be provided in parentheses,
169               e.g. lvm(xfs).
170
171               Without this option snapper tries to detect the filesystem.
172
173           -t, --template name
174               Name of template for the new configuration file.
175
176       delete-config
177           Delete a configuration for a filesystem or subvolume. For this
178           command you will likely need to global option --config, see GLOBAL
179           OPTIONS and CONCEPTS.
180
181       get-config
182           Displays the settings of the configuration.
183
184       set-config configdata
185           Changes the settings of the configuration. The settings configdata
186           are a list of key-value-pairs separated by spaces and the key and
187           value must be separated by an equal sign, e.g. "NUMBER_CLEANUP=yes
188           NUMBER_LIMIT=10". The value of SUBVOLUME and FSTYPE cannot be
189           changed.
190
191       list (ls) [options]
192           List snapshots.
193
194           -t, --type type
195               Selects type of snapshots to list. Possible values are all,
196               single and pre-post.
197
198           --disable-used-space
199               Disable display of used space.
200
201               Calculating the used space needs some time. Thus this option
202               can speedup the listing.
203
204           -a, --all-configs
205               List snapshots from all configs accessible by the user.
206
207           For each snapshot the output consists of several columns. Some need
208           explanation:
209
210           #, Pre # and Post #
211               The number of the snapshot.
212
213               For btrfs the number can be followed by a sign. A "-" indicates
214               that the snapshot is the currently mounted snapshot and a "+"
215               indicates that the snapshot will be mounted next time (It is
216               the btrfs default subvolume). If both conditions apply a "*" is
217               displayed.
218
219           Used Space
220               For btrfs the exclusive space of the btrfs quota group
221               corresponding to the snapshot.
222
223               Display of used space is automatically disabled if not
224               available, e.g. quota not enabled on btrfs.
225
226       create [options]
227           Create a new snapshot.
228
229           -t, --type type
230               Specifies the type of the new snapshot. Possible values are
231               single, pre and post.
232
233           --pre-number number
234               For post snapshots the number of the pre snapshot must be
235               provided.
236
237           -p, --print-number
238               Print number of the created snapshot.
239
240           -d, --description description
241               Description for the snapshot.
242
243           -c, --cleanup-algorithm cleanup-algorithm
244               Set the cleanup algorithm for the snapshot.
245
246           -u, --userdata userdata
247               Set userdata for the snapshot. The key-value pairs must be
248               separated by comma and the key and value must be separated by
249               an equal sign, e.g. requestid=42,user=arthur.
250
251           --command command
252               Create a pre and post snapshot and run command in between.
253
254       modify [options] number
255           Modify a snapshot.
256
257           -d, --description description
258               New description for snapshot.
259
260           -c, --cleanup-algorithm cleanup-algorithm
261               Set the cleanup algorithm for the snapshot.
262
263           -u, --userdata userdata
264               Set userdata for the snapshot. The key-value pairs must be
265               separated by comma and the key and value must be separated by
266               an equal sign, e.g. requestid=42,user=arthur.
267
268       delete (remove|rm) number | number1-number2
269           Delete a snapshot or a range of snapshots.
270
271           -s, --sync
272               Sync the filesystem after deleting the snapshots. The details
273               depend on the filesystem type.
274
275               Btrfs normally asynchronously frees space after deleting
276               snapshots. With this option snapper will wait until the space
277               once used by the deleted snapshots is actually available again.
278
279           Snapshot 0 cannot be deleted. For btrfs the currently mounted
280           snapshot and the snapshot that will be mounted next time (the btrfs
281           default subvolume) can also not be deleted.
282
283       mount number
284           Mount a snapshot. Not required for all filesystem types.
285
286       umount number
287           Unmount a snapshot. Not required for all filesystem types.
288
289       status [options] number1..number2
290           Compare the snapshots number1 and number2. This will show a list of
291           files and directories that have been created, modified or deleted
292           in the time between the two snapshots have been made.
293
294           -o, --output file
295               Write output to file file.
296
297           The output consists of a string encoding the status followed by the
298           filename. The characters of the status string are:
299
300            1. A "+" means the file was created, a "-" means the file was
301               deleted. A "c" means the content of the file has changed and a
302               "t" means the type of the file has changed (e.g. from regular
303               file to directory).
304
305            2. A "p" means the permissions are have changed.
306
307            3. An "u" means the user ownership has changed.
308
309            4. A "g" means the group ownership has changed.
310
311            5. A "x" means the extended attribute information has changed.
312
313            6. An "a" means the ACL information has changed.
314
315           If there is no change a "." is outputted.
316
317       diff [options] number1..number2 [files]
318           Compare the snapshots number1 and number2. This will show a diff of
319           the content of files and directories that have been created,
320           modified or deleted in the time between the two snapshots have been
321           made.
322
323           -i, --input file
324               Read files to diff from file file.
325
326           --diff-cmd command
327               Command used for comparing files. The default is /usr/bin/diff
328               --new-file --unified. The two files to compare are passed as
329               parameters to the command.
330
331           -x, --extensions options
332               Extra options passed to the diff command.
333
334       undochange [options] number1..number2 [files]
335           Undo changes done between snapshot number1 and number2.
336
337           -i, --input file
338               Read files for which to undo changes from file file.
339
340       rollback [options] [number]
341           Creates two new snapshots and sets the default subvolume. Per
342           default the system boots from the default subvolume of the root
343           filesystem. The exact actions depend on whether a number is
344           provided or not:
345
346           ·   Without a number, a first read-only snapshot of the default
347               subvolume is created. A second read-write snapshot of the
348               current system is created. The system is set to boot from the
349               second snapshot.
350
351           ·   With a number, a first read-only snapshot of the current system
352               is created. A second read-write snapshot is created of number.
353               The system is set to boot from the second snapshot.
354
355           Rollback is only supported with btrfs and requires a properly
356           configured system.
357
358           -p, --print-number
359               Print number of the second created snapshot.
360
361           -d, --description description
362               Description for the snapshot.
363
364           -c, --cleanup-algorithm cleanup-algorithm
365               Set the cleanup algorithm for the snapshot.
366
367           -u, --userdata userdata
368               Set userdata for the snapshot. The key-value pairs must be
369               separated by comma and the key and value must be separated by
370               an equal sign, e.g. requestid=42,user=arthur.
371
372           The rollback command also sets the description, the cleanup
373           algorithm and some userdata unless the values are specified on the
374           command line. This will automate cleanup of snapshots created by
375           rollbacks.
376
377       setup-quota
378           Sets up quota. Currently only supported with btrfs.
379
380       cleanup cleanup-algorithm
381           Run the cleanup algorithm cleanup-algorithm. Currently implemented
382           cleanup algorithms are number, timeline and empty-pre-post.
383
384       xadiff number1..number2 [files]
385           Compare the extended attributes between snapshot number1 and
386           number2. See examples below:
387
388           ·   +:user.foo for created attributes
389
390           ·   -:user.bar for removed attributes
391
392           ·   -+:security.selinux for modified attributes
393

PERMISSIONS

395       Non-root users can be allowed to use a configuration by setting
396       ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
397       work, the user must also be able to read and access the .snapshots
398       directory inside the subvolume. The .snapshots directory must be owned
399       by root and must not be writable by anybody else.
400
401       Here are some methods how to achieve that:
402
403       ·   Make the directory accessible for everyone:
404
405           chmod a+rx .snapshots
406
407       ·   Make the directory accessible for a group the user belongs to,
408           e.g.:
409
410           chown :users .snapshots
411
412       ·   Make the directory accessible for the user using ACLs, e.g.:
413
414           setfacl -m u:tux:rx .snapshots
415
416       The last method can be performed by snapper, see the SYNC_ACL setting
417       in snapper-configs(5).
418

FILES

420       /etc/sysconfig/snapper
421           Global configuration file.
422
423       /etc/snapper/configs
424           Directory containing configuration files.
425
426       /etc/snapper/config-templates
427           Directory containing configuration templates.
428
429       /etc/snapper/filters/*.txt
430           Filter files.
431
432       /var/log/snapper.log
433           Logfile. Please include this file in bug reports.
434

NOTES

436       There is no mechanism to ensure consistency of the files while a
437       snapshot it made. E.g. the files of a database can be inconsistent
438       while the database is running.
439
440       Consistency after undochange is not guaranteed. E.g. when the creation
441       of a user is undone, there might still exist files from that user.
442
443       Support for individual filesystems, rollback and extended attributes
444       are compile-time options and may not be available.
445

HOMEPAGE

447       http://snapper.io/
448

AUTHORS

450       Arvin Schnell <aschnell@suse.com>
451

SEE ALSO

453       snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
454       lvm(8), attr(5), acl(5)
455
456
457
4580.8.3                             2018-10-29                        SNAPPER(8)
Impressum