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 cronjob or systemd timer creates hourly snapshots, if
59 TIMELINE_CREATE is enabled for a config.
60 • Certain programs like YaST and zypper create pre/post snapshot
62 pairs when modifying the system.
63 Cleanup Algorithms
65 Snapper provides several algorithms to clean up old snapshots. The
66 algorithms are executed in a daily cronjob or systemd timer. This can
67 be configured in the corresponding configurations files along with
68 parameters for every algorithm.
69 number
71 Deletes old snapshots when a certain number of snapshots is
72 reached.
73 timeline
75 Deletes old snapshots but keeps a number of hourly, daily, weekly,
76 monthly and yearly snapshots.
77 empty-pre-post
79 Deletes pre/post snapshot pairs with empty diffs.
80 The number and timeline cleanup algorithms can also try to keep the
82 space used by snapshots below a limit and the free space of the
83 filesystem above a limit. For the first condition quota must be setup,
84 see command setup-quota. Additional the NUMBER_LIMIT and TIMELINE_LIMIT
85 variables in the config file must have ranges (min- and max-value). The
86 algorithms will then make two passes:
87 1. Delete snapshots above the max-value independent of the snapshot
89 and filesystem space.
90 2. Delete snapshots above the min-value until the limits for the
92 snapshot and filesystem are reached.
93 The limit for the used space can be configured via the SPACE_LIMIT
95 variable. Note: Only snapshots that have a cleanup algorithm set are
96 taken into account when calculating the space used by snapshots. The
97 limit for the free space can be configured via the FREE_LIMIT variable.
98 Filters
100 Some files keep state information of the system, e.g. /etc/mtab. Such
101 files should never be reverted. To help users, snapper allows one to
102 ignore these files.
103 Filters are read from the files /etc/snapper/filters/*.txt and
105 /usr/share/snapper/filters/*.txt, where for files with the same name
106 the former location has precedence. Each line in those files specifies
107 a pattern. When snapper computes the difference between two snapshots
108 it ignores all files and directories matching any of those patterns by
109 using fnmatch(3) with the flag FNM_LEADING_DIR.
110 Note that filters do not exclude files or directories from being
112 snapshotted. For that, use subvolumes or mount points.
113
115 -q, --quiet
116 Suppress normal output. Error messages will still be printed,
117 though.
118 -v, --verbose
120 Increase verbosity.
121 --utc
123 Display dates and times in UTC. By default, local time is used.
124 --iso
126 Display dates and times in ISO format. ISO format is always used
127 for machine-readable outputs.
128 -t, --table-style style
130 Specifies table style. Table style is identified by an integer
131 number.
132 --abbreviate
134 Try to abbreviate texts in some columns so that tables fit the
135 width of the screen.
136 --machine-readable format
138 Specifies a machine-readable output format. Possible options are
139 csv and json.
140 --csvout
142 Sets CSV output format. See RFC 4180[1] for the details, except
143 lines end with a LF, not CR+LF.
144 --jsonout
146 Sets JSON output format.
147 --separator character
149 Specifies the character separator for CSV output format.
150 -c, --config name
152 Use specified configuration instead of the default configuration.
153 The default configuration is named "root".
154 --no-dbus
156 Operate without a DBus connection.
157 Use with caution since a running snapperd will not know about
159 modifications made to the system.
160 -r, --root path
162 Operate on target root. Only works together with no-dbus and only
163 for some commands.
164 -a, --ambit ambit
166 Operate in the specified ambit. Can be used to override the ambit
167 detection. Allowed ambits are auto, classic and transactional.
168 --version
170 Print version and exit.
171
173 Snapper provides a number of commands. Each command accepts the options
174 listed in the GLOBAL OPTIONS section. These options must be specified
175 before the command name. In addition, many commands have specific
176 options, which are listed in this section. These command-specific
177 options must be specified after the name of the command and before any
178 of the command arguments.
179 help
181 Show short help text.
182 list-configs [options]
184 List available configurations.
185 --columns columns
187 Select columns to show separated by comma.
188 Possible columns are: config, subvolume.
190 create-config [options] subvolume
192 Create a new configuration for a filesystem or subvolume. For this
193 command you will likely need the global option --config, see GLOBAL
194 OPTIONS and CONCEPTS.
195 -f, --fstype fstype
197 Manually set filesystem type. Supported values are btrfs and
198 lvm. For lvm, snapper uses LVM thin-provisioned snapshots. The
199 filesystem type on top of LVM must be provided in parentheses,
200 e.g. lvm(xfs).
201 Without this option snapper tries to detect the filesystem.
203 -t, --template name
205 Name of template for the new configuration file.
206 delete-config
208 Delete a configuration for a filesystem or subvolume. For this
209 command you will likely need to global option --config, see GLOBAL
210 OPTIONS and CONCEPTS.
211 get-config [options]
213 Displays the settings of the configuration.
214 --columns columns
216 Select columns to show separated by comma.
217 Possible columns are: key, value.
219 Columns are not selected when JSON format is used.
221 set-config configdata
223 Changes the settings of the configuration. The settings configdata
224 are a list of key-value-pairs separated by spaces and the key and
225 value must be separated by an equal sign, e.g. "NUMBER_CLEANUP=yes
226 NUMBER_LIMIT=10". The value of SUBVOLUME and FSTYPE cannot be
227 changed.
228 list (ls) [options]
230 List snapshots.
231 -t, --type type
233 Selects type of snapshots to list. Possible values are all,
234 single and pre-post.
235 --disable-used-space
237 Disable display of used space.
238 Calculating the used space needs some time. Thus this option
240 can speedup the listing.
241 -a, --all-configs
243 List snapshots from all configs accessible by the user.
244 --columns columns
246 Select columns to show separated by comma.
247 Possible columns are: config, subvolume, number, default,
249 active, date, user, used-space, cleanup, description, userdata,
250 pre-number, post-number, post-date.
251 For each snapshot the output consists of several columns. Some need
253 explanation:
254 #, Pre # and Post #
256 The number of the snapshot.
257 For btrfs the number can be followed by a sign. A "-" indicates
259 that the snapshot is the currently mounted snapshot and a "+"
260 indicates that the snapshot will be mounted next time (It is
261 the btrfs default subvolume). If both conditions apply a "*" is
262 displayed.
263 Used Space
265 For btrfs the exclusive space of the btrfs quota group
266 corresponding to the snapshot.
267 Display of used space is automatically disabled if not
269 available, e.g. quota not enabled on btrfs.
270 create [options]
272 Create a new snapshot.
273 -t, --type type
275 Specifies the type of the new snapshot. Possible values are
276 single, pre and post.
277 --pre-number number
279 For post snapshots the number of the pre snapshot must be
280 provided.
281 -p, --print-number
283 Print number of the created snapshot.
284 -d, --description description
286 Description for the snapshot.
287 -c, --cleanup-algorithm cleanup-algorithm
289 Set the cleanup algorithm for the snapshot.
290 -u, --userdata userdata
292 Set userdata for the snapshot. The key-value pairs must be
293 separated by comma and the key and value must be separated by
294 an equal sign, e.g. requestid=42,user=arthur.
295 --command command
297 Create a pre and post snapshot and run command in between.
298 --read-only
300 Create a read-only snapshot. This is the default.
301 --read-write
303 Create a read-write snapshot.
304 --from number
306 Create a snapshot from the snapshot with the provided number
307 instead of snapshot 0.
308 modify [options] number
310 Modify a snapshot.
311 -d, --description description
313 New description for snapshot.
314 -c, --cleanup-algorithm cleanup-algorithm
316 Set the cleanup algorithm for the snapshot.
317 -u, --userdata userdata
319 Set userdata for the snapshot. The key-value pairs must be
320 separated by comma and the key and value must be separated by
321 an equal sign, e.g. requestid=42,user=arthur.
322 delete (remove|rm) number | number1-number2
324 Delete a snapshot or a range of snapshots.
325 -s, --sync
327 Sync the filesystem after deleting the snapshots. The details
328 depend on the filesystem type.
329 Btrfs normally asynchronously frees space after deleting
331 snapshots. With this option snapper will wait until the space
332 once used by the deleted snapshots is actually available again.
333 Snapshot 0 cannot be deleted. For btrfs the currently mounted
335 snapshot and the snapshot that will be mounted next time (the btrfs
336 default subvolume) can also not be deleted.
337 mount number
339 Mount a snapshot. Not required for all filesystem types.
340 umount number
342 Unmount a snapshot. Not required for all filesystem types.
343 status [options] number1..number2
345 Compare the snapshots number1 and number2. This will show a list of
346 files and directories that have been created, modified or deleted
347 in the time between the two snapshots have been made.
348 -o, --output file
350 Write output to file file.
351 The output consists of a string encoding the status followed by the
353 filename. The characters of the status string are:
354 1. A "+" means the file was created, a "-" means the file was
356 deleted. A "c" means the content of the file has changed and a
357 "t" means the type of the file has changed (e.g. from regular
358 file to directory).
359 2. A "p" means the permissions are have changed.
361 3. An "u" means the user ownership has changed.
363 4. A "g" means the group ownership has changed.
365 5. A "x" means the extended attribute information has changed.
367 6. An "a" means the ACL information has changed.
369 If there is no change a "." is outputted.
371 diff [options] number1..number2 [files]
373 Compare the snapshots number1 and number2. This will show a diff of
374 the content of files and directories that have been created,
375 modified or deleted in the time between the two snapshots have been
376 made.
377 -i, --input file
379 Read files to diff from file file.
380 --diff-cmd command
382 Command used for comparing files. The default is /usr/bin/diff
383 --new-file --unified. The two files to compare are passed as
384 parameters to the command.
385 -x, --extensions options
387 Extra options passed to the diff command.
388 undochange [options] number1..number2 [files]
390 Undo changes done between snapshot number1 and number2.
391 -i, --input file
393 Read files for which to undo changes from file file.
394 rollback [options] [number]
396 Creates two new snapshots and sets the default subvolume. Per
397 default the system boots from the default subvolume of the root
398 filesystem. The exact actions depend on whether a number is
399 provided or not:
400 • Without a number, a first read-only snapshot of the default
402 subvolume is created. A second read-write snapshot of the
403 current system is created. The system is set to boot from the
404 second snapshot.
405 • With a number, a first read-only snapshot of the current system
407 is created. A second read-write snapshot is created of number.
408 The system is set to boot from the second snapshot.
409 Rollback is only supported with btrfs and requires a properly
411 configured system.
412 -p, --print-number
414 Print number of the second created snapshot.
415 -d, --description description
417 Description for the snapshot.
418 -c, --cleanup-algorithm cleanup-algorithm
420 Set the cleanup algorithm for the snapshot.
421 -u, --userdata userdata
423 Set userdata for the snapshot. The key-value pairs must be
424 separated by comma and the key and value must be separated by
425 an equal sign, e.g. requestid=42,user=arthur.
426 The rollback command also sets the description, the cleanup
428 algorithm and some userdata unless the values are specified on the
429 command line. This will automate cleanup of snapshots created by
430 rollbacks.
431 In other ambits than classic the rollback command does what is
433 required to do a rollback. Anyway it is recommended to use specific
434 programs in that case.
435 setup-quota
437 Sets up quota. Currently only supported with btrfs.
438 cleanup [options] cleanup-algorithm
440 Run the cleanup algorithm cleanup-algorithm. Currently implemented
441 cleanup algorithms are number, timeline and empty-pre-post. To run
442 all cleanup algorithms, all can be provided as cleanup-algorithm.
443 --path path
445 Cleanup all configs affecting path. Only useful for btrfs.
446 --free-space free-space
448 Try to make free-space available. Only useful for btrfs.
449 xadiff number1..number2 [files]
451 Compare the extended attributes between snapshot number1 and
452 number2. See examples below:
453 • +:user.foo for created attributes
455 • -:user.bar for removed attributes
457 • -+:security.selinux for modified attributes
459
461 Non-root users can be allowed to use a configuration by setting
462 ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
463 work, the user must also be able to read and access the .snapshots
464 directory inside the subvolume. The .snapshots directory must be owned
465 by root and must not be writable by anybody else.
466 Here are some methods how to achieve that:
468 • Make the directory accessible for everyone:
470 chmod a+rx .snapshots
472 • Make the directory accessible for a group the user belongs to,
474 e.g.:
475 chown :users .snapshots
477 • Make the directory accessible for the user using ACLs, e.g.:
479 setfacl -m u:tux:rx .snapshots
481 The last method can be performed by snapper, see the SYNC_ACL setting
483 in snapper-configs(5).
484
486 snapper can execute external scripts after certain actions. Scripts
487 have to be placed in /usr/libexec/snapper/plugins. The name has to
488 start with a digit, execution order is alphabetical.
489 The first argument of a script is the action snapper executed. The
491 following actions are defined:
492 create-config subvolume fstype
494 Executed when a new config gets created
495 delete-config subvolume fstype
497 Executed when a config gets deleted
498 create-snapshot subvolume fstype snapshot-number
500 Executed when a new snapshot gets created
501 delete-snapshot subvolume fstype snapshot-number
503 Executed when a snapshot is removed
504 modify-snapshot subvolume fstype snapshot-number
506 Executed when a snapshot gets modified
507 set-default-snapshot subvolume fstype snapshot-number
509 Executed when the default snapshot gets changed
510 rollback subvolume fstype old-snapshot-number new-snapshot-number
512 Executed when a rollback is done
513 More actions and arguments can be added any time. Using snapper in the
515 plugins is not allowed.
516
518 /etc/sysconfig/snapper
519 Global configuration file.
520 /etc/snapper/configs
522 Directory containing configuration files.
523 /etc/snapper/config-templates
525 Directory containing configuration templates.
526 /usr/share/snapper/config-templates
528 Fallback directory containing configuration templates.
529 /etc/snapper/filters/*.txt
531 Filter files.
532 /usr/share/snapper/filters/*.txt
534 Fallback filter files.
535 /var/log/snapper.log
537 Logfile. Please include this file in bug reports.
538
540 There is no mechanism to ensure consistency of the files while a
541 snapshot it made. E.g. the files of a database can be inconsistent
542 while the database is running.
543 Consistency after undochange is not guaranteed. E.g. when the creation
545 of a user is undone, there might still exist files from that user.
546 Support for individual filesystems, rollback and extended attributes
548 are compile-time options and may not be available.
549
551 http://snapper.io/
552
554 Arvin Schnell <aschnell@suse.com>
555
557 snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
558 lvm(8), attr(5), acl(5)
559
561 1. RFC 4180
562 https://tools.ietf.org/html/rfc4180
5630.10.4 2022-06-02 SNAPPER(8)