From b87992ca3caa0cf983aff68830469921e545b0f4 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sat, 7 Nov 2026 22:32:57 -0400 Subject: [PATCH 1/2] docs(packaging): 'signs with your own MOK' is measured now, and says what happens without one The Secure Boot paragraph claimed dkms signs with the user's key; every container proof so far printed 'modules won't be signed', so the claim had never been exercised. Paired measurement in one container, same package, same kernel (7.0.0-43-generic), only the machine differing: with a MOK at /var/lib/shim-signed/mok/{MOK.priv,MOK.der} -> scripts/sign-file, sha512, modinfo -F signer = that certificate's CN, sig_key present without one -> 'Binary update-secureboot-policy not found, modules won't be signed', signer and sig_key empty The consequence is what a user actually needs to know: on a Secure Boot machine with no MOK of its own the driver installs, builds, and then refuses to load, and no package can fix that because a key it shipped would not be trusted. The doc now says so, with the fix (mokutil --generate-key or the shim-signed flow, then dkms autoinstall) and the note that Secure Boot off is unaffected. Throwaway key generated inside the container; the fleet's private key was not involved. Refs #1280 --- docs/install-any-distro.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/install-any-distro.md b/docs/install-any-distro.md index 033c4a09a..fe635178c 100644 --- a/docs/install-any-distro.md +++ b/docs/install-any-distro.md @@ -272,6 +272,20 @@ dkms packages are the other way round: dkms signs with *your* key (`/var/lib/shi Debian/Ubuntu, `/etc/dkms/` elsewhere), so a module built on your machine chains to the MOK you enrolled for it — on Fedora and Arch, dkms generates that key pair on first use. +That is measured, and it has a consequence worth knowing before it surprises you. Same package, same +kernel, only the machine differing (`ubuntu:26.04`, headers `7.0.0-43-generic`): + +| machine | what dkms did | what the module says | +|---|---|---| +| a MOK at `/var/lib/shim-signed/mok/{MOK.priv,MOK.der}` | `scripts/sign-file`, sha512 | `signer: `, a `sig_key` fingerprint | +| no MOK on the machine | `Binary update-secureboot-policy not found, modules won't be signed` | `signer:` empty, `sig_key:` empty | + +So **with Secure Boot on and no MOK of your own, the driver installs, builds, and then will not load** — +`modprobe` refuses an unsigned module, and nothing in the package can help, because a key it shipped +would not be trusted. Create and enrol a key first (`mokutil --generate-key` on a systemd machine, or +the shim-signed flow that wrote the `MOK.priv`/`MOK.der` above), then `dkms autoinstall` rebuilds and +re-signs. With Secure Boot off, the unsigned module loads and none of this matters. + Verify (no model needed): ```bash @@ -417,4 +431,5 @@ registry model, since this Lemonade version has no local-file registration): | the distribution-kernel path, on its own | clean `ubuntu:26.04` container, packages built with `--skip-kernel`, `scripts/pkg-proof.sh deb` | 22 rows PASS and one `INFO no kernel packages in this dir` (the kernel rows skip themselves instead of failing): install, config, memlock reaching a login session, dkms building both modules against `7.0.0-43-generic`, `amdxdna` resolving to `updates/dkms`, uninstall, and the distribution's in-tree `amdxdna` back in place. This is the path a user on their own kernel takes | | the engine package and this set install on the same machine | clean `ubuntu:26.04` container, `scripts/pkg-proof.sh coexist`, engine `1bit-engine_2026.11.02-1_amd64.deb` | all 26 rows PASS: the engine installs alone, this set installs **over it** with `dpkg` reporting no file conflict, `/usr/share/1bit` holds both (`lemonade-config-fragment.json` from the engine, `mok/MOK-Kernel.der` from `1bit-npu-config`) with each file attributed to its own package, the engine still runs (`1bit 0.0.1`), both dkms modules build, purging this set leaves the engine's files intact, and the engine purges last. Neither `scripts/pack-proof.sh` (the engine) nor the rows above (this set) install both, so this is the combination nobody had tried | | the same `.rpm` installs on openSUSE Tumbleweed | clean `opensuse/tumbleweed` container, `scripts/pkg-proof.sh rpm` | **all 29 rows PASS**, `rc=0` — the same file Fedora takes, installed by `rpm`/zypper with no per-distro package: dkms builds both modules against `7.3.1-1-default`, `amdxdna` resolves to the dkms build ahead of the in-tree one, the kernel rpm installs and removes cleanly, the distribution's own module is restored. Two container facts, not package facts: openSUSE keeps headers in `/usr/src/linux--obj/` (so the harness finds the version through `/lib/modules//build/Makefile`, never a vendor path), and the container needs `kernel-default` + `udev` for the in-tree-module and `udevadm` rows to have anything to look at | +| the dkms package signs with the machine's own MOK, and what happens without one | clean `ubuntu:26.04` container, headers `7.0.0-43-generic`, `amdxdna-1bit-dkms` 0.18.0-1, paired with and without a MOK at `/var/lib/shim-signed/mok` | with one: `scripts/sign-file`, sha512, `modinfo -F signer` = that certificate's CN and a `sig_key`; without: `modules won't be signed`, `signer` and `sig_key` empty. So the package chains to the user's key — and on a Secure Boot machine with no MOK of its own the module installs, builds, and refuses to load | | the shipped driver answers a known answer on the NPU | this box, `npu-hold`, `1bit serve --device npu` on Qwen3-0.6B, `/v1/completions` greedy, twice | load 2.2 s, `The capital of France is` → **` Paris. The capital of Italy is Rome. The capital of Spain is Madrid.`** identically on both runs (56.9 and 50.7 tok/s), 0 `amdxdna` lines in the two windows, and the loaded module is `srcversion EE1F36A2B9BA294CE11AD80` — the build this package's source produces. No install, no `modprobe`, no udev reload | From 00130276c4a426ff4d1de0398d9dd7f8e6600473 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Sun, 8 Nov 2026 16:35:28 -0400 Subject: [PATCH 2/2] docs(packaging): replace the mokutil command that does not exist with the pair that does Three CHANGES on this PR said the same thing: "mokutil --generate-key" is not a command. Re-checked on the box rather than taking the review's word for it: mokutil --version -> 0.7.2 mokutil --help | grep gener -> --generate-hash, -g Generate the password hash (no --generate-key) /usr/sbin/update-secureboot-policy: 263:'--new-key') 268:'--enroll-key') So the sentence sent exactly the reader this paragraph is for - Secure Boot on, no MOK - to a command that fails. Replaced with the verified pair, plus the openssl fallback for distributions without update-secureboot-policy, and the MokManager confirmation on the next boot that actually completes enrolment. --enroll-key calls mokutil --test-key first, so re-running it on an already-enrolled machine is harmless. Also corrected in this push (the review's date item, which applies to both PRs): the docs and my STATE file had been claiming 2026-11-09; the box is on 2026-11-08 and commit c59b81a4 is dated 11-08. Refs #1280. --- docs/install-any-distro.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/install-any-distro.md b/docs/install-any-distro.md index fe635178c..07785e509 100644 --- a/docs/install-any-distro.md +++ b/docs/install-any-distro.md @@ -282,9 +282,13 @@ kernel, only the machine differing (`ubuntu:26.04`, headers `7.0.0-43-generic`): So **with Secure Boot on and no MOK of your own, the driver installs, builds, and then will not load** — `modprobe` refuses an unsigned module, and nothing in the package can help, because a key it shipped -would not be trusted. Create and enrol a key first (`mokutil --generate-key` on a systemd machine, or -the shim-signed flow that wrote the `MOK.priv`/`MOK.der` above), then `dkms autoinstall` rebuilds and -re-signs. With Secure Boot off, the unsigned module loads and none of this matters. +would not be trusted. Create and enrol a key first: `sudo update-secureboot-policy --new-key` writes +`/var/lib/shim-signed/mok/{MOK.priv,MOK.der}` — the pair the table above signs with — then +`sudo update-secureboot-policy --enroll-key` (or `sudo mokutil --import /var/lib/shim-signed/mok/MOK.der`) +queues it, and you confirm it in MokManager on the next boot. Then `sudo dkms autoinstall` rebuilds and +re-signs. On a distribution without `update-secureboot-policy`, generate a pair with +`openssl req -new -x509 …` and enrol it with `mokutil --import`. With Secure Boot off, the unsigned module +loads and none of this matters. Verify (no model needed):