From 7b121388fb19dc71eef3536856f0ca683ab33a2d Mon Sep 17 00:00:00 2001 From: Rob Norris Date: Sat, 8 Nov 2025 01:01:59 +1100 Subject: [PATCH] man: describe zfs-rewrite method and properties We've heard anecdotes that suggest some confusion/surprise/disappointment that a changed recordsize is not applied during rewrite. Until such time as we actually can do that, we can at least explicitly mention it at something that doesn't work. Sponsored-by: Klara, Inc. Sponsored-by: Wasabi Technology, Inc. Reviewed-by: Brian Behlendorf Reviewed-by: Alexander Motin Reviewed-by: Allan Jude Signed-off-by: Rob Norris Closes #17898 --- man/man8/zfs-rewrite.8 | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/man/man8/zfs-rewrite.8 b/man/man8/zfs-rewrite.8 index ca5340c7e..ae0a15882 100644 --- a/man/man8/zfs-rewrite.8 +++ b/man/man8/zfs-rewrite.8 @@ -20,8 +20,9 @@ .\" CDDL HEADER END .\" .\" Copyright (c) 2025 iXsystems, Inc. +.\" Copyright (c) 2025, Klara, Inc. .\" -.Dd July 23, 2025 +.Dd November 5, 2025 .Dt ZFS-REWRITE 8 .Os . @@ -39,9 +40,10 @@ .Sh DESCRIPTION Rewrite blocks of specified .Ar file -as is without modification at a new location and possibly with new -properties, such as checksum, compression, dedup, copies, etc, +as is without modification at a new location and possibly with new properties, as if they were atomically read and written back. +.No See Sx NOTES . +for more information about property changes that may be applied during rewrite. .Bl -tag -width "-r" .It Fl P Perform physical rewrite, preserving logical birth time of blocks. @@ -64,6 +66,20 @@ Print names of all successfully rewritten files. Don't cross file system mount points when recursing. .El .Sh NOTES +Rewrite works by replacing an existing block with a new block of the same +logical size. +Changed dataset properties that operate on the data or metadata without +changing the logical size will be applied. +These include +.Sy checksum , +.Sy compression , +.Sy dedup +and +.Sy copies . +Changes to properties that affect the size of a logical block, like +.Sy recordsize , +will have no effect. +.Pp Rewrite of cloned blocks and blocks that are part of any snapshots, same as some property changes may increase pool space usage. Holes that were never written or were previously zero-compressed are