Skip to content

docs: OS-specific commands and risk callouts #276

Closed

Description

@Bugs5382

Summary

The operator docs assume a Unix shell for workstation commands (random key generation, password hashing, EST calls with base64, cat and grep pipelines, </dev/null redirects), so a Windows operator has no working equivalent. Risks such as the maintenance-mode takeover window, the nodeid dev-tier key posture and key-custody rules sit in paragraph text, and expected output is easy to mistake for a command. Show OS-specific commands for both platforms, move the risks into alerts, and put expected output in tip alerts.

Acceptance criteria

  • Every command that depends on the reader's OS is shown twice: Linux / macOS (bash) and Windows (PowerShell) (powershell), and every PowerShell command works in PowerShell 5.1 and 7.
  • Commands that behave the same everywhere (openssl, cryptosctl, docker, helm, kubectl, npm, task) stay a single block. Commands that run on the node, a Linux build host or a domain controller stay single.
  • Every real risk a reader can hit is a GitHub alert placed right before the step it guards ([!CAUTION] for irreversible or security-critical steps, [!WARNING] for steps that break or take something down, [!IMPORTANT] for easy mistakes and preconditions, [!TIP] / [!NOTE] for checks and context). Inline bold "do not" warnings become alerts with the same meaning.
  • Every expected-output block sits in a > [!TIP] alert that says what the output means and what to do when it differs.
  • No change to meaning, step order or other wording.

Tasks

  • README.md
  • build/README.md
  • docs/acme.md, docs/est.md
  • docs/active-directory.md, docs/management-trust.md, docs/vmca-subordination.md, docs/subordinate-recertify.md
  • docs/certificate-profiles.md, docs/image-upgrade.md, docs/issued-certificates.md, docs/secure-boot.md

Notes

Docs-only change. cryptosctl has no Windows build yet (#275), so each page that runs cryptosctl says once that it runs on Linux and macOS today and a Windows build is coming.

Metadata

Metadata

Assignees

Labels

documentationDocumentation only (docs).

Type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions