Skip to content

docs: OS-specific commands and risk callouts - #277

Merged
Bugs5382 merged 1 commit into
mainfrom
docs/276-os-commands-callouts
Sep 30, 2026
Merged

Bugs5382 merged 1 commit into
mainfrom
docs/276-os-commands-callouts

Conversation

@Bugs5382

Copy link
Copy Markdown
Contributor

What and why

The operator docs assumed a Unix shell for workstation commands, kept risks in paragraph text, and showed expected output in bare code blocks that read like commands. This PR:

  • Shows each OS-specific workstation command twice, Linux / macOS (bash) and Windows (PowerShell) (powershell): the ACME external account key and EST password generation, the EST /cacerts and simpleenroll calls, the openssl management-certificate fetch (</dev/null has no PowerShell form), and the VMCA grep / cat steps. openssl, cryptosctl and task commands stay single, as do commands that only run on a Linux build host, a live Linux USB or a domain controller.
  • EST simplereenroll stays single for now. On Windows, curl.exe (Schannel) takes a client certificate from the certificate store or a PFX file, not the PEM pair the example uses, and that path has not been checked on Windows.
  • Adds a note on each page that runs cryptosctl: it runs on Linux and macOS today, and a Windows build is coming (feat(cryptosctl): ship a Windows build #275).
  • Moves each real risk into a GitHub alert with its existing wording: [!CAUTION] for key material, revocation, the maintenance-mode takeover window, the nodeid dev tier and PCR 7 changes; [!WARNING] for reboots, the vCenter import and untested hardware paths; [!IMPORTANT] for preconditions and easy mistakes; [!NOTE] for scope.
  • Puts every expected-output block in a [!TIP] alert that says what the output means and, where it matters, what to do when it differs.
  • In docs/image-upgrade.md, three items from "Limits worth knowing" (the pre-reseal TPM node, an image that does not boot, no production-hardware run yet) move, wording unchanged, into callouts at the steps they guard. Everything else keeps its order and wording.

Closes #276

Verification

  • Lint clean
  • Tests pass
  • Build succeeds
  • Documentation updated (if behavior or API changed)

How this was verified

  • task ci (gofmt, golangci-lint, vet, test, build) and task license pass locally.
  • Every file was rendered through the GitHub Markdown API: every > [!…] alert renders as an alert.
  • Every PowerShell block parses cleanly with the PowerShell 7 parser. The ACME key and EST password blocks, the Select-String filters, Get-Content/Set-Content and the 'Q' | openssl s_client fetch were also run in PowerShell 7. The EST password digest matches sha256sum for the same password, and the generated key decodes with base64.RawURLEncoding as the config loader does. The blocks avoid PowerShell 7-only syntax. Native-to-native pipes carry only PEM text, and binary data goes through files, because PowerShell 5.1 does not pipe bytes.
  • Select-String takes -CaseSensitive to match grep: without it, CA: also matches hex bytes in the modulus.
  • Claims were checked against the code: revocation has no undo path (internal/revocation/store.go), the maintenance listener requires NoClientCert, EST returns single-line base64 and reenrol requires clientAuth, and ACME keys decode as unpadded base64url.

…ed output into callouts

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
@Bugs5382 Bugs5382 reopened this Sep 30, 2026
@Bugs5382

Copy link
Copy Markdown
Contributor Author

Closing summary: OS-specific commands in README, build/README and docs/ now show Windows (PowerShell) next to Linux / macOS, and risks and expected output sit in GitHub alert callouts. Rebased onto main with the DCO sign-off added. One conflict with #282 in docs/vmca-subordination.md: #282's CAUTION callout for TPM-held RSA keys replaces this PR's now-outdated "TPM-resident RSA not supported" note; every other hunk is unchanged. (While the branch was being rebased it was briefly pointed at main, which auto-closed this PR; it was restored and reopened.) CI green on d8caff5. Squash-merging with the owner's approval; closes #276.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation only (docs).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: OS-specific commands and risk callouts

1 participant