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 Automatic Snapshot Creation
51 Next to manual snapshot creation, snapshots are also created
52 automatically.
53 · A cron-job creates hourly snapshots.
55 Cleanup Algorithms
57 Snapper provides several algorithms to clean up old snapshots. The
58 algorithms are executed in a daily cron-job. This can be configured in
59 the corresponding configurations files along with parameters for every
60 algorithm.
61 number
63 Deletes old snapshots when a certain number of snapshots is
64 reached.
65 timeline
67 Deletes old snapshots but keeps a number of hourly, daily, weekly,
68 monthly and yearly snapshots.
69 empty-pre-post
71 Deletes pre/post snapshot pairs with empty diffs.
72 Filters
74 Some files keep state information of the system, e.g. /etc/mtab. Such
75 files should never be reverted. To help users, snapper allows to ignore
76 these files.
77 Each line in all files /etc/snapper/filters/*.txt specifies a pattern.
79 When snapper computes the difference between two snapshots it ignores
80 all files and directories matching any of those patterns by using
81 fnmatch(3) with the flag FNM_LEADING_DIR.
82 Note that filters do not exclude files or directories from being
84 snapshotted. For that, use subvolumes or mount points.
85
87 -q, --quiet
88 Suppress normal output. Error messages will still be printed,
89 though.
90 -v, --verbose
92 Increase verbosity.
93 --utc
95 Display dates and times in UTC.
96 --iso
98 Display dates and times in ISO format.
99 -t, --table-style
101 Specifies table style. Table style is identified by an integer
102 number.
103 -c, --config name
105 Use specified configuration instead of the default configuration.
106 The default configuration is named "root".
107 --no-dbus
109 Operate without a DBus connection. Only works for some commands.
110 Use with caution since a running snapperd will not know about
112 modifications made to the system.
113 -r, --root path
115 Operate on target root. Only works together with no-dbus and only
116 for some commands.
117 --version
119 Print version and exit.
120
122 Snapper provides a number of commands. Each command accepts the options
123 listed in the GLOBAL OPTIONS section. These options must be specified
124 before the command name. In addition, many commands have specific
125 options, which are listed in this section. These command-specific
126 options must be specified after the name of the command and before any
127 of the command arguments.
128 help
130 Show short help text.
131 list-configs
133 List available configurations.
134 create-config [options] subvolume
136 Create a new configuration for a filesystem or subvolume. For this
137 command you will likely need the global option --config, see GLOBAL
138 OPTIONS and CONCEPTS.
139 -f, --fstype fstype
141 Manually set filesystem type. Supported values are btrfs and
142 lvm. For lvm, snapper uses LVM thin-provisioned snapshots. The
143 filesystem type on top of LVM must be provided in parentheses,
144 e.g. lvm(xfs).
145 Without this option snapper tries to detect the filesystem.
147 -t, --template name
149 Name of template for the new configuration file.
150 delete-config
152 Delete a configuration for a filesystem or subvolume. For this
153 command you will likely need to global option --config, see GLOBAL
154 OPTIONS and CONCEPTS.
155 get-config
157 Displays the settings of the configuration.
158 set-config configdata
160 Changes the settings of the configuration. The settings configdata
161 are a list of key-value-pairs separated by spaces and the key and
162 value must be separated by an equal sign, e.g. "NUMBER_CLEANUP=yes
163 NUMBER_LIMIT=10". The value of SUBVOLUME and FSTYPE cannot be
164 changed.
165 list (ls) [options]
167 List snapshots.
168 -t, --type type
170 Selects type of snapshots to list. Possible values are all,
171 single and pre-post.
172 -a, --all-configs
174 List snapshots from all configs accessible by the user.
175 create [options]
177 Create a new snapshot.
178 -t, --type type
180 Specifies the type of the new snapshot. Possible values are
181 single, pre and post.
182 --pre-number number
184 For post snapshots the number of the pre snapshot must be
185 provided.
186 -p, --print-number
188 Print number of the created snapshot.
189 -d, --description description
191 Description for the snapshot.
192 -c, --cleanup-algorithm cleanup-algorithm
194 Set the cleanup algorithm for the snapshot.
195 -u, --userdata userdata
197 Set userdata for the snapshot. The key-value pairs must be
198 separated by comma and the key and value must be separated by
199 an equal sign, e.g. requestid=42,user=arthur.
200 --command command
202 Create a pre and post snapshot and run command in between.
203 modify [options] number
205 Modify a snapshot.
206 -d, --description description
208 New description for snapshot.
209 -c, --cleanup-algorithm cleanup-algorithm
211 Set the cleanup algorithm for the snapshot.
212 -u, --userdata userdata
214 Set userdata for the snapshot. The key-value pairs must be
215 separated by comma and the key and value must be separated by
216 an equal sign, e.g. requestid=42,user=arthur.
217 delete (remove|rm) number | number1-number2
219 Delete a snapshot or a range of snapshots.
220 -s, --sync
222 Sync the filesystem after deleting the snapshots. The details
223 depend on the filesystem type.
224 Btrfs normally asynchronously frees space after deleting
226 snapshots. With this option snapper will wait until the space
227 once used by the deleted snapshots is actually available again.
228 mount number
230 Mount a snapshot. Not required for all filesystem types.
231 umount number
233 Unmount a snapshot. Not required for all filesystem types.
234 status [options] number1..number2
236 Compare the snapshots number1 and number2. This will show a list of
237 files and directories that have been created, modified or deleted
238 in the time between the two snapshots have been made.
239 -o, --output file
241 Write output to file file.
242 The output consists of a string encoding the status followed by the
244 filename. The characters of the status string are:
245 1. A "+" means the file was created, a "-" means the file was
247 deleted. A "c" means the content of the file has changed and a
248 "t" means the type of the file has changed (e.g. from regular
249 file to directory).
250 2. A "p" means the permissions are have changed.
252 3. An "u" means the user ownership has changed.
254 4. A "g" means the group ownership has changed.
256 5. A "x" means the extended attribute information has changed.
258 6. An "a" means the ACL information has changed.
260 If there is no change a "." is outputted.
262 diff [options] number1..number2 [files]
264 Compare the snapshots number1 and number2. This will show a diff of
265 the content of files and directories that have been created,
266 modified or deleted in the time between the two snapshots have been
267 made.
268 -i, --input file
270 Read files to diff from file file.
271 --diff-cmd command
273 Command used for comparing files. The default is /usr/bin/diff
274 --new-file --unified. The two files to compare are passed as
275 parameters to the command.
276 -x, --extensions options
278 Extra options passed to the diff command.
279 undochange [options] number1..number2 [files]
281 Undo changes done between snapshot number1 and number2.
282 -i, --input file
284 Read files for which to undo changes from file file.
285 rollback [options] [number]
287 Creates two new snapshots and sets the default subvolume. Per
288 default the system boots from the default subvolume of the root
289 filesystem. The exact actions depend on whether a number is
290 provided or not:
291 · Without a number, a first read-only snapshot of the default
293 subvolume is created. A second read-write snapshot of the
294 current system is created. The system is set to boot from the
295 second snapshot.
296 · With a number, a first read-only snapshot of the current system
298 in created. A second read-write snapshot is created of number.
299 The system is set to boot from the second snapshot.
300 Rollback is only supported with btrfs and requires a properly
302 configured system.
303 -p, --print-number
305 Print number of the second created snapshot.
306 -d, --description description
308 Description for the snapshot.
309 -c, --cleanup-algorithm cleanup-algorithm
311 Set the cleanup algorithm for the snapshot.
312 -u, --userdata userdata
314 Set userdata for the snapshot. The key-value pairs must be
315 separated by comma and the key and value must be separated by
316 an equal sign, e.g. requestid=42,user=arthur.
317 cleanup cleanup-algorithm
319 Run the cleanup algorithm cleanup-algorithm. Currently implemented
320 cleanup algorithms are number, timeline and empty-pre-post.
321 xadiff number1..number2 [files]
323 Compare the extended attributes between snapshot number1 and
324 number2. See examples below:
325 · +:user.foo for created attributes
327 · -:user.bar for removed attributes
329 · -+:security.selinux for modified attributes
331
333 Non-root users can be allowed to use a configuration by setting
334 ALLOW_USERS or ALLOW_GROUPS in the config file. For all operations to
335 work, the user must also be able to read and access the .snapshots
336 directory inside the subvolume. The .snapshots directory must be owned
337 by root and must not be writable by anybody else.
338 Here are some methods how to achieve that:
340 · Make the directory accessible for everyone:
342 chmod a+rx .snapshots
344 · Make the directory accessible for a group the user belongs to,
346 e.g.:
347 chown :users .snapshots
349 · Make the directory accessible for the user using ACLs, e.g.:
351 setfacl -m u:tux:rx .snapshots
353 The last method can be performed by snapper, see the SYNC_ACL setting
355 in snapper-configs(5).
356
358 /etc/sysconfig/snapper
359 Global configuration file.
360 /etc/snapper/configs
362 Directory containing configuration files.
363 /etc/snapper/config-templates
365 Directory containing configuration templates.
366 /etc/snapper/filters/*.txt
368 Filter files.
369 /var/log/snapper.log
371 Logfile. Please include this file in bug reports.
372
374 There is no mechanism to ensure consistency of the files while a
375 snapshot it made. E.g. the files of a database can be inconsistent
376 while the database is running.
377 Consistency after undochange is not guaranteed. E.g. when the creation
379 of a user is undone, there might still exist files from that user.
380 Support for individual filesystems, rollback and extended attributes
382 are compile-time options and may not be available.
383
385 http://snapper.io/
386
388 Arvin Schnell <aschnell@suse.de>
389
391 snapper-configs(5), snapper-zypp-plugin(8), pam_snapper(8), btrfs(8),
392 lvm(8), attr(5), acl(5)
3930.2.8 2014-04-07 SNAPPER(8)