A couple of weeks ago I opened two more pull requests to the OpenZFS project — PR #18303 and PR #18300. One adds a man page for a long-undocumented tool; the other removes stale flags from a core command that should never have been there in the first place.

Background

My earlier OpenZFS contributions were on the C side: error handling improvements for zpool create (PRs #18184, #18213, and #18268 — ENXIO handling, device-specific error reporting, and an EDOM error handler). These new PRs continue in the same spirit of cleaning up rough edges, though from different angles.

PR #18303 — Documenting zilstat

zilstat has existed in OpenZFS for some time, but it was effectively undocumented — no man page, nothing in the official documentation. The tool gives you per-pool ZIL (ZFS Intent Log) statistics: commit counts, write sizes broken down by type, and itx classifications across indirect, copied, and needcopy writes.

If you are trying to understand whether a SLOG device is actually doing useful work, or why synchronous write latency is higher than expected, zilstat is exactly the right tool. The lack of a man page meant most users did not know it existed, and those who found it had to reverse-engineer its output from the source.

PR #18303 adds a proper man page covering the synopsis, description, output fields, and usage examples — so the tool is now actually discoverable and usable by anyone consulting the documentation.

PR #18300 — Removing stale rewind flags from zpool clear

This one is a code change, and a satisfying one. zpool clear had been quietly accepting three flags — -F, -n, and -X — that it had no business accepting. These are rewind flags inherited from OpenSolaris, where they make sense in the context of zpool import: when importing a pool that is not yet loaded, you can select a specific transaction group to rewind to.

But zpool clear is a completely different situation. It operates on an already-imported pool whose in-memory state is ahead of what is on disk. Rewinding transactions there would require force-exporting the pool first — it simply cannot work. The flags were vestigial, undocumented, and misleading to anyone who stumbled across them in the usage string.

PR #18300 removes -F, -n, and -X from zpool clear entirely. The rewind policy passed to zpool_clear() is now always ZPOOL_NO_REWIND. The usage string is cleaned up to match. This closes issue #13825, which had been open since 2022. The commit was reviewed by Alexander Motin (TrueNAS) and Brian Behlendorf (LLNL), and tested on FreeBSD 16.0-CURRENT.

On cleaning things up

Both of these PRs are about the same underlying problem: a gap between what the codebase does and what users can reliably know or rely on. An undocumented tool and a command silently accepting flags that do nothing are both forms of technical debt that erode trust in the tooling over time. Removing the wrong thing is just as valuable as adding the right thing.

I will keep working through the OpenZFS codebase where I find similar rough edges. If you have spotted something undocumented or suspect a flag that does not do what it claims, opening an issue — or better yet, a PR — is the way to move it forward.