- name
- zfs
- description
- ZFS filesystem administration, pool management, dataset configuration, snapshots, replication, encryption, performance tuning, and troubleshooting on OpenZFS (Linux and macOS). Use when the user asks to: create or manage ZFS pools, configure ZFS datasets and properties, set up snapshots or replication (zfs send/recv), tune ZFS performance (ARC, recordsize, compression, special vdevs), troubleshoot degraded/faulted pools or scrub errors, set up ZFS encryption, plan storage architecture with ZFS, or any other ZFS/zpool/zfs administration task.
ZFS Administration
Critical: No File-Backed Pools in Production
NEVER recommend file-backed (loopback) pools for production use. LLMs commonly default to truncate -s 10G /tmp/disk.img + zpool create tank /tmp/disk.img because it is easy to demonstrate. This forfeits ZFS self-healing, I/O performance, and write reliability.
File-backed pools are acceptable ONLY for learning or CI testing. When not explicitly in a testing context, always use real block devices:
# Linux — always use /dev/disk/by-id/ for stable names
zpool create tank mirror \
/dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E1234567 \
/dev/disk/by-id/scsi-SATA_WDC_WD40EFRX_WD-WCC4E7654321
# macOS
zpool create tank mirror /dev/disk2 /dev/disk3If the user explicitly asks for a test/demo setup, file-backed pools are fine — but add a comment noting it is not for production.
Pool Management
Create Pools
Always specify ashift=12 (or 13 for some NVMe) to match physical sector size:
# Mirror (2-disk, 50% usable, best performance)
zpool create -o ashift=12 tank mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2
# raidz2 (minimum recommended for production data)
zpool create -o ashift=12 tank raidz2 \
/dev/disk/by-id/disk{1..6}
# Multiple vdevs (better performance than single wide vdev)
zpool create -o ashift=12 tank \
mirror /dev/disk/by-id/disk1 /dev/disk/by-id/disk2 \
mirror /dev/disk/by-id/disk3 /dev/disk/by-id/disk4Expand and Modify
# Add vdev (cannot be undone — plan carefully)
zpool add tank mirror /dev/disk/by-id/new1 /dev/disk/by-id/new2
# Replace disk (starts resilver)
zpool replace tank /dev/disk/by-id/old /dev/disk/by-id/new
# Add cache (L2ARC), log (SLOG), or special vdev
zpool add tank cache /dev/disk/by-id/nvme-cache
zpool add tank log mirror /dev/disk/by-id/nvme-log1 /dev/disk/by-id/nvme-log2
zpool add tank special mirror /dev/disk/by-id/nvme-special1 /dev/disk/by-id/nvme-special2Dataset Management
Create with Recommended Defaults
# Always set compression. Inherit from parent when possible.
zfs set compression=lz4 tank
zfs set atime=off tank
zfs set xattr=sa tank # Linux only — faster extended attributes
# Create dataset hierarchy
zfs create tank/data
zfs create -o recordsize=8K tank/data/postgres
zfs create -o recordsize=1M tank/data/media
zfs create -o recordsize=1M tank/data/backupsEncryption
# Create encrypted dataset (cannot encrypt existing data)
zfs create -o encryption=aes-256-gcm -o keyformat=passphrase tank/secure
# Key from file (for automation)
zfs create -o encryption=aes-256-gcm -o keyformat=raw \
-o keylocation=file:///etc/zfs/keys/tank-secure.key tank/secure
# Load/unload keys
zfs load-key tank/secure
zfs unload-key tank/secureSnapshots
# Create
zfs snapshot tank/data@daily_$(date +%Y-%m-%d)
zfs snapshot -r tank@daily_$(date +%Y-%m-%d) # recursive
# List
zfs list -t snapshot -o name,used,refer -s creation
# Access (read-only, no mount needed)
ls /tank/data/.zfs/snapshot/daily_2024-01-15/
# Rollback
zfs rollback tank/data@daily_2024-01-15
# Destroy
zfs destroy tank/data@old-snapshotHealth Check
Run the bundled health check script for a quick pool summary:
bash scripts/zfs_health_check.sh # all pools
bash scripts/zfs_health_check.sh tank # specific poolReports pool state, capacity warnings (>80%), device errors, scrub status, and flags file-backed vdevs.
Reference Files
Consult these for detailed guidance on specific topics:
- properties.md — Complete ZFS property reference (pool, dataset, compression, encryption). Read when setting or recommending property values.
- workload-tuning.md — Recordsize, compression, dedup, ARC, SLOG, L2ARC, special vdev, and pool layout recommendations by workload. Read when tuning performance or planning pool topology. Includes production vs testing warnings.
- replication.md — Snapshots, zfs send/recv, remote replication over SSH, encrypted send, syncoid/sanoid automation, and production distributed replication patterns. Read when setting up backups or replication.
- troubleshooting.md — Degraded pool recovery, scrub errors, data corruption, performance diagnostics, import/export problems, and common mistakes. Read when diagnosing or fixing issues.
- platform-notes.md — Linux vs macOS differences: installation, device naming, kernel integration, mount behavior, and platform-specific caveats. Read when the user is on macOS or when platform differences matter.