.ie t .ds o \(bu .el .ds o o .de hP .IP \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c .. .TH snaptab 5 "6 November 2011" "distorted.org.uk backup" .SH NAME snaptab \- device-level snapshot parameters .SH DESCRIPTION The .B snaptab file describes mechanisms and parameters for taking snapshots of block devices. The .BR snap (8) program by default reads .BR @sysconfdir@/snaptab , but it can be instructed to read a different file using the .B \-c command-line option. .SS Syntax The file consists of a sequence of logical lines. A logical line consists of one or more newline-terminated physical lines, all but the last of which ends with a backslash .B ` \e ' followed by zero or more whitespace characters. These trailing backslashes and trailing whitespace are stripped from the logical line during parsing, and are not further significant. .PP A logical line may be .IR empty , consisting only of whitespace; a .IR comment , beginning with zero or more whitespace characters followed by a .RB ` # '; or a .IR "data line" . Empty lines and comments are ignored. .PP A data line consists of two or more whitespace-separated fields. There may be leading or trailing whitespace; this is not significant. Whitespace characters may be included in a field using escaping or quoting, in a manner similar to the Bourne shell, though it is not possible for a field to contain a newline character. .PP The precise quoting and escaping rules are as follows. All characters other than whitespace (i.e., space, horizontal and vertical tabs, and formfeed), the backslash .RB ` \e ', the single-quote .RB ` ' ', and the double-quote .RB ` """" ', are .I ordinary and have no special meaning. A character preceded by an unescaped backslash is .IR escaped ; any other character is .I unescaped . If an unquoted, unescaped double- or single-quote character occurs, the following characters, up until but not including the next unescaped occurrence of the same quote character, are .I double- or .I single-quoted respectively; other characters are .IR unquoted . A character is .I constituent if it is ordinary, escaped, single-quoted, or both double-quoted and not a backslash. A field's text consists of all of the constituent characters bounded by the start of the line, the end of the line, or sequences of one or more unescaped, unquoted whitespace characters. .PP The fields of a data line are as follows. .IP .I "device type option \fR..." Briefly, the fields are interpreted as follows. A full description is given below. .TP .I device The name of a device which can be snapshot. This is usually the name of a device node in .B /dev without the .RB ` /dev ' prefix, though strictly speaking its interpretation is left up to the snapshot handler program. Alternatively, this can be the special name .RB ` * ' to define default options for a particular snapshot type. .TP .I type The type of snapshot to be performed. For each snapshot type, there is a program .BI snap. type which manages snapshots of that type. .TP .IB option The remaining fields are option assignments: these are either individual .IB key = value assignments, or tokens of the form .B *. type to interpolate the current default options for the given .IR type . .SS Interpretation The configuration file's data lines describe a mapping from .I device names to .IR type s and sequences of .IR options . This section describes how the mapping is derived from the file contents. .PP Abstractly, .IR device s and .IR type s are arbitrary strings, and .IR option s are strings of the form .IB key = value \fR, where the .I key is a nonempty string which contains no .RB ` = ' characters, and the .I value is an arbitrary string. An option of the form .IB key . type = value is said to be .IR qualified ; otherwise, an option is .IR unqualified . In a qualified option, the .I type may not contain a .RB ` . ' character. .PP A data line's .I option sequence may contain .IB key = value assignments, which are not further interpreted, and various special tokens. These tokens are replaced with other options or sequences of options during .IR expansion . The following tokens are recognized during expansion, and replaced. .TP .BI *. type The replacement sequence is constructed as follows. Start with the default option sequence for the .I type for this line (see below). Each qualified option in this sequence is retained; each unqualified option .IB key = value is qualified by .I type yielding .IB key . type = value \fR. .PP The .I "default option sequence" for a particular .I type .I t at a given line in the file is the concatenation of the expanded option sequences of all earlier data lines whose .I device field is .B * and whose .I type is .IR t . .PP The option sequence of a data line whose .I device is not .B * is .I augmented by prefixing the expanded option sequence with the default option sequence for the corresponding .I type at that line. .PP It is an error if two data lines with equal .I device fields have different .I type fields, unless the .I device is .BR * . .PP The mapping from .I device names to .IR type s and .I option sequences can now be defined. Collect all of the data lines whose .I device field matches the input .I device name. The common .I type field from these lines is the resulting .IR type ; The resulting option sequence is the concatenation of the augmented option sequences for the collected lines. .PP Note that the .BR snap (8) program filters the option sequence, retaining only the last option with an given .IR key . .SH EXAMPLE Consider the file below. .IP .nf .ft B .ta 8 16 24 32 40 48 56 64 ## Set defaults. * lvm \e snapsz=5%ORIGIN * rfreezefs \e subtype=lvm \e *.lvm ## Local filesystems. md/boot ro dir=/boot vg-ibanez/root lvm vg-ibanez/home lvm vg-ibanez/scratch lvm vg-ibanez/usr lvm vg-ibanez/var lvm ## Remotely mounted filesystems. * rfreezefs host=roadstar vg-ibanez/db rfreezefs dir=/mnt/db vg-ibanez/ftp rfreezefs dir=/mnt/ftp vg-ibanez/news rfreezefs dir=/var/spool/news * rfreezefs host=jem vg-ibanez/homes rfreezefs dir=/home vg-ibanez/jb rfreezefs dir=/mnt/jb .fi .ft P .PP Now: .hP \*o At the .B md/boot line, the default option list for type .B lvm is .B snapsz=5%ORIGIN and the default option list for type .B rfreezefs is .B subtype=lvm .BR snapsz.lvm=5%ORIGIN . .hP \*o The device .B vg-ibanez/scratch has type .B lvm and option list .BR snapsz=5%ORIGIN . .hP \*o The device .B vg-ibanez/db maps to type .B rfreezefs and option list .B subtype=lvm .B snapsz.lvm=5%ORIGIN .B host=roadstar .BR dir=/mnt/db . .hP \*o The device .B vg-ibanez/jb maps to type .B rfreezefs and option list .B subtype=lvm .B snapsz.lvm=5%ORIGIN .B host=roadstar .B host=jem .BR dir=/mnt/db ; but only the latter .B host option is significant \(en the other will be omitted from the list passed to .BR snap.rfreezefs (8). .SH SEE ALSO .BR snap (8) .SH AUTHOR Mark Wooding,