zfs - SKILL.md Agent Skill

name: zfs description: > ZFS (OpenZFS) space efficiency and snapshotting for FreeBSD and Linux developers. Use when cloning datasets, creating build sandboxes, replicating storage, or writing Rust/C code that works with ZFS pools on macOS, FreeBSD, or Linux. Trigger phrases: "zfs snapshot", "zfs clone", "COW dataset", "zpool", "send/receive", "zfs dedup", "OpenZFS", "FreeBSD storage", "build rollback on ZFS". Covers: clone, snapshot, send/receive, dedup, Rust patterns, FreeBSD vs Linux differences.

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

Operation	Command	Notes
Create snapshot	`zfs snapshot pool/ds@name`	Instant, space = changed blocks only
List snapshots	`zfs list -t snapshot`
Clone snapshot	`zfs clone pool/ds@snap pool/ds-clone`	COW — zero space at creation
Rollback	`zfs rollback pool/ds@snap`	Destroys data after snapshot
Destroy clone/snap	`zfs destroy pool/ds@snap`	Clone must be destroyed first
Send (backup)	`zfs send pool/ds@snap \| zfs receive backup/ds`	Stream to remote or file
Incremental send	`zfs send -i pool/ds@prev pool/ds@now \| zfs receive backup/ds`	Delta only
Space usage	`zfs list -o name,used,avail,refer`
Enable dedup	`zfs set dedup=on pool/ds`	Block-level; RAM-intensive
Enable compression	`zfs set compression=lz4 pool/ds`	Almost always worth enabling

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

Aspect	FreeBSD	Linux (OpenZFS)
Pool device naming	`/dev/ada0`, `/dev/da0`, `/dev/gpt/label`	`/dev/sda`, `/dev/nvme0n1`
Import on boot	Automatic via `/etc/rc.conf`: `zfs_enable="YES"`	`zpool import -a` in initrd or systemd unit
Default pool name	`zroot` (installer default)	`rpool` (Ubuntu default)
ARC (cache) tuning	`vfs.zfs.arc_max` in `/boot/loader.conf`	`zfs_arc_max` in `/etc/modprobe.d/zfs.conf`
Encrypted root	Native ZFS encryption or GELI (FreeBSD)	Native ZFS encryption or LUKS
`zpool status`	Identical	Identical
`zfs` commands	Identical	Identical

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