Carry the .fogsettings key rename into the docs, and clear the pre-rename PR backlog

[darksidemilk]

FOG 1.6 (GH-1120) renamed all 79 managed .fogsettings keys to CATEGORY_lower_snake_case, leaving 66 — six retired, nine absorbed, two promoted. That change deliberately left the admin-facing docs alone ("The admin-facing fog-docs pages, and the still-stale command-line-options.md, remain a separate change"). This is that change.

Key names, flag list and behaviour all come from the shipped working-1.6 code — managedKeys/deprecatedKeys in lib/common/functions.sh, the option handlers in bin/installfog.sh — not from the plan. The plan's own Outcome section records where the two diverged.

The two pages that were asked for

docs/management/server/install-fogsettings.md — rewritten to the nine-category model. All 66 keys documented by category, each tagged preference / record / hand-set / inferred preference. That taxonomy was previously implicit; it is now explicit and stated once up front, because it is the thing that tells a reader whether a hand edit survives the next installer run. Includes why a preference and a record can never share one key, using the BOOT_url_proto bug as the worked example.

docs/installation/server/command-line-options.md — regenerated; it was still showing the pre-1.6 option list. --install-mode (with the four presets), --netboot-proto, --public-web-cert and --rebuild-ipxe-with-my-ca are all covered.

The full option block is now rendered from the installer's own --help output rather than transcribed by hand. That is what caught --no-ca-trust and --no-sb-name-constraints, both removed in 1.6 with the settings behind them, and picked up help text the page predated: -C implying --recreate-keys, -K's warning that every registered fog-client must be re-pinned, and --no-secure-boot now declining enrolment rather than signing.

Two corrections that are not renames

Some pages did not merely name retired settings — they told readers to set them, and following them now breaks a server.

The ACME instructions inverted. external-ca-lets-encrypt.md had the ACME client install certificates straight to FOG's canonical leaf paths and then set acmeLeaf=yes. Under 1.6 that produces the exact failure it was written to prevent: _externallyManagedLeaf() decides ownership by asking whether PKI_web_vhost_cert resolves outside _pkiZoneDir web, so a real file at that path reads as FOG's own and gets re-issued from the stored CSR while the ACME private key sits beside it — a mismatched pair and a web server that will not start, silently, under -y. The client now owns its own directory and the canonical paths are symlinked at it.

Relocating a certificate by editing the path. pki-zones.md did this with sed on .fogsettings. Canonical paths are recomputed every run, so that edit moves nothing.

PR backlog

Five PRs predated the rename and overlapped it.

• Scope the db-alone enrolment claim to firmware and hypervisor routes #130 — merged separately. It was clean and fixed an inaccuracy already live on master; master is merged back into this branch.
• Document local ESP boot, and stop saying FOG cannot sign its own iPXE #125 closed, salvage carried here: the correction that FOG does sign its own iPXE binaries (so the tradeoff is whether a custom binary is worth enrolling a key before netboot, not "signed shim or custom binary"), plus the migrating-fog-server.md tidy. Its local-esp-boot.md was superseded by merged Document booting FOG from a machine's own ESP, and what db enrolment replaces #129.
• Add a Let's Encrypt walkthrough, and flag the fog-client question #128 closed, walkthrough carried here with step 2 rewritten to the canonical-symlink model. Its step 1 ("do not copy the files into FOG's own PKI tree") was already correct and is unchanged.
• Document the transport and PKI keys, and the 1.6 rename #126 and Document the install modes and every undocumented installer flag #127 closed as superseded — they document the intermediate camelCase step (httpProto, sslPath) and, in Document the install modes and every undocumented installer flag #127's case, the two removed flags. Their surviving substance is folded in.
• Document the ping hosts service and the two last-seen fields #131 untouched — not ours, and verified read-only to name no retired setting.

Neither #125's nor #128's kb/how-tos/index.md was usable: both branched before #129 and would have deleted the Secure Boot section it added. The one new entry is added by hand instead.

Each closed PR carries a comment explaining what moved and why.

Verification

• cd quartz && npm i && npm run docs:build — clean, no warnings (110 files, 954 emitted).
• All 66/66 managed keys present, with no invented names (cross-checked against managedKeys).
• Every internal wikilink and in-page anchor on the changed pages resolves; the deep anchors into external-ca-lets-encrypt still land.
• Literal [[ in the built HTML held at 12, all pre-existing and unrelated — 9 are shell [[ -z $var ]] inside code blocks, 3 are old MediaWiki links in pages not touched here.
• Retired-key sweep: every remaining hit is either a deliberate "this was renamed/removed" table row, a labelled FOG 1.5 mention, or the storage-node sslpath CSV field that ADR 0024 explicitly excludes (it is that endpoint's own field name mapping to a storageNode column).

One trap worth knowing

A wikilink inside a table cell needs its pipe escaped — [[target\|Text]]. Unescaped, the | is read as a column separator and the link renders literally as [[page, and the build does not warn. This bit the change once before being caught in the built HTML. The check is grep -rnE '^\|.*\[\[[^]]*[^\\]\|' docs --include=*.md, and it may be worth adding to CLAUDE.md alongside the existing newline-wrapped-wikilink warning.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Gj9EW4NNDT8JHHghG3pZDt

---

Generated by Claude Code