From 3a29567d23e71f76486b7d7932f8f75fedc58e84 Mon Sep 17 00:00:00 2001 From: Tom Elliott Date: Mon, 3 Aug 2026 09:10:22 -0500 Subject: [PATCH] Secure Boot: document the staged ipxe.efi fallback chain fog-ipxe v2.0.0-fog.3 stages a second signed chain beside snponly, so a site whose firmware UEFI SNP is broken now has a fallback that needs nothing but a DHCP change. The page already mentioned upstream's all-drivers ipxe.efi, but framed it as something you go and fetch from the upstream tarball yourself. It is staged for you now, so that tip is replaced by a symptom-led subsection under step 3a: an admin hitting this has no way to know the fault is in their firmware's network stack, and "loads but the network never comes up" is the only signal that distinguishes the two chains. Placed after the autoexec.ipxe discussion rather than before it, because that discussion applies to both chains equally. Added a version note: an install pinned to an earlier fog-ipxe release stages only the snponly pair, and MANIFEST is what tells you which you have. Not added to the step-3 troubleshooting table -- that table is scoped to kernel signature violations, and a dead network stack is not one. Co-Authored-By: Claude Opus 5 --- docs/kb/how-tos/secure-boot-signing.md | 38 ++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/docs/kb/how-tos/secure-boot-signing.md b/docs/kb/how-tos/secure-boot-signing.md index 623450fa..30b92081 100644 --- a/docs/kb/how-tos/secure-boot-signing.md +++ b/docs/kb/how-tos/secure-boot-signing.md @@ -189,13 +189,25 @@ Since FOG 1.6.0, every install stages them at `/tftpboot/secureboot/`: ``` /tftpboot/secureboot/ ├── snponly-shimx64.efi Microsoft-signed shim (2011 + 2023), from ipxe/shim -├── snponly.efi upstream's signed iPXE +├── snponly.efi upstream's signed iPXE — firmware's own NIC driver +├── ipxe-shimx64.efi the same shim again, under the name that loads ipxe.efi +├── ipxe.efi upstream's signed iPXE — iPXE's own NIC drivers ├── mmx64.efi MokManager, used during enrolment ├── autoexec.ipxe FOG's boot script ├── MANIFEST where each file came from, with checksums └── arm64-efi/ the same set for arm64 ``` +Two complete chains, so you can switch between them with nothing but a DHCP +change. `snponly` is the default and the right first choice; `ipxe` is the +fallback for firmware whose own network stack does not work. [Which to +use](#3a-serve-the-signed-chain) is covered in step 3a. + +>[!info] Version note +>The `ipxe.efi` pair arrived with **fog-ipxe v2.0.0-fog.3**. An install pinned +>to an earlier release stages only the `snponly` pair — check `MANIFEST`, which +>lists exactly what your install has. + Everything but `autoexec.ipxe` is upstream's, republished byte for byte through the [fog-ipxe](https://github.com/FOGProject/fog-ipxe) release the installer already downloads. Every file's SHA-256 and its signer are verified when that @@ -464,11 +476,6 @@ both binaries already carry signatures the firmware and shim trust. >every other client. So a Secure Boot machine now behaves like the rest of your >estate rather than being a special case — the only difference is the shim in >front and the signature on the kernel. -> ->Upstream also publishes a signed all-drivers `ipxe.efi` in the same ->`-sb/` directory, paired with `ipxe-shim.efi`. Use it only if you have a ->NIC the firmware's own driver does not handle; it is the more invasive option, ->and it is the one that hangs on hardware where the takeover fails. Because upstream's `snponly.efi` has no boot script compiled in, it fetches one over TFTP, and **where it looks is not a single fixed path**. iPXE asks for the @@ -525,6 +532,25 @@ lives under `secureboot/` and is reached only by machines you point there. >binaries doing the same job by different means, which is why the signed one >gets its own directory rather than replacing the other. +#### If the chain loads but the network never comes up + +Shim runs, iPXE starts, and then there is no link or no DHCP. That points at +the firmware's own UEFI network stack, not at anything you signed. Set the DHCP +boot file to **`secureboot/ipxe-shimx64.efi`** instead — on arm64, +`secureboot/arm64-efi/ipxe-shimaa64.efi`. + +That chain runs the all-drivers `ipxe.efi`, which replaces the firmware's NIC +driver with iPXE's own rather than binding the firmware's UEFI network +protocol. It recovers machines whose firmware SNP is broken or absent, and it +is the more invasive option — on hardware where the takeover fails, it hangs +instead. So try `snponly` first and move to this only on the symptom above. + +Everything about the rest of this step is unchanged: both binaries are staged +for you, both are already signed, and `autoexec.ipxe` is hard-linked into +`secureboot/` for either one. **Nothing needs renaming server-side** — the shim +picks its second stage from its own filename, so the two chains sit side by +side in one directory and DHCP alone decides which runs. + ### 3b — The FOS kernels This is the part that is genuinely yours to sign, and **the installer has