Cheat sheets

Cheat sheet: ZFS

ZFS pools and datasets management: checking status, creating snapshots, and sending data to another disk or server. More information: RAID and ZFS explained and the RAID and ZFS calculator.

View pools

All pools with status zpool status
Short list with space zpool list
Only check if everything is healthy zpool status -x
Usage per disk, every 2 seconds zpool iostat -v 2
The history of a pool zpool history tank

Manage pools

Create a mirror (warning: erases the disks!) zpool create tank mirror /dev/disk/by-id/DISK-A /dev/disk/by-id/DISK-B
Start a check of all data (scrub) zpool scrub tank
Replace a broken disk zpool replace tank OLD-DISK NEW-DISK
Safely detach a pool zpool export tank
Reattach a pool zpool import tank
Clear an error after recovery zpool clear tank

Datasets (folders with custom settings)

Show datasets zfs list
Create a dataset zfs create tank/data
Enable compression zfs set compression=lz4 tank/data
Set a limit zfs set quota=500G tank/data
Change the mount point zfs set mountpoint=/mnt/data tank/data
Show space usage zfs get used,available tank/data

Snapshots

Create a snapshot zfs snapshot tank/data@before-update
Show snapshots zfs list -t snapshot
Roll back to a snapshot (erases later work) zfs rollback tank/data@before-update
Delete a snapshot zfs destroy tank/data@before-update
Retrieve a single file from a snapshot ls /tank/data/.zfs/snapshot/before-update/

Send (backups)

Send a snapshot to another pool zfs send tank/data@snap1 | zfs receive backup/data
To another server via SSH zfs send tank/data@snap1 | ssh user@host zfs receive backup/data
Only the difference since the previous snapshot zfs send -i tank/data@snap1 tank/data@snap2 | ssh user@host zfs receive backup/data

Good to know

  • zpool create, zfs destroy, and zfs rollback can irreversibly erase data. Check the names carefully.
  • For disks, use the fixed names from /dev/disk/by-id/, not /dev/sda: those numbers can change.
  • RAID and snapshots are not a backup. See the 3-2-1 rule.

Sources and attribution

This overview is compiled in our own words. Commands and options vary by version: check the official documentation when in doubt.