docs(runbook): say where the lab's certificates are and how to move them (#262) - #322
Merged
Conversation
…hem (#262) §5 said "copy three files into ~/HomeLab/certificates/ on alexander" and left every part of that unanswered: which directory they come from, that the destination does not exist, and that the obvious way to move them cannot work. **99 → 30 is closed.** An scp from `prometheus` to `alexander` has no rule to carry it — the one exception on that interface is the iLO's SNMP return path. Hicks reaches both segments, so the Mac is the only machine that can see both ends, and the copy has to be driven from there. Nothing said so, and the failure is a hang rather than a refusal. `certificates/` is gitignored, so a fresh clone on the guest does not have the directory at all and scp fails into a path that is not there. The mkdir is now the first command rather than something to work out from an error. `scp -3 -p`, so the private key is routed through the Mac without being written to its disk, and so the mode survives the trip — a default umask would leave a TLS private key world-readable, and the runbook now says to check rather than assume. 0640 owned by the deploying user is what compose.yaml's `group_add: ${RENDER_GID}` on grafana is built around, so the reason the mode matters is stated where the mode is set. A CAUTION on `ca-key.pem`: it is deliberately absent from the list, and `scp certificates/*` would put the key that signs every certificate in the estate onto the segment built to hold attackers. Naming the three files is the control, so the reason for naming them is written down. The files are listed in a table with what each one is for, because "copy three files" reads as three interchangeable blobs and one of them is a private key. 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.
Found by following §5 on a real build. It said "copy three files into
~/HomeLab/certificates/onalexander" and left every part of that unanswered.The one that actually blocks you
99 → 30is closed. Anscpfromprometheustoalexanderhas no rule to carry it — the only exception on that interface is the iLO's SNMP return path. Hicks reaches both segments, so the Mac is the only machine that can see both ends, and the copy has to be driven from there.Nothing said so, and the failure mode is a hang rather than a refusal, which is the worst way to learn it.
The rest of what was missing
certificates/at the root of the deploy checkout —/home/robo/code/Gerrrt/HomeLab/certificates/onprometheus. §5 never named a source directory.certificates/is gitignored, so a fresh clone on the guest has no such directory andscpfails into a path that is not there. Themkdiris now the first command instead of something to reverse-engineer from an error.scp -3 -p, so the private key routes through the Mac without touching its disk, and so the mode survives. A default umask would leave a TLS private key world-readable; the runbook now says to check rather than assume.0640owned by the deploying user is whatcompose.yaml'sgroup_add: ${RENDER_GID}on grafana is built around, so the reason the mode matters is stated where the mode is set.And one that could have been expensive
A
CAUTIONonca-key.pem. It is deliberately absent from the list, and a reflexivescp certificates/*would put the key that signs every certificate in the estate onto the segment built to hold attackers. Naming the three files individually is the control, so the reason for naming them is now written down next to them.The three are listed in a table with what each is for, because "copy three files" reads as three interchangeable blobs and one of them is a private key.
Verification
make check-docsandmake lintpass. Documentation only — no configs touched, nothing deployed.🤖 Generated with Claude Code