Zfs

ZFS — OpenZFS Reference

ZFS is the COW filesystem for FreeBSD (first-class, ships by default since FreeBSD 13) and available on Linux via OpenZFS (Ubuntu, Debian, Arch). Commands are identical across platforms — pool naming and device paths differ.

The core rule

On ZFS, the unit of COW cloning is a dataset (filesystem or volume), not a file. To clone a directory tree: snapshot the dataset, then clone the snapshot.

zfs snapshot pool/dataset@tag
zfs clone pool/dataset@tag pool/dataset-clone

Clone is instant, zero space until divergence. This is the ZFS equivalent of cp -c on APFS.

Quick reference

Snapshots for build isolation

# Before a risky migration
zfs snapshot pool/src@pre-migration-2026-03-07

# Something went wrong — roll back
zfs rollback pool/src@pre-migration-2026-03-07

# Done — clean up
zfs destroy pool/src@pre-migration-2026-03-07

Snapshots consume space proportional to blocks changed after the snapshot, not the full dataset.

Dataset clones for test environments

# Snapshot the production dataset
zfs snapshot pool/prod@test-base

# Create a clone — writable, COW, instant
zfs clone pool/prod@test-base pool/test

# Use pool/test — all writes go to clone, prod is untouched

# Destroy when done (must destroy clone before its origin snapshot)
zfs destroy pool/test
zfs destroy pool/prod@test-base

Send/receive — replication

# Full send to remote
zfs send pool/ds@snap | ssh user@remote zfs receive backup/ds

# Incremental (only changed blocks since @prev)
zfs send -i pool/ds@prev pool/ds@now | ssh user@remote zfs receive -F backup/ds

# Send to a file
zfs send pool/ds@snap | gzip > ds-backup.gz
zfs send pool/ds@snap > ds-backup.zfs  # raw, faster to restore

# Restore
zfs receive pool/ds < ds-backup.zfs

Compression — always enable

zfs set compression=lz4 pool/dataset   # fast, good ratio — default choice
zfs set compression=zstd pool/dataset  # better ratio, slower — good for cold data

LZ4 compression typically saves 30–50% on source code and logs with near-zero CPU cost. Enable at dataset creation; only new writes are compressed.

Dedup — use carefully

zfs set dedup=on pool/dataset

Block-level deduplication. Requires ~5GB RAM per TB of data for the dedup table. Only worth enabling when data has high block-level duplication (VM images, backups). NOT recommended for source code or build artifacts — too much RAM, little gain.

Rust patterns

ZFS has no stable clonefile()-style syscall for userspace. Options:

1. Shell out (simplest, recommended for most cases):

use std::process::Command;

fn zfs_snapshot(dataset: &str, tag: &str) -> std::io::Result<()> {
    let status = Command::new("zfs")
        .args(["snapshot", &format!("{dataset}@{tag}")])
        .status()?;
    if status.success() { Ok(()) } else {
        Err(std::io::Error::other("zfs snapshot failed"))
    }
}

fn zfs_clone(origin: &str, tag: &str, clone: &str) -> std::io::Result<()> {
    let snap = format!("{origin}@{tag}");
    let status = Command::new("zfs")
        .args(["clone", &snap, clone])
        .status()?;
    if status.success() { Ok(()) } else {
        Err(std::io::Error::other("zfs clone failed"))
    }
}

2. libzfs FFI (advanced, avoids process overhead): libzfs is available on FreeBSD and Linux but has no stable API — version-specific. Use the zfs-sys crate if it exists for your OpenZFS version, otherwise shell out.

FreeBSD vs Linux differences

Space audit commands

zpool list                          # pool-level free/used
zfs list -o name,used,avail,refer   # dataset breakdown
zfs list -t snapshot                # all snapshots and their sizes
zpool iostat -v                     # I/O per vdev
zdb -b pool/dataset                 # block-level stats (verbose)

Pools — bare minimum setup

# Single disk pool (development only — no redundancy)
zpool create mypool /dev/ada1

# Mirror (RAID-1 equivalent)
zpool create mypool mirror /dev/ada1 /dev/ada2

# Status
zpool status mypool

# Destroy (irreversible)
zpool destroy mypool

Always enable compression on the pool or root dataset after creation:

zfs set compression=lz4 mypool