zfs-ondiskformat
An independently written specification of the ZFS on-disk format for modern OpenZFS, in 16 chapters.
Background
The authoritative reference for ZFS on-disk layout is the ZFS On-Disk Specification published by Sun Microsystems in 2006. That document covers the foundational structures — virtual devices, block pointers, the Meta Object Set, DMU, DSL, ZAP, ZPL, ZIL, and ZVOL.
OpenZFS has added substantial functionality since 2006. Native encryption, dRAID, block cloning, persistent L2ARC, deduplication tables, and the feature flag mechanism — none of these appear in the original specification. Existing documentation for these additions is scattered across mailing lists, OpenZFS GitHub history, source code comments, and conference talks.
This project extends the original specification to cover the current state of OpenZFS, written from the publicly available source code. It is not a fork or reformatting of the original — it is independently written content organized to match the structure of the 2006 document and fill in everything that came after.
Contents
- Conventions, glossary, and architecture introduction
- Chapter 1: Virtual Devices, Labels, and Boot Block
- Chapter 2: Block Pointers and Indirect Blocks
- Chapter 3: Data Management Unit (DMU)
- Chapter 4: Dataset and Snapshot Layer (DSL)
- Chapter 5: ZFS Attribute Processor (ZAP)
- Chapter 6: ZFS POSIX Layer (ZPL)
- Chapter 7: ZFS Intent Log (ZIL)
- Chapter 8: ZVOL
- Chapter 9: Space Maps and Metaslabs
- Chapter 10: Native Encryption
- Chapter 11: RAID-Z and dRAID
- Chapter 12: Allocation Classes and Device Removal
- Chapter 13: Feature Flags and Compatibility
- Chapter 14: Deduplication Tables and Block Cloning
- Chapter 15: Persistent L2ARC Cache
- Chapter 16: Pool Operations State
Status
Phases 1 through 3 are complete. The document is currently in maintenance mode. Planned Phase 4
work covers advanced topics: send/receive stream format details, MOS object-directory reference
material, zdb verification guidance, and feature-activation behavior mapping.
License
New content is MIT licensed. Content derived from the original Sun Microsystems specification is under the Berkeley License.