sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget6/translations/zh_CN/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/zh_TW/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/it_IT/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/ja_JP/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/ko_KR/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/pt_BR/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget6/translations/sp_SP/admin-guide/device-mapper/dm-clonemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h%SPDX-License-Identifier: GPL-2.0-onlyh]h%SPDX-License-Identifier: GPL-2.0-only}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhP/var/lib/git/docbuild/linux/Documentation/admin-guide/device-mapper/dm-clone.rsthKubhsection)}(hhh](htitle)}(hdm-cloneh]hdm-clone}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXdm-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.h]hXdm-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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hX^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.h]hX^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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXFor 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.h]hXFor 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hWhen 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.h]hWhen 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hUThe dm-clone target reuses the metadata library used by the thin-provisioning target.h]hUThe dm-clone target reuses the metadata library used by the thin-provisioning target.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hGlossaryh]hGlossary}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj>hhhhhK!ubh block_quote)}(hHydration 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. h]hdefinition_list)}(hhh]hdefinition_list_item)}(hHydration 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. h](hterm)}(h Hydrationh]h Hydration}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1j`hhhK&hj\ubh definition)}(hhh]h)}(hThe 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.h]hThe 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.}(hjuhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK$hjrubah}(h]h ]h"]h$]h&]uh1jphj\ubeh}(h]h ]h"]h$]h&]uh1jZhhhK&hjWubah}(h]h ]h"]h$]h&]uh1jUhjQubah}(h]h ]h"]h$]h&]uh1jOhhhK#hj>hhubh)}(hWOnce a region gets hydrated we redirect all I/O regarding it to the destination device.h]hWOnce a region gets hydrated we redirect all I/O regarding it to the destination device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hj>hhubeh}(h]glossaryah ]h"]glossaryah$]h&]uh1hhhhhhhhK!ubh)}(hhh](h)}(hDesignh]hDesign}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK,ubh)}(hhh](h)}(h Sub-devicesh]h Sub-devices}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK/ubh)}(hfThe target is constructed by passing three devices to it (along with other parameters detailed later):h]hfThe target is constructed by passing three devices to it (along with other parameters detailed later):}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjhhubhenumerated_list)}(hhh](h list_item)}(hUA source device - the read-only device that gets cloned and source of the hydration. h]h)}(hTA source device - the read-only device that gets cloned and source of the hydration.h]hTA source device - the read-only device that gets cloned and source of the hydration.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK4hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hiA destination device - the destination of the hydration, which will become a clone of the source device. h]h)}(hhA destination device - the destination of the hydration, which will become a clone of the source device.h]hhA destination device - the destination of the hydration, which will become a clone of the source device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK7hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(hA 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. h]h)}(hA 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.h]hA 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjhhhhhK4ubh)}(h[The size of the destination device must be at least equal to the size of the source device.h]h[The size of the destination device must be at least equal to the size of the source device.}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK>hjhhubeh}(h] sub-devicesah ]h"] sub-devicesah$]h&]uh1hhjhhhhhK/ubh)}(hhh](h)}(hRegionsh]hRegions}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQhhhhhKBubh)}(hdm-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.h]hdm-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.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhjQhhubh)}(hXThe region size is configurable when you first create the dm-clone device. The recommended region size is the same as the file system block size, which usually is 4KB. The region size must be between 8 sectors (4KB) and 2097152 sectors (1GB) and a power of two.h]hXThe region size is configurable when you first create the dm-clone device. The recommended region size is the same as the file system block size, which usually is 4KB. The region size must be between 8 sectors (4KB) and 2097152 sectors (1GB) and a power of two.}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjQhhubh)}(hSReads and writes from/to hydrated regions are serviced from the destination device.h]hSReads and writes from/to hydrated regions are serviced from the destination device.}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhjQhhubh)}(hPA read to a not yet hydrated region is serviced directly from the source device.h]hPA read to a not yet hydrated region is serviced directly from the source device.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKPhjQhhubh)}(hA write to a not yet hydrated region will be delayed until the corresponding region has been hydrated and the hydration of the region starts immediately.h]hA write to a not yet hydrated region will be delayed until the corresponding region has been hydrated and the hydration of the region starts immediately.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhjQhhubh)}(hNote that a write request with size equal to region size will skip copying of the corresponding region from the source device and overwrite the region of the destination device directly.h]hNote that a write request with size equal to region size will skip copying of the corresponding region from the source device and overwrite the region of the destination device directly.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhjQhhubeh}(h]regionsah ]h"]regionsah$]h&]uh1hhjhhhhhKBubh)}(hhh](h)}(hDiscardsh]hDiscards}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKZubh)}(hXdm-clone interprets a discard request to a range that hasn't been hydrated yet as a hint to skip hydration of the regions covered by the request, i.e., it skips copying the region's data from the source to the destination device, and only updates its metadata.h]hXdm-clone interprets a discard request to a range that hasn’t been hydrated yet as a hint to skip hydration of the regions covered by the request, i.e., it skips copying the region’s data from the source to the destination device, and only updates its metadata.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjhhubh)}(hlIf the destination device supports discards, then by default dm-clone will pass down discard requests to it.h]hlIf the destination device supports discards, then by default dm-clone will pass down discard requests to it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKahjhhubeh}(h]discardsah ]h"]discardsah$]h&]uh1hhjhhhhhKZubh)}(hhh](h)}(hBackground Hydrationh]hBackground Hydration}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKeubh)}(hpdm-clone copies continuously from the source to the destination device, until all of the device has been copied.h]hpdm-clone copies continuously from the source to the destination device, until all of the device has been copied.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKghjhhubh)}(hX;Copying data from the source to the destination device uses bandwidth. The user can set a throttle to prevent more than a certain amount of copying occurring at any one time. Moreover, dm-clone takes into account user I/O traffic going to the devices and pauses the background hydration when there is I/O in-flight.h]hX;Copying data from the source to the destination device uses bandwidth. The user can set a throttle to prevent more than a certain amount of copying occurring at any one time. Moreover, dm-clone takes into account user I/O traffic going to the devices and pauses the background hydration when there is I/O in-flight.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubh)}(hA message `hydration_threshold <#regions>` can be used to set the maximum number of regions being copied, the default being 1 region.h](h A message }(hj hhhNhNubhtitle_reference)}(h `hydration_threshold <#regions>`h]hhydration_threshold <#regions>}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubh[ can be used to set the maximum number of regions being copied, the default being 1 region.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKohjhhubh)}(hXdm-clone employs dm-kcopyd for copying portions of the source device to the destination device. By default, we issue copy requests of size equal to the region size. A message `hydration_batch_size <#regions>` can be used to tune the size of these copy requests. Increasing the hydration batch size results in dm-clone trying to batch together contiguous regions, so we copy the data in batches of this many regions.h](hdm-clone employs dm-kcopyd for copying portions of the source device to the destination device. By default, we issue copy requests of size equal to the region size. A message }(hjBhhhNhNubj))}(h!`hydration_batch_size <#regions>`h]hhydration_batch_size <#regions>}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1j(hjBubh can be used to tune the size of these copy requests. Increasing the hydration batch size results in dm-clone trying to batch together contiguous regions, so we copy the data in batches of this many regions.}(hjBhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(h]When the hydration of the destination device finishes, a dm event will be sent to user space.h]h]When the hydration of the destination device finishes, a dm event will be sent to user space.}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKyhjhhubeh}(h]background-hydrationah ]h"]background hydrationah$]h&]uh1hhjhhhhhKeubh)}(hhh](h)}(hUpdating on-disk metadatah]hUpdating on-disk metadata}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjxhhhhhK}ubh)}(hXYOn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the dm-clone device behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.h]hXYOn-disk metadata is committed every time a FLUSH or FUA bio is written. If no such requests are made then commits will occur every second. This means the dm-clone device behaves like a physical disk that has a volatile write cache. If power is lost you may lose some recent writes. The metadata should always be consistent in spite of any crash.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjxhhubeh}(h]updating-on-disk-metadataah ]h"]updating on-disk metadataah$]h&]uh1hhjhhhhhK}ubeh}(h]designah ]h"]designah$]h&]uh1hhhhhhhhK,ubh)}(hhh](h)}(hTarget Interfaceh]hTarget Interface}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h Constructorh]h Constructor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubjP)}(hXr :: clone [<#feature args> []* [<#core args> []*]] ================ ============================================================== metadata dev Fast device holding the persistent metadata destination dev The destination device, where the source will be cloned source dev Read only device containing the data that gets cloned region size The size of a region in sectors #feature args Number of feature arguments passed feature args no_hydration or no_discard_passdown #core args An even number of arguments corresponding to key/value pairs passed to dm-clone core args Key/value pairs passed to dm-clone, e.g. `hydration_threshold 256` ================ ============================================================== h](jP)}(h:: clone [<#feature args> []* [<#core args> []*]] h]h literal_block)}(hclone [<#feature args> []* [<#core args> []*]]h]hclone [<#feature args> []* [<#core args> []*]]}hjsbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1jOhhhKhjubhtable)}(hhh]htgroup)}(hhh](hcolspec)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK>uh1jhjubhtbody)}(hhh](hrow)}(hhh](hentry)}(hhh]h)}(h metadata devh]h metadata dev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h+Fast device holding the persistent metadatah]h+Fast device holding the persistent metadata}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj*ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(hdestination devh]hdestination dev}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjJubah}(h]h ]h"]h$]h&]uh1jhjGubj)}(hhh]h)}(h7The destination device, where the source will be clonedh]h7The destination device, where the source will be cloned}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjaubah}(h]h ]h"]h$]h&]uh1jhjGubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h source devh]h source dev}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj~ubj)}(hhh]h)}(h5Read only device containing the data that gets clonedh]h5Read only device containing the data that gets cloned}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj~ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h region sizeh]h region size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hThe size of a region in sectorsh]hThe size of a region in sectors}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h #feature argsh]h #feature args}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h"Number of feature arguments passedh]h"Number of feature arguments passed}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h feature argsh]h feature args}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj&ubah}(h]h ]h"]h$]h&]uh1jhj#ubj)}(hhh]h)}(h#no_hydration or no_discard_passdownh]h#no_hydration or no_discard_passdown}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj=ubah}(h]h ]h"]h$]h&]uh1jhj#ubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h #core argsh]h #core args}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj]ubah}(h]h ]h"]h$]h&]uh1jhjZubj)}(hhh]h)}(hOAn even number of arguments corresponding to key/value pairs passed to dm-cloneh]hOAn even number of arguments corresponding to key/value pairs passed to dm-clone}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjtubah}(h]h ]h"]h$]h&]uh1jhjZubeh}(h]h ]h"]h$]h&]uh1j hj ubj )}(hhh](j)}(hhh]h)}(h core argsh]h core args}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hBKey/value pairs passed to dm-clone, e.g. `hydration_threshold 256`h](h)Key/value pairs passed to dm-clone, e.g. }(hjhhhNhNubj))}(h`hydration_threshold 256`h]hhydration_threshold 256}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j(hjubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hj ubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jOhhhKhjhhubh)}(hOptional feature arguments are:h]hOptional feature arguments are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjP)}(hXS==================== ========================================================= no_hydration Create a dm-clone instance with background hydration disabled no_discard_passdown Disable passing down discards to the destination device ==================== ========================================================= h]j)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK9uh1jhjubj)}(hhh](j )}(hhh](j)}(hhh]h)}(h no_hydrationh]h no_hydration}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj!ubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h=Create a dm-clone instance with background hydration disabledh]h=Create a dm-clone instance with background hydration disabled}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj8ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(hno_discard_passdownh]hno_discard_passdown}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXubah}(h]h ]h"]h$]h&]uh1jhjUubj)}(hhh]h)}(h7Disable passing down discards to the destination deviceh]h7Disable passing down discards to the destination device}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjoubah}(h]h ]h"]h$]h&]uh1jhjUubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jOhhhKhjhhubh)}(hOptional core arguments are:h]hOptional core arguments are:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubjP)}(hX================================ ============================================== hydration_threshold <#regions> Maximum number of regions being copied from the source to the destination device at any one time, during background hydration. hydration_batch_size <#regions> During background hydration, try to batch together contiguous regions, so we copy data from the source to the destination device in batches of this many regions. ================================ ============================================== h]j)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthK uh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK.uh1jhjubj)}(hhh](j )}(hhh](j)}(hhh]h)}(hhydration_threshold <#regions>h]hhydration_threshold <#regions>}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h~Maximum number of regions being copied from the source to the destination device at any one time, during background hydration.h]h~Maximum number of regions being copied from the source to the destination device at any one time, during background hydration.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(hhydration_batch_size <#regions>h]hhydration_batch_size <#regions>}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hDuring background hydration, try to batch together contiguous regions, so we copy data from the source to the destination device in batches of this many regions.h]hDuring background hydration, try to batch together contiguous regions, so we copy data from the source to the destination device in batches of this many regions.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj%ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1jOhhhKhjhhubeh}(h] constructorah ]h"] constructorah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hStatush]hStatus}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjchhhhhKubjP)}(hX :: <#used metadata blocks>/<#total metadata blocks> <#hydrated regions>/<#total regions> <#hydrating regions> <#feature args> * <#core args> * ======================= ======================================================= metadata block size Fixed block size for each metadata block in sectors #used metadata blocks Number of metadata blocks used #total metadata blocks Total number of metadata blocks region size Configurable region size for the device in sectors #hydrated regions Number of regions that have finished hydrating #total regions Total number of regions to hydrate #hydrating regions Number of regions currently hydrating #feature args Number of feature arguments to follow feature args Feature arguments, e.g. `no_hydration` #core args Even number of core arguments to follow core args Key/value pairs for tuning the core, e.g. `hydration_threshold 256` clone metadata mode ro if read-only, rw if read-write In serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string 'Fail'. If the metadata mode changes, a dm event will be sent to user space. ======================= ======================================================= h](jP)}(h:: <#used metadata blocks>/<#total metadata blocks> <#hydrated regions>/<#total regions> <#hydrating regions> <#feature args> * <#core args> * h]j)}(h <#used metadata blocks>/<#total metadata blocks> <#hydrated regions>/<#total regions> <#hydrating regions> <#feature args> * <#core args> * h]h <#used metadata blocks>/<#total metadata blocks> <#hydrated regions>/<#total regions> <#hydrating regions> <#feature args> * <#core args> * }hj|sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhjxubah}(h]h ]h"]h$]h&]uh1jOhhhKhjtubj)}(hhh]j)}(hhh](j)}(hhh]h}(h]h ]h"]h$]h&]colwidthKuh1jhjubj)}(hhh]h}(h]h ]h"]h$]h&]colwidthK7uh1jhjubj)}(hhh](j )}(hhh](j)}(hhh]h)}(hmetadata block sizeh]hmetadata block size}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h3Fixed block size for each metadata block in sectorsh]h3Fixed block size for each metadata block in sectors}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h#used metadata blocksh]h#used metadata blocks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hNumber of metadata blocks usedh]hNumber of metadata blocks used}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h#total metadata blocksh]h#total metadata blocks}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(hTotal number of metadata blocksh]hTotal number of metadata blocks}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj5ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h region sizeh]h region size}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjUubah}(h]h ]h"]h$]h&]uh1jhjRubj)}(hhh]h)}(h2Configurable region size for the device in sectorsh]h2Configurable region size for the device in sectors}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjlubah}(h]h ]h"]h$]h&]uh1jhjRubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h#hydrated regionsh]h#hydrated regions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h.Number of regions that have finished hydratingh]h.Number of regions that have finished hydrating}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h#total regionsh]h#total regions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h"Total number of regions to hydrateh]h"Total number of regions to hydrate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h#hydrating regionsh]h#hydrating regions}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubj)}(hhh]h)}(h%Number of regions currently hydratingh]h%Number of regions currently hydrating}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h #feature argsh]h #feature args}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj1 ubah}(h]h ]h"]h$]h&]uh1jhj. ubj)}(hhh]h)}(h%Number of feature arguments to followh]h%Number of feature arguments to follow}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjH ubah}(h]h ]h"]h$]h&]uh1jhj. ubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h feature argsh]h feature args}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjh ubah}(h]h ]h"]h$]h&]uh1jhje ubj)}(hhh]h)}(h&Feature arguments, e.g. `no_hydration`h](hFeature arguments, e.g. }(hj hhhNhNubj))}(h`no_hydration`h]h no_hydration}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhje ubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h #core argsh]h #core args}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(h'Even number of core arguments to followh]h'Even number of core arguments to follow}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(h core argsh]h core args}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubj)}(hhh]h)}(hCKey/value pairs for tuning the core, e.g. `hydration_threshold 256`h](h*Key/value pairs for tuning the core, e.g. }(hj hhhNhNubj))}(h`hydration_threshold 256`h]hhydration_threshold 256}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1j hjubj )}(hhh](j)}(hhh]h)}(hclone metadata modeh]hclone metadata mode}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj) ubah}(h]h ]h"]h$]h&]uh1jhj& ubj)}(hhh](h)}(h!ro if read-only, rw if read-writeh]h!ro if read-only, rw if read-write}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj@ ubh)}(hIn serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string 'Fail'. If the metadata mode changes, a dm event will be sent to user space.h]hIn serious cases where even a read-only mode is deemed unsafe no further I/O will be permitted and the status will just contain the string ‘Fail’. If the metadata mode changes, a dm event will be sent to user space.}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj@ ubeh}(h]h ]h"]h$]h&]uh1jhj& ubeh}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]colsKuh1jhjubah}(h]h ]h"]h$]h&]uh1jhjtubeh}(h]h ]h"]h$]h&]uh1jOhhhKhjchhubeh}(h]statusah ]h"]statusah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hMessagesh]hMessages}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubjP)}(hX=`disable_hydration` Disable the background hydration of the destination device. `enable_hydration` Enable the background hydration of the destination device. `hydration_threshold <#regions>` Set background hydration threshold. `hydration_batch_size <#regions>` Set background hydration batch size. h]jV)}(hhh](j[)}(hP`disable_hydration` Disable the background hydration of the destination device. h](ja)}(h`disable_hydration`h]j))}(hj h]hdisable_hydration}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubah}(h]h ]h"]h$]h&]uh1j`hhhKhj ubjq)}(hhh]h)}(h;Disable the background hydration of the destination device.h]h;Disable the background hydration of the destination device.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jZhhhKhj ubj[)}(hN`enable_hydration` Enable the background hydration of the destination device. h](ja)}(h`enable_hydration`h]j))}(hj h]henable_hydration}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubah}(h]h ]h"]h$]h&]uh1j`hhhKhj ubjq)}(hhh]h)}(h:Enable the background hydration of the destination device.h]h:Enable the background hydration of the destination device.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jZhhhKhj ubj[)}(hE`hydration_threshold <#regions>` Set background hydration threshold. h](ja)}(h `hydration_threshold <#regions>`h]j))}(hj h]hhydration_threshold <#regions>}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hj ubah}(h]h ]h"]h$]h&]uh1j`hhhKhj ubjq)}(hhh]h)}(h#Set background hydration threshold.h]h#Set background hydration threshold.}(hj2 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj/ ubah}(h]h ]h"]h$]h&]uh1jphj ubeh}(h]h ]h"]h$]h&]uh1jZhhhKhj ubj[)}(hG`hydration_batch_size <#regions>` Set background hydration batch size. h](ja)}(h!`hydration_batch_size <#regions>`h]j))}(hjR h]hhydration_batch_size <#regions>}(hjT hhhNhNubah}(h]h ]h"]h$]h&]uh1j(hjP ubah}(h]h ]h"]h$]h&]uh1j`hhhKhjL ubjq)}(hhh]h)}(h$Set background hydration batch size.h]h$Set background hydration batch size.}(hjj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjg ubah}(h]h ]h"]h$]h&]uh1jphjL ubeh}(h]h ]h"]h$]h&]uh1jZhhhKhj ubeh}(h]h ]h"]h$]h&]uh1jUhj ubah}(h]h ]h"]h$]h&]uh1jOhhhKhj hhubeh}(h]messagesah ]h"]messagesah$]h&]uh1hhjhhhhhKubeh}(h]target-interfaceah ]h"]target interfaceah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hExamplesh]hExamples}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hhh](h)}(h'Clone a device containing a file systemh]h'Clone a device containing a file system}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubj)}(hhh](j)}(hCreate the dm-clone device. :: dmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \ $source_dev 8 1 no_hydration" h](h)}(hCreate the dm-clone device.h]hCreate the dm-clone device.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(hjdmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \ $source_dev 8 1 no_hydration"h]hjdmsetup create clone --table "0 1048576000 clone $metadata_dev $dest_dev \ $source_dev 8 1 no_hydration"}hj sbah}(h]h ]h"]h$]h&]hhuh1jhhhKhj ubeh}(h]h ]h"]h$]h&]uh1jhj hhhhhNubj)}(hMount the device and trim the file system. dm-clone interprets the discards sent by the file system and it will not hydrate the unused space. :: mount /dev/mapper/clone /mnt/cloned-fs fstrim /mnt/cloned-fs h](h)}(hMount the device and trim the file system. dm-clone interprets the discards sent by the file system and it will not hydrate the unused space.h]hMount the device and trim the file system. dm-clone interprets the discards sent by the file system and it will not hydrate the unused space.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubj)}(hjjjKjjjQjjjrjjjxj jj]jj jcj j j{ j js j j j jpj u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.