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. Btrfs and
20       thin-provisioned LVM logical volumes are supported. Some filesystems
21       might not be supported depending on your installation.
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. By default, local time is used.
121
122       --iso
123           Display dates and times in ISO format. ISO format is always used
124           for machine-readable outputs.
125
126       -t, --table-style style
127           Specifies table style. Table style is identified by an integer
128           number.
129
130       --abbreviate
131           Try to abbreviate texts in some columns so that tables fit the
132           width of the screen.
133
134       --machine-readable format
135           Specifies a machine-readable output format. Possible options are
136           csv and json.
137
138       --csvout
139           Sets CSV output format. See RFC 4180[1] for the details, except
140           lines end with a LF, not CR+LF.
141
142       --jsonout
143           Sets JSON output format.
144
145       --separator character
146           Specifies the character separator for CSV output format.
147
148       -c, --config name
149           Use specified configuration instead of the default configuration.
150           The default configuration is named "root".
151
152       --no-dbus
153           Operate without a DBus connection.
154
155           Use with caution since a running snapperd will not know about
156           modifications made to the system.
157
158       -r, --root path
159           Operate on target root. Only works together with no-dbus and only
160           for some commands.
161
162       -a, --ambit ambit
163           Operate in the specified ambit. Can be used to override the ambit
164           detection. Allowed ambits are auto, classic and transactional.
165
166       --version
167           Print version and exit.
168

COMMANDS

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

PERMISSIONS

458       Non-root users can be allowed to use a configuration by setting
459       ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
460       work, the user must also be able to read and access the .snapshots
461       directory inside the subvolume. The .snapshots directory must be owned
462       by root and must not be writable by anybody else.
463
464       Here are some methods how to achieve that:
465
466       •   Make the directory accessible for everyone:
467
468           chmod a+rx .snapshots
469
470       •   Make the directory accessible for a group the user belongs to,
471           e.g.:
472
473           chown :users .snapshots
474
475       •   Make the directory accessible for the user using ACLs, e.g.:
476
477           setfacl -m u:tux:rx .snapshots
478
479       The last method can be performed by snapper, see the SYNC_ACL setting
480       in snapper-configs(5).
481

FILES

483       /etc/sysconfig/snapper
484           Global configuration file.
485
486       /etc/snapper/configs
487           Directory containing configuration files.
488
489       /etc/snapper/config-templates
490           Directory containing configuration templates.
491
492       /etc/snapper/filters/*.txt
493           Filter files.
494
495       /var/log/snapper.log
496           Logfile. Please include this file in bug reports.
497

NOTES

499       There is no mechanism to ensure consistency of the files while a
500       snapshot it made. E.g. the files of a database can be inconsistent
501       while the database is running.
502
503       Consistency after undochange is not guaranteed. E.g. when the creation
504       of a user is undone, there might still exist files from that user.
505
506       Support for individual filesystems, rollback and extended attributes
507       are compile-time options and may not be available.
508

HOMEPAGE

510       http://snapper.io/
511

AUTHORS

513       Arvin Schnell <aschnell@suse.com>
514

SEE ALSO

516       snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
517       lvm(8), attr(5), acl(5)
518

NOTES

520        1. RFC 4180
521           https://tools.ietf.org/html/rfc4180
522
523
524
5250.8.16                            2020-06-15                        SNAPPER(8)
Impressum