[distorted-backup] / lvm-rmsnap.8

.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>
Commit	Line	Data
99248ed2 MW	1	.ie t .ds o \(bu
	2	.el .ds o o
	3	.de hP
	4	.IP
	5	\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
	6	..
	7	.TH lvm-rmsnap 8 "6 November 2011" "distorted.org.uk backup"
	8	.SH NAME
	9	lvm-rmsnap \- remove an LVM snapshot, despite LVM bugs
	10	.SH SYNOPSIS
	11	.B lvm-rmsnap
	12	.RB [ \-dn ]
	13	.IB vgname / lvname
	14	.SH DESCRIPTION
	15	The
	16	.B lvm-rmsnap
	17	tool removes an LVM snapshot volume. The command
	18	.IP
	19	.BI "lvm-rmsnap " vgname / lvname
	20	.PP
	21	does what you'd hope, in an ideal world,
	22	.IP
	23	.BI "lvremove \-f " vgname / lvname
	24	.PP
	25	would do. (Yes,
	26	.B lvm-rmsnap
	27	doesn't prompt if the snapshot is active. There are LVM bugs which
	28	prevent you from deactivating the snapshot, and this tool is intended to
	29	be used in noninteractive scripts.)
	30	.PP
	31	Unfortunately, the world is not ideal, and trying to remove snapshots
	32	using current versions of LVM runs into a collection of nasty race
	33	conditions with
	34	.BR udev (7).
	35	The purpose of
	36	.B lvm-rmsnap
	37	is to remove snapshots despite these bugs. It acts as a `nanny' for
	38	.BR lvremove ,
	39	carefully tracking all of the toys, and putting them back in the pram.
	40	.SS "Command line"
	41	The following command-line options are accepted.
	42	.TP
	43	.B "\-h, \-\-help"
	44	Print a help message to standard output and exit with status zero.
	45	.TP
	46	.B "\-v, \-\-version"
	47	Print the program's version number to standard output and exit with
	48	status zero.
	49	.TP
	50	.B "\-d, \-\-debug"
	51	Print to standard error information about what the program is doing and
	52	what things it's found out. This may be useful if you're trying to find
	53	out why
	54	.B lvm-rmsnap
	55	is misbehaving.
	56	.TP
	57	.B "\-n, \-\-noact"
	58	Don't actually perform corrective actions. This is pretty useless
	59	without
	60	.BR \-d .
	61	You probably don't want to use this unless you're testing
	62	.BR lvm-rmsnap .
	63	.SS "Operation"
	64	The basic problem with
65	.BR lvremove (8)
66	is that, partway through, it discovers that some device it was about to
67	fiddle with is currently in use by some other process \(en usually
68	invoked by a
69	.BR udev (7)
70	rule \(en and then gives up, leaving things in a messed-up state.
71	There's an elaborate and wobbly synchronization protocol which involves
72	passing System V semaphore set ids through the kernel and is meant to
73	make stuff like this not go wrong, but it does anyway.
74	.PP
75	The job of
76	.B lvm-rmsnap
77	is to remove a snapshot despite these bugs. Usually, repeating the
78	.B lvremove
79	attempt will succeed, though there's often debris of various kinds to be
80	cleared away. Here's a list of the things that
81	.B lvm-rmsnap
82	tries to do.
83	.hP \*o
84	If you're very unlucky, then LVM will leave the snapshot origin volume
85	suspended, which will cause a subsequent
86	.B lvremove
87	attempt to wedge itself (and block any other processes trying to do I/O
88	to that volume). So
89	.B lvm-rmsnap
90	resumes the volume before retrying.
91	.hP \*o
92	A failed
93	.B lvremove
94	can leak `cookies', which are really System V semaphore sets. These use
95	up kernel memory, and can't be automatically garbage-collected (this is
96	a well-known mistake in the System V IPC design). So
97	.B lvm-rmsnap
98	keeps track of the cookies used, and releases them if
99	.B lvmremove
100	failed to do so.
101	.hP \*o
102	Setting up a snapshot involves a little juggle: a new
103	.RB ` real '
104	device is created, exactly like the origin volume; and then the origin
105	volume is changed to be a
106	.B snapshot-origin
107	volume pointing at the new device. When
108	.B lvremove
109	fails, the
110	.RB ` real '
111	device can be left behind. So
112	.B lvm-rmsnap
113	detects this situation and removes it, after checking that it really
114	isn't needed for anything.
115	.SH BUGS
116	If you know of an LVM snapshot-removal bug which this won't work around
117	then please let the author know.
118	.SH SEE ALSO
119	.BR dmsetup (8),
120	.BR lvm (8),
121	.BR lvremove (8),
122	.BR udev (7).
123	.SH AUTHOR
124	Mark Wooding, <mdw@distorted.org.uk>