mirror of
https://git.proxmox.com/git/mirror_zfs.git
synced 2026-03-10 20:36:21 +03:00
2646bd5585
Rewrite of cloned and snapshotted blocks can allocate additional space, that may be undesired. In some cases it may have sense to still rewrite snapshotted blocks, expecting the snapshots to rotate with time, freeing space. In other cases rewrite of cloned blocks may be acceptable, despite persistent space usage increase. For this reason add them as separate flags to `zfs rewrite`. Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov> Reviewed-by: Rob Norris <robn@despairlabs.com> Reviewed-by: Ameer Hamza <ahamza@ixsystems.com> Signed-off-by: Alexander Motin <alexander.motin@TrueNAS.com> Closes #18179
124 lines
3.9 KiB
Groff
124 lines
3.9 KiB
Groff
.\" SPDX-License-Identifier: CDDL-1.0
|
|
.\"
|
|
.\" CDDL HEADER START
|
|
.\"
|
|
.\" The contents of this file are subject to the terms of the
|
|
.\" Common Development and Distribution License (the "License").
|
|
.\" You may not use this file except in compliance with the License.
|
|
.\"
|
|
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
|
|
.\" or https://opensource.org/licenses/CDDL-1.0.
|
|
.\" See the License for the specific language governing permissions
|
|
.\" and limitations under the License.
|
|
.\"
|
|
.\" When distributing Covered Code, include this CDDL HEADER in each
|
|
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
|
|
.\" If applicable, add the following below this CDDL HEADER, with the
|
|
.\" fields enclosed by brackets "[]" replaced with your own identifying
|
|
.\" information: Portions Copyright [yyyy] [name of copyright owner]
|
|
.\"
|
|
.\" CDDL HEADER END
|
|
.\"
|
|
.\" Copyright (c) 2025 iXsystems, Inc.
|
|
.\" Copyright (c) 2025, Klara, Inc.
|
|
.\"
|
|
.Dd November 5, 2025
|
|
.Dt ZFS-REWRITE 8
|
|
.Os
|
|
.
|
|
.Sh NAME
|
|
.Nm zfs-rewrite
|
|
.Nd rewrite specified files without modification
|
|
.Sh SYNOPSIS
|
|
.Nm zfs
|
|
.Cm rewrite
|
|
.Oo Fl CPSrvx Ns Oc
|
|
.Op Fl l Ar length
|
|
.Op Fl o Ar offset
|
|
.Ar file Ns | Ns Ar directory Ns …
|
|
.
|
|
.Sh DESCRIPTION
|
|
Rewrite blocks of specified
|
|
.Ar file
|
|
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 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.
|
|
.It Fl 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.
|
|
Physical rewrite requires the
|
|
.Sy physical_rewrite
|
|
feature to be enabled on the pool.
|
|
.It Fl 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.
|
|
.It Fl l Ar length
|
|
Rewrite at most this number of bytes.
|
|
.It Fl o Ar offset
|
|
Start at this offset in bytes.
|
|
.It Fl r
|
|
Recurse into directories.
|
|
.It Fl v
|
|
Print names of all successfully rewritten files.
|
|
.It Fl x
|
|
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.
|
|
Use the
|
|
.Fl C
|
|
and
|
|
.Fl 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.
|
|
.Pp
|
|
If a
|
|
.Fl l
|
|
or
|
|
.Fl o
|
|
value request a rewrite to regions past the end of the file, then those
|
|
regions are silently ignored, and no error is reported.
|
|
.Pp
|
|
By default, rewritten blocks update their logical birth time,
|
|
meaning they will be included in incremental
|
|
.Nm zfs Cm send
|
|
streams as modified data.
|
|
When the
|
|
.Fl P
|
|
flag is used, rewritten blocks preserve their logical birth time, since
|
|
there are no user data changes.
|
|
.
|
|
.Sh SEE ALSO
|
|
.Xr zfsprops 7 ,
|
|
.Xr zpool-features 7
|