Skip to content

Add a Let's Encrypt walkthrough, and flag the fog-client question - #128

Closed
darksidemilk wants to merge 1 commit into
masterfrom
lets-encrypt-worked-example
Closed

darksidemilk wants to merge 1 commit into
masterfrom
lets-encrypt-worked-example

Conversation

@darksidemilk

Copy link
Copy Markdown
Member

Part of FOGProject/fogproject#1120 (Phase 3). Depends on #124 for the link target.

Adds docs/kb/how-tos/lets-encrypt-setup.md. external-ca-lets-encrypt explains the reasoning well and never quite tells anyone what to type — this is the steps: issue with DNS-01, point .fogsettings at the files, fix the two places the server's name has to match, run the installer in public-cert mode, verify, wire up renewal.

Written around the two things that catch people out

acmeLeaf and publicWebCert look redundant and are not. One says who renews the leaf, the other says what it chains to. All four combinations are real, and an internal step-ca is the acmeLeaf=yes / publicWebCert=no corner. You want both here, for different reasons.

FOG_WEB_HOST has to be set to the certificate's FQDN. Miss it and netboot fails in the most misleading way available — the first hop succeeds, because the boot script uses the hostname, and then every URL boot.php builds afterwards uses the IP address FOG_WEB_HOST still holds. It looks like a certificate problem and is not.

One thing the page deliberately does not answer

pki-zones puts the cost of changing the Web TLS zone at "None" since the 1.6 zone split, while external-ca-lets-encrypt still documents fog-client as pinning ca.cert.der and needing it in the served chain — which a Let's Encrypt chain does not have. That passage predates the split and has not been re-verified against it, and fog-client is not in the fogproject repository to check.

Rather than guess, the page says the two disagree, tells you to prove it on one registered client before a fleet rollout, and gives the step-ca route as the fallback if the pinning caveat still holds. Netboot and browser trust are unaffected either way.

This is worth resolving properly — whichever way it lands, one of the two pages needs correcting.

Cloudflare recipe

Marked as a slot to fill, per the issue. Nothing else on the page depends on which DNS provider is used.

Verified

Full Quartz build: no errors, unparsed-wikilink count still 12, and both cross-page anchors confirmed present as ids in the built HTML rather than assumed — Quartz does not warn about a wrong anchor.

…is not known

external-ca-lets-encrypt explains the reasoning well and never quite tells
anyone what to type. This is the steps: issue with DNS-01, point .fogsettings
at the files, fix the two places the server's name has to match, run the
installer in public-cert mode, verify, wire up renewal.

Written around the two things that actually catch people out.

acmeLeaf and publicWebCert look redundant and are not: one says who renews the
leaf, the other says what it chains to. All four combinations are real, and an
internal step-ca is the acmeLeaf=yes / publicWebCert=no corner. You want both
here, for different reasons.

FOG_WEB_HOST has to be set to the certificate's FQDN. Miss it and netboot fails
in the most misleading way available -- the first hop succeeds, because the
boot script uses the hostname, and then every URL boot.php builds afterwards
uses the IP address FOG_WEB_HOST still holds. It looks like a certificate
problem and is not.

On fog-client the page deliberately does not answer. pki-zones puts the cost of
changing the Web TLS zone at 'None' since the 1.6 zone split, while
external-ca-lets-encrypt still documents fog-client as pinning ca.cert.der and
needing it in the served chain -- which a Let's Encrypt chain does not have.
That passage predates the split and has not been re-verified against it, and
fog-client is not in this repository to check. Rather than guess, the page says
the two disagree and tells you to prove it on one registered client before a
fleet rollout, with the step-ca route as the fallback if the pinning caveat
still holds.

The Cloudflare DNS-01 recipe is marked as a slot to fill; nothing else on the
page depends on which DNS provider is used.

Verified with a full Quartz build: no errors, unparsed-wikilink count still 12,
and both cross-page anchors confirmed present as ids in the built HTML rather
than assumed -- Quartz does not warn about a wrong anchor.

Co-Authored-By: Claude <noreply@anthropic.com>
darksidemilk added a commit that referenced this pull request Aug 23, 2026
Both PRs predate the .fogsettings rename and each had one file that master
has since replaced, so the salvageable content is carried here rather than
merged.

From #125, the substantive correction to secure-boot-signing.md: FOG *does*
sign its own iPXE binaries with this server's Secure Boot key, so the page
no longer claims it cannot. The real tradeoff is whether a custom binary is
worth enrolling a key before the machine can netboot -- not "signed shim or
custom binary". Its local-esp-boot.md is dropped; merged #129 put a newer
version of that page on master.

From #128, the Let's Encrypt walkthrough, with step 2 rewritten. As written
it set acmeLeaf=yes and repointed the certificate paths, and under 1.6 that
is the failure it was written to prevent: acmeLeaf is retired, repointing a
canonical path moves nothing because the installer recomputes it, and a real
file at the canonical path sits inside FOG's own web zone -- so FOG concludes
the leaf is its and re-issues it. The page now symlinks the canonical paths
at the ACME files and sets PKI_web_cert_publicly_trusted, and separates the
two questions FOG answers differently: who renews the leaf is derived from
the filesystem, what it chains to is the one thing that must be declared.

Neither PR's kb/how-tos/index.md is used -- both branched before #129 added
the Secure Boot section and would have removed it. The one new entry is
added by hand instead.

Also drops a dev branch name that had leaked into admin-facing text in
migrating-fog-server.md, where --external-ca was described as the
working-1.6 spelling; both spellings ship and work.

Co-authored-by: Jesse Fullmer <jfullmer@arrowheaddental.com>

Copy link
Copy Markdown
Member Author

Closing — the walkthrough is carried forward on claude/fogsettings-key-rename-docs-b1i2vg (commit d37d196), with step 2 rewritten.

The reason it needed rewriting rather than renaming. Step 2 said:

acmeLeaf='yes'
publicWebCert='yes'
sslPrivKey='/etc/letsencrypt/live/fog.example.com/privkey.pem'
sslPubCert='/etc/letsencrypt/live/fog.example.com/fullchain.pem'

Under working-1.6 all four lines are inert or wrong, and following them produces the exact failure the step was written to prevent:

  • acmeLeaf is retired. It had to be typed in by hand, and forgetting it meant FOG re-issued the leaf from the stored request while an ACME private key sat beside it — a mismatched pair and a web server that would not start, silently, under -y. The signal is derived now: _externallyManagedLeaf() asks whether PKI_web_vhost_cert resolves outside _pkiZoneDir web. A symlink cannot disagree with itself, where a persisted flag and two recorded paths could each disagree with the vhost.
  • Repointing the certificate paths does nothing. PKI_web_vhost_cert/_key are canonical and recomputed on every run. The model is inverted from 1.5: the setting holds FOG's fixed path, and you make that path resolve to your file.
  • Consequently, having the ACME client write a real file to /opt/fog/pki/web/leaf/.webLeaf.pem — the natural reading of the old instruction — is now the worst option available. That path is inside FOG's own web zone, so FOG concludes the leaf is its and re-issues it.

Step 2 now symlinks the canonical paths at the ACME files and sets PKI_web_cert_publicly_trusted='yes', and separates the two questions FOG answers differently: who renews the leaf is derived from the filesystem, what it chains to is the one thing that has to be declared, because nothing on disk can tell FOG that. The step-ca example survives as "externally renewed leaf with PKI_web_cert_publicly_trusted='no'".

Step 1's "Do not copy the files into FOG's own PKI tree" was already right under the new model and is unchanged. --install-mode public-cert's effects are restated with shipped key names, and the renewal section now says FOG follows the symlinks rather than reading "where you pointed it".

The rest came across intact, including the FOG_WEB_HOST warning, the verification steps, and the fog-client caveat with its unresolved disagreement flagged as unresolved. The context_id: lets-encrypt-setup is unique. The Cloudflare DNS-01 placeholder is preserved and still credited to @darksidemilk — converted to an Obsidian callout per the repo convention.

kb/how-tos/index.md was not taken: this branch predates #129, so its version would have removed the Secure Boot section. The one new entry is added by hand.


Generated by Claude Code

darksidemilk added a commit that referenced this pull request Aug 23, 2026
Both PRs predate the .fogsettings rename and each had one file that master
has since replaced, so the salvageable content is carried here rather than
merged.

From #125, the substantive correction to secure-boot-signing.md: FOG *does*
sign its own iPXE binaries with this server's Secure Boot key, so the page
no longer claims it cannot. The real tradeoff is whether a custom binary is
worth enrolling a key before the machine can netboot -- not "signed shim or
custom binary". Its local-esp-boot.md is dropped; merged #129 put a newer
version of that page on master.

From #128, the Let's Encrypt walkthrough, with step 2 rewritten. As written
it set acmeLeaf=yes and repointed the certificate paths, and under 1.6 that
is the failure it was written to prevent: acmeLeaf is retired, repointing a
canonical path moves nothing because the installer recomputes it, and a real
file at the canonical path sits inside FOG's own web zone -- so FOG concludes
the leaf is its and re-issues it. The page now symlinks the canonical paths
at the ACME files and sets PKI_web_cert_publicly_trusted, and separates the
two questions FOG answers differently: who renews the leaf is derived from
the filesystem, what it chains to is the one thing that must be declared.

Neither PR's kb/how-tos/index.md is used -- both branched before #129 added
the Secure Boot section and would have removed it. The one new entry is
added by hand instead.

Also drops a dev branch name that had leaked into admin-facing text in
migrating-fog-server.md, where --external-ca was described as the
working-1.6 spelling; both spellings ship and work.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gj9EW4NNDT8JHHghG3pZDt
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant