.TH snap 8 "6 November 2011" "distorted.org.uk backup"
.SH NAME
snap \- create and remove snapshot devices
.SH SYNOPSIS
.B snap
.RB [ \-u ]
.RB [ \-c
.IR file ]
.I device
.RI [ key \c
.BI = value
\&...]
.SH DESCRIPTION
The
.B snap
utility manages device-level snapshots in a mechanism-independent way.
It's intended to be used as part of automated filesystem maintenance
activities, such as backups or online filesystem checking.
.PP
The command line options are as follows.
.TP
.B "\-h, \-\-help"
Print a help message to standard output and exit with status zero.
.TP
.B "\-v, \-\-version"
Print the program's version number to standard output and exit with
status zero.
.TP
.BI "\-c, \-\-config-file=" file
Read configuration from
.I
file
rather than
.BR @sysconfdir@/snaptab .
.TP
.B "\-u, \-\-unsnap"
Remove a snapshot, rather than creating a new one.  Strictly speaking,
this just passes the option
.B op=unsnap
to the handler, though the conventional interpretation is to remove the
snapshot.
.SS Operation
An
.B op
option is synthesized from the command-line options.  Specifically, if the
.B \-u
as given, then
.B op=unsnap
is set; otherwise
.B op=snap
is assumed.
.PP
The
.B snap
program looks up the
.I device
in the configuration file \(en either
.B /etc/snaptab
or the
.I file
named by the
.B \-u
option \(en and retrieves a snapshot
.I type
and some options.  See
.BR snaptab (5)
for the details of the file format and the process of constructing the
options list.  The
.I device
is usually the name of a device node, relative to
.BR /dev ,
though specific handler programs may have their own conventions.
.PP
The option list from the configuration file, the synthesized
.B op
option, and the command-line option list, are concatenated, in that
order; then, if the resulting list contains two or more options with the
same
.I key
then only the last is retained.  (The
.I key
is the portion of the option before the first
.RB ` = '
character.)
.PP
Finally, the snapshot handler for the selected
.I type
is invoked, as
.IP
.BI @snaplibexecdir@/snap. type
.I device
.IR key = value
\&...
.SS Handler conventions
Much of the behaviour of
.B snap
is left up to individual type-specific handler programs.  In order to
maintain consistency, the following conventions are adopted.
.PP
Options are processed strictly left-to-right.  Each option is parsed as
.IP
.IR key [\fB. type ]\fB= value
.PP
where the
.I key
and
.I type
do not contain
.RB ` = '
characters, and the
.I type
does not contain a
.RB ` . '
character.  If the
.I type
is omitted, or is equal to the handler's type, then the option is
processed; the
.I type
suffix is otherwise ignored; an error is reported if the
.I key
is unrecognized.  Options bearing a different type are silently ignored.
If the same
.I key
occurs more than once, only the last occurrence is significant.
.PP
Two options are always recognized.
.TP
.B op
Synthesized by the
.B snap
program.  The value is
.B snap
if a snapshot is to be created, or
.B unsnap
if it is to be removed (the
.B \-u
option was given).  It is permissible for handlers to define meanings
for other
.B op
values; unrecognized values are an error.
.TP
.B tag
A short arbitrary string which is assigned to the snapshot to
distinguish it from snapshots created by other clients.  The acceptable
form for the tag may vary with the snapshot type, but alphanumerics and
hyphens are always allowed.  This option may be omitted, though this is
discouraged in scripted use: it is not specified whether this is
equivalent to providing some default tag.
.PP
If the
.B op
is
.B snap
then the handler should print the (full) pathname of the block device
containing the snapshot to standard output, followed by a newline.  If
.B op
is
.B unsnap
then the handler should print nothing to standard output.  Other
.B op
values may cause the handler to produce output at its discretion.
.SH BUGS
The
.B snap
program doesn't even try to handle filesystem-level snapshots, as you'd
get in ZFS or BtrFS.  Trying to do both device- and filesystem-level
snapshots in one program leads to all sorts of difficulties, and it's
probably a mistake to try.  The distinction is still annoying, though.
.SH SEE ALSO
.BR snaptab (5).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>