Skip to content

docs: sync operator guides with current flags and behavior - #36

Merged
mattmattox merged 3 commits into
mainfrom
claude/docs-operator-sync
Oct 24, 2026
Merged

mattmattox merged 3 commits into
mainfrom
claude/docs-operator-sync

Conversation

@mattmattox

Copy link
Copy Markdown
Contributor

Brings docs/OPERATIONS.md, DEPLOYMENT.md and TROUBLESHOOTING.md in line with e31fa92 and adds a Security Model section to OPERATIONS.md. docs/DESIGN*.md are untouched; their stale statements go to the author separately.

Checked on .68 at e31fa92: format, unformatted-device error, -h, fsck -version, the snapshot → clone backup flow, df -i, superblock magic, and the startup and unmount log lines.

Found while verifying, not fixed here (code bugs):

  • chmod drops the file-type bits (ino.Mode = mode & 0777 in File.Setattr); the file then reads as a directory and fsck reports invalid file type.
  • Cache hit rates print far above 100%.
  • Journal FullThreshold and lock DefaultTimeout are never used.

🤖 Generated with Claude Code

mattmattox and others added 3 commits October 24, 2026 17:45
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>
ErrLockTimeout only fires when the request context is cancelled;
lock.DefaultTimeout is never used.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
-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>
@mattmattox
mattmattox merged commit f93390e into main Oct 24, 2026
8 checks passed
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