ISO from the same build as the template: plan (decision 0052) #21

New issue

Open

opened 2026-10-08 04:02:04 -03:00 by marcos-mendez · 0 comments

marcos-mendez commented

2026-10-08 04:02:04 -03:00

(Migrated from github.com)

Decision 0052: every release ships a .tar.zst and a bootable .iso from the same build. The boot layer this builds on is #20 (with Keel-Linux/common#47 and Keel-Linux/keel#89). The ISO builder is not implemented yet: this issue is the plan. Until it exists, testing pre-releases ship the .tar.zst only (point 4).

What exists today

fab (share/product.mk) has cdroot and product.iso targets. They squash root.patched into live/10root.squashfs, copy the kernel and initrd into live/, and write the ISO with xorriso and isolinux, which boots under BIOS only. A run-genisoimage-uefi recipe exists (-e efi.img -isohybrid-gpt-basdat), but nothing calls it and no cdroot contains an efi.img.
Keel-Linux/cdroots: only the isolinux/gfxboot BIOS menus (gfxboot-turnkey, generic). There is no EFI tree.
bt-iso is TurnKey's monolithic flow: make product.iso, clicksnap screenshots and publishing to TurnKey's buckets. It knows nothing about layers, and Keel will not use it as it is. bin/iso-machine-id-check can be reused as it is.
Build host: 8 cores (E5-2630 v2), 15 GB, /dev/kvm present. xorriso, mksquashfs, isohybrid and grub-mkrescue are installed. qemu-system-x86, ovmf, grub-efi-amd64-bin and the signed shim/grub are not.

How the ISO is made from the same build

bt-layer --boot APP builds APP-boot on top of the APP layer that was just built (#20).
keel-release stages APP-boot with the other layers. It keyscans the tarball (release_refuse_key_files) and verifies it like any layer.
keel assemble APP-boot --rootfs R, without --template. R is the template's rootfs plus the boot layer, with the kernel kept. The template comes from the same staged APP chain, and keel refuses it if it has a kernel.
New bt-iso-layer APP R, a thin wrapper over the fab recipes:
- mksquashfs R live/10root.squashfs -comp xz -no-sparse, with timestamps fixed to SOURCE_DATE_EPOCH;
- live/vmlinuz and live/initrd.img from R/boot;
- BIOS: isolinux plus isohdpfx.bin, from a new cdroots/keel tree;
- UEFI: an efi.img FAT image with EFI/BOOT/BOOTX64.EFI = Debian's shimx64.efi.signed, grubx64.efi.signed and a grub.cfg that loads the live kernel. Secure Boot works with Debian's own signed chain, so no key of ours is needed. shim-signed and grub-efi-amd64-signed join plans/keel-boot, so tkl-installer can install UEFI systems too;
- xorriso -as mkisofs ... -eltorito-alt-boot -e efi.img -isohybrid-gpt-basdat gives a hybrid ISO that boots from CD or USB under BIOS and UEFI.
Name it debian-13-keel-APP_VERSION_amd64.iso, next to the template.

QEMU boot test (release gate)

Install qemu-system-x86 and ovmf on the build host, or on the dedicated runner VM if CI runs it.
With KVM, headless, -serial stdio, and a console=ttyS0 boot entry:
- SeaBIOS live boot;
- OVMF live boot with Secure Boot on (OVMF_VARS_4M.ms.fd);
- after the first two pass, the install check of point 3: tkl-installer unattended onto a virtio disk, then a reboot from the disk under OVMF.
It passes when the serial console shows the getty login prompt (later, a marker the first boot writes) within a timeout. It fails when that never appears, or on a kernel panic or emergency shell.
If it fails, the ISO is not signed, indexed or published. The template is unaffected.

Signing and keyscan

The ISO gets .sha512 and .sha512.asc from the same signing step as the templates, and is listed in the release MANIFEST.
Keyscan:
- every staged layer, including APP-boot, is already scanned as a tarball;
- the squashfs is scanned again, because the ISO carries files that are not in any layer tarball: run keyscan over tar -C R -cf - . before mksquashfs, then check that unsquashfs -lls of the squashfs in the ISO lists the same tree.
- bin/iso-machine-id-check runs on the finished ISO.
efi.img and the cdroot hold only bootloaders and config. They are listed and checked for *.key, the same as everything else.

How long it adds

Measured locally: mksquashfs -comp xz of the 904 MB core rootfs with its kernel took 32 s on 24 threads and gave 383 MB. Estimates per appliance on the 8-core host:

Step	Time
boot layer build (kernel install, initramfs)	~3-5 min
mksquashfs	~2 min
xorriso	<30 s
QEMU BIOS + UEFI live boots	~3 min
install check	~5 min

That is about 10-15 min per appliance. For the 13 appliances in conf/appliances it comes to about 2.5 h if run one after another, or about 1.5 h if the install check runs only for core and the live boots run for every appliance.

Steps

cdroots/keel: isolinux menu plus a GRUB EFI tree.
plans/keel-boot: add shim-signed and grub-efi-amd64-signed.
bt-iso-layer and its tests (a small ISO, as tests/machine-id already does).
keel-release: build and stage APP-boot, assemble, the ISO, the gate, signing.
Install qemu and OVMF on the build host, or the runner VM.
Confirm the 990 pin before the first ISO (decision 0052, point 5).

Decision 0052: every release ships a `.tar.zst` and a bootable `.iso` from the same build. The boot layer this builds on is #20 (with Keel-Linux/common#47 and Keel-Linux/keel#89). The ISO builder is not implemented yet: this issue is the plan. Until it exists, testing pre-releases ship the `.tar.zst` only (point 4). ## What exists today - **fab** (`share/product.mk`) has `cdroot` and `product.iso` targets. They squash `root.patched` into `live/10root.squashfs`, copy the kernel and initrd into `live/`, and write the ISO with xorriso and isolinux, which boots under BIOS only. A `run-genisoimage-uefi` recipe exists (`-e efi.img -isohybrid-gpt-basdat`), but nothing calls it and no cdroot contains an `efi.img`. - **Keel-Linux/cdroots**: only the isolinux/gfxboot BIOS menus (`gfxboot-turnkey`, `generic`). There is no EFI tree. - **bt-iso** is TurnKey's monolithic flow: `make product.iso`, clicksnap screenshots and publishing to TurnKey's buckets. It knows nothing about layers, and Keel will not use it as it is. `bin/iso-machine-id-check` can be reused as it is. - **Build host**: 8 cores (E5-2630 v2), 15 GB, `/dev/kvm` present. xorriso, mksquashfs, isohybrid and grub-mkrescue are installed. qemu-system-x86, ovmf, grub-efi-amd64-bin and the signed shim/grub are not. ## How the ISO is made from the same build 1. `bt-layer --boot APP` builds `APP-boot` on top of the `APP` layer that was just built (#20). 2. keel-release stages `APP-boot` with the other layers. It keyscans the tarball (`release_refuse_key_files`) and verifies it like any layer. 3. `keel assemble APP-boot --rootfs R`, without `--template`. R is the template's rootfs plus the boot layer, with the kernel kept. The template comes from the same staged `APP` chain, and keel refuses it if it has a kernel. 4. New `bt-iso-layer APP R`, a thin wrapper over the fab recipes: - `mksquashfs R live/10root.squashfs -comp xz -no-sparse`, with timestamps fixed to `SOURCE_DATE_EPOCH`; - `live/vmlinuz` and `live/initrd.img` from `R/boot`; - BIOS: isolinux plus `isohdpfx.bin`, from a new `cdroots/keel` tree; - UEFI: an `efi.img` FAT image with `EFI/BOOT/BOOTX64.EFI` = Debian's `shimx64.efi.signed`, `grubx64.efi.signed` and a `grub.cfg` that loads the live kernel. Secure Boot works with Debian's own signed chain, so no key of ours is needed. `shim-signed` and `grub-efi-amd64-signed` join `plans/keel-boot`, so tkl-installer can install UEFI systems too; - `xorriso -as mkisofs ... -eltorito-alt-boot -e efi.img -isohybrid-gpt-basdat` gives a hybrid ISO that boots from CD or USB under BIOS and UEFI. 5. Name it `debian-13-keel-APP_VERSION_amd64.iso`, next to the template. ## QEMU boot test (release gate) - Install `qemu-system-x86` and `ovmf` on the build host, or on the dedicated runner VM if CI runs it. - With KVM, headless, `-serial stdio`, and a `console=ttyS0` boot entry: - SeaBIOS live boot; - OVMF live boot with Secure Boot on (`OVMF_VARS_4M.ms.fd`); - after the first two pass, the install check of point 3: tkl-installer unattended onto a virtio disk, then a reboot from the disk under OVMF. - It passes when the serial console shows the getty login prompt (later, a marker the first boot writes) within a timeout. It fails when that never appears, or on a kernel panic or emergency shell. - If it fails, the ISO is not signed, indexed or published. The template is unaffected. ## Signing and keyscan - The ISO gets `.sha512` and `.sha512.asc` from the same signing step as the templates, and is listed in the release MANIFEST. - Keyscan: - every staged layer, including `APP-boot`, is already scanned as a tarball; - the squashfs is scanned again, because the ISO carries files that are not in any layer tarball: run `keyscan` over `tar -C R -cf - .` before `mksquashfs`, then check that `unsquashfs -lls` of the squashfs in the ISO lists the same tree. - `bin/iso-machine-id-check` runs on the finished ISO. - `efi.img` and the cdroot hold only bootloaders and config. They are listed and checked for `*.key`, the same as everything else. ## How long it adds Measured locally: `mksquashfs -comp xz` of the 904 MB core rootfs with its kernel took 32 s on 24 threads and gave 383 MB. Estimates per appliance on the 8-core host: | Step | Time | |---|---| | boot layer build (kernel install, initramfs) | ~3-5 min | | mksquashfs | ~2 min | | xorriso | <30 s | | QEMU BIOS + UEFI live boots | ~3 min | | install check | ~5 min | That is about 10-15 min per appliance. For the 13 appliances in `conf/appliances` it comes to about 2.5 h if run one after another, or about 1.5 h if the install check runs only for core and the live boots run for every appliance. ## Steps 1. `cdroots/keel`: isolinux menu plus a GRUB EFI tree. 2. `plans/keel-boot`: add shim-signed and grub-efi-amd64-signed. 3. `bt-iso-layer` and its tests (a small ISO, as tests/machine-id already does). 4. keel-release: build and stage `APP-boot`, assemble, the ISO, the gate, signing. 5. Install qemu and OVMF on the build host, or the runner VM. 6. Confirm the 990 pin before the first ISO (decision 0052, point 5).