.ie t .ds o \(bu
.el .ds o o
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.TH lvm-rmsnap 8 "6 November 2011" "distorted.org.uk backup"
.SH NAME
lvm-rmsnap \- remove an LVM snapshot, despite LVM bugs
.SH SYNOPSIS
.B lvm-rmsnap
.RB [ \-dn ]
.IB vgname / lvname
.SH DESCRIPTION
The
.B lvm-rmsnap
tool removes an LVM snapshot volume.  The command
.IP
.BI "lvm-rmsnap " vgname / lvname
.PP
does what you'd hope, in an ideal world,
.IP
.BI "lvremove \-f " vgname / lvname
.PP
would do.  (Yes,
.B lvm-rmsnap
doesn't prompt if the snapshot is active.  There are LVM bugs which
prevent you from deactivating the snapshot, and this tool is intended to
be used in noninteractive scripts.)
.PP
Unfortunately, the world is not ideal, and trying to remove snapshots
using current versions of LVM runs into a collection of nasty race
conditions with
.BR udev (7).
The purpose of
.B lvm-rmsnap
is to remove snapshots despite these bugs.  It acts as a `nanny' for
.BR lvremove ,
carefully tracking all of the toys, and putting them back in the pram.
.SS "Command line"
The following command-line options are accepted.
.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
.B "\-d, \-\-debug"
Print to standard error information about what the program is doing and
what things it's found out.  This may be useful if you're trying to find
out why
.B lvm-rmsnap
is misbehaving.
.TP
.B "\-n, \-\-noact"
Don't actually perform corrective actions.  This is pretty useless
without
.BR \-d .
You probably don't want to use this unless you're testing
.BR lvm-rmsnap .
.SS "Operation"
The basic problem with
.BR lvremove (8)
is that, partway through, it discovers that some device it was about to
fiddle with is currently in use by some other process \(en usually
invoked by a
.BR udev (7)
rule \(en and then gives up, leaving things in a messed-up state.
There's an elaborate and wobbly synchronization protocol which involves
passing System V semaphore set ids through the kernel and is meant to
make stuff like this not go wrong, but it does anyway.
.PP
The job of
.B lvm-rmsnap
is to remove a snapshot despite these bugs.  Usually, repeating the
.B lvremove
attempt will succeed, though there's often debris of various kinds to be
cleared away.  Here's a list of the things that
.B lvm-rmsnap
tries to do.
.hP \*o
If you're very unlucky, then LVM will leave the snapshot origin volume
suspended, which will cause a subsequent
.B lvremove
attempt to wedge itself (and block any other processes trying to do I/O
to that volume).  So
.B lvm-rmsnap
resumes the volume before retrying.
.hP \*o
A failed
.B lvremove
can leak `cookies', which are really System V semaphore sets.  These use
up kernel memory, and can't be automatically garbage-collected (this is
a well-known mistake in the System V IPC design).  So
.B lvm-rmsnap
keeps track of the cookies used, and releases them if
.B lvmremove
failed to do so.
.hP \*o
Setting up a snapshot involves a little juggle: a new 
.RB ` real '
device is created, exactly like the origin volume; and then the origin
volume is changed to be a
.B snapshot-origin
volume pointing at the new device.  When
.B lvremove
fails, the
.RB ` real '
device can be left behind.  So
.B lvm-rmsnap
detects this situation and removes it, after checking that it really
isn't needed for anything.
.SH BUGS
If you know of an LVM snapshot-removal bug which this won't work around
then please let the author know.
.SH SEE ALSO
.BR dmsetup (8),
.BR lvm (8),
.BR lvremove (8),
.BR udev (7).
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>