> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# ggRock Secure Boot shim chain

Replace ggRock's stock `ipxe.efi` PXE path with a `shimx64 → grubx64` chain compatible with stock Microsoft factory keys. 
No sidecar files needed — the wrapper downloads everything.

**Boot chain (before → after)**
`firmware → ipxe.efi` becomes `firmware → shimx64.efi → grubx64.efi → iPXE → Windows`

## Quick start
Two oneliners — install and revert. Both download from the hosted bundle, run in a temp directory, and clean up after themselves.

**Install**
```
wget -O - https://images.ggleap.com/ManagedServices/Scripts/shim-bundle/install.sh | bash -
```

**Revert**
```
wget -O - https://images.ggleap.com/ManagedServices/Scripts/shim-bundle/revert.sh | bash -
```

|| Both scripts are idempotent. Running install twice is safe — it skips any step already in the correct state. Running revert on an already-reverted machine is also safe.

## What the wrapper does
1. Creates a temp directory and registers a cleanup trap — nothing is left on disk after exit.
2. Downloads all five bundle files from `images.ggleap.com`: `install-shim-chain.sh`, `shimx64.efi`, `mmx64.efi`, `grubx64.efi`, and `MOK.cer`.
3. Runs `install-shim-chain.sh`, which verifies the MOK fingerprint, stages binaries in `/var/lib/tftp/`, patches `/etc/dnsmasq.d/pxe.conf`, and restarts dnsmasq.
4. Temp directory is removed automatically on exit. The revert wrapper only downloads the installer script — EFI sidecars are not needed for undo.

## Before you run: BIOS requirements

||| Secure Boot must be in **Factory/Standard mode** with **factory keys restored** before running the installer. If the BIOS is in User mode or has custom keys loaded, the shim will not validate against the Microsoft factory keys in db.


On each client machine before deploying:
1. Enter BIOS → **Secure Boot** settings.
2. Set Secure Boot mode to **Standard** (sometimes labelled Setup or Factory).
3. Use **Restore Factory Keys** (or equivalent) to load the default Microsoft keys into db/dbx.
4. Save and exit. The machine is now ready to enroll the MOK via MokManager on first PXE boot.

## Post-install steps
### Step 1 — disable Secure boot keys auto enrollment

||| The shim chain uses MOK for trust. Leaving this toggle on causes clients to attempt LockDown.efi enrollment instead, and the handoff will fail.

In the ggRock UI: **Settings → Secure boot → Secure boot keys auto enrollment → toggle OFF**

![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image_1gck4hn.png)

### Step 2 — enroll the MOK on each client (one-time)
1. Copy [**MOK.cer**](https://images.ggleap.com/ManagedServices/Scripts/shim-bundle/MOK.cer) to a FAT-formatted USB stick.
2. On first PXE boot, MokManager will appear automatically.
3. Select **Enroll key from disk**, navigate to `MOK.cer`, and confirm.
![](https://storage.crisp.chat/users/helpdesk/website/-/a/f/d/6/afd6941e8bc7d800/image_1rp9c0h.png)
1. Verify the SHA-256 fingerprint shown on screen matches the expected value before accepting.

| MokManager only appears on the first boot after the shim is loaded. If it doesn't appear, confirm that Secure boot keys auto enrollment is disabled and that the BIOS has factory keys restored.

### Step 3 — validate
Reboot the client and confirm the full chain: `firmware → shim → grubx64.efi → iPXE → Windows`.

In PowerShell on the booted client:
```
Confirm-SecureBootUEFI
```

Should return `True`.

## Hosted bundle
All files are served from `https://images.ggleap.com/ManagedServices/Scripts/shim-bundle/`
| File | Purpose |
| ---- |
| `install.sh` | Wrapper — downloads bundle and runs installer |
| `revert.sh` | Wrapper — downloads installer and runs with `--revert` |
| `install-shim-chain.sh` | Core installer / revert logic |
| `shimx64.efi` | MS-signed shim (Debian `shim-signed`) |
| `mmx64.efi` | MS-signed MokManager (Debian `shim-signed`) |
| `grubx64.efi` | iPXE binary pre-signed with MOK private key |
| `MOK.cer` | DER-encoded MOK public cert — clients enroll this |

## Reverting
Run the revert oneliner. It restores the original dnsmasq config and removes the shim/grub/MOK binaries from TFTP.
```
wget -O - https://images.ggleap.com/ManagedServices/Scripts/shim-bundle/revert.sh | bash -
```

|| After reverting, re-enable Secure boot keys auto enrollment in the ggRock UI if you want LockDown.efi behavior back, making sure to delete factory keys from the BIOS.

||| If `/root/ggrock-shim-backups/pxe.conf.original` is missing and the config doesn't look pristine, the revert will refuse to proceed. Inspect `/etc/dnsmasq.d/pxe.conf` manually before retrying.

### Restoring ggRock custom certificates after revert
If your ggRock setup uses custom Secure Boot certificates (rather than the Microsoft factory keys), restore them after reverting:
1. Enter BIOS on each client → **Secure Boot** settings.
2. **Delete all Secure Boot keys** (clears db, dbx, KEK, PK — puts firmware into Setup mode).
3. In the ggRock UI, re-enable **Secure boot keys auto enrollment** (Settings → Secure boot → toggle **ON**).
4. PXE boot the client — ggRock will re-enroll its custom certificates via LockDown.efi automatically.

## Troubleshooting
| Symptom | Likely cause / fix |
| ---- |
| MOK.cer fingerprint mismatch | Bundle on the host has a different cert than the pinned SHA-256. Verify with `openssl x509 -inform der -in MOK.cer -noout -fingerprint -sha256`. |
| Download failure during install | Verify the server can reach `images.ggleap.com`. The wrapper exits immediately on any failed `wget`. |
| dnsmasq not active after install | Config syntax error. Run `journalctl -u dnsmasq -n 30`. The installer runs `dnsmasq --test` before restarting. |
| Script aborts: "config in unexpected state" | The dnsmasq config was hand-edited between runs. Inspect `/etc/dnsmasq.d/pxe.conf` manually. |
| Client hangs at shim | `grubx64.efi` signature doesn't match the enrolled MOK. Re-sign, re-upload to the bundle host, then re-run the install oneliner. |
| MokManager doesn't appear on first boot | Secure boot keys auto enrollment is still enabled, or BIOS is not in Standard mode with factory keys. Check both. |
| Clients still attempting LockDown.efi enrollment | Secure boot keys auto enrollment is still enabled in the ggRock UI. Disable it (see Step 1 above). |
| Secure Boot not active after boot | MOK not enrolled on the client. Repeat the USB enrollment step. |
| BIOS rejects shim on boot | BIOS is in User/Custom mode — factory keys not restored. Reset to Standard mode with factory keys and retry. |