Repository navigation
Document booting FOG from a machine's own ESP, and what db enrolment replaces - #129
Merged
Merged
Conversation
…replaces
FOG 1.6 publishes fog-esp-<arch> archives so a machine with no PXE boot option
can boot FOG from an iPXE binary on its own EFI System Partition. Nothing here
described how to use them. The guide had been written into the installer repo's
docs/SUPPORTED_CUSTOMIZATIONS.md, which is the wrong home -- that page is about
what survives an install, and admins read docs.fogproject.org, not the installer
tree. It moves here and that page now links to this one.
New: kb/how-tos/local-esp-boot.md
* which folder to use, as a table rather than prose -- the archive holds one
folder per boot route and each is self-contained
* what works in which Secure Boot state, measured on physical hardware, VMware
and KVM rather than reasoned. Including the two results that surprise people:
a MOK does nothing for a shim-less boot, because firmware never reads
MokList; and with nothing enrolled the shim route does not offer to enrol, it
simply fails, because shim launches MokManager only when a request is already
pending
* "nothing enrolled" reaches the menu and exits to disk but CANNOT IMAGE, since
FOS's kernel carries the server's signature -- a bootstrap state, not a
destination
* db enrolment needs MOK.der ALONE, no PK and no KEK, with the VMware .vmx
recipe, append-not-replace, and the BitLocker PCR 7 warning
* why the shim's second stage is not the file you expect (ipxe/ipxe#1684): shim
derives it from its own filename at runtime, most firmwares will not report
that filename on a local boot, and it then falls back to ipxe.efi whichever
shim you launched. Which is why the archive ships FOG's build under both
names, and why renaming a shim cannot help
* the firmware trap, with screenshots: an OVMF NIC whose IPv4 setting is not
DHCP produces no SNP device at all, so snp/snponly builds find nothing AND
the firmware offers no UEFI PXE option -- indistinguishable from a machine
with no PXE ROM until you know to look. Enable DHCP, save with F10.
Updated: secure-boot-setup-mode-enrollment.md
* the page's own title is the term nobody finds in their firmware. Dell, HP,
Lenovo and AMI all say "Custom"; "Setup Mode" is the spec's word. Says so up
front now.
* a section for enrolling db BY HAND, because the .auth files this page
describes are signed variable updates that a firmware menu or a hypervisor
cannot read -- they want MOK.der. Offering PK.auth to a file picker is the
most common way this goes wrong, and the page previously gave no hint.
Updated: secure-boot-mok-enrollment.md -- what a MOK does not cover, since its
limits only show up when someone tries the shim-less route and cannot see why it
is refused.
Updated: kb/how-tos/index.md -- it listed none of the secure-boot pages, so the
whole family was unreachable from the index. Added them along with the new page,
plus firewall and unify-certificates which were also missing.
Screenshots are of generic OVMF firmware screens with all four MAC occurrences
redacted.
NOT VALIDATED WITH npm run docs:build -- the Node toolchain is not installed in
this environment. Checked by hand instead: every wikilink target exists, every
image embed matches a file on disk, context_id is unique, and no wikilink is
wrapped across a newline.
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>
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
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.
Document booting FOG from a machine's own ESP, and what db enrolment replaces
FOG 1.6 publishes fog-esp- archives so a machine with no PXE boot option
can boot FOG from an iPXE binary on its own EFI System Partition. Nothing here
described how to use them. The guide had been written into the installer repo's
docs/SUPPORTED_CUSTOMIZATIONS.md, which is the wrong home -- that page is about
what survives an install, and admins read docs.fogproject.org, not the installer
tree. It moves here and that page now links to this one.
New: kb/how-tos/local-esp-boot.md
folder per boot route and each is self-contained
and KVM rather than reasoned. Including the two results that surprise people:
a MOK does nothing for a shim-less boot, because firmware never reads
MokList; and with nothing enrolled the shim route does not offer to enrol, it
simply fails, because shim launches MokManager only when a request is already
pending
FOS's kernel carries the server's signature -- a bootstrap state, not a
destination
recipe, append-not-replace, and the BitLocker PCR 7 warning
derives it from its own filename at runtime, most firmwares will not report
that filename on a local boot, and it then falls back to ipxe.efi whichever
shim you launched. Which is why the archive ships FOG's build under both
names, and why renaming a shim cannot help
DHCP produces no SNP device at all, so snp/snponly builds find nothing AND
the firmware offers no UEFI PXE option -- indistinguishable from a machine
with no PXE ROM until you know to look. Enable DHCP, save with F10.
Updated: secure-boot-setup-mode-enrollment.md
Lenovo and AMI all say "Custom"; "Setup Mode" is the spec's word. Says so up
front now.
describes are signed variable updates that a firmware menu or a hypervisor
cannot read -- they want MOK.der. Offering PK.auth to a file picker is the
most common way this goes wrong, and the page previously gave no hint.
Updated: secure-boot-mok-enrollment.md -- what a MOK does not cover, since its
limits only show up when someone tries the shim-less route and cannot see why it
is refused.
Updated: kb/how-tos/index.md -- it listed none of the secure-boot pages, so the
whole family was unreachable from the index. Added them along with the new page,
plus firewall and unify-certificates which were also missing.
Screenshots are of generic OVMF firmware screens with all four MAC occurrences
redacted.
NOT VALIDATED WITH npm run docs:build -- the Node toolchain is not installed in
this environment. Checked by hand instead: every wikilink target exists, every
image embed matches a file on disk, context_id is unique, and no wikilink is
wrapped across a newline.
Co-Authored-By: Claude noreply@anthropic.com