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

Source file repositories/reference/linux-study-clean/Documentation/admin-guide/device-mapper/dm-clone.rst

File Facts

System
Linux kernel
Corpus path
Documentation/admin-guide/device-mapper/dm-clone.rst
Extension
.rst
Size
13154 bytes
Lines
334
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0-only

========
dm-clone
========

Introduction
============

dm-clone is a device mapper target which produces a one-to-one copy of an
existing, read-only source device into a writable destination device: It
presents a virtual block device which makes all data appear immediately, and
redirects reads and writes accordingly.

The main use case of dm-clone is to clone a potentially remote, high-latency,
read-only, archival-type block device into a writable, fast, primary-type device
for fast, low-latency I/O. The cloned device is visible/mountable immediately
and the copy of the source device to the destination device happens in the
background, in parallel with user I/O.

For example, one could restore an application backup from a read-only copy,
accessible through a network storage protocol (NBD, Fibre Channel, iSCSI, AoE,
etc.), into a local SSD or NVMe device, and start using the device immediately,
without waiting for the restore to complete.

When the cloning completes, the dm-clone table can be removed altogether and be
replaced, e.g., by a linear table, mapping directly to the destination device.

The dm-clone target reuses the metadata library used by the thin-provisioning
target.

Glossary
========

   Hydration
     The process of filling a region of the destination device with data from
     the same region of the source device, i.e., copying the region from the
     source to the destination device.

Once a region gets hydrated we redirect all I/O regarding it to the destination
device.

Design
======

Sub-devices
-----------

The target is constructed by passing three devices to it (along with other
parameters detailed later):

1. A source device - the read-only device that gets cloned and source of the
   hydration.

2. A destination device - the destination of the hydration, which will become a
   clone of the source device.

3. A small metadata device - it records which regions are already valid in the
   destination device, i.e., which regions have already been hydrated, or have
   been written to directly, via user I/O.

The size of the destination device must be at least equal to the size of the
source device.

Regions
-------

dm-clone divides the source and destination devices in fixed sized regions.
Regions are the unit of hydration, i.e., the minimum amount of data copied from
the source to the destination device.

Annotation

Implementation Notes