Block Cloning in ZFS

Overview

Block cloning lets ZFS create a file — or extend an existing one — that references another file's existing data blocks instead of copying them. Nothing is read from or written to the underlying vdevs; only block pointers and a reference count change. Writing to a cloned region later behaves exactly like any other copy-on-write: ZFS allocates a fresh block for the changed data and leaves every other reference to the original block untouched. This is ZFS's version of what XFS, Btrfs, and Windows ReFS call a reflink.

Block cloning landed in OpenZFS 2.2.0 (October 2023), authored by Pawel Dawidek as PR #13392, after being proposed at the 2020 OpenZFS Developer Summit.

Block Cloning vs. Related Mechanisms

ZFS has four different ways to make one block do the work of many. Only one of them is block cloning.

The Block Reference Table

Every cloned block gets an entry in the Block Reference Table (BRT): a vdev, an offset, and a reference count. It's a much simpler structure than the dedup table (DDT), and the two behave very differently in practice:

• The DDT is checksum-indexed and consulted on every write while dedup is on, whether or not that particular write turns out to match anything already on disk. That lookup, plus keeping a large hash table resident in memory, is most of why dedup has a reputation for wrecking write throughput.
• The BRT is only touched when a program explicitly asks to clone a range. A plain write never consults it, so it carries effectively no cost for workloads that don't use cloning — which is why OpenZFS leaves it enabled unconditionally instead of gating it behind a dataset property the way dedup is gated.

One asymmetry runs the other way. Block pointers carry a spare bit (the "D" bit) that flags whether a block is in the DDT, so freeing a non-deduped block skips the DDT lookup entirely. There's no equivalent bit for block cloning, so every block free has to check the BRT regardless of whether that particular block was ever cloned. Cloning is free on the read and write side; it isn't quite free on the free path.

Modifying a cloned block is ordinary copy-on-write: ZFS allocates a new block for the changed data, decrements the BRT reference count on the original, and every other file still pointing at that original block is unaffected.

Triggering a Clone

Block cloning is opt-in per operation — nothing clones automatically just because two files happen to contain the same bytes. A program has to explicitly ask, through one of:

• copy_file_range(2) — the primary Linux syscall; modern cp, and a growing number of other copy tools, call this under the hood
• FICLONE / FICLONERANGE ioctls — the same ioctls XFS and Btrfs use for their own reflinks
• cp --reflink=always or --reflink=auto — GNU coreutils has defaulted to --reflink=auto since 9.2, so a stock cp on a current distro tries to clone first and silently falls back to a normal copy if it can't; FreeBSD's /bin/cp gained the same behavior in 13.0
• Copying out of a live filesystem's .zfs/snapshot/ directory — this goes through the same reflink-capable cp, so restoring a large file from a snapshot doesn't temporarily double its space usage
• Server-side copy over NFS (the COPY operation) and SMB (FSCTL_SRV_COPYCHUNK, via Samba) — a client asking the server to copy a file on its own disk can land on block cloning instead of streaming the data twice over the wire

$ cp --reflink=always /tank/vm/base.qcow2 /tank/vm/clone.qcow2
$ cp /tank/movies/.zfs/snapshot/nightly/movie.mkv /tank/movies/

copy_file_range(2)

ZFS clones through this syscall whenever the source range, destination range, and both files' properties satisfy the requirements below — otherwise the kernel transparently falls back to a read/write copy loop.

ssize_t copy_file_range(int fd_in, off_t *off_in,
                         int fd_out, off_t *off_out,
                         size_t len, unsigned int flags);

FICLONERANGE takes an explicit source/destination range via a struct passed to ioctl(2):

struct file_clone_range {
    __s64 src_fd;
    __u64 src_offset;
    __u64 src_length;
    __u64 dest_offset;
};

Requirements and Limitations

A clone request falls back to a real copy — sometimes silently — unless all of the following hold:

• Same pool. Block cloning cannot cross a pool boundary; block pointers only make sense within the pool that allocated them.
• Matching recordsize. Cloning across datasets requires the source and destination to have the same recordsize property.
• Compatible encryption. Both sides unencrypted, or both encrypted and sharing the same master key — a child dataset that inherited its key from its parent, for example. A mismatched key, or one encrypted side paired with one plaintext side, can't clone.
• Whole blocks only. A range that doesn't line up on block boundaries gets its unaligned edges copied normally; only the block-aligned middle actually clones.
• Source data must already be on disk. Dirty, not-yet-synced blocks have no BRT entry to reference yet — see zfs_bclone_wait_dirty below.

Feature Flag and Tunables

# cat /sys/module/zfs/parameters/zfs_bclone_enabled
1
# echo "options zfs zfs_bclone_enabled=1" > /etc/modprobe.d/zfs.conf

Stability History

Current OpenZFS defaults zfs_bclone_enabled back to 1 — but confirm the actual value on your system before relying on it; distributions can and do override module defaults. Any host still running a 2.2.x release should be treated as off-by-default and opt-in only, regardless of what upstream ships elsewhere.

Observability

Pool-level properties expose clone savings without walking the filesystem for BRT references:

$ zpool get bcloneused,bclonesaved,bcloneratio tank
NAME  PROPERTY      VALUE   SOURCE
tank  bcloneused    100M    -
tank  bclonesaved   100M    -
tank  bcloneratio   2.00x   -

zfs send / zfs receive

Practical Use Cases

• VM and container image templates. Cloning a multi-gigabyte disk image is a metadata-only operation regardless of image size; copy-on-write divergence only happens on the blocks a given instance actually touches afterward.
• Restoring from .zfs/snapshot/. A plain cp out of a snapshot clones instead of duplicating, so pulling a large file back into the live filesystem doesn't temporarily double its space usage.
• Backup "synthetic full" construction. Backup software — Veeam on a ZFS-backed repository is the most commonly cited case — builds a new full backup by cloning unchanged extents from the previous full and only writing the blocks that actually changed, instead of rewriting the entire file. This pattern puts far more sustained load on block cloning than casual desktop use, and has driven a fair share of the post-2.2.1 bug reports.