Skip to content

docs: sync operator guides with main after the API, lock and layout changes - #99

Merged
mattmattox merged 2 commits into
mainfrom
claude/docs-sync-53ef02a
Nov 13, 2026
Merged

mattmattox merged 2 commits into
mainfrom
claude/docs-sync-53ef02a

Conversation

@mattmattox

Copy link
Copy Markdown
Contributor

Brings README.md, docs/OPERATIONS.md, DEPLOYMENT.md, TROUBLESHOOTING.md and API-CONFIG.md in line with main at 30500b7.

Checked on 172.25.1.68 at 30500b7 (rebased onto c3d2543; only #86/#95/#96 landed since, and the #96 OPERATIONS conflict is merged by hand):

  • Format a 1 GB image (698 data blocks), clean remount (no recovery line), -skip-recovery=5 ignored on slot 0, kill -9 then remount (replayed 2 txns, file kept), SIGTERM shutdown (exit 0), gfsctl stats cluster|cache|health, /metrics memory lines, 403 for a foreign Host and for snapshots without a token, "Dashboard not built", the four startup refusals as quoted, and fsck clean plus -list-slots.
  • The 12 tests that -short skips all passed in 244 s.
  • The full suite without -short took 915 s: 129 passed, 2 skipped, 3 failed. TestFsckRepairsOlderSharing and TestSFBPersistence hit fusermount: ... Device or resource busy on unmount, then the remount failed (likely the shared host). TestMultiNodeExtentCacheCoherency/TruncateRewrite read 262144 bytes, wanted 307200. These tests also run under -short in CI, so they need a look.

Code and doc mismatches found, not fixed here:

DESIGN*.md drift at 53ef02a (not edited; for the author)

None of the DESIGN files changed since e31fa92. Each item: doc line, the claim, what the code does now.

DESIGN.md

DESIGN-journal.md

DESIGN-snapshot.md

  • :13,271-358 O(1) creation with background refcounts: synchronous, touches every block, hidden data inode, retries if a write moved blocks (fix(snapshot): order in-place writes with snapshots on other nodes #42); worker only deletes.
  • :197-216 CoW under exclusive inode lock: in-place writes take a shared inode lock plus exclusive extent lock and recheck sharing; copies happen under the exclusive inode lock (fix(snapshot): order in-place writes with snapshots on other nodes #42, fix(snapshot): copy shared blocks under the exclusive inode lock #46).
  • :242-259 partial-write copy, free inside CoW: full block copied; old block released after the inode write commits; old uncounted sharing never released.
  • :48,213,239,255 "0 = free, 1 = exclusive": 0 and 1 both mean one owner; share sets max(n,1)+1; release frees at ≤1.
  • :688-698 all snapshot ops journaled: none are.
  • :649-666 incomplete creation becomes Active: rolled back at mount unless another node activated it.
  • :363-505 leaf/middle/root deletion: one worker path.
  • :509-547 CreateWritableClone: a clone is a normal root-directory file sharing blocks; other directories get ENOTSUP.
  • :79-122 registry header, MaxSnapshots 256, Name[64]: no header; 128-byte descriptors (~7,936 per MB) with a DataInode; names ≤47 bytes, unique per volume; IDs n×64 + slot.
  • :124-130 states Creating=0 … Orphaned=3: Invalid=0, Creating=1, Active=2, Deleting=3.
  • :101,293 directory subtrees, ParentSnapshotID: files only; parent always 0.
  • :29,60-71 RefCount header "GCLSREFC": no header; 511 entries + CRC32C per 4 KB sector.

DESIGN-write-path.md

DESIGN-v2.md

DESIGN-cache.md

DESIGN-thin.md

  • :161-180 PUNCH_HOLE and ZERO_RANGE handled: both return EOPNOTSUPP.
  • :81,126,162,186 reads/writes take the inode lock, fallocate inode then bitmap: reads unlocked; fallocate allocates first.
  • :278-299 flush TRIMs every queued block: only blocks still free, held allocated during the discard (fix: stop TRIM discarding reallocated blocks and dedupe broadcasts per sender #37).
  • :36-37 hole = block 0, Length uint32: hole is MaxUint64, Length uint64.
  • :30-31 future compressed/encrypted bits: bit 3 SFB, bits 4-5 SFB tier, bit 6 FlagCounted.

Fixed since the last list: DESIGN.md:579-581 (30 s lock timeout now enforced, #54) and DESIGN-snapshot.md:38-40 (refcount table sized from the device, #47).

🤖 Generated with Claude Code

mattmattox and others added 2 commits November 13, 2026 14:21
…hanges

README, OPERATIONS, DEPLOYMENT, TROUBLESHOOTING and API-CONFIG still
said there was no metrics endpoint, that cache hit rates were wrong,
that a broadcast failure only logged a warning, that lock waits always
ended in EIO after 30 seconds, that the inode count was fixed at 4096,
and listed env vars that do not exist.

They now cover the HTTP API, gfsctl and /metrics, the unicast port and
the broadcast startup check, lock wait limits for live and failed
holders, the v2 and pre-#85 format errors, when -skip-recovery is
safe, the log lines that show whether recovery ran, what SIGINT and
SIGTERM do at shutdown, and how to run the tests -short skips. Commands
and log lines were checked on a test host at 30500b7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mattmattox
mattmattox merged commit ba5668b into main Nov 13, 2026
13 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