configure.ac: Don't let the LIBS setting leak out.

[distorted-backup] / snaptab.5.in

.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, <mdw@distorted.org.uk>