From 8495536f7f6051849d6e56834766cd4fe2ff9c5e Mon Sep 17 00:00:00 2001 From: Rob N Date: Sat, 7 Oct 2023 03:06:29 +1100 Subject: [PATCH] zfsconcepts: add description of block cloning Here I'm trying to succinctly introduce the concept, the basics of its construction, how its different to dedup, how to use it, and where its limitations lie, in four paragraphs and with enough searchable terms to help the reader find more information both within OpenZFS and elsewhere. Phew. Sponsored-By: Klara, Inc. Reviewed-by: Brian Behlendorf Signed-off-by: Rob Norris Closes #15362 --- man/man7/zfsconcepts.7 | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/man/man7/zfsconcepts.7 b/man/man7/zfsconcepts.7 index 18a9e9b5c..1be3d961c 100644 --- a/man/man7/zfsconcepts.7 +++ b/man/man7/zfsconcepts.7 @@ -28,8 +28,9 @@ .\" Copyright 2019 Richard Laager. All rights reserved. .\" Copyright 2018 Nexenta Systems, Inc. .\" Copyright 2019 Joyent, Inc. +.\" Copyright 2023 Klara, Inc. .\" -.Dd June 30, 2019 +.Dd October 6, 2023 .Dt ZFSCONCEPTS 7 .Os . @@ -205,3 +206,40 @@ practices, such as regular backups. Consider using the .Sy compression property as a less resource-intensive alternative. +.Ss Block cloning +Block cloning is a facility that allows a file (or parts of a file) to be +.Qq cloned , +that is, a shallow copy made where the existing data blocks are referenced +rather than copied. +Later modifications to the data will cause a copy of the data block to be taken +and that copy modified. +This facility is used to implement +.Qq reflinks +or +.Qq file-level copy-on-write . +.Pp +Cloned blocks are tracked in a special on-disk structure called the Block +Reference Table +.Po BRT +.Pc . +Unlike deduplication, this table has minimal overhead, so can be enabled at all +times. +.Pp +Also unlike deduplication, cloning must be requested by a user program. +Many common file copying programs, including newer versions of +.Nm /bin/cp , +will try to create clones automatically. +Look for +.Qq clone , +.Qq dedupe +or +.Qq reflink +in the documentation for more information. +.Pp +There are some limitations to block cloning. +Only whole blocks can be cloned, and blocks can not be cloned if they are not +yet written to disk, or if they are encrypted, or the source and destination +.Sy recordsize +properties differ. +The OS may add additional restrictions; +for example, most versions of Linux will not allow clones across datasets.