0001 ==============================
0002 Device-mapper snapshot support
0003 ==============================
0004
0005 Device-mapper allows you, without massive data copying:
0006
0007 - To create snapshots of any block device i.e. mountable, saved states of
0008 the block device which are also writable without interfering with the
0009 original content;
0010 - To create device "forks", i.e. multiple different versions of the
0011 same data stream.
0012 - To merge a snapshot of a block device back into the snapshot's origin
0013 device.
0014
0015 In the first two cases, dm copies only the chunks of data that get
0016 changed and uses a separate copy-on-write (COW) block device for
0017 storage.
0018
0019 For snapshot merge the contents of the COW storage are merged back into
0020 the origin device.
0021
0022
0023 There are three dm targets available:
0024 snapshot, snapshot-origin, and snapshot-merge.
0025
0026 - snapshot-origin <origin>
0027
0028 which will normally have one or more snapshots based on it.
0029 Reads will be mapped directly to the backing device. For each write, the
0030 original data will be saved in the <COW device> of each snapshot to keep
0031 its visible content unchanged, at least until the <COW device> fills up.
0032
0033
0034 - snapshot <origin> <COW device> <persistent?> <chunksize>
0035 [<# feature args> [<arg>]*]
0036
0037 A snapshot of the <origin> block device is created. Changed chunks of
0038 <chunksize> sectors will be stored on the <COW device>. Writes will
0039 only go to the <COW device>. Reads will come from the <COW device> or
0040 from <origin> for unchanged data. <COW device> will often be
0041 smaller than the origin and if it fills up the snapshot will become
0042 useless and be disabled, returning errors. So it is important to monitor
0043 the amount of free space and expand the <COW device> before it fills up.
0044
0045 <persistent?> is P (Persistent) or N (Not persistent - will not survive
0046 after reboot). O (Overflow) can be added as a persistent store option
0047 to allow userspace to advertise its support for seeing "Overflow" in the
0048 snapshot status. So supported store types are "P", "PO" and "N".
0049
0050 The difference between persistent and transient is with transient
0051 snapshots less metadata must be saved on disk - they can be kept in
0052 memory by the kernel.
0053
0054 When loading or unloading the snapshot target, the corresponding
0055 snapshot-origin or snapshot-merge target must be suspended. A failure to
0056 suspend the origin target could result in data corruption.
0057
0058 Optional features:
0059
0060 discard_zeroes_cow - a discard issued to the snapshot device that
0061 maps to entire chunks to will zero the corresponding exception(s) in
0062 the snapshot's exception store.
0063
0064 discard_passdown_origin - a discard to the snapshot device is passed
0065 down to the snapshot-origin's underlying device. This doesn't cause
0066 copy-out to the snapshot exception store because the snapshot-origin
0067 target is bypassed.
0068
0069 The discard_passdown_origin feature depends on the discard_zeroes_cow
0070 feature being enabled.
0071
0072
0073 - snapshot-merge <origin> <COW device> <persistent> <chunksize>
0074 [<# feature args> [<arg>]*]
0075
0076 takes the same table arguments as the snapshot target except it only
0077 works with persistent snapshots. This target assumes the role of the
0078 "snapshot-origin" target and must not be loaded if the "snapshot-origin"
0079 is still present for <origin>.
0080
0081 Creates a merging snapshot that takes control of the changed chunks
0082 stored in the <COW device> of an existing snapshot, through a handover
0083 procedure, and merges these chunks back into the <origin>. Once merging
0084 has started (in the background) the <origin> may be opened and the merge
0085 will continue while I/O is flowing to it. Changes to the <origin> are
0086 deferred until the merging snapshot's corresponding chunk(s) have been
0087 merged. Once merging has started the snapshot device, associated with
0088 the "snapshot" target, will return -EIO when accessed.
0089
0090
0091 How snapshot is used by LVM2
0092 ============================
0093 When you create the first LVM2 snapshot of a volume, four dm devices are used:
0094
0095 1) a device containing the original mapping table of the source volume;
0096 2) a device used as the <COW device>;
0097 3) a "snapshot" device, combining #1 and #2, which is the visible snapshot
0098 volume;
0099 4) the "original" volume (which uses the device number used by the original
0100 source volume), whose table is replaced by a "snapshot-origin" mapping
0101 from device #1.
0102
0103 A fixed naming scheme is used, so with the following commands::
0104
0105 lvcreate -L 1G -n base volumeGroup
0106 lvcreate -L 100M --snapshot -n snap volumeGroup/base
0107
0108 we'll have this situation (with volumes in above order)::
0109
0110 # dmsetup table|grep volumeGroup
0111
0112 volumeGroup-base-real: 0 2097152 linear 8:19 384
0113 volumeGroup-snap-cow: 0 204800 linear 8:19 2097536
0114 volumeGroup-snap: 0 2097152 snapshot 254:11 254:12 P 16
0115 volumeGroup-base: 0 2097152 snapshot-origin 254:11
0116
0117 # ls -lL /dev/mapper/volumeGroup-*
0118 brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
0119 brw------- 1 root root 254, 12 29 ago 18:15 /dev/mapper/volumeGroup-snap-cow
0120 brw------- 1 root root 254, 13 29 ago 18:15 /dev/mapper/volumeGroup-snap
0121 brw------- 1 root root 254, 10 29 ago 18:14 /dev/mapper/volumeGroup-base
0122
0123
0124 How snapshot-merge is used by LVM2
0125 ==================================
0126 A merging snapshot assumes the role of the "snapshot-origin" while
0127 merging. As such the "snapshot-origin" is replaced with
0128 "snapshot-merge". The "-real" device is not changed and the "-cow"
0129 device is renamed to <origin name>-cow to aid LVM2's cleanup of the
0130 merging snapshot after it completes. The "snapshot" that hands over its
0131 COW device to the "snapshot-merge" is deactivated (unless using lvchange
0132 --refresh); but if it is left active it will simply return I/O errors.
0133
0134 A snapshot will merge into its origin with the following command::
0135
0136 lvconvert --merge volumeGroup/snap
0137
0138 we'll now have this situation::
0139
0140 # dmsetup table|grep volumeGroup
0141
0142 volumeGroup-base-real: 0 2097152 linear 8:19 384
0143 volumeGroup-base-cow: 0 204800 linear 8:19 2097536
0144 volumeGroup-base: 0 2097152 snapshot-merge 254:11 254:12 P 16
0145
0146 # ls -lL /dev/mapper/volumeGroup-*
0147 brw------- 1 root root 254, 11 29 ago 18:15 /dev/mapper/volumeGroup-base-real
0148 brw------- 1 root root 254, 12 29 ago 18:16 /dev/mapper/volumeGroup-base-cow
0149 brw------- 1 root root 254, 10 29 ago 18:16 /dev/mapper/volumeGroup-base
0150
0151
0152 How to determine when a merging is complete
0153 ===========================================
0154 The snapshot-merge and snapshot status lines end with:
0155
0156 <sectors_allocated>/<total_sectors> <metadata_sectors>
0157
0158 Both <sectors_allocated> and <total_sectors> include both data and metadata.
0159 During merging, the number of sectors allocated gets smaller and
0160 smaller. Merging has finished when the number of sectors holding data
0161 is zero, in other words <sectors_allocated> == <metadata_sectors>.
0162
0163 Here is a practical example (using a hybrid of lvm and dmsetup commands)::
0164
0165 # lvs
0166 LV VG Attr LSize Origin Snap% Move Log Copy% Convert
0167 base volumeGroup owi-a- 4.00g
0168 snap volumeGroup swi-a- 1.00g base 18.97
0169
0170 # dmsetup status volumeGroup-snap
0171 0 8388608 snapshot 397896/2097152 1560
0172 ^^^^ metadata sectors
0173
0174 # lvconvert --merge -b volumeGroup/snap
0175 Merging of volume snap started.
0176
0177 # lvs volumeGroup/snap
0178 LV VG Attr LSize Origin Snap% Move Log Copy% Convert
0179 base volumeGroup Owi-a- 4.00g 17.23
0180
0181 # dmsetup status volumeGroup-base
0182 0 8388608 snapshot-merge 281688/2097152 1104
0183
0184 # dmsetup status volumeGroup-base
0185 0 8388608 snapshot-merge 180480/2097152 712
0186
0187 # dmsetup status volumeGroup-base
0188 0 8388608 snapshot-merge 16/2097152 16
0189
0190 Merging has finished.
0191
0192 ::
0193
0194 # lvs
0195 LV VG Attr LSize Origin Snap% Move Log Copy% Convert
0196 base volumeGroup owi-a- 4.00g
