Uberblok, an OpenZFS museum where every room cites the code

Uberblok is live: a museum about OpenZFS that you visit room by room. Fourteen stops: a hall, a wing devoted to history, eleven technical rooms and an engine room. Every technical claim points to an annotated excerpt of the OpenZFS code at zfs-2.4.4, pinned at commit 71a9f95. Every fact in the History wing has its line in SOURCES.md.

AI agents built it, between October 18 and 20. I wrote the mission, gave my opinion on every version and approved the release. The site’s engine room says it in one sentence: “The site was written by AI agents, from a mission set by a human who validates the release.”

# Why ZFS

ZFS mattered a lot in my career. From 2010 to 2018, I was technical lead for file storage at OVHcloud. ZFS’s robustness impressed us as soon as we tried it, like other forward-looking technologies from Sun, Solaris and then OpenSolaris: Zones, or Crossbow. On that foundation we built really powerful products, up to high-availability systems that fail over from one head to the other, and heavily optimized send/receive, with mbuffer and compression. Deployed at scale, ZFS is a joy.

The wish to pay tribute to it came naturally: diving into the guts of its code, which is a magnificent piece of software engineering.

# What I wanted

The mission fit in one sentence: « un musée que l’on visite salle par salle, où chaque salle rend visible […] une idée d’ingénierie du code source d’OpenZFS » [a museum you visit room by room, where each room makes visible […] an engineering idea from the OpenZFS source code]. Two rules came with it. For the rooms: « Une animation qui ne correspond à rien dans le code n’existe pas. » [An animation that matches nothing in the code does not exist.] For history: « Aucun fait, aucune date, aucune citation sans source vérifiable. Dans le doute, on retire. » [No fact, no date, no quote without a verifiable source. When in doubt, cut it.]

So the code came before the figures. A first file, ANALYSIS.md, maps the architecture and, for each room, the functions and structures that carry the idea. It now holds 116 excerpts. The pages read them at build time, and a script checks that each one is identical, byte for byte, to the file at the pinned commit. Most figures run a transcription of the code they show, tested against cases worked out by hand. The History wing rests on 43 sources, and CI checks that every note on the site matches a line in SOURCES.md.

# Where it broke

The first mistake came from my own mission. In it, I described the object in the hall as « l’uberblock et son ring de 128 » [the uberblock and its ring of 128]. The code says otherwise: the ring takes 128 KiB per label, and the size of a slot depends on the disk’s ashift (vdev_impl.h, L482 to L496). There are 128 slots with 512-byte sectors, but only 32 at ashift 12, the usual case for disks with 4 KiB sectors.

Three options were weighed. Writing “128 uberblocks” with no caveat was wrong for most pools in service. Showing only 32 was accurate, but lost the original picture. The choice: a 128 KiB ring, drawn with 128 slots, and an ashift selector that merges them into 64, 32 or 16. The hall stays true to the code, and the mission’s picture is kept.

The second was caught by the code review of a slice. A note in the send / receive room claimed that deduplication and block cloning don’t cause unchanged data to be sent again. The spa.h comment it cited says the opposite: for those blocks, the physical birth can be earlier than the logical birth. Since send relies on the logical birth, a block deduplicated or cloned after the starting snapshot is sent again. The note was fixed, on the page and in ANALYSIS.md.

# The room that works the brain hardest

For me, it’s Metaslabs and space maps. Metaslabs are really something! A software revolution few people are aware of.

The starting problem, as the room puts it: with copy-on-write, every write allocates fresh space, and free space has to be recorded on disk. A bitmap for a 16 TiB pool, one bit per 4 KiB sector, would weigh 512 MiB and would have to be modified in place, which copy-on-write forbids. Instead, ZFS cuts each vdev into metaslabs, about 200 by default, keeps each one’s free space in an in-memory tree and writes only the changes to disk, in a space map that is only ever appended to. When it grows too long, it rewrites it shorter from the tree.

In the figure, the space map of a 512 MiB metaslab is a strip of 64-bit words, encoded the way the macros in space_map.h do it. Rewriting a 64 MiB database until the condensing test says yes, the map shrinks from 66,432 to 3,376 bytes.

# Where I am

My mind hasn’t yet taken in everything that was generated! That’s what impresses me about this project: it teaches me things while I build it. A lifetime probably won’t be enough to understand all the subtleties of ZFS.

The mission’s success criterion was: « si Matt Ahrens ou Jeff Bonwick tombaient dessus, ils trouveraient l’exposé exact, élégant, et fidèle au code » [if Matt Ahrens or Jeff Bonwick stumbled on it, they would find the explanation accurate, elegant, and true to the code]. I don’t have the skills to say whether it’s met. If one of them ever lands on the site, I only hope he won’t find too many typos. And that he’ll enjoy taking it apart as much as I do.

The museum is live; its code, ANALYSIS.md, DECISIONS.md and BUILDLOG.md are in the public repository.