Document local ESP boot, and stop saying FOG cannot sign its own iPXE - #125
Closed
darksidemilk wants to merge 5 commits into
Closed
Document local ESP boot, and stop saying FOG cannot sign its own iPXE#125darksidemilk wants to merge 5 commits into
darksidemilk wants to merge 5 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>
The page said the archives 'replace an earlier arrangement that published the same binaries loose in a browsable directory'. That reads as a migration, and it is not one: the loose set existed for about a day inside the 1.6 beta and nobody ran it. Telling an admin their setup was replaced, when they never had the thing being replaced, sends them looking for something to change. As far as FOG is concerned this capability is brand new. The real prior art is admins hand-assembling an ESP themselves -- finding a binary that drives the hardware, writing a boot script, keeping both in step with the server by hand -- so the callout now says that, says a hand-rolled setup keeps working, and gives the actual reason to switch: the server regenerates the archives on every upgrade, so they cannot drift out of step with it. Retitled 'What you give up' to 'What the archives cannot do' for the same reason. Nothing is given up relative to anything an admin had; packaging the binaries means none of them has its own URL, which is a property of the design and a real limitation, but not a loss. Rebuilt: 108 files, no errors, unparsed-wikilink count still 12. Co-Authored-By: Claude <noreply@anthropic.com>
The install section mounted /dev/sda1 with sudo and stopped there. Most people
running FOG are on Windows, where the ESP is not mounted at all by default, so
the one worked example was the one least likely to apply.
Windows now leads, using FogApi's Mount-WinEfi -- it defaults to A:, wraps
mountvol.exe /S, and remounts if the ESP is already mounted elsewhere, with
Get-EfiMountLetter to check and Dismount-WinEFI to finish. mountvol A: /S is
given as the no-module fallback. A single FogApi command for the whole job is
noted as planned and explicitly NOT released, because it does not exist yet and
a doc promising it would send people looking.
More to the point, the page prescribed one path when the kit's value is that it
does not need one. Three more routes documented, because they are what makes it
worth having:
- A USB stick. Nothing mounted, nothing on the machine's disk touched --
either from a UEFI shell, or as \EFI\BOOT\bootx64.efi so the firmware
offers it as removable media. Also the most direct way to enrol Secure Boot
material on a machine that cannot netboot at all, since MOK.der and the
.auth files travel inside the archive.
- rEFInd as a selector. It scans for EFI binaries and lists them, the shim
included, so you can pick it and reach FOG without adding a firmware boot
entry or changing the boot order -- which is the answer when the firmware's
own menu is locked down or will not show a file you added.
- The permanent boot entry, which is now one option among several rather than
the assumed end of the procedure.
Intro rewritten to say the archive is more than one route and name them, rather
than implying the ESP is the only destination.
Rebuilt: 108 files, no errors, unparsed-wikilink count still 12, and the new
in-page anchor confirmed present as an id in the built HTML.
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>
Member
Author
|
Closing — the salvageable half is carried forward on Why not merged. What was taken, unchanged in substance:
One addition. This PR removed one Checked against the GH-1120 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
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.Windows first, and every route the kit supports
The install steps were Linux-only —
sudo mount /dev/sda1— which is theaudience least likely to apply. Windows now leads, using FogApi's
Mount-WinEfi(defaults to
A:, wrapsmountvol.exe /S, remounts if the ESP is alreadymounted elsewhere), with
mountvol A: /Sas the no-module fallback. A singleFogApi command for the whole job is noted as planned and not released, since
it does not exist yet.
More importantly the page prescribed one path when the kit's value is that it
does not need one. Now documented:
or as
\EFI\BOOT\bootx64.efiso firmware offers it as removable media. Alsothe most direct way to enrol Secure Boot material on a machine that cannot
netboot at all, since
MOK.derand the.authfiles travel in the archive.pick it and reach FOG without adding a firmware boot entry or changing boot
order. The answer when firmware's own menu is locked down.
assumed end of the procedure.
This is a new feature, not a replacement
An earlier draft said the archives "replace an earlier arrangement that published
the same binaries loose in a browsable directory". They do not — that loose set
existed for about a day inside the 1.6 beta and nobody ran it. Telling an admin
their setup was replaced, when they never had the thing being replaced, sends
them looking for something to change.
The real prior art is admins hand-assembling an ESP themselves. The page says
that, says a hand-rolled setup keeps working, and gives the actual reason to
switch: the server regenerates the archives on every upgrade, so the binaries
and the boot script cannot drift out of step with it.
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.