1 .. SPDX-License-Identifier: GPL-2.0-only
2
3 ========
4 dm-clone
5 ========
6
7 Introduction
8 ============
9
10 dm-clone is a device mapper target which produ
11 existing, read-only source device into a writa
12 presents a virtual block device which makes al
13 redirects reads and writes accordingly.
14
15 The main use case of dm-clone is to clone a po
16 read-only, archival-type block device into a w
17 for fast, low-latency I/O. The cloned device i
18 and the copy of the source device to the desti
19 background, in parallel with user I/O.
20
21 For example, one could restore an application
22 accessible through a network storage protocol
23 etc.), into a local SSD or NVMe device, and st
24 without waiting for the restore to complete.
25
26 When the cloning completes, the dm-clone table
27 replaced, e.g., by a linear table, mapping dir
28
29 The dm-clone target reuses the metadata librar
30 target.
31
32 Glossary
33 ========
34
35 Hydration
36 The process of filling a region of the de
37 the same region of the source device, i.e
38 source to the destination device.
39
40 Once a region gets hydrated we redirect all I/
41 device.
42
43 Design
44 ======
45
46 Sub-devices
47 -----------
48
49 The target is constructed by passing three dev
50 parameters detailed later):
51
52 1. A source device - the read-only device that
53 hydration.
54
55 2. A destination device - the destination of t
56 clone of the source device.
57
58 3. A small metadata device - it records which
59 destination device, i.e., which regions hav
60 been written to directly, via user I/O.
61
62 The size of the destination device must be at
63 source device.
64
65 Regions
66 -------
67
68 dm-clone divides the source and destination de
69 Regions are the unit of hydration, i.e., the m
70 the source to the destination device.
71
72 The region size is configurable when you first
73 recommended region size is the same as the fil
74 is 4KB. The region size must be between 8 sect
75 (1GB) and a power of two.
76
77 Reads and writes from/to hydrated regions are
78 device.
79
80 A read to a not yet hydrated region is service
81
82 A write to a not yet hydrated region will be d
83 region has been hydrated and the hydration of
84
85 Note that a write request with size equal to r
86 the corresponding region from the source devic
87 destination device directly.
88
89 Discards
90 --------
91
92 dm-clone interprets a discard request to a ran
93 as a hint to skip hydration of the regions cov
94 skips copying the region's data from the sourc
95 only updates its metadata.
96
97 If the destination device supports discards, t
98 down discard requests to it.
99
100 Background Hydration
101 --------------------
102
103 dm-clone copies continuously from the source t
104 all of the device has been copied.
105
106 Copying data from the source to the destinatio
107 can set a throttle to prevent more than a cert
108 any one time. Moreover, dm-clone takes into ac
109 the devices and pauses the background hydratio
110
111 A message `hydration_threshold <#regions>` can
112 of regions being copied, the default being 1 r
113
114 dm-clone employs dm-kcopyd for copying portion
115 destination device. By default, we issue copy
116 region size. A message `hydration_batch_size <
117 size of these copy requests. Increasing the hy
118 dm-clone trying to batch together contiguous r
119 batches of this many regions.
120
121 When the hydration of the destination device f
122 to user space.
123
124 Updating on-disk metadata
125 -------------------------
126
127 On-disk metadata is committed every time a FLU
128 such requests are made then commits will occur
129 dm-clone device behaves like a physical disk t
130 power is lost you may lose some recent writes.
131 consistent in spite of any crash.
132
133 Target Interface
134 ================
135
136 Constructor
137 -----------
138
139 ::
140
141 clone <metadata dev> <destination dev> <sou
142 [<#feature args> [<feature arg>]* [<#
143
144 ================ ============================
145 metadata dev Fast device holding the pers
146 destination dev The destination device, wher
147 source dev Read only device containing
148 region size The size of a region in sect
149
150 #feature args Number of feature arguments
151 feature args no_hydration or no_discard_p
152
153 #core args An even number of arguments
154 passed to dm-clone
155 core args Key/value pairs passed to dm
156 256`
157 ================ ============================
158
159 Optional feature arguments are:
160
161 ==================== ========================
162 no_hydration Create a dm-clone instan
163 disabled
164 no_discard_passdown Disable passing down dis
165 ==================== ========================
166
167 Optional core arguments are:
168
169 ================================ ============
170 hydration_threshold <#regions> Maximum numb
171 the source t
172 one time, du
173 hydration_batch_size <#regions> During backg
174 together con
175 from the sou
176 batches of t
177 ================================ ============
178
179 Status
180 ------
181
182 ::
183
184 <metadata block size> <#used metadata block
185 <region size> <#hydrated regions>/<#total r
186 <#feature args> <feature args>* <#core args
187 <clone metadata mode>
188
189 ======================= =====================
190 metadata block size Fixed block size for
191 #used metadata blocks Number of metadata bl
192 #total metadata blocks Total number of metad
193 region size Configurable region s
194 #hydrated regions Number of regions tha
195 #total regions Total number of regio
196 #hydrating regions Number of regions cur
197 #feature args Number of feature arg
198 feature args Feature arguments, e.
199 #core args Even number of core a
200 core args Key/value pairs for t
201 `hydration_threshold
202 clone metadata mode ro if read-only, rw i
203
204 In serious cases wher
205 unsafe no further I/O
206 will just contain the
207 mode changes, a dm ev
208 ======================= =====================
209
210 Messages
211 --------
212
213 `disable_hydration`
214 Disable the background hydration of the
215
216 `enable_hydration`
217 Enable the background hydration of the d
218
219 `hydration_threshold <#regions>`
220 Set background hydration threshold.
221
222 `hydration_batch_size <#regions>`
223 Set background hydration batch size.
224
225 Examples
226 ========
227
228 Clone a device containing a file system
229 ---------------------------------------
230
231 1. Create the dm-clone device.
232
233 ::
234
235 dmsetup create clone --table "0 1048576000
236 $source_dev 8 1 no_hydration"
237
238 2. Mount the device and trim the file system.
239 sent by the file system and it will not hyd
240
241 ::
242
243 mount /dev/mapper/clone /mnt/cloned-fs
244 fstrim /mnt/cloned-fs
245
246 3. Enable background hydration of the destinat
247
248 ::
249
250 dmsetup message clone 0 enable_hydration
251
252 4. When the hydration finishes, we can replace
253 table.
254
255 ::
256
257 dmsetup suspend clone
258 dmsetup load clone --table "0 1048576000 l
259 dmsetup resume clone
260
261 The metadata device is no longer needed and
262 for other purposes.
263
264 Known issues
265 ============
266
267 1. We redirect reads, to not-yet-hydrated regi
268 reading the source device has high latency
269 the same regions, this behaviour could degr
270 these reads as hints to hydrate the relevan
271 rely on the page cache to cache these regio
272 reading them multiple times from the source
273
274 2. Release in-core resources, i.e., the bitmap
275 hydrated, after the hydration has finished.
276
277 3. During background hydration, if we fail to
278 destination device, we print an error messa
279 continues indefinitely, until it succeeds.
280 hydration after a number of failures and em
281 notice.
282
283 Why not...?
284 ===========
285
286 We explored the following alternatives before
287
288 1. Use dm-cache with cache size equal to the s
289 cloning policy:
290
291 * The resulting cache device is not a one-t
292 and thus we cannot remove the cache devic
293
294 * dm-cache writes to the source device, whi
295 the source device must be treated as read
296
297 * Caching is semantically different from cl
298
299 2. Use dm-snapshot with a COW device equal to
300
301 * dm-snapshot stores its metadata in the CO
302 is not a one-to-one mirror of the source
303
304 * No background copying mechanism.
305
306 * dm-snapshot needs to commit its metadata
307 completes, to ensure snapshot consistency
308 need to be so strict and can rely on comm
309 or FUA bio is written, or periodically, l
310 improves the performance significantly.
311
312 3. Use dm-mirror: The mirror target has a back
313 mechanism, but it writes to all mirrors, th
314 the source device must be treated as read-o
315
316 4. Use dm-thin's external snapshot functionali
317 promising among all alternatives, as the th
318 one-to-one mirror of the source device and
319 un-provisioned/not-yet-cloned areas the sam
320
321 Still:
322
323 * There is no background copying mechanism,
324
325 * Most importantly, we want to support arbi
326 destination of the cloning process and no
327 thinly-provisioned volumes. Thin-provisio
328 overhead, for maintaining the thin volume
329 degrades performance.
330
331 Moreover, cloning a device shouldn't force
332 the other hand, if we wish to use thin prov
333 LV as dm-clone's destination device.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.