Skip to content

fix(fsck): match what the runtime writes and make -repair safe - #32

Merged
mattmattox merged 5 commits into
mainfrom
fix-fsck-release
Oct 24, 2026
Merged

mattmattox merged 5 commits into
mainfrom
fix-fsck-release

Conversation

@mattmattox

Copy link
Copy Markdown
Contributor

On a valid runtime image, main's fsck reports 300+ errors (255 from the directory parser alone). This branch reports none.

  • -repair refuses while a node's heartbeat counter moves. The mount binary never clears its slot, so this takes up to 11s right after an unmount. It also refuses while a stopped node's journal is dirty. -force overrides only the journal check.
  • Repair fixes refcounts, older uncounted sharing and the superblock checksum. It reports everything else.
  • Tested on .68: lint, unit -race, fsck integration, and four fuzz targets for 2-2.5 min each (no crashes).
  • Not run: Docker/VM. No runtime paths changed, and both suites are TODO in the manifest because their images lack goclusterfs-fsck.

🤖 Generated with Claude Code

mattmattox and others added 5 commits October 24, 2026 16:30
fsck reported errors on every valid filesystem: it read sector checksums
at the wrong offset, compared superblock counters the runtime never
updates, and parsed every 4KB of a directory block as entries. It now
checks what the runtime writes, reads with aligned buffers, and stops in
phase 1 on a layout that would send later phases to the wrong place.

-repair rebuilds refcounts from every inode, snapshot data inode, clone
and extent tree, and marks blocks older versions shared as counted, so
snapshots and clones of them work again. It refuses to run while a node
heartbeats or a stopped node's journal still needs replay, and -dry-run
reports what it would change. Exit codes are 0 clean, 1 errors remain,
2 repaired, 4 failed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fix the fsck command lines in the docs, which passed a -device flag
fsck never had, and replace the known-issue notes with what -repair
checks before it runs and what it changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review fixes:
- Watch every registry slot, so a node that mounts during the watch
  counts as running, and check the registry again right before repair
  writes refcounts or flags.
- Sync after the refcount writes, so counted-sharing flags never reach
  the disk before the counts they rely on, and after the flags.
- Use fsck(8) exit codes: 1 corrected, 4 uncorrected, 8 operational
  error, 16 usage error, OR'ed together.
- Check mode no longer reads the node registry; dry runs warn when
  repair would refuse.
- Directory entries must fill exactly the first 4KB chunk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… a node

A failed read of a slot left nil in both the watch and the pre-write
check, so a node whose slot read failed twice went unnoticed. Comparing
the raw slot bytes catches any write to a slot, readable or not, and a
failed registry read now refuses repair.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattmattox
mattmattox merged commit 5d31aa3 into main Oct 24, 2026
8 checks passed
mattmattox added a commit that referenced this pull request Oct 24, 2026
* docs: sync operator guides with current flags and behavior

OPERATIONS, DEPLOYMENT and TROUBLESHOOTING still used the old
goclusterfs binary name, a -format without -mount, a .snapshots
directory and snapshot API that never existed, lost+found, a
-fuse-debug flag, a mount -version flag, pprof, and read-only mounts.

They now match the code at e31fa92: format v2 and per-node journals,
-skip-recovery and damaged journal slots (#34), fsck exit codes and
-repair (#32), -attr-timeout (#24), lock renewal and takeover (#13,
#23), xattr snapshots and clones (#16), and the real log lines.

OPERATIONS.md gains a Security Model section: trust in the shared
device, single-user mounts with no permission checks, lock limits,
and unauthenticated broadcast unless -broadcast-secret is set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: lock waits have no time limit

ErrLockTimeout only fires when the request context is cancelled;
lock.DefaultTimeout is never used.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs: make damaged-journal recovery safe and fix review findings

-skip-recovery discards the journal of whichever slot the mount takes,
which is not the damaged slot once a peer holds its recovery lease.
The steps now say when to run it and how to check the slot, and only
use it for a damaged header, not for I/O or replay errors.

Also quote the real legacy-layout and superblock errors, cover a v2
device with a wiped superblock, state that there is no HTTP API, and
correct peer-announce, replay, unicast fallback and cache lag claims.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant