Document netboot transport and PKI, and retire the mutual-exclusion claim - #124
Merged
Conversation
…laim FOG 1.6 splits what 1.5 conflated into a single httpproto setting: the web protocol, the HTTP-to-HTTPS redirect and whether iPXE is recompiled are now independent keys, with --install-mode as a preset over them. None of that was documented, and several pages still told admins the opposite. The flat contradiction was proxy-dhcp's "Secure Boot and HTTPS are mutually exclusive". They are not. Every 1.6 install mode stages the Secure Boot binaries; the old installer skipped them on any HTTPS install, so the feature was missing precisely on the servers whose admins had gone furthest out of their way to configure TLS. pki-zones said a rebuilt iPXE "forfeits the signed Secure Boot shim", and that there is no mechanism for signing a custom-rebuilt binary with FOG's own Secure Boot certificate. FOG signs every EFI binary in its TFTP tree, and upstream's shim loads the result once the MOK is enrolled -- so embed-ca moves the enrolment earlier rather than giving Secure Boot up, and Setup Mode is an alternative rather than the only route. compile_ipxe_binaries had not been touched since 2024. It cloned over git://, pointed its config-header wgets at fogproject's 1.5 tree rather than the fog-ipxe repository that now holds them, built 1.5-era target names, and said nothing about TRUST= or about what a rebuild costs a Secure Boot client. It now also warns against EMBED= on a UEFI target, which since v2.0.0-fog.8 produces the /dev/ram0 panic. The new page states the FQDN and public-DNS prerequisite for public-cert, that the ca.ipxe.org cross-certificate is fetched by the booting client so an air-gapped network needs embed-ca however public its certificate is, why the redirect is off by default, and that FOG_WEB_HOST has to be set to the certificate's FQDN before HTTPS netboot works past the first hop. kb/reference/index.md was also missing pki-zones, pki-glossary, bringing-your-own-ca and secure-boot-technical-details, so four existing pages were unreachable from their own index. Verified with a full Quartz build against this worktree: 108 files, no errors, and the unparsed-wikilink count in the built HTML is still 12 -- all pre-existing, none in a file touched here. Co-Authored-By: Claude <noreply@anthropic.com>
The page turns on the difference between a public and a private CA and on enrolling a MOK before a machine can netboot, and it used all of those cold. An admin arriving here is choosing an install mode, which does not presuppose knowing what a Machine Owner Key is -- and the whole argument for embed-ca costing an extra enrolment is unreadable without it. Adds a terms callout covering netboot, FQDN, MOK, shim, ACME and the public-versus-private CA distinction the four modes turn on. Rebuilt: 108 files, no errors, unparsed-wikilink count still 12. Co-Authored-By: Claude <noreply@anthropic.com>
This was referenced Aug 19, 2026
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.
Part of
FOGProject/fogproject#1120(Phase 3).Adds
docs/kb/reference/netboot-transport-and-pki.mdand corrects the pages that contradict it.Why
FOG 1.6 split what 1.5 conflated into a single
httpproto: the web protocol, the HTTP→HTTPS redirect and whether iPXE is recompiled are now independent keys with--install-modeas a preset over them. None of that was documented, and several pages still told admins the opposite.The flat contradiction
proxy-dhcp.mdcarried a callout titled "Secure Boot and HTTPS are mutually exclusive". They are not. Every 1.6 install mode stages the Secure Boot binaries — the old installer skipped them on any HTTPS install, so the feature was missing precisely on the servers whose admins had gone furthest to configure TLS.pki-zones.mdsaid a rebuilt iPXE "forfeits the signed Secure Boot shim" and that there is no mechanism for signing a custom build with FOG's own key. FOG signs every EFI binary in its TFTP tree, and upstream's shim loads the result once the MOK is enrolled — soembed-camoves the enrolment earlier rather than giving Secure Boot up, and Setup Mode is an alternative rather than the only route.Also
compile_ipxe_binaries.mdhad not been touched since 2024: cloned overgit://, pointed its config-headerwgets at fogproject's 1.5 tree rather than thefog-ipxerepo that now holds them, built 1.5-era target names, and said nothing aboutTRUST=. It now also warns againstEMBED=on a UEFI target, which sincev2.0.0-fog.8produces the/dev/ram0panic.kb/reference/index.mdwas missingpki-zones,pki-glossary,bringing-your-own-caandsecure-boot-technical-details, so four existing pages were unreachable from their own index.The new page states plainly
public-cert, and why.ca.ipxe.orgis fetched by the booting client, so air-gapped sites needembed-cahowever public their certificate is.embed-caadds an enrolment step.FOG_WEB_HOSTmust be set to the certificate's FQDN before HTTPS netboot works past the first hop.Verified
Full Quartz build against this worktree: 108 files, no errors. Unparsed-wikilink count in the built HTML still 12 — all pre-existing, none in a file touched here.
Merge this first — the other four docs branches forward-reference the new page.