Repository navigation
ZFS Basic
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.
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.
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.
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.
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.
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
A clone is a writable copy of a snapshot. It starts with no additional disk space and diverges from the original as writes occur.
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.
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) |
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=alwaysor applications that callfsync()). A bad SLOG device can cause data loss on power failure; use enterprise-grade SSDs.
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# 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-upgradeZNAS 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.
| 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 |
- ZFS Pools and Datasets & ZVols — Create and manage pools, datasets, and snapshots inside ZNAS
- Encryption — ZFS native encryption setup and key management
- Capacity Trends — Historical usage charts per pool and dataset
- Snapshots & Protection — Snapshots, schedules, and ZFS replication
Getting Started
Storage
- Dashboard & Monitoring
- Physical Disks
- ZFS Pools
- Datasets & ZVols
- MergerFS
- Snapshots & Protection
- File Sharing — SMB
- File Sharing — NFS
- iSCSI
- S3 Object Storage
- Capacity Trends
- Encryption
- UPS Management
Virtualization
Networking
Administration
Reference