zfs-rewrite.8
| ZFS-REWRITE(8) | System Manager's Manual | ZFS-REWRITE(8) |
NAME
zfs-rewrite —
rewrite specified files without modification
SYNOPSIS
zfs |
rewrite [-CPSWrvx]
[-l length]
[-o offset]
file|directory… |
DESCRIPTION
Rewrite blocks of specified file as is without modification at a new location and possibly with new properties, as if they were atomically read and written back. See NOTES. for more information about property changes that may be applied during rewrite.
-C- Skip blocks that are shared via block cloning (BRT). Cloned blocks are referenced by multiple files or datasets. Rewriting these blocks would create separate copies and increase space usage. This flag prevents such expansion by skipping cloned blocks.
-P- Perform physical rewrite, preserving logical birth time of blocks. By
default, rewrite updates logical birth times, making blocks appear as
modified in snapshots and incremental send streams. Physical rewrite
preserves logical birth times, avoiding unnecessary inclusion in
incremental streams. Raw incremental streams of encrypted datasets, sent
with
zfssend-w, still include the rewritten blocks, since rewriting an encrypted block gives it a new IV and MAC. Physical rewrite requires the physical_rewrite feature to be enabled on the pool. -S- Skip blocks that are shared with snapshots. Blocks created before the most recent snapshot are shared with that snapshot. Rewriting these blocks would create new copies, leaving the old copies for the snapshot and increasing space usage. This flag prevents such expansion by skipping snapshot-shared blocks.
-W- Skip blocks that a rewrite would leave as they are: blocks that already have the checksum, compression, number of copies and deduplication that the properties of their dataset would give them now, that would be allocated in the same class, as special_small_blocks decides, and, on a RAID-Z vdev, that were written at its current width. After a RAID-Z expansion, the blocks written before it completed are rewritten, even those that the new width stores in the same space, which would otherwise leave the space freed around them fragmented. The blocks written since are skipped, so an interrupted rewrite can be run again without rewriting the same blocks twice. Gang blocks, and blocks on removed devices or on vdevs that take no new allocations, are always rewritten. A rewrite gives a deduplicated block the copies of its table entry again, so it is not rewritten for their width, nor, with a fast dedup table, for having more of them than the copies property asks for. A block stored uncompressed is taken as one that compression did not shrink, so it is not rewritten only to be compressed, and a change of the compression level alone is not seen.
-llength- Rewrite at most this number of bytes.
-ooffset- Start at this offset in bytes.
-r- Recurse into directories.
-v- Print names of all successfully rewritten files.
-x- Don't cross file system mount points when recursing.
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 checksum, compression, dedup and copies. Changes to properties that affect the size of a logical block, like recordsize, will have no effect.
Rewrite of cloned blocks and blocks that are part of any
snapshots, same as some property changes may increase pool space usage. Use
the -C and -S flags to skip
cloned and snapshot-shared blocks respectively to prevent this expansion.
Holes that were never written or were previously zero-compressed are not
rewritten and will remain holes even if compression is disabled.
On a RAID-Z vdev, rewritten blocks use the width of the vdev once its expansion has completed, see zpool-attach(8). Blocks rewritten while the expansion is in progress keep their old width. Blocks that are already deduplicated stay where they are, and keep their width.
If a -l or -o
value request a rewrite to regions past the end of the file, then those
regions are silently ignored, and no error is reported.
By default, rewritten blocks update their logical
birth time, meaning they will be included in incremental
zfs send streams as modified
data. When the -P flag is used, rewritten blocks
preserve their logical birth time, since there are no user data changes. A
deduplicated block whose copies change keeps it only when the rewrite writes
all of its copies. If the block still points to a copy that was already in
the deduplication table, as when copies is raised on a
pool whose deduplication table uses the
fast_dedup
format, or to the copies of other data with the same content, it gets a new
logical birth time.
SEE ALSO
| November 3, 2026 | Ubuntu |