chiark - git - mdw - distorted-backup/blob - snaptab.5.in

   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>