ZFS Commands Reference
This document provides a comprehensive reference for essential ZFS commands, focusing on managing storage pools and file systems. It's crucial to use immutable device IDs (e.g., /dev/disk/by-id/*) instead of dynamic block device names (e.g., /dev/{sd,nvme}*) to prevent issues when hardware is re-enumerated.
ZFS Pool Management
Managing ZFS pools involves creating, importing, exporting, and monitoring their status and integrity. Understanding pool configuration is key to robust storage solutions.
Pool Creation and Configuration
# Create a new "RAID-5" (raidz1) pool
# Recommended: use entire devices rather than partitions
zpool create ${pool} raidz1 ${device} ${device} ${device} [...]
# Add 2nd-level "RAID-1" (mirror) ZFS Intent Log (ZIL; synchronous write cache):
# Recommended: use separate, fast, low-latency devices (e.g. NVMe)
zpool add ${pool} log mirror ${part} ${part}
# Add 2nd-level "RAID-0" Adaptive Replacement Cache (ARC; read cache):
# Recommended: use separate, fast, low-latency devices (e.g. NVMe)
zpool add ${pool} cache ${part} ${part} [...]
# Remove log or cache components:
zpool remove zfs ${part} [...]
Pool Import and Export
# Import (enable) existing pool from newly connected devices:
# Note: this will create the /etc/zfs/zpool.cache devices cache
zpool import -d /dev/disk/by-id -aN
# Import (enable) existing pool using the devices cache:
zpool import -c /etc/zfs/zpool.cache -aN
# Export (disable) pool (e.g. before shutdown):
zpool export -a
Pool Monitoring and Maintenance
# List all (imported) pools:
zpool list
# See pool status:
zpool status ${pool}
# See detailed pool I/O statistics:
zpool iostat ${pool} -v
# Verify pool integrity (data checksums):
# (watch progress with 'zpool status')
zpool scrub ${pool}
# Remove a failing device from a pool:
# Note: redundant pools (mirror, raidz) will continue working in degraded state
zpool detach ${pool} ${device}
# Replace a failed device in a pool:
# Note: new device will be "resilvered" automatically (parity reconstruction)
# (watch progress with 'zpool status')
zpool replace ${pool} ${failed-device} ${new-device}
# Erase zpool labels ("superblock") from a device/partition:
# WARNING: MUST do before reusing a device/partition for other purposes
zpool labelclear ${device}
Querying and Setting Pool Properties
# Query pool configuration (properties):
zpool get all ${pool}
# Change pool configuration (property):
zpool set <property>=<value> ${pool}
# Dump the entire pool (commands) history:
zpool history ${pool}
# More...
man zpool
ZFS File Systems and Volumes
ZFS allows for the creation and management of file systems and block devices (volumes) with advanced features like snapshots and efficient data transfer.
File System and Volume Creation
# Create a new file system:
zfs create ${pool}/${fs_vol}
# Create a new volume ("block device"):
# Note: look for it in /dev/zvol/${pool}/${fs_vol}
zfs create -V <size> ${pool}/${fs_vol}
Listing and Mounting
# List all file systems / volumes:
zfs list
# Mount all file systems:
# Note: see 'zfs get mountpoint ${pool}' for mountpoint root path
zfs mount -a
Snapshots and Data Transfer
# Create a snapshot:
zfs snapshot ${pool}/${fs_vol}@${snapshot}
# Delete a snapshot:
zfs destroy ${pool}/${fs_vol}@${snapshot}
# Delete a range of snapshots:
zfs destroy ${pool}/${fs_vol}@${first-snapshot}%${last-snapshot}
# Full backup:
# Note: pipe (|) source to destination through netcat, SSH, etc.
# ... on source:
zfs send -p -R ${pool}/${fs_vol}@${snapshot}
# ... on destination:
zfs receive -F ${pool}/${fs_vol}
# Incremental backup:
# Note: pipe (|) source to destination through netcat, SSH, etc.
# ... on source:
zfs send -p -R -i ${pool}/${fs_vol}@${snapshot-previous} ${pool}/${fs_vol}@${snapshot}
# ... on destination:
zfs receive -F ${pool}/${fs_vol}
Querying and Setting File System/Volume Properties
# Query file system / volume configuration (properties):
zfs get all ${pool}
zfs get all ${pool}/${fs_vol}
# Change file system / volume configuration (property):
zfs set <property>=<value> ${pool}/${fs_vol}
# More...
man zfs