Commit | Line | Data |
---|---|---|
99248ed2 MW |
1 | .TH snap 8 "6 November 2011" "distorted.org.uk backup" |
2 | .SH NAME | |
3 | snap \- create and remove snapshot devices | |
4 | .SH SYNOPSIS | |
5 | .B snap | |
6 | .RB [ \-u ] | |
7 | .RB [ \-c | |
8 | .IR file ] | |
9 | .I device | |
10 | .RI [ key \c | |
11 | .BI = value | |
12 | \&...] | |
13 | .SH DESCRIPTION | |
14 | The | |
15 | .B snap | |
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. | |
19 | .PP | |
20 | The command line options are as follows. | |
21 | .TP | |
22 | .B "\-h, \-\-help" | |
23 | Print a help message to standard output and exit with status zero. | |
24 | .TP | |
25 | .B "\-v, \-\-version" | |
26 | Print the program's version number to standard output and exit with | |
27 | status zero. | |
28 | .TP | |
29 | .BI "\-c, \-\-config-file=" file | |
30 | Read configuration from | |
31 | .I | |
32 | file | |
33 | rather than | |
34 | .BR @sysconfdir@/snaptab . | |
35 | .TP | |
36 | .B "\-u, \-\-unsnap" | |
37 | Remove a snapshot, rather than creating a new one. Strictly speaking, | |
38 | this just passes the option | |
39 | .B op=unsnap | |
40 | to the handler, though the conventional interpretation is to remove the | |
41 | snapshot. | |
42 | .SS Operation | |
43 | An | |
44 | .B op | |
45 | option is synthesized from the command-line options. Specifically, if the | |
46 | .B \-u | |
47 | as given, then | |
48 | .B op=unsnap | |
49 | is set; otherwise | |
50 | .B op=snap | |
51 | is assumed. | |
52 | .PP | |
53 | The | |
54 | .B snap | |
55 | program looks up the | |
56 | .I device | |
57 | in the configuration file \(en either | |
58 | .B /etc/snaptab | |
59 | or the | |
60 | .I file | |
61 | named by the | |
62 | .B \-u | |
63 | option \(en and retrieves a snapshot | |
64 | .I type | |
65 | and some options. See | |
66 | .BR snaptab (5) | |
67 | for the details of the file format and the process of constructing the | |
68 | options list. The | |
69 | .I device | |
70 | is usually the name of a device node, relative to | |
71 | .BR /dev , | |
72 | though specific handler programs may have their own conventions. | |
73 | .PP | |
74 | The option list from the configuration file, the synthesized | |
75 | .B op | |
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 | |
78 | same | |
79 | .I key | |
80 | then only the last is retained. (The | |
81 | .I key | |
82 | is the portion of the option before the first | |
83 | .RB ` = ' | |
84 | character.) | |
85 | .PP | |
86 | Finally, the snapshot handler for the selected | |
87 | .I type | |
88 | is invoked, as | |
89 | .IP | |
90 | .BI @snaplibexecdir@/snap. type | |
91 | .I device | |
92 | .IR key = value | |
93 | \&... | |
94 | .SS Handler conventions | |
95 | Much of the behaviour of | |
96 | .B snap | |
97 | is left up to individual type-specific handler programs. In order to | |
98 | maintain consistency, the following conventions are adopted. | |
99 | .PP | |
100 | Options are processed strictly left-to-right. Each option is parsed as | |
101 | .IP | |
102 | .IR key [\fB. type ]\fB= value | |
103 | .PP | |
104 | where the | |
105 | .I key | |
106 | and | |
107 | .I type | |
108 | do not contain | |
109 | .RB ` = ' | |
110 | characters, and the | |
111 | .I type | |
112 | does not contain a | |
113 | .RB ` . ' | |
114 | character. If the | |
115 | .I type | |
116 | is omitted, or is equal to the handler's type, then the option is | |
117 | processed; the | |
118 | .I type | |
119 | suffix is otherwise ignored; an error is reported if the | |
120 | .I key | |
121 | is unrecognized. Options bearing a different type are silently ignored. | |
122 | If the same | |
123 | .I key | |
124 | occurs more than once, only the last occurrence is significant. | |
125 | .PP | |
126 | Two options are always recognized. | |
127 | .TP | |
128 | .B op | |
129 | Synthesized by the | |
130 | .B snap | |
131 | program. The value is | |
132 | .B snap | |
133 | if a snapshot is to be created, or | |
134 | .B unsnap | |
135 | if it is to be removed (the | |
136 | .B \-u | |
137 | option was given). It is permissible for handlers to define meanings | |
138 | for other | |
139 | .B op | |
140 | values; unrecognized values are an error. | |
141 | .TP | |
142 | .B tag | |
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. | |
149 | .PP | |
150 | If the | |
151 | .B op | |
152 | is | |
153 | .B snap | |
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 | |
156 | .B op | |
157 | is | |
158 | .B unsnap | |
159 | then the handler should print nothing to standard output. Other | |
160 | .B op | |
161 | values may cause the handler to produce output at its discretion. | |
162 | .SH BUGS | |
163 | The | |
164 | .B snap | |
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. | |
169 | .SH SEE ALSO | |
170 | .BR snaptab (5). | |
171 | .SH AUTHOR | |
172 | Mark Wooding, <mdw@distorted.org.uk> |