Skip to content

Document booting FOG from a machine's own ESP, and what db enrolment replaces - #129

Merged
darksidemilk merged 1 commit into
masterfrom
local-esp-boot
Aug 21, 2026
Merged

darksidemilk merged 1 commit into
masterfrom
local-esp-boot

Conversation

@darksidemilk

Copy link
Copy Markdown
Member

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

  • 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 (snponly-shimx64.efi loading ipxe.efi (instead of snponly.efi) 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

…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
darksidemilk merged commit efb2d73 into master Aug 21, 2026
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
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