Skip to content

docs(runbook): four rules not three, and the switch step §0 never had (#413) - #501

Merged
Gerrrt merged 5 commits into
mainfrom
gerrrt/nas-smaug-casabonita-10f61a
Sep 18, 2026
Merged

Gerrrt merged 5 commits into
mainfrom
gerrrt/nas-smaug-casabonita-10f61a

Conversation

@Gerrrt

@Gerrrt Gerrrt commented Sep 17, 2026

Copy link
Copy Markdown
Owner

build-the-nas.md §0 is complete and §1–§7 is blocked on two drives that have
not been delivered — the last carrier event is 2026-09-11 and the estimated
window (Mon Sep 14 – Thu Sep 17) has now lapsed. So this corrects the documents
the build will be run from rather than advancing the build.

This PR was opened before three peer sessions landed overlapping work, and
has been rewritten to say what actually survives.
It has since merged main
twice, dropped its own §0.2b and its own security.md change in favour of
better versions, and closed #502
as superseded after taking that PR's better idea. What is left is listed below.

What this PR still contributes

§0.6's recorded proof pointed at the wrong command — the core of it

The evidence read "167–168 before 169 on igc0.99, 194–195 before 196 on
igc0.50"
. Those are right for pfctl -sr | grep -n and wrong for
pfctl -sr -vv, which numbers the same four rules @148, @149, @175,
@176. Both readings came off the live ruleset in one invocation — they
disagree by however many scrub rules precede the filter set, because -vv
numbers each ruleset from zero while grep -n counts output lines.

The command §0.6 needs is the one the numbers do not match, because the
tripwire check reads a counter and counters only come from -vv. §0.6 now
proves position by rule description, with a command verified against
morpheus, and says to read the order rather than the numbers. §0.5 carries
each rule's description because §0.6 matches on it.

The tripwire wording now separates packets, which must be zero, from
evaluations, which only climb — 118,621, then 128,629, then 129,266, with
nothing wrong on any reading.

§0.5's count, and stacks/media/README.md

§0.5 was headed "Create the three rules" over a three-row table while the
callout at the top of the same file said four. Now four rows, one per port.
stacks/media/README.md called the Hicks access "the one rule"; it is two.

network.md — the count now lives in one bullet

Adopted from #502, which had the better answer: two adjacent bullets both
counted the passes and drifted apart, so the first no longer counts them at all
and the second is the authority. Correcting both would have left the drift
vector in place. Also carries the port-15 record.

Three gaps that would have bitten mid-build

  • §2 offered SSH as an alternative to the console. TrueNAS ships it
    disabled, §0.5 says the port-22 pass is inert, and 10.0.40.30:22 is closed
    from the monitoring host.
  • §6 said "deploy the stack" with no command.
  • §6's QSV check was ls -l /dev/dri on the host, which re-confirms the
    half that was never in doubt. ADR-0040's reopen condition is whether a
    container reaches the iGPU, so the check now runs inside it and inspects
    the supplementary groups group_add exists to set.
  • §7's 9100 bullet read as a step that would pass, when nothing in §1–§6
    stands up a listener and Add the scrape path for a host that pushes nothing #256 has yet to settle its shape.

One claim made true rather than softened

ADR-0040 keeps stacks/media here so that "Dependabot, the digest pins and
make validate keep reaching it"
, and §6 and the stack README repeat it. The
pins and make validate did reach it; Dependabot did not — there was no
/stacks/media entry, so the Jellyfin digest pin was rotting unattended.

One sentence kept from this branch's own §0.2b

main's §0.2b (PR #494) is the better section and is what survives — cable
colour, the TrueNAS test-and-confirm rollback, the port 1 / port 3 exclusions.
This branch added one thing it lacked: that the section must stay lettered,
because renumbering §0.3 onward would move §0.5, which ADR-0016 and ADR-0040
both cite by name
while ADRs are immutable (ADR-0001).

What this PR dropped to peers

CI

check-docs is red on this branch entirely from main — two ADR-0041
files and README.md's ADR and runbook counts. Nothing here causes or can fix
it; #509 does. This PR goes green
once that merges.

Re-read from morpheus before pushing: four passes above Block access to
CasaBonita
on their interfaces, 443 still refused from Winterfell,
igc0.40 tripwire zero packets.

Scope

Refs #413the build is not done; the drives are still in transit and
§1–§7 is untouched.

Found and left out, worth their own issues: make backup STACK=media dies
today for want of a backup sentinel, scripts/pin-digests.sh only ever reads
stacks/observability, and README.md:210 says 39 ADRs in a spot
check_docs.py does not guard.

🤖 Generated with Claude Code

…#413)

build-the-nas.md §0 is complete and §1–§7 is blocked on two drives that have
not been delivered. So this corrects the documents the build will be run from
rather than advancing the build.

Four things were wrong, and three of them were files contradicting themselves.

THE RULE COUNT. Four passes were created on 2026-09-16; §0.5's heading, its
table and two other documents still said three. §0.5 now lists four rows, one
per port, and carries each rule's description — which §0.6 has started
matching on. network.md said "the three rules created that day" seven lines
above a bullet correctly saying four. security.md was worse: "Neither is
created yet; both wait on the host that would use them", of two decisions,
only one of which is still pending. Checked on the live ruleset: ADR-0016's
passes exist, ADR-0035's pass to the Hue bridge genuinely does not, so the
sentence is split rather than replaced. stacks/media/README.md called the
Hicks access "the one rule" and it is two.

THE RECORDED PROOF. §0.6's evidence was "167-168 before 169 on igc0.99,
194-195 before 196 on igc0.50". Those numbers are right for
`pfctl -sr | grep -n` and wrong for `pfctl -sr -vv`, which numbers the same
four rules @148, @149, @175 and @176 — both read off the live ruleset in one
invocation, the two disagreeing by however many scrub rules precede the filter
set. The command §0.6 needs is the one the numbers do not match, because the
tripwire check reads a counter and counters only come from -vv. §0.6 now
asserts the invariant by rule description and says to read the order rather
than the numbers. The tripwire wording separates packets, which must be zero,
from evaluations, which only climb: 118,621 then 128,629 with nothing wrong on
either day.

THE SWITCH STEP. §0 never said the port had to move from VLAN 30 to VLAN 40,
nor which port it was. Added as §0.2b — before §0.3, because a static on a
port still carrying VLAN 30 is a host with no gateway and makes §0.4's
reservation and §0.5's four rules silently pointless. Lettered rather than
renumbering §0.3 onward, because ADR-0016 and ADR-0040 both cite §0.5 by name
and ADRs are immutable.

THREE GAPS THAT WOULD BITE MID-BUILD. §2 offered SSH as an alternative to the
console; TrueNAS ships it disabled and §0.5 says the port-22 pass is inert.
§6 said "deploy the stack" with no command. §6's QSV check was `ls -l /dev/dri`
on the host, which re-confirms the half that was never in doubt — ADR-0040's
reopen condition is whether a container reaches the iGPU, so the check now
runs inside it and looks at the supplementary groups group_add exists to set.
§7's 9100 bullet read as a step that would pass, when nothing in §1–§6 stands
up a listener and #256 has yet to settle its shape.

Also adds the /stacks/media Dependabot entry. ADR-0040 keeps the media stack
in this repository so that "Dependabot, the digest pins and make validate keep
reaching it", and build-the-nas.md §6 and the stack README repeat the claim.
The pins and make validate did reach it; Dependabot did not.

Verified against the live firewall from morpheus: all four passes above
Block access to CasaBonita on their interfaces, 443 still refused from
Winterfell, igc0.40 tripwire zero packets.

Refs #413
Closes #481

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
main landed #481's switch step (PR #494) while this branch was doing the same
work. Resolved by taking main's §0.2b wholesale — it is the better section:
it has the cable-colour re-patch (ADR-0009), the TrueNAS test-and-confirm
rollback that explains *why* the order matters, and the port 1 / port 3
exclusions. This branch's own §0.2b is dropped entirely.

Four conflicts, each resolved to keep both intents:

- Header "You will need": main's `neo` web UI and yellow lead, plus this
  branch's correction that smaug's web UI cannot run §2 or §6 and SSH is off.
- Status block: main's, which carries the §0.2b line and the note that it is
  the one step in §0 without a date.
- §0.2b: main's, plus one sentence this branch had and main lacks — that the
  section must stay lettered, because renumbering §0.3 onward would move §0.5,
  which ADR-0016 and ADR-0040 both cite by name and ADRs are immutable.
- §7: main's port-15 bullet, which is better worded (read in the switch UI,
  not inferred from the host having an address), plus this branch's #256
  cross-reference on the 9100 bullet and the packets-versus-evaluations split
  on the tripwire.

main's §0.5 still said "Create the three rules", so this branch's rule-count
correction is unaffected and still needed.

NOTE: main is red independently of this merge — README.md:95-96 claim 41 ADRs
and 26 runbooks against 42 and 27 on disk, and two ADR-0041 files exist
(0041-run-the-crs326-... and 0041-terminate-the-remote-path-...). None of
those files are touched by this branch.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The count was stated in two adjacent bullets and they drifted apart — one
said three long after four existed, which is how #501 found it. Correcting
both would have left the drift vector in place, so the first bullet no longer
counts them at all and the second is the authority.

Taken from #502, which reached the same three files independently and had the
better answer on this one point.

Refs #413

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Gerrrt and others added 2 commits September 18, 2026 01:06
Two conflicts, resolved in opposite directions.

docs/security.md — took main's wholesale. It rewrites the paragraph into two
labelled halves, "CasaBonita's exist" and "Skids' does not exist", adds that
the passes were verified in position with pfctl rather than read off the web
UI, notes that the 22 is inert under ADR-0040, points at network.md as the
authority for the list, and cites #134 for the Skids pass. That is strictly
better than this branch's split of the same sentence, so this branch's version
of security.md is dropped entirely.

docs/network.md — kept this branch's. main corrected the first bullet's count
from three to four; this branch removes the count from that bullet altogether
and leaves the next one as the sole authority, because the count being stated
twice is what let the two drift apart in the first place. Correcting both
leaves the drift vector in place. This side also carries the port-15 bullet.

NOTE: check-docs is still red on this branch, entirely from main — the two
ADR-0041 files and README.md's ADR and runbook counts. PR #509 fixes those;
nothing here can.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Gerrrt
Gerrrt merged commit 0d52cc6 into main Sep 18, 2026
3 checks passed
@Gerrrt
Gerrrt deleted the gerrrt/nas-smaug-casabonita-10f61a branch September 18, 2026 03:00
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