admin-guide/device-mapper/dm-clone.rst

1 .. SPDX-License-Identifier: GPL-2.0-only
4 dm-clone
10 dm-clone is a device mapper target which produces a one-to-one copy of an
11 existing, read-only source device into a writable destination device: It
12 presents a virtual block device which makes all data appear immediately, and
15 The main use case of dm-clone is to clone a potentially remote, high-latency,
16 read-only, archival-type block device into a writable, fast, primary-type device
17 for fast, low-latency I/O. The cloned device is visible/mountable immediately
19 background, in parallel with user I/O.
21 For example, one could restore an application backup from a read-only copy,
26 When the cloning completes, the dm-clone table can be removed altogether and be
29 The dm-clone target reuses the metadata library used by the thin-provisioning
37      the same region of the source device, i.e., copying the region from the
40 Once a region gets hydrated we redirect all I/O regarding it to the destination
46 Sub-devices
47 -----------
52 1. A source device - the read-only device that gets cloned and source of the
55 2. A destination device - the destination of the hydration, which will become a
58 3. A small metadata device - it records which regions are already valid in the
59    destination device, i.e., which regions have already been hydrated, or have
60    been written to directly, via user I/O.
62 The size of the destination device must be at least equal to the size of the
66 -------
68 dm-clone divides the source and destination devices in fixed sized regions.
69 Regions are the unit of hydration, i.e., the minimum amount of data copied from
72 The region size is configurable when you first create the dm-clone device. The
73 recommended region size is the same as the file system block size, which usually
74 is 4KB. The region size must be between 8 sectors (4KB) and 2097152 sectors
85 Note that a write request with size equal to region size will skip copying of
90 --------
92 dm-clone interprets a discard request to a range that hasn't been hydrated yet
93 as a hint to skip hydration of the regions covered by the request, i.e., it
97 If the destination device supports discards, then by default dm-clone will pass
101 --------------------
103 dm-clone copies continuously from the source to the destination device, until
108 any one time. Moreover, dm-clone takes into account user I/O traffic going to
109 the devices and pauses the background hydration when there is I/O in-flight.
114 dm-clone employs dm-kcopyd for copying portions of the source device to the
115 destination device. By default, we issue copy requests of size equal to the
116 region size. A message `hydration_batch_size <#regions>` can be used to tune the
117 size of these copy requests. Increasing the hydration batch size results in
118 dm-clone trying to batch together contiguous regions, so we copy the data in
124 Updating on-disk metadata
125 -------------------------
127 On-disk metadata is committed every time a FLUSH or FUA bio is written. If no
129 dm-clone device behaves like a physical disk that has a volatile write cache. If
137 -----------
141    clone <metadata dev> <destination dev> <source dev> <region size>
148  region size      The size of a region in sectors
154                   passed to dm-clone
155  core args        Key/value pairs passed to dm-clone, e.g. `hydration_threshold
162  no_hydration         Create a dm-clone instance with background hydration
180 ------
184    <metadata block size> <#used metadata blocks>/<#total metadata blocks>
185    <region size> <#hydrated regions>/<#total regions> <#hydrating regions>
190  metadata block size     Fixed block size for each metadata block in sectors
193  region size             Configurable region size for the device in sectors
202  clone metadata mode     ro if read-only, rw if read-write
204                          In serious cases where even a read-only mode is deemed
205                          unsafe no further I/O will be permitted and the status
211 --------
223       Set background hydration batch size.
229 ---------------------------------------
231 1. Create the dm-clone device.
235     dmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \
238 2. Mount the device and trim the file system. dm-clone interprets the discards
243     mount /dev/mapper/clone /mnt/cloned-fs
244     fstrim /mnt/cloned-fs
252 4. When the hydration finishes, we can replace the dm-clone table with a linear
258     dmsetup load clone --table "0 1048576000 linear $dest_dev 0"
267 1. We redirect reads, to not-yet-hydrated regions, to the source device. If
271    rely on the page cache to cache these regions, so we hopefully don't end up
274 2. Release in-core resources, i.e., the bitmaps tracking which regions are
286 We explored the following alternatives before implementing dm-clone:
288 1. Use dm-cache with cache size equal to the source device and implement a new
291    * The resulting cache device is not a one-to-one mirror of the source device
292      and thus we cannot remove the cache device once cloning completes.
294    * dm-cache writes to the source device, which violates our requirement that
295      the source device must be treated as read-only.
299 2. Use dm-snapshot with a COW device equal to the source device:
301    * dm-snapshot stores its metadata in the COW device, so the resulting device
302      is not a one-to-one mirror of the source device.
306    * dm-snapshot needs to commit its metadata whenever a pending exception
309      or FUA bio is written, or periodically, like dm-thin and dm-cache do. This
312 3. Use dm-mirror: The mirror target has a background copying/mirroring
314    the source device must be treated as read-only.
316 4. Use dm-thin's external snapshot functionality. This approach is the most
317    promising among all alternatives, as the thinly-provisioned volume is a
318    one-to-one mirror of the source device and handles reads and writes to
319    un-provisioned/not-yet-cloned areas the same way as dm-clone does.
325    * Most importantly, we want to support arbitrary block devices as the
327      thinly-provisioned volumes. Thin-provisioning has an inherent metadata
331    Moreover, cloning a device shouldn't force the use of thin-provisioning. On
333    LV as dm-clone's destination device.