| 1 | .ie t .ds o \(bu |
| 2 | .el .ds o o |
| 3 | .de hP |
| 4 | .IP |
| 5 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c |
| 6 | .. |
| 7 | .TH snaptab 5 "6 November 2011" "distorted.org.uk backup" |
| 8 | .SH NAME |
| 9 | snaptab \- device-level snapshot parameters |
| 10 | .SH DESCRIPTION |
| 11 | The |
| 12 | .B snaptab |
| 13 | file describes mechanisms and parameters for taking snapshots of block |
| 14 | devices. The |
| 15 | .BR snap (8) |
| 16 | program by default reads |
| 17 | .BR @sysconfdir@/snaptab , |
| 18 | but it can be instructed to read a different file using the |
| 19 | .B \-c |
| 20 | command-line option. |
| 21 | .SS Syntax |
| 22 | The file consists of a sequence of logical lines. A logical line |
| 23 | consists of one or more newline-terminated physical lines, all but the |
| 24 | last of which ends with a backslash |
| 25 | .B ` \e ' |
| 26 | followed by zero or more whitespace characters. These trailing |
| 27 | backslashes and trailing whitespace are stripped from the logical line |
| 28 | during parsing, and are not further significant. |
| 29 | .PP |
| 30 | A logical line may be |
| 31 | .IR empty , |
| 32 | consisting only of whitespace; |
| 33 | a |
| 34 | .IR comment , |
| 35 | beginning with zero or more whitespace characters followed by a |
| 36 | .RB ` # '; |
| 37 | or a |
| 38 | .IR "data line" . |
| 39 | Empty lines and comments are ignored. |
| 40 | .PP |
| 41 | A data line consists of two or more whitespace-separated fields. There |
| 42 | may be leading or trailing whitespace; this is not significant. |
| 43 | Whitespace characters may be included in a field using escaping or |
| 44 | quoting, in a manner similar to the Bourne shell, though it is not |
| 45 | possible for a field to contain a newline character. |
| 46 | .PP |
| 47 | The precise quoting and escaping rules are as follows. All characters |
| 48 | other than whitespace (i.e., space, horizontal and vertical tabs, and |
| 49 | formfeed), the backslash |
| 50 | .RB ` \e ', |
| 51 | the single-quote |
| 52 | .RB ` ' ', |
| 53 | and the double-quote |
| 54 | .RB ` """" ', |
| 55 | are |
| 56 | .I ordinary |
| 57 | and have no special meaning. A character preceded by an unescaped |
| 58 | backslash is |
| 59 | .IR escaped ; |
| 60 | any other character is |
| 61 | .I unescaped . |
| 62 | If an unquoted, unescaped double- or single-quote character occurs, the |
| 63 | following characters, up until but not including the next unescaped |
| 64 | occurrence of the same quote character, are |
| 65 | .I double- |
| 66 | or |
| 67 | .I single-quoted |
| 68 | respectively; other characters are |
| 69 | .IR unquoted . |
| 70 | A character is |
| 71 | .I constituent |
| 72 | if it is ordinary, escaped, single-quoted, or both double-quoted and not |
| 73 | a backslash. A field's text consists of all of the constituent |
| 74 | characters bounded by the start of the line, the end of the line, or |
| 75 | sequences of one or more unescaped, unquoted whitespace characters. |
| 76 | .PP |
| 77 | The fields of a data line are as follows. |
| 78 | .IP |
| 79 | .I "device type option \fR..." |
| 80 | Briefly, the fields are interpreted as follows. A full description is |
| 81 | given below. |
| 82 | .TP |
| 83 | .I device |
| 84 | The name of a device which can be snapshot. This is usually the name of |
| 85 | a device node in |
| 86 | .B /dev |
| 87 | without the |
| 88 | .RB ` /dev ' |
| 89 | prefix, though strictly speaking its interpretation is left up to the |
| 90 | snapshot handler program. Alternatively, this can be the special name |
| 91 | .RB ` * ' |
| 92 | to define default options for a particular snapshot type. |
| 93 | .TP |
| 94 | .I type |
| 95 | The type of snapshot to be performed. For each snapshot type, there is |
| 96 | a program |
| 97 | .BI snap. type |
| 98 | which manages snapshots of that type. |
| 99 | .TP |
| 100 | .IB option |
| 101 | The remaining fields are option assignments: these are either individual |
| 102 | .IB key = value |
| 103 | assignments, or tokens of the form |
| 104 | .B *. type |
| 105 | to interpolate the current default options for the given |
| 106 | .IR type . |
| 107 | .SS Interpretation |
| 108 | The configuration file's data lines describe a mapping from |
| 109 | .I device |
| 110 | names to |
| 111 | .IR type s |
| 112 | and sequences of |
| 113 | .IR options . |
| 114 | This section describes how the mapping is derived from the file |
| 115 | contents. |
| 116 | .PP |
| 117 | Abstractly, |
| 118 | .IR device s |
| 119 | and |
| 120 | .IR type s |
| 121 | are arbitrary strings, and |
| 122 | .IR option s |
| 123 | are strings of the form |
| 124 | .IB key = value \fR, |
| 125 | where the |
| 126 | .I key |
| 127 | is a nonempty string which contains no |
| 128 | .RB ` = ' |
| 129 | characters, and the |
| 130 | .I value |
| 131 | is an arbitrary string. An option of the form |
| 132 | .IB key . type = value |
| 133 | is said to be |
| 134 | .IR qualified ; |
| 135 | otherwise, an option is |
| 136 | .IR unqualified . |
| 137 | In a qualified option, the |
| 138 | .I type |
| 139 | may not contain a |
| 140 | .RB ` . ' |
| 141 | character. |
| 142 | .PP |
| 143 | A data line's |
| 144 | .I option |
| 145 | sequence may contain |
| 146 | .IB key = value |
| 147 | assignments, which are not further interpreted, and various special |
| 148 | tokens. These tokens are replaced with other options or sequences of |
| 149 | options during |
| 150 | .IR expansion . |
| 151 | The following tokens are recognized during expansion, and replaced. |
| 152 | .TP |
| 153 | .BI *. type |
| 154 | The replacement sequence is constructed as follows. Start with the |
| 155 | default option sequence for the |
| 156 | .I type |
| 157 | for this line (see below). Each qualified option in this sequence is |
| 158 | retained; each unqualified option |
| 159 | .IB key = value |
| 160 | is qualified by |
| 161 | .I type |
| 162 | yielding |
| 163 | .IB key . type = value \fR. |
| 164 | .PP |
| 165 | The |
| 166 | .I "default option sequence" |
| 167 | for a particular |
| 168 | .I type |
| 169 | .I t |
| 170 | at a given line in the file is the concatenation of the expanded option |
| 171 | sequences of all earlier data lines whose |
| 172 | .I device |
| 173 | field is |
| 174 | .B * |
| 175 | and whose |
| 176 | .I type |
| 177 | is |
| 178 | .IR t . |
| 179 | .PP |
| 180 | The option sequence of a data line whose |
| 181 | .I device |
| 182 | is not |
| 183 | .B * |
| 184 | is |
| 185 | .I augmented |
| 186 | by prefixing the expanded option sequence with the default option |
| 187 | sequence for the corresponding |
| 188 | .I type |
| 189 | at that line. |
| 190 | .PP |
| 191 | It is an error if two data lines with equal |
| 192 | .I device |
| 193 | fields have different |
| 194 | .I type |
| 195 | fields, unless the |
| 196 | .I device |
| 197 | is |
| 198 | .BR * . |
| 199 | .PP |
| 200 | The mapping from |
| 201 | .I device |
| 202 | names to |
| 203 | .IR type s |
| 204 | and |
| 205 | .I option |
| 206 | sequences can now be defined. Collect all of the data lines whose |
| 207 | .I device |
| 208 | field matches the input |
| 209 | .I device |
| 210 | name. The common |
| 211 | .I type |
| 212 | field from these lines is the resulting |
| 213 | .IR type ; |
| 214 | The resulting option sequence is the concatenation of the augmented |
| 215 | option sequences for the collected lines. |
| 216 | .PP |
| 217 | Note that the |
| 218 | .BR snap (8) |
| 219 | program filters the option sequence, retaining only the last option with |
| 220 | an given |
| 221 | .IR key . |
| 222 | .SH EXAMPLE |
| 223 | Consider the file below. |
| 224 | .IP |
| 225 | .nf |
| 226 | .ft B |
| 227 | .ta 8 16 24 32 40 48 56 64 |
| 228 | ## Set defaults. |
| 229 | * lvm \e |
| 230 | snapsz=5%ORIGIN |
| 231 | |
| 232 | * rfreezefs \e |
| 233 | subtype=lvm \e |
| 234 | *.lvm |
| 235 | |
| 236 | ## Local filesystems. |
| 237 | md/boot ro dir=/boot |
| 238 | vg-ibanez/root lvm |
| 239 | vg-ibanez/home lvm |
| 240 | vg-ibanez/scratch lvm |
| 241 | vg-ibanez/usr lvm |
| 242 | vg-ibanez/var lvm |
| 243 | |
| 244 | ## Remotely mounted filesystems. |
| 245 | * rfreezefs host=roadstar |
| 246 | vg-ibanez/db rfreezefs dir=/mnt/db |
| 247 | vg-ibanez/ftp rfreezefs dir=/mnt/ftp |
| 248 | vg-ibanez/news rfreezefs dir=/var/spool/news |
| 249 | |
| 250 | * rfreezefs host=jem |
| 251 | vg-ibanez/homes rfreezefs dir=/home |
| 252 | vg-ibanez/jb rfreezefs dir=/mnt/jb |
| 253 | .fi |
| 254 | .ft P |
| 255 | .PP |
| 256 | Now: |
| 257 | .hP \*o |
| 258 | At the |
| 259 | .B md/boot |
| 260 | line, the default option list for type |
| 261 | .B lvm |
| 262 | is |
| 263 | .B snapsz=5%ORIGIN |
| 264 | and the default option list for type |
| 265 | .B rfreezefs |
| 266 | is |
| 267 | .B subtype=lvm |
| 268 | .BR snapsz.lvm=5%ORIGIN . |
| 269 | .hP \*o |
| 270 | The device |
| 271 | .B vg-ibanez/scratch |
| 272 | has type |
| 273 | .B lvm |
| 274 | and option list |
| 275 | .BR snapsz=5%ORIGIN . |
| 276 | .hP \*o |
| 277 | The device |
| 278 | .B vg-ibanez/db |
| 279 | maps to type |
| 280 | .B rfreezefs |
| 281 | and option list |
| 282 | .B subtype=lvm |
| 283 | .B snapsz.lvm=5%ORIGIN |
| 284 | .B host=roadstar |
| 285 | .BR dir=/mnt/db . |
| 286 | .hP \*o |
| 287 | The device |
| 288 | .B vg-ibanez/jb |
| 289 | maps to type |
| 290 | .B rfreezefs |
| 291 | and option list |
| 292 | .B subtype=lvm |
| 293 | .B snapsz.lvm=5%ORIGIN |
| 294 | .B host=roadstar |
| 295 | .B host=jem |
| 296 | .BR dir=/mnt/db ; |
| 297 | but only the latter |
| 298 | .B host |
| 299 | option is significant \(en the other will be omitted from the list |
| 300 | passed to |
| 301 | .BR snap.rfreezefs (8). |
| 302 | .SH SEE ALSO |
| 303 | .BR snap (8) |
| 304 | .SH AUTHOR |
| 305 | Mark Wooding, <mdw@distorted.org.uk> |