| 1 | .TH snap.lvm 8 "6 November 2011" "distorted.org.uk backup" |
| 2 | .SH NAME |
| 3 | snap.lvm \- snapshot handler for LVM logical volumes |
| 4 | .SH SYNOPSIS |
| 5 | .B snap.lvm |
| 6 | .IB vg-name / lv-name |
| 7 | .IB key = value |
| 8 | \&... |
| 9 | .SH DESCRIPTION |
| 10 | This is a snapshot handler for LVM volumes: see |
| 11 | .BR snap (8) |
| 12 | for more information about how snapshot handlers fit into the overall |
| 13 | system. It creates or removes a snapshot of the logical volume named |
| 14 | .I lv-name |
| 15 | on the volume group |
| 16 | .IR vg-name . |
| 17 | .PP |
| 18 | The following options keys are recognized, either with a |
| 19 | .RB ` .lvm ' |
| 20 | suffix or without. Other keys are reported as errors, unless the key |
| 21 | contains a |
| 22 | .RB ` . ' |
| 23 | character. |
| 24 | .TP |
| 25 | .BI op= op |
| 26 | The |
| 27 | .I op |
| 28 | must be either |
| 29 | .B snap |
| 30 | (the default) to create a snapshot, or |
| 31 | .B unsnap |
| 32 | to remove it. |
| 33 | .TP |
| 34 | .BI tag= tag |
| 35 | The snapshot volume will be named |
| 36 | .IB lv-name . tag \fR. |
| 37 | The default tag is |
| 38 | .BR snap . |
| 39 | It is recommended that scripts always provide a tag identifying their |
| 40 | purpose. |
| 41 | .TP |
| 42 | .BI snapsz= sz |
| 43 | The size to allocate for the snapshot's backing store. This may be an |
| 44 | absolute size followed by an optional unit suffix |
| 45 | .RB ` K ', |
| 46 | .RB ` M ', |
| 47 | .RB ` T ', |
| 48 | .RB ` P ', |
| 49 | or |
| 50 | .RB ` E ' |
| 51 | for kilobytes, megabytes (the default), terabytes, petabytes, or |
| 52 | exabytes, respectively; or a relative size of the form |
| 53 | .IB n % what \fR, |
| 54 | where |
| 55 | .I what |
| 56 | is |
| 57 | .BR VG , |
| 58 | .BR FREE , |
| 59 | or |
| 60 | .BR ORIGIN , |
| 61 | to request |
| 62 | .IR n % |
| 63 | of the total space in the volume group, the free space remaining in the |
| 64 | volume group, or the size of the origin volume, respectively. (The |
| 65 | .I what |
| 66 | suffix may be abbreviated to just the first letter; the suffixes are not |
| 67 | case-sensitive in either case.) |
| 68 | .SH BUGS |
| 69 | The LVM tools are rather buggy, and exhibit nasty races with |
| 70 | .B udev (8). |
| 71 | The |
| 72 | .BR lvremove (8) |
| 73 | tool is particularly awful. |
| 74 | The |
| 75 | .B snap.lvm |
| 76 | handler uses |
| 77 | .BR lvm-rmsnap (8) |
| 78 | to work around these bugs. |
| 79 | .PP |
| 80 | If you make a snapshot of a logical volume while a filesystem is |
| 81 | directly mounted from the logical volume on the same machine, and the |
| 82 | filesystem kernel driver implements the |
| 83 | .B freeze_fs |
| 84 | and |
| 85 | .B unfreeze_fs |
| 86 | superblock operations, then the kernel will arrange for the snapshot to |
| 87 | contain a consistent and clean snapshot of the filesystem \(en in |
| 88 | particular, it shouldn't need the ministrations of |
| 89 | .BR fsck (8). |
| 90 | If the filesystem is mounted by a different machine, e.g., a guest |
| 91 | running on the same host, or via a network block-device access protocol, |
| 92 | you will need to negotiate with the remote machine in order to obtain a |
| 93 | clean snapshot. See |
| 94 | .BR snap.rfreezefs (8) |
| 95 | for a snapshot handler which copes with this, and |
| 96 | .BR rfreezefs (8) |
| 97 | for the actual machinery. |
| 98 | .SH SEE ALSO |
| 99 | .BR snap (8), |
| 100 | .BR lvm (8), |
| 101 | .BR lvm-rmsnap (8), |
| 102 | .BR rfreezefs (8). |
| 103 | .SH AUTHOR |
| 104 | Mark Wooding, <mdw@distorted.org.uk> |