1SNAPPER(8) Filesystem Snapshot Management SNAPPER(8)
2
6 snapper - Command-line program for filesystem snapshot management
7
9 snapper [--global-opts] command [--command-opts] [command-arguments]
10 snapper {--help}
12
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 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
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 Snapshots
30 Snapper distinguishes three types of snapshots.
31 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 post
38 See pre type.
39 single
41 These snapshots have no special relationship to other snapshots.
42 Note that filesystem-wise all three types are the same.
44 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 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 Automatic Snapshot Creation
55 Next to manual snapshot creation, snapshots are also created
56 automatically.
57 • A cron-job creates hourly snapshots.
59 • Certain programs like YaST and zypper create pre/post snapshot
61 pairs when modifying the system.
62 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 number
70 Deletes old snapshots when a certain number of snapshots is
71 reached.
72 timeline
74 Deletes old snapshots but keeps a number of hourly, daily, weekly,
75 monthly and yearly snapshots.
76 empty-pre-post
78 Deletes pre/post snapshot pairs with empty diffs.
79 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 1. Delete snapshots above the max-value independent of the snapshot
88 and filesystem space.
89 2. Delete snapshots above the min-value until the limits for the
91 snapshot and filesystem are reached.
92 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 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 Filters are read from the files /etc/snapper/filters/*.txt and
104 /usr/share/snapper/filters/*.txt, where for files with the same name
105 the former location has precedence. Each line in those files specifies
106 a pattern. When snapper computes the difference between two snapshots
107 it ignores all files and directories matching any of those patterns by
108 using fnmatch(3) with the flag FNM_LEADING_DIR.
109 Note that filters do not exclude files or directories from being
111 snapshotted. For that, use subvolumes or mount points.
112
114 -q, --quiet
115 Suppress normal output. Error messages will still be printed,
116 though.
117 -v, --verbose
119 Increase verbosity.
120 --utc
122 Display dates and times in UTC. By default, local time is used.
123 --iso
125 Display dates and times in ISO format. ISO format is always used
126 for machine-readable outputs.
127 -t, --table-style style
129 Specifies table style. Table style is identified by an integer
130 number.
131 --abbreviate
133 Try to abbreviate texts in some columns so that tables fit the
134 width of the screen.
135 --machine-readable format
137 Specifies a machine-readable output format. Possible options are
138 csv and json.
139 --csvout
141 Sets CSV output format. See RFC 4180[1] for the details, except
142 lines end with a LF, not CR+LF.
143 --jsonout
145 Sets JSON output format.
146 --separator character
148 Specifies the character separator for CSV output format.
149 -c, --config name
151 Use specified configuration instead of the default configuration.
152 The default configuration is named "root".
153 --no-dbus
155 Operate without a DBus connection.
156 Use with caution since a running snapperd will not know about
158 modifications made to the system.
159 -r, --root path
161 Operate on target root. Only works together with no-dbus and only
162 for some commands.
163 -a, --ambit ambit
165 Operate in the specified ambit. Can be used to override the ambit
166 detection. Allowed ambits are auto, classic and transactional.
167 --version
169 Print version and exit.
170
172 Snapper provides a number of commands. Each command accepts the options
173 listed in the GLOBAL OPTIONS section. These options must be specified
174 before the command name. In addition, many commands have specific
175 options, which are listed in this section. These command-specific
176 options must be specified after the name of the command and before any
177 of the command arguments.
178 help
180 Show short help text.
181 list-configs [options]
183 List available configurations.
184 --columns columns
186 Select columns to show separated by comma.
187 Possible columns are: config, subvolume.
189 create-config [options] subvolume
191 Create a new configuration for a filesystem or subvolume. For this
192 command you will likely need the global option --config, see GLOBAL
193 OPTIONS and CONCEPTS.
194 -f, --fstype fstype
196 Manually set filesystem type. Supported values are btrfs and
197 lvm. For lvm, snapper uses LVM thin-provisioned snapshots. The
198 filesystem type on top of LVM must be provided in parentheses,
199 e.g. lvm(xfs).
200 Without this option snapper tries to detect the filesystem.
202 -t, --template name
204 Name of template for the new configuration file.
205 delete-config
207 Delete a configuration for a filesystem or subvolume. For this
208 command you will likely need to global option --config, see GLOBAL
209 OPTIONS and CONCEPTS.
210 get-config [options]
212 Displays the settings of the configuration.
213 --columns columns
215 Select columns to show separated by comma.
216 Possible columns are: key, value.
218 Columns are not selected when JSON format is used.
220 set-config configdata
222 Changes the settings of the configuration. The settings configdata
223 are a list of key-value-pairs separated by spaces and the key and
224 value must be separated by an equal sign, e.g. "NUMBER_CLEANUP=yes
225 NUMBER_LIMIT=10". The value of SUBVOLUME and FSTYPE cannot be
226 changed.
227 list (ls) [options]
229 List snapshots.
230 -t, --type type
232 Selects type of snapshots to list. Possible values are all,
233 single and pre-post.
234 --disable-used-space
236 Disable display of used space.
237 Calculating the used space needs some time. Thus this option
239 can speedup the listing.
240 -a, --all-configs
242 List snapshots from all configs accessible by the user.
243 --columns columns
245 Select columns to show separated by comma.
246 Possible columns are: config, subvolume, number, default,
248 active, date, user, used-space, cleanup, description, userdata,
249 pre-number, post-number, post-date.
250 For each snapshot the output consists of several columns. Some need
252 explanation:
253 #, Pre # and Post #
255 The number of the snapshot.
256 For btrfs the number can be followed by a sign. A "-" indicates
258 that the snapshot is the currently mounted snapshot and a "+"
259 indicates that the snapshot will be mounted next time (It is
260 the btrfs default subvolume). If both conditions apply a "*" is
261 displayed.
262 Used Space
264 For btrfs the exclusive space of the btrfs quota group
265 corresponding to the snapshot.
266 Display of used space is automatically disabled if not
268 available, e.g. quota not enabled on btrfs.
269 create [options]
271 Create a new snapshot.
272 -t, --type type
274 Specifies the type of the new snapshot. Possible values are
275 single, pre and post.
276 --pre-number number
278 For post snapshots the number of the pre snapshot must be
279 provided.
280 -p, --print-number
282 Print number of the created snapshot.
283 -d, --description description
285 Description for the snapshot.
286 -c, --cleanup-algorithm cleanup-algorithm
288 Set the cleanup algorithm for the snapshot.
289 -u, --userdata userdata
291 Set userdata for the snapshot. The key-value pairs must be
292 separated by comma and the key and value must be separated by
293 an equal sign, e.g. requestid=42,user=arthur.
294 --command command
296 Create a pre and post snapshot and run command in between.
297 --read-only
299 Create a read-only snapshot. This is the default.
300 --read-write
302 Create a read-write snapshot.
303 --from number
305 Create a snapshot from the snapshot with the provided number
306 instead of snapshot 0.
307 modify [options] number
309 Modify a snapshot.
310 -d, --description description
312 New description for snapshot.
313 -c, --cleanup-algorithm cleanup-algorithm
315 Set the cleanup algorithm for the snapshot.
316 -u, --userdata userdata
318 Set userdata for the snapshot. The key-value pairs must be
319 separated by comma and the key and value must be separated by
320 an equal sign, e.g. requestid=42,user=arthur.
321 delete (remove|rm) number | number1-number2
323 Delete a snapshot or a range of snapshots.
324 -s, --sync
326 Sync the filesystem after deleting the snapshots. The details
327 depend on the filesystem type.
328 Btrfs normally asynchronously frees space after deleting
330 snapshots. With this option snapper will wait until the space
331 once used by the deleted snapshots is actually available again.
332 Snapshot 0 cannot be deleted. For btrfs the currently mounted
334 snapshot and the snapshot that will be mounted next time (the btrfs
335 default subvolume) can also not be deleted.
336 mount number
338 Mount a snapshot. Not required for all filesystem types.
339 umount number
341 Unmount a snapshot. Not required for all filesystem types.
342 status [options] number1..number2
344 Compare the snapshots number1 and number2. This will show a list of
345 files and directories that have been created, modified or deleted
346 in the time between the two snapshots have been made.
347 -o, --output file
349 Write output to file file.
350 The output consists of a string encoding the status followed by the
352 filename. The characters of the status string are:
353 1. A "+" means the file was created, a "-" means the file was
355 deleted. A "c" means the content of the file has changed and a
356 "t" means the type of the file has changed (e.g. from regular
357 file to directory).
358 2. A "p" means the permissions are have changed.
360 3. An "u" means the user ownership has changed.
362 4. A "g" means the group ownership has changed.
364 5. A "x" means the extended attribute information has changed.
366 6. An "a" means the ACL information has changed.
368 If there is no change a "." is outputted.
370 diff [options] number1..number2 [files]
372 Compare the snapshots number1 and number2. This will show a diff of
373 the content of files and directories that have been created,
374 modified or deleted in the time between the two snapshots have been
375 made.
376 -i, --input file
378 Read files to diff from file file.
379 --diff-cmd command
381 Command used for comparing files. The default is /usr/bin/diff
382 --new-file --unified. The two files to compare are passed as
383 parameters to the command.
384 -x, --extensions options
386 Extra options passed to the diff command.
387 undochange [options] number1..number2 [files]
389 Undo changes done between snapshot number1 and number2.
390 -i, --input file
392 Read files for which to undo changes from file file.
393 rollback [options] [number]
395 Creates two new snapshots and sets the default subvolume. Per
396 default the system boots from the default subvolume of the root
397 filesystem. The exact actions depend on whether a number is
398 provided or not:
399 • Without a number, a first read-only snapshot of the default
401 subvolume is created. A second read-write snapshot of the
402 current system is created. The system is set to boot from the
403 second snapshot.
404 • With a number, a first read-only snapshot of the current system
406 is created. A second read-write snapshot is created of number.
407 The system is set to boot from the second snapshot.
408 Rollback is only supported with btrfs and requires a properly
410 configured system.
411 -p, --print-number
413 Print number of the second created snapshot.
414 -d, --description description
416 Description for the snapshot.
417 -c, --cleanup-algorithm cleanup-algorithm
419 Set the cleanup algorithm for the snapshot.
420 -u, --userdata userdata
422 Set userdata for the snapshot. The key-value pairs must be
423 separated by comma and the key and value must be separated by
424 an equal sign, e.g. requestid=42,user=arthur.
425 The rollback command also sets the description, the cleanup
427 algorithm and some userdata unless the values are specified on the
428 command line. This will automate cleanup of snapshots created by
429 rollbacks.
430 In other ambits than classic the rollback command does what is
432 required to do a rollback. Anyway it is recommended to use specific
433 programs in that case.
434 setup-quota
436 Sets up quota. Currently only supported with btrfs.
437 cleanup [options] cleanup-algorithm
439 Run the cleanup algorithm cleanup-algorithm. Currently implemented
440 cleanup algorithms are number, timeline and empty-pre-post. To run
441 all cleanup algorithms, all can be provided as cleanup-algorithm.
442 --path path
444 Cleanup all configs affecting path. Only useful for btrfs.
445 --free-space free-space
447 Try to make free-space available. Only useful for btrfs.
448 xadiff number1..number2 [files]
450 Compare the extended attributes between snapshot number1 and
451 number2. See examples below:
452 • +:user.foo for created attributes
454 • -:user.bar for removed attributes
456 • -+:security.selinux for modified attributes
458
460 Non-root users can be allowed to use a configuration by setting
461 ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
462 work, the user must also be able to read and access the .snapshots
463 directory inside the subvolume. The .snapshots directory must be owned
464 by root and must not be writable by anybody else.
465 Here are some methods how to achieve that:
467 • Make the directory accessible for everyone:
469 chmod a+rx .snapshots
471 • Make the directory accessible for a group the user belongs to,
473 e.g.:
474 chown :users .snapshots
476 • Make the directory accessible for the user using ACLs, e.g.:
478 setfacl -m u:tux:rx .snapshots
480 The last method can be performed by snapper, see the SYNC_ACL setting
482 in snapper-configs(5).
483
485 /etc/sysconfig/snapper
486 Global configuration file.
487 /etc/snapper/configs
489 Directory containing configuration files.
490 /etc/snapper/config-templates
492 Directory containing configuration templates.
493 /usr/share/snapper/config-templates
495 Fallback directory containing configuration templates.
496 /etc/snapper/filters/*.txt
498 Filter files.
499 /usr/share/snapper/filters/*.txt
501 Fallback filter files.
502 /var/log/snapper.log
504 Logfile. Please include this file in bug reports.
505
507 There is no mechanism to ensure consistency of the files while a
508 snapshot it made. E.g. the files of a database can be inconsistent
509 while the database is running.
510 Consistency after undochange is not guaranteed. E.g. when the creation
512 of a user is undone, there might still exist files from that user.
513 Support for individual filesystems, rollback and extended attributes
515 are compile-time options and may not be available.
516
518 http://snapper.io/
519
521 Arvin Schnell <aschnell@suse.com>
522
524 snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
525 lvm(8), attr(5), acl(5)
526
528 1. RFC 4180
529 https://tools.ietf.org/html/rfc4180
5300.10.1 2021-09-21 SNAPPER(8)