Skip to content

ZFS Basic

gitsync edited this page Jul 14, 2026 · 3 revisions

This page is a primer on ZFS — the filesystem and volume manager that powers ZNAS. Understanding these concepts will help you make better decisions when configuring storage, encryption, snapshots, and sharing.


What is ZFS?

ZFS (Zettabyte File System) is a combined filesystem and logical volume manager originally developed by Sun Microsystems. It is designed for data integrity, scalability, and ease of administration. Unlike traditional filesystems, ZFS manages both the storage devices and the filesystem layer together, which enables features like checksumming, copy-on-write, and native snapshots.

Key properties:

  • Copy-on-Write (CoW) — Data is never overwritten in place; changes are written to new blocks. This makes snapshots and rollbacks instantaneous.
  • End-to-End Checksumming — Every block is checksummed; corrupted data is detected and (with redundancy) automatically repaired.
  • Pooled Storage — Disks are combined into a zpool rather than individually partitioned. Datasets within the pool share capacity dynamically.
  • Snapshots and Clones — Instant, space-efficient read-only snapshots of any dataset or zvol.
  • Native Compression — Transparent on-the-fly compression at the dataset level.
  • Native Encryption — AES-256-GCM encryption at the dataset or pool level.

Core Concepts

zpool

A zpool is the top-level storage container. It is made up of one or more vdevs (virtual devices). All datasets and zvols live inside a pool.

Pool type Description
Single disk No redundancy — any disk failure = data loss
Mirror Two or more disks mirror each other (like RAID-1)
RAIDZ1 Parity across N+1 disks; tolerates 1 disk loss
RAIDZ2 Parity across N+2 disks; tolerates 2 disk losses
RAIDZ3 Parity across N+3 disks; tolerates 3 disk losses

Tip: RAIDZ2 is the most common choice for NAS builds. It balances redundancy, usable capacity, and write performance.

Dataset

A dataset is a ZFS filesystem within a pool. Each dataset has its own properties (compression, quota, snapshot policy, encryption, etc.) and can be mounted independently.

Datasets are hierarchical: tank/data/photos is a child of tank/data, and can inherit or override properties from its parent.

Zvol

A zvol is a block device backed by ZFS. It behaves like a raw disk and is used for iSCSI targets or VM disk images.

Snapshot

A snapshot is a read-only, point-in-time copy of a dataset. Snapshots are instant and space-efficient (they only store the delta of changed blocks). They can be rolled back, cloned, or sent to another system.

Naming convention: tank/data@2024-01-15_daily

Clone

A clone is a writable copy of a snapshot. It starts with no additional disk space and diverges from the original as writes occur.

Send / Receive

ZFS can stream datasets (including their snapshot history) from one system to another using zfs send | zfs recv. This is the foundation of ZFS-based replication.


Important ZFS Properties

These properties can be set per dataset and have significant impact on behavior:

Property Description Typical Values
compression Transparent compression algorithm lz4 (fast), zstd (better ratio), off
atime Update access time on every file read off recommended for NAS (reduces writes)
quota Hard cap on dataset size e.g. 100G, off
refquota Quota that excludes snapshots 100G
reservation Guarantee minimum space for a dataset e.g. 50G
recordsize ZFS block size for this dataset 128K default; 1M for large sequential files; 16K for databases
dedup Deduplication (expensive — use with caution) on, off
sync Sync write semantics standard, always (safer), disabled (faster, risky)
canmount Whether dataset is auto-mounted on, off, noauto
encryption Native encryption algorithm aes-256-gcm
keylocation Where the encryption key is stored file:///path, prompt
snapdir Visibility of .zfs/snapshot directory hidden, visible
copies Number of data copies within the pool 1 (default), 2, 3
xattr Extended attribute storage method sa (recommended on Linux for performance)

ARC: Adaptive Replacement Cache

ZFS uses RAM as a read cache called the ARC (Adaptive Replacement Cache). It is self-tuning and will consume as much RAM as is available without starving other processes.

  • L2ARC — A secondary read cache on a fast SSD. Useful if your working set is larger than RAM.
  • ZIL / SLOG — The ZFS Intent Log buffers synchronous writes. A dedicated SLOG device (fast NVMe/SSD) can dramatically improve sync-write performance without touching the main pool.

Important: An SLOG device does NOT speed up async writes — only sync (sync=always or applications that call fsync()). A bad SLOG device can cause data loss on power failure; use enterprise-grade SSDs.


Scrub

A scrub reads all data in the pool and verifies checksums. It detects (and, with redundancy, repairs) silent data corruption. Run scrubs regularly — monthly is a common schedule.

zpool scrub tank
zpool status tank   # check scrub progress / results

Common Commands

# Pool status
zpool status
zpool list

# Dataset list
zfs list
zfs list -t all          # include snapshots and zvols

# Create dataset
zfs create tank/mydata

# Set property
zfs set compression=lz4 tank/mydata
zfs set quota=200G tank/mydata

# Take a snapshot
zfs snapshot tank/mydata@before-upgrade

# Rollback to snapshot
zfs rollback tank/mydata@before-upgrade

# Send / receive (replication)
zfs send tank/mydata@snap1 | ssh remote zfs recv backup/mydata

# Destroy snapshot
zfs destroy tank/mydata@before-upgrade

ZFS on Linux (OpenZFS)

ZNAS runs on OpenZFS, the open-source successor to the original Sun ZFS. OpenZFS is maintained by the community and tracks the original ZFS feature set closely. On Debian/Ubuntu systems it is available as the zfsutils-linux package.

Always check that your Linux kernel version is supported by the installed OpenZFS release before upgrading the OS.


Further Reading

Resource What you will find
OpenZFS Documentation Official docs: installation, tuning, administration
OpenZFS Man Pages — zfs(8) Full property reference and command reference
OpenZFS Man Pages — zpool(8) Pool creation, import/export, scrub, resilver
Aaron Toponce's ZFS Administration Series Practical deep-dives: vdev types, ARC, ZIL, L2ARC
OpenZFS Performance Tuning recordsize, atime, xattr=sa, ARC tuning, workload-specific tips
ZFS Raidz Capacity Calculator Estimate usable capacity for different RAIDZ configurations
ZFS Compression Comparison lz4 vs zstd vs gzip benchmarks
OpenZFS GitHub Source, issues, release notes

Related ZNAS Pages

Clone this wiki locally