docs(runbook): §0 had no switch step, and port 15 had moved - #494
Merged
Merged
Conversation
`build-the-nas.md` §0 reads as the complete list of what can be done before the drives land — BIOS, AMT, the static, the reservation, the rules, the proof — and it was missing a step that had demonstrably been taken: `smaug`'s switch port moved from VLAN 30 to VLAN 40. Read off `neo` on 2026-09-17: port 15 is untagged VLAN 40 with PVID 40, `smaug`'s MAC is learned on it in VLAN 40, and the link is up at 1000M full. The map was last read on 2026-09-04 with port 15 still ImaginationLAN's and matching the documented map exactly, so the move happened between those two readings. The install is the obvious occasion and that is recorded as an inference rather than a date, because the move itself was never written down. Adds §0.2b rather than the §0.4b the issue suggested. The step has to precede §0.3: that step sets a static on 10.0.40.0/24 and TrueNAS applies it on a test-and-confirm timer, so on a port still carrying VLAN 30 the static loses contact and rolls itself back. Inserted as a letter suffix rather than a renumber because ADR-0016 and ADR-0040 both cite this file's §0.5 by number and ADR-0001 makes accepted ADRs immutable. The step records this machine's port and not the port map — that lives on the wiki's `infrastructure/switching` page, and copying it here would be a second copy with nothing checking it (ADR-0026). It also carries the re-patch: VLAN 40 is the yellow cable and VLAN 30 the green one, so a port taken from the lab segment is holding the wrong lead, which is the trap ADR-0009 exists to close. §7 gains the reading that proves it, taken in the switch UI rather than over SNMP. §0.3–§0.6 are untouched. Refs #481 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Gerrrt
added a commit
that referenced
this pull request
Sep 17, 2026
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
build-the-nas.md§0 is written as the complete list of what can be done beforethe drives land — BIOS, AMT, the static, the Kea reservation, the firewall
rules, then the proof. It was missing a step that had demonstrably been taken:
smaug's switch port moved from VLAN 30 to VLAN 40.Read off
neoon 2026-09-17: port 15 is untagged VLAN 40 with PVID 40,smaug's MAC is learned on it in VLAN 40, and the link is up at 1000M full— the fastest thing answering on that segment, which is what identifies the
port. The map was last read on 2026-09-04 with port 15 still ImaginationLAN's
and matching the documented map exactly, so the move happened between the two
readings. The install on 2026-09-16 is the obvious occasion, and that is written
down as an inference rather than a date, because the move itself was never
recorded.
Why it is a step and not a shrug
§0.3 and §0.4 hold the address twice "because either alone is a single point of
drift". The port is that argument one layer down: a NAS on a port still on the
lab segment takes a lab address, none of §0.5's rules reach it, and "can I
reach the NAS" fails in a way indistinguishable from a firewall fault —
which sends the search to the pfSense UI, where the answer is not. §0.5 warns
about the mirror image of that, a rule appended where it matches nothing and
leaves the question passing for the wrong reason.
The runbook also recorded no port number at all, so a successor re-cabling this
machine had nothing to re-cable it to.
§0.2b, not the §0.4b the issue suggested
The step has to precede §0.3. That step sets a static on
10.0.40.0/24andTrueNAS applies it on a test-and-confirm timer, so on a port still carrying VLAN
30 the static loses contact the moment it is applied and rolls itself back —
§0.4b would put the step after the two steps that depend on it.
A letter suffix rather than a renumber, because ADR-0016 and ADR-0040 both
cite this file's §0.5 by number and ADR-0001 makes accepted ADRs immutable.
§0.3–§0.6 are untouched.
What the step carries
neo, untagged VLAN 40, PVID 40 — read back after saving, since membership and PVID are set separately on this firmwaremorpheus) or port 3 (the unmanaged shelf switch)infrastructure/switchingpage. Copying it here would be a second copy with nothing checking it (ADR-0026). Only this machine's own port is recordedA hedge the reading earns: port 15 is a fact about
neo, and the MikroTikbought to replace it (#444) will need its own reading.
§7 gains the assertion, taken in the switch UI rather than over SNMP —
ADR-0025 records that Winterfell's only durable path to
10.7.7.2is SNMP, andthat the
10.0.99.20 → 10.7.7.2:80/tcppass which would carry an HTTP check"grants access nothing uses" and is due for removal. A check built on it would
rot.
Blast radius
secrets/*.sops.yamlThe port move already happened on the switch; this records it. Documentation
only — no host, service or config is touched.
Verification
make validatewas started and had not cleared the observabilitypromtool test rulesstage after several minutes on a host at load 32 — the known local flakeunder a busy shared docker daemon. Nothing in a prose edit to one runbook can
reach it, and CI runs it on a clean runner.
Out of scope, filed separately
A three-versus-four rule count contradicting itself in two documents: §0.5's
heading and table say three rules while the status callout says four were
created, and
network.md's CasaBonita notes say "the three rules created thatday" in one bullet and "four host-scoped, port-scoped passes" in the next.
Neither is guarded by
check_docs.py.Closes #481
🤖 Generated with Claude Code