An independently written description of the ZFS on-disk format for modern OpenZFS.
This document is derived from the ZFS On-Disk Specification (2006), Copyright 1994–2006 Sun Microsystems, Inc., licensed under the Berkeley License (see LICENSE-SUN.md).
The original specification is maintained by Matthew Ahrens at github.com/ahrens/zfsondisk. This project extends it with all changes made by OpenZFS since 2006, written from the publicly available OpenZFS source code.
The documentation is organized into chapters covering each layer of the ZFS on-disk format:
- Conventions -- Notation, byte order, diagram style
- Glossary -- Terms, type enumerations, constants
- Introduction -- Architecture overview and data traversal
- Chapter 1: Virtual Devices, Labels, and Boot Block
- Chapter 2: Block Pointers and Indirect Blocks
- Chapter 3: Data Management Unit
- Chapter 4: Dataset and Snapshot Layer
- Chapter 5: ZFS Attribute Processor
- Chapter 6: ZFS POSIX Layer
- Chapter 7: ZFS Intent Log
- 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
Phase 1 (initial documentation of the on-disk format) is complete. Phase 2 (modernization with post-2006 OpenZFS features: encryption, dRAID, block cloning, feature flags, etc.) is also complete. Phase 3 (new chapters covering modern OpenZFS on-disk topics beyond the original 2006 specification) is also complete.
The project is currently in maintenance mode.
Future Phase 4 work is planned as advanced OpenZFS deep dives, such as send/receive stream format details, MOS object-directory reference material, zdb verification guidance, and feature-activation behavior mapping.
- OpenZFS
- OpenZFS Developer Resources
- ZFS On-Disk Specification (original) -- Matthew Ahrens
- ZFS On-Disk Specification (PDF)
- Examining ZFS On-Disk Format Using mdb and zdb -- Max Bruning
- The Zettabyte File System
- ZFS: The Last Word in Filesystems
- The ZFS File System (CS308 Slides)
This project is dual-licensed:
- New content: MIT License
- Derived from: Sun Microsystems Berkeley License