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. Supported filesystems
20 are btrfs as well as snapshots of LVM logical volumes with
21 thin-provisioning.
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 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 Note that filters do not exclude files or directories from being
109 snapshotted. For that, use subvolumes or mount points.
110
112 -q, --quiet
113 Suppress normal output. Error messages will still be printed,
114 though.
115 -v, --verbose
117 Increase verbosity.
118 --utc
120 Display dates and times in UTC. By default, local time is used.
121 --iso
123 Display dates and times in ISO format. ISO format is always used
124 for machine-readable outputs.
125 -t, --table-style
127 Specifies table style. Table style is identified by an integer
128 number.
129 --machine-readable
131 Specifies a machine-readable output format. Possible options are
132 csv and json.
133 --csvout
135 Sets CSV output format. See RFC 4180[1] for the details, except
136 lines end with a LF, not CR+LF.
137 --jsonout
139 Sets JSON output format.
140 --separator
142 Specifies the character separator for CSV output format.
143 -c, --config name
145 Use specified configuration instead of the default configuration.
146 The default configuration is named "root".
147 --no-dbus
149 Operate without a DBus connection.
150 Use with caution since a running snapperd will not know about
152 modifications made to the system.
153 -r, --root path
155 Operate on target root. Only works together with no-dbus and only
156 for some commands.
157 --version
159 Print version and exit.
160
162 Snapper provides a number of commands. Each command accepts the options
163 listed in the GLOBAL OPTIONS section. These options must be specified
164 before the command name. In addition, many commands have specific
165 options, which are listed in this section. These command-specific
166 options must be specified after the name of the command and before any
167 of the command arguments.
168 help
170 Show short help text.
171 list-configs
173 List available configurations.
174 --columns columns
176 Select columns to show separated by comma.
177 Possible columns are: config, subvolume.
179 create-config [options] subvolume
181 Create a new configuration for a filesystem or subvolume. For this
182 command you will likely need the global option --config, see GLOBAL
183 OPTIONS and CONCEPTS.
184 -f, --fstype fstype
186 Manually set filesystem type. Supported values are btrfs and
187 lvm. For lvm, snapper uses LVM thin-provisioned snapshots. The
188 filesystem type on top of LVM must be provided in parentheses,
189 e.g. lvm(xfs).
190 Without this option snapper tries to detect the filesystem.
192 -t, --template name
194 Name of template for the new configuration file.
195 delete-config
197 Delete a configuration for a filesystem or subvolume. For this
198 command you will likely need to global option --config, see GLOBAL
199 OPTIONS and CONCEPTS.
200 get-config
202 Displays the settings of the configuration.
203 --columns columns
205 Select columns to show separated by comma.
206 Possible columns are: key, value.
208 Columns are not selected when JSON format is used.
210 set-config configdata
212 Changes the settings of the configuration. The settings configdata
213 are a list of key-value-pairs separated by spaces and the key and
214 value must be separated by an equal sign, e.g. "NUMBER_CLEANUP=yes
215 NUMBER_LIMIT=10". The value of SUBVOLUME and FSTYPE cannot be
216 changed.
217 list (ls) [options]
219 List snapshots.
220 -t, --type type
222 Selects type of snapshots to list. Possible values are all,
223 single and pre-post.
224 --disable-used-space
226 Disable display of used space.
227 Calculating the used space needs some time. Thus this option
229 can speedup the listing.
230 -a, --all-configs
232 List snapshots from all configs accessible by the user.
233 --columns columns
235 Select columns to show separated by comma.
236 Possible columns are: config, subvolume, number, default,
238 active, date, user, used-space, cleanup, description, userdata,
239 pre-number, post-number, post-date.
240 For each snapshot the output consists of several columns. Some need
242 explanation:
243 #, Pre # and Post #
245 The number of the snapshot.
246 For btrfs the number can be followed by a sign. A "-" indicates
248 that the snapshot is the currently mounted snapshot and a "+"
249 indicates that the snapshot will be mounted next time (It is
250 the btrfs default subvolume). If both conditions apply a "*" is
251 displayed.
252 Used Space
254 For btrfs the exclusive space of the btrfs quota group
255 corresponding to the snapshot.
256 Display of used space is automatically disabled if not
258 available, e.g. quota not enabled on btrfs.
259 create [options]
261 Create a new snapshot.
262 -t, --type type
264 Specifies the type of the new snapshot. Possible values are
265 single, pre and post.
266 --pre-number number
268 For post snapshots the number of the pre snapshot must be
269 provided.
270 -p, --print-number
272 Print number of the created snapshot.
273 -d, --description description
275 Description for the snapshot.
276 -c, --cleanup-algorithm cleanup-algorithm
278 Set the cleanup algorithm for the snapshot.
279 -u, --userdata userdata
281 Set userdata for the snapshot. The key-value pairs must be
282 separated by comma and the key and value must be separated by
283 an equal sign, e.g. requestid=42,user=arthur.
284 --command command
286 Create a pre and post snapshot and run command in between.
287 --read-only
289 Create a read-only snapshot. This is the default.
290 --read-write
292 Create a read-write snapshot.
293 --from number
295 Create a snapshot from the snapshot with the provided number
296 instead of snapshot 0.
297 modify [options] number
299 Modify a snapshot.
300 -d, --description description
302 New description for snapshot.
303 -c, --cleanup-algorithm cleanup-algorithm
305 Set the cleanup algorithm for the snapshot.
306 -u, --userdata userdata
308 Set userdata for the snapshot. The key-value pairs must be
309 separated by comma and the key and value must be separated by
310 an equal sign, e.g. requestid=42,user=arthur.
311 delete (remove|rm) number | number1-number2
313 Delete a snapshot or a range of snapshots.
314 -s, --sync
316 Sync the filesystem after deleting the snapshots. The details
317 depend on the filesystem type.
318 Btrfs normally asynchronously frees space after deleting
320 snapshots. With this option snapper will wait until the space
321 once used by the deleted snapshots is actually available again.
322 Snapshot 0 cannot be deleted. For btrfs the currently mounted
324 snapshot and the snapshot that will be mounted next time (the btrfs
325 default subvolume) can also not be deleted.
326 mount number
328 Mount a snapshot. Not required for all filesystem types.
329 umount number
331 Unmount a snapshot. Not required for all filesystem types.
332 status [options] number1..number2
334 Compare the snapshots number1 and number2. This will show a list of
335 files and directories that have been created, modified or deleted
336 in the time between the two snapshots have been made.
337 -o, --output file
339 Write output to file file.
340 The output consists of a string encoding the status followed by the
342 filename. The characters of the status string are:
343 1. A "+" means the file was created, a "-" means the file was
345 deleted. A "c" means the content of the file has changed and a
346 "t" means the type of the file has changed (e.g. from regular
347 file to directory).
348 2. A "p" means the permissions are have changed.
350 3. An "u" means the user ownership has changed.
352 4. A "g" means the group ownership has changed.
354 5. A "x" means the extended attribute information has changed.
356 6. An "a" means the ACL information has changed.
358 If there is no change a "." is outputted.
360 diff [options] number1..number2 [files]
362 Compare the snapshots number1 and number2. This will show a diff of
363 the content of files and directories that have been created,
364 modified or deleted in the time between the two snapshots have been
365 made.
366 -i, --input file
368 Read files to diff from file file.
369 --diff-cmd command
371 Command used for comparing files. The default is /usr/bin/diff
372 --new-file --unified. The two files to compare are passed as
373 parameters to the command.
374 -x, --extensions options
376 Extra options passed to the diff command.
377 undochange [options] number1..number2 [files]
379 Undo changes done between snapshot number1 and number2.
380 -i, --input file
382 Read files for which to undo changes from file file.
383 rollback [options] [number]
385 Creates two new snapshots and sets the default subvolume. Per
386 default the system boots from the default subvolume of the root
387 filesystem. The exact actions depend on whether a number is
388 provided or not:
389 · Without a number, a first read-only snapshot of the default
391 subvolume is created. A second read-write snapshot of the
392 current system is created. The system is set to boot from the
393 second snapshot.
394 · With a number, a first read-only snapshot of the current system
396 is created. A second read-write snapshot is created of number.
397 The system is set to boot from the second snapshot.
398 Rollback is only supported with btrfs and requires a properly
400 configured system.
401 -p, --print-number
403 Print number of the second created snapshot.
404 -d, --description description
406 Description for the snapshot.
407 -c, --cleanup-algorithm cleanup-algorithm
409 Set the cleanup algorithm for the snapshot.
410 -u, --userdata userdata
412 Set userdata for the snapshot. The key-value pairs must be
413 separated by comma and the key and value must be separated by
414 an equal sign, e.g. requestid=42,user=arthur.
415 The rollback command also sets the description, the cleanup
417 algorithm and some userdata unless the values are specified on the
418 command line. This will automate cleanup of snapshots created by
419 rollbacks.
420 setup-quota
422 Sets up quota. Currently only supported with btrfs.
423 cleanup cleanup-algorithm
425 Run the cleanup algorithm cleanup-algorithm. Currently implemented
426 cleanup algorithms are number, timeline and empty-pre-post.
427 xadiff number1..number2 [files]
429 Compare the extended attributes between snapshot number1 and
430 number2. See examples below:
431 · +:user.foo for created attributes
433 · -:user.bar for removed attributes
435 · -+:security.selinux for modified attributes
437
439 Non-root users can be allowed to use a configuration by setting
440 ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
441 work, the user must also be able to read and access the .snapshots
442 directory inside the subvolume. The .snapshots directory must be owned
443 by root and must not be writable by anybody else.
444 Here are some methods how to achieve that:
446 · Make the directory accessible for everyone:
448 chmod a+rx .snapshots
450 · Make the directory accessible for a group the user belongs to,
452 e.g.:
453 chown :users .snapshots
455 · Make the directory accessible for the user using ACLs, e.g.:
457 setfacl -m u:tux:rx .snapshots
459 The last method can be performed by snapper, see the SYNC_ACL setting
461 in snapper-configs(5).
462
464 /etc/sysconfig/snapper
465 Global configuration file.
466 /etc/snapper/configs
468 Directory containing configuration files.
469 /etc/snapper/config-templates
471 Directory containing configuration templates.
472 /etc/snapper/filters/*.txt
474 Filter files.
475 /var/log/snapper.log
477 Logfile. Please include this file in bug reports.
478
480 There is no mechanism to ensure consistency of the files while a
481 snapshot it made. E.g. the files of a database can be inconsistent
482 while the database is running.
483 Consistency after undochange is not guaranteed. E.g. when the creation
485 of a user is undone, there might still exist files from that user.
486 Support for individual filesystems, rollback and extended attributes
488 are compile-time options and may not be available.
489
491 http://snapper.io/
492
494 Arvin Schnell <aschnell@suse.com>
495
497 snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
498 lvm(8), attr(5), acl(5)
499
501 1. RFC 4180
502 https://tools.ietf.org/html/rfc4180
5030.8.9 2019-10-14 SNAPPER(8)