--- title: ZFS Common Commands description: ZFS Commands published: true date: 2026-01-31T15:23:07.585Z tags: zfs commands editor: markdown dateCreated: 2026-01-31T15:23:07.585Z --- # ZFS Essential Commands Cheat Sheet --- ## Pool Health & Status zpool status zpool status -v zpool list ## Dataset Space & Usage zfs list zfs list -r vault zfs list -o name,used,avail,refer,logicalused,compressratio zfs list -r -o name,used,avail,refer,quota,reservation vault ## Dataset Properties & Settings zfs get all vault/dataset zfs get -r compression,dedup,recordsize,atime,quota,reservation vault zfs get -r compression,dedup,recordsize,encryption,keylocation,keyformat,snapdir vault zfs get -s local -r all vault zfs get quota,refquota,reservation,refreservation -r vault ## Pool I/O & Performance Monitoring zpool iostat -v 1 arcstat 1 cat /proc/spl/kstat/zfs/arcstats ## Scrubs & Data Integrity zpool scrub vault zpool scrub -s vault zpool status ## Snapshots zfs snapshot vault/dataset@snapname zfs list -t snapshot zfs rollback vault/dataset@snapname zfs clone vault/dataset@snapname vault/dataset-clone ## Replication (Send / Receive) zfs send vault/dataset@snap1 | zfs receive backup/dataset zfs send -i snap1 vault/dataset@snap2 | zfs receive backup/dataset zfs send -nv vault/dataset@snap1 ## Dataset Tuning (Live-Safe Changes) zfs set compression=lz4 vault/dataset zfs set recordsize=1M vault/dataset zfs set atime=off vault/dataset zfs set dedup=on vault/dataset ## Encryption Management zfs get encryption,keylocation,keystatus vault/dataset zfs unload-key vault/dataset zfs load-key vault/dataset ## Disk Preparation & Cleanup wipefs /dev/sdX wipefs -a /dev/sdX zpool labelclear -f /dev/sdX sgdisk --zap-all /dev/sdX lsblk -f /dev/sdX ## Pool Expansion (Add VDEV) zpool add vault raidz2 \ /dev/disk/by-id/disk1 \ /dev/disk/by-id/disk2 \ /dev/disk/by-id/disk3 \ /dev/disk/by-id/disk4 \ /dev/disk/by-id/disk5 ## Pool Import / Recovery zpool import zpool import vault zpool import -f vault zpool import -o readonly=on vault ## Locks, Holds & History zfs holds -r vault zpool history zfs diff vault/dataset@snap1 vault/dataset@snap2 ## Deduplication & Compression Stats zpool list -v zdb -DD vault ## Inventory / Documentation Dumps zpool status > zpool-status.txt zfs list -r > zfs-layout.txt zfs get -r all vault > zfs-settings.txt ## Top 10 Must-Know Commands zpool status zpool list zpool iostat -v 1 zpool scrub vault zfs list zfs get all vault/dataset zfs snapshot vault/dataset@snap zfs rollback vault/dataset@snap zfs send | zfs receive arcstat 1 You said: can I tie my zfs keys to a ubikey ChatGPT said: Short answer: yes — indirectly, and safely. ZFS cannot talk to a YubiKey by itself, but you can bind ZFS encryption unlock to a YubiKey-backed secret using standard Linux plumbing. There are three sane ways to do this. I’ll rank them from best → worst for a homelab like yours. 🥇 Best option: YubiKey → unlock file → ZFS keylocation=file:// This is the most common, reliable, and automation-friendly approach. How it works (conceptually) YubiKey ↓ (touch / PIN) Decrypts keyfile ↓ ZFS loads dataset key ZFS never sees the YubiKey — it just reads a key file that only exists while the YubiKey is present. Step-by-step (clean + robust) 1️⃣ Generate a random ZFS keyfile mkdir -p /root/zfs-keys chmod 700 /root/zfs-keys dd if=/dev/urandom of=/root/zfs-keys/vault.key bs=32 count=1 chmod 600 /root/zfs-keys/vault.key 2️⃣ Encrypt that keyfile to the YubiKey Using GPG (most flexible): gpg --encrypt --recipient \ /root/zfs-keys/vault.key This creates: vault.key.gpg Then securely delete the plaintext key: shred -u /root/zfs-keys/vault.key 3️⃣ Set ZFS to expect a keyfile zfs set keyformat=raw vault/Secret zfs set keylocation=file:///root/zfs-keys/vault.key vault/Secret 4️⃣ Unlock procedure (manual or scripted) Insert YubiKey → decrypt → load ZFS key: gpg --decrypt /root/zfs-keys/vault.key.gpg > /root/zfs-keys/vault.key zfs load-key vault/Secret shred -u /root/zfs-keys/vault.key ✔️ Dataset unlocked ✔️ Keyfile wiped ✔️ YubiKey required every time 5️⃣ Lock again (optional) zfs unload-key vault/Secret 🥈 Alternative: YubiKey challenge–response → derived key This uses the YubiKey’s HMAC-SHA1 challenge/response slot. Pros No stored keyfile Strong hardware binding Cons More brittle Harder to recover Less transparent Typical flow: ykchalresp -2 | sha256sum | zfs load-key ⚠️ I only recommend this if you are comfortable with irreversible crypto mistakes. 🥉 Not recommended: YubiKey PIV directly with ZFS ZFS: ❌ Cannot use PKCS#11 ❌ Cannot read smartcards ❌ Cannot prompt hardware Anything claiming “direct ZFS + YubiKey” is lying or wrapping option #1. 🚨 Critical recovery warnings (read this) If you do this: 🔒 BACK UP THE ENCRYPTED KEYFILE 🔑 Have a second YubiKey 🧾 Document the unlock process offline Best practice: • Primary YubiKey • Spare YubiKey enrolled to same GPG key • Encrypted keyfile backup (offline) If you lose the YubiKey and the encrypted keyfile: The data is permanently unrecoverable ZFS encryption is not forgiving. ✅ Recommended pattern for your lab Given your setup (servers, NFS, ZFS send, occasional offline use): Use file-based keys Protect keyfile with YubiKey + GPG Unlock only datasets that truly need encryption Leave media + Docker unencrypted for sanity Example layout: vault/Green (unencrypted) vault/Docker (unencrypted) vault/Backups (encrypted, YubiKey) vault/Secrets (encrypted, YubiKey) 🧠 Want next? I can: Write a one-command unlock script with safety checks Design a boot-time + manual unlock hybrid Help you rotate keys or migrate existing encrypted datasets Just tell me how automated you want this to be.