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