Document local ESP boot, and stop saying FOG cannot sign its own iPXE - #125
Open
darksidemilk wants to merge 3 commits into
Open
Document local ESP boot, and stop saying FOG cannot sign its own iPXE#125darksidemilk wants to merge 3 commits into
darksidemilk wants to merge 3 commits into
Conversation
The fog-esp archives had no documentation at all. Nothing under docs/ mentioned localboot, fog-esp or the manifest, so the only way to find the feature was to already know the URL. This adds a how-to covering where the archives live, what is in one, how to lay it on an EFI System Partition, and which entry point to name for each of the three Secure Boot situations. Two claims on secure-boot-signing were wrong rather than merely stale. It said FOG's own builds "carry no signature" and that there is "no mechanism, on any FOG release, for signing a custom-rebuilt iPXE binary with FOG's own Secure Boot certificate". FOG signs every .efi in its TFTP tree with this server's signing key, and upstream's shim loads the result once that key is enrolled as a MOK. So a rebuild costs an enrolment before the machine can netboot -- it does not cost Secure Boot. The same page's own summary bullet 400 lines below already said the milder version of this, so the page contradicted itself. It also said the secureboot/ directory would be missing on "HTTPS-netboot installs using FOG's own CA", which was true of the old gate and is not true now: 1.6 stages it in every install mode. A failed download is the only remaining reason. On the archives themselves, the page is written against what actually ships. The two -10sec archives are published but contain none of FOG's own EFI binaries -- the 10secdelay EFI builds they are sourced from are deleted by _retireStaleEfiPaths() during the same install, 47 lines before the archives are built, and v2.0.0-fog.8 stopped shipping them anyway. Rather than describe six working kits, the page names the three that work and says plainly that the delay variants are not currently usable. Filed separately. Also: the ESP-versus-network shim behaviour is left deliberately open. The archive's own README says each shim loads its matching loader, while this page's automatic_next_path() note says a local ESP always falls back to ipxe.efi. Both loaders are in the archive, so either behaviour boots; the page says that instead of picking a side that has not been confirmed on hardware. Removed a branch name that had leaked into published prose on migrating-fog-server, and added the five how-tos missing from their own index, including all three Secure Boot guides. Verified with a full Quartz build: 108 files, no errors, unparsed-wikilink count in the built HTML unchanged at 12. The one unresolved link target, netboot-transport-and-pki, is the sibling branch's new page and resolves once both land. Co-Authored-By: Claude <noreply@anthropic.com>
The page used ESP eight times, MOK five and SNP twice while only ever spelling out "EFI System Partition" once, in a sentence a reader skimming for the install steps would not necessarily land on. Someone reaching this page is there because PXE did not work for them, which is not a filter for already knowing UEFI boot vocabulary. Adds a terms callout up front covering ESP, UEFI, PXE, shim, MOK, MokManager and SNP, and expands the first prose mention to "EFI System Partition (ESP)". Also drops "NIC" from the opening sentence in favour of "network card", since that one appears before any definition could. Rebuilt: 108 files, no errors, unparsed-wikilink count still 12. Co-Authored-By: Claude <noreply@anthropic.com>
Written two days too early. 046fe81e9 landed on working-1.6 after this page was drafted and changed most of what it described, so this is a correction, not a polish. Six archives became three. The -10sec variants were not repaired, they were deleted -- this page said there were five, two of them unusable, and told readers --boot-delay could not help them. Both wrong now: --boot-delay writes a live sleep into local/autoexec.ipxe as well as the server's netboot copy, so one option covers both paths, and the commented-out form is sitting in the file for anyone fixing one machine by hand. The layout is the substance of the page now, because it is load-bearing and flattening it stops the machine booting. Since v2.0.0-fog.8 no EFI binary carries FOG's boot script; each reads autoexec.ipxe resolved against its own directory. Two binaries need two scripts, hence two directories: the root one is a chain ladder read by upstream's signed loader, local/autoexec.ipxe is FOG's real DHCP/proxyDHCP/next-server logic read by whichever fog*.efi runs. A flat archive gave FOG's binary the ladder, so it chained itself. Also new here: rEFInd ships in refind/ and the page says why it is still there now that UEFI hosts exit via sanboot; the manifest is schema 2 with paths rather than basenames; i386 has no root ladder but does have local/autoexec.ipxe; and the trap most likely to bite someone rearranging the archive -- ipxe.efi at the root is upstream's, and booted off an ESP it does not load its own NIC drivers, so it is only ever a chain stage. Entry points updated to local/fogipxe.efi throughout, and the install step now says to keep the subdirectories. Rebuilt: 108 files, no errors, unparsed-wikilink count still 12. Co-Authored-By: Claude <noreply@anthropic.com>
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). Depends on #124 for thenetboot-transport-and-pkilink target.Adds
docs/kb/how-tos/local-esp-boot.md— thefog-esparchives had no documentation at all. Nothing underdocs/mentionedlocalboot,fog-espor the manifest, so the only way to find the feature was to already know the URL.Written twice
The page was drafted against the five-archive layout, then
FOGProject/fogproject@046fe81e9landed and changed most of it. The version here describes what actually ships:-10secvariants were deleted, not repaired.--boot-delaycovers ESP boot too — it writes a livesleepintolocal/autoexec.ipxeas well as the server's netboot copy. The first draft said it could not help.v2.0.0-fog.8no EFI binary carries FOG's boot script; each readsautoexec.ipxeresolved against its own directory. Two binaries need two scripts, hence two directories: the root one is a chain ladder read by upstream's signed loader,local/autoexec.ipxeis FOG's real DHCP/proxyDHCP/next-server logic. A flat archive gave FOG's binary the ladder, so it chained itself.refind/, and why it is still there now UEFI hosts exit viasanboot.local/autoexec.ipxe.ipxe.efiat the root is upstream's, and booted off an ESP it does not load its own NIC drivers — it is only ever a chain stage.Corrections to
secure-boot-signing.mdTwo claims were wrong rather than stale.
It said FOG's builds "carry no signature" and that there is "no mechanism, on any FOG release, for signing a custom-rebuilt iPXE binary with FOG's own Secure Boot certificate". FOG signs every
.efiin its TFTP tree, and shim loads the result once the key is enrolled. The same page's own summary bullet 400 lines below already said the milder version, so the page contradicted itself.It also said
secureboot/would be missing on "HTTPS-netboot installs using FOG's own CA". True of the old gate; every mode stages it now.Also
A branch name had leaked into published prose on
migrating-fog-server.md, andkb/how-tos/index.mdwas missing five how-tos including all three Secure Boot guides.Verified
Full Quartz build: 108 files, no errors, unparsed-wikilink count still 12.