.TH snap.lvm 8 "6 November 2011" "distorted.org.uk backup"
.SH NAME
snap.lvm \- snapshot handler for LVM logical volumes
.SH SYNOPSIS
.B snap.lvm
.IB vg-name / lv-name
.IB key = value
\&...
.SH DESCRIPTION
This is a snapshot handler for LVM volumes: see
.BR snap (8)
for more information about how snapshot handlers fit into the overall
system.  It creates or removes a snapshot of the logical volume named
.I lv-name
on the volume group
.IR vg-name .
.PP
The following options keys are recognized, either with a
.RB ` .lvm '
suffix or without.  Other keys are reported as errors, unless the key
contains a
.RB ` . '
character.
.TP
.BI op= op
The
.I op
must be either
.B snap
(the default) to create a snapshot, or
.B unsnap
to remove it.
.TP
.BI tag= tag
The snapshot volume will be named
.IB lv-name . tag \fR.
The default tag is
.BR snap .
It is recommended that scripts always provide a tag identifying their
purpose.
.TP
.BI snapsz= sz
The size to allocate for the snapshot's backing store.  This may be an
absolute size followed by an optional unit suffix
.RB ` K ',
.RB ` M ',
.RB ` T ',
.RB ` P ',
or
.RB ` E '
for kilobytes, megabytes (the default), terabytes, petabytes, or
exabytes, respectively; or a relative size of the form
.IB n % what \fR,
where
.I what
is
.BR VG ,
.BR FREE ,
or
.BR ORIGIN ,
to request
.IR n %
of the total space in the volume group, the free space remaining in the
volume group, or the size of the origin volume, respectively.  (The
.I what
suffix may be abbreviated to just the first letter; the suffixes are not
case-sensitive in either case.)
.SH BUGS
The LVM tools are rather buggy, and exhibit nasty races with
.B udev (8).
The
.BR lvremove (8)
tool is particularly awful.
The
.B snap.lvm
handler uses
.BR lvm-rmsnap (8)
to work around these bugs.
.PP
If you make a snapshot of a logical volume while a filesystem is
directly mounted from the logical volume on the same machine, and the
filesystem kernel driver implements the
.B freeze_fs
and
.B unfreeze_fs
superblock operations, then the kernel will arrange for the snapshot to
contain a consistent and clean snapshot of the filesystem \(en in
particular, it shouldn't need the ministrations of
.BR fsck (8).
If the filesystem is mounted by a different machine, e.g., a guest
running on the same host, or via a network block-device access protocol,
you will need to negotiate with the remote machine in order to obtain a
clean snapshot.  See
.BR snap.rfreezefs (8)
for a snapshot handler which copes with this, and
.BR rfreezefs (8)
for the actual machinery.
.SH SEE ALSO
.BR snap (8),
.BR lvm (8),
.BR lvm-rmsnap (8),
.BR rfreezefs (8).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>