chiark / gitweb / Fix whitespace errors in definition of `SUBSTVARS'.
[distorted-backup] / lvm-rmsnap.8
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" " backup"
9 lvm-rmsnap \- remove an LVM snapshot, despite LVM bugs
11 .B lvm-rmsnap
12 .RB [ \-dn ]
13 .IB vgname / lvname
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.
119 .BR dmsetup (8),
120 .BR lvm (8),
121 .BR lvremove (8),
122 .BR udev (7).
124 Mark Wooding, <>