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> |