1 .TH snap 8 "6 November 2011" "distorted.org.uk backup"
3 snap \- create and remove snapshot devices
16 utility manages device-level snapshots in a mechanism-independent way.
17 It's intended to be used as part of automated filesystem maintenance
18 activities, such as backups or online filesystem checking.
20 The command line options are as follows.
23 Print a help message to standard output and exit with status zero.
26 Print the program's version number to standard output and exit with
29 .BI "\-c, \-\-config-file=" file
30 Read configuration from
34 .BR @sysconfdir@/snaptab .
37 Remove a snapshot, rather than creating a new one. Strictly speaking,
38 this just passes the option
40 to the handler, though the conventional interpretation is to remove the
45 option is synthesized from the command-line options. Specifically, if the
57 in the configuration file \(en either
63 option \(en and retrieves a snapshot
67 for the details of the file format and the process of constructing the
70 is usually the name of a device node, relative to
72 though specific handler programs may have their own conventions.
74 The option list from the configuration file, the synthesized
76 option, and the command-line option list, are concatenated, in that
77 order; then, if the resulting list contains two or more options with the
80 then only the last is retained. (The
82 is the portion of the option before the first
86 Finally, the snapshot handler for the selected
90 .BI @snaplibexecdir@/snap. type
94 .SS Handler conventions
95 Much of the behaviour of
97 is left up to individual type-specific handler programs. In order to
98 maintain consistency, the following conventions are adopted.
100 Options are processed strictly left-to-right. Each option is parsed as
102 .IR key [\fB. type ]\fB= value
116 is omitted, or is equal to the handler's type, then the option is
119 suffix is otherwise ignored; an error is reported if the
121 is unrecognized. Options bearing a different type are silently ignored.
124 occurs more than once, only the last occurrence is significant.
126 Two options are always recognized.
131 program. The value is
133 if a snapshot is to be created, or
135 if it is to be removed (the
137 option was given). It is permissible for handlers to define meanings
140 values; unrecognized values are an error.
143 A short arbitrary string which is assigned to the snapshot to
144 distinguish it from snapshots created by other clients. The acceptable
145 form for the tag may vary with the snapshot type, but alphanumerics and
146 hyphens are always allowed. This option may be omitted, though this is
147 discouraged in scripted use: it is not specified whether this is
148 equivalent to providing some default tag.
154 then the handler should print the (full) pathname of the block device
155 containing the snapshot to standard output, followed by a newline. If
159 then the handler should print nothing to standard output. Other
161 values may cause the handler to produce output at its discretion.
165 program doesn't even try to handle filesystem-level snapshots, as you'd
166 get in ZFS or BtrFS. Trying to do both device- and filesystem-level
167 snapshots in one program leads to all sorts of difficulties, and it's
168 probably a mistake to try. The distinction is still annoying, though.
172 Mark Wooding, <mdw@distorted.org.uk>