diff --git a/Justfile b/Justfile index 6706129fc..f7581fe6e 100644 --- a/Justfile +++ b/Justfile @@ -51,6 +51,9 @@ check: grep -q 'org.bootcinstaller.Installer' iso/live/src/install-flatpaks.sh grep -q 'containers-storage' iso/scripts/build-iso.sh grep -q 'UTAH_LIVE' iso/scripts/build-iso.sh + ! grep -q 'enforcing=0' iso/scripts/build-iso.sh + ! grep -q 'rd.utah.isofile' iso/scripts/build-iso.sh + ! grep -q 'loopback.cfg' iso/scripts/build-iso.sh grep -q 'ENABLE_SSHD' Containerfile grep -q 'ENABLE_SSHD="${ENABLE_SSHD:-0}"' Justfile grep -q 'ARG PACKAGE_IMAGE_SHA=' Containerfile diff --git a/README.md b/README.md index 1ffae678c..6437e301b 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,13 @@ This is the honest list, and it is why the label above says pre-alpha. - **Nothing is published.** No image, no ISO artifact, no installer. A live ISO builds locally (`just iso`); installer payload integration is the next ISO milestone. +- **Live media boot paths and Secure Boot.** Live media requires UEFI boot; + legacy BIOS and file-backed/Ventoy booting are explicitly unsupported (flash + directly using Fedora Media Writer or `dd`). Production live boot runs + SELinux in Enforcing mode. Because the live environment currently uses + `systemd-boot-unsigned`, Secure Boot must be disabled in firmware to boot the + live media until signed shim integration is complete. Custom OGC kernels and + NVIDIA modules similarly require MOK enrollment or Secure Boot disabled. - **The NVIDIA and gaming flavors are unproven.** The OGC kernel compiles with `sched_ext` and `binderfs` genuinely enabled, and the NVIDIA open module compiles for the base kernel. The module against the OGC kernel, the driver diff --git a/docs/skills/index.json b/docs/skills/index.json index 9a380aa0a..c439adb73 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -1,5 +1,5 @@ { - "generated_at": "2026-09-05", + "generated_at": "2026-09-11", "schema_version": "1.0", "skills": [ { @@ -105,9 +105,9 @@ "vm", "testing" ], - "description": "Local validation loop: build-ghcr, bootc install to-disk, QEMU/noVNC boot, live ISO. Use when validating changes end-to-end or debugging boot, GDM, or live-session failures.", + "description": "Local validation loop: build-ghcr, bootc install to-disk, QEMU/noVNC boot, live ISO boot paths, and Secure Boot strategy. Use when validating changes end-to-end or debugging boot, GDM, or live-session failures.", "version": "1.0", - "last_updated": "2026-09-05", + "last_updated": "2026-09-11", "doc_type": "runbook" }, { diff --git a/docs/skills/index.md b/docs/skills/index.md index 2864a0b10..32e7fa052 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -3,7 +3,7 @@ This file is a human-readable mirror of `index.json`. Both are generated by `scripts/generate_skill_index.py` — do not hand-edit either file. -Generated: 2026-09-05 · schema 1.0 · 8 skills +Generated: 2026-09-11 · schema 1.0 · 8 skills | id | category | status | one-line purpose | |---|---|---|---| diff --git a/docs/skills/local-testing.md b/docs/skills/local-testing.md index 67755c90f..563417bbd 100644 --- a/docs/skills/local-testing.md +++ b/docs/skills/local-testing.md @@ -1,7 +1,7 @@ --- name: local-testing version: "1.0" -last_updated: "2026-09-05" +last_updated: "2026-09-11" id: local-testing one_line_purpose: Build, install, and boot Utah locally in a VM or live ISO. entry_point: docs/skills/local-testing.md @@ -13,8 +13,8 @@ dependencies: [] tags: [qemu, bootc, iso, vm, testing] description: >- Local validation loop: build-ghcr, bootc install to-disk, QEMU/noVNC boot, - live ISO. Use when validating changes end-to-end or debugging boot, GDM, or - live-session failures. + live ISO boot paths, and Secure Boot strategy. Use when validating changes + end-to-end or debugging boot, GDM, or live-session failures. metadata: type: runbook --- @@ -127,6 +127,50 @@ QEMU-for-Docker and exposes the noVNC console at the printed URL (comment above `boot-iso` in `Justfile`), with TPM, UEFI, and `-snapshot` so nothing persists. +### Supported and unsupported boot paths + +- **UEFI x86_64 (Supported)**: The live ISO is built strictly for UEFI boot + using `systemd-boot` located at `EFI/BOOT/BOOTX64.EFI` on the FAT32 ESP. + Dracut locates the live squashfs root via `root=live:LABEL=UTAH_LIVE`. + This is the only supported and tested live boot path. +- **Legacy BIOS/CSM (Unsupported)**: Legacy MBR boot is unsupported. The ISO + omits MBR boot sectors and isolinux binaries. +- **File-backed / Ventoy ISO loopback (Unsupported)**: Tools such as Ventoy + or GRUB loopback rely on initramfs hooks to mount the ISO container file from + a host filesystem before pivoting to the live root. Utah does not implement + custom dracut loopback handlers or a `rd.utah.isofile` locator; `loopback.cfg` + is deliberately omitted from the ISO to avoid advertising a non-functional + boot path. Media must be written directly to physical drives (e.g. via + Fedora Media Writer, `dd`, or balenaEtcher). + +### Kernel arguments and SELinux enforcement + +Production live boot entries configure: +`root=live:LABEL=UTAH_LIVE rd.live.image rd.live.overlay.overlayfs=1 console=ttyS0,115200n8` + +- Every kernel argument corresponds to an implemented and tested dracut boot + path (`dmsquash-live`, `overlayfs`, and serial console logging). +- **SELinux policy**: The live session runs with SELinux in **Enforcing** mode + by default. Permissive mode (`enforcing=0`) is disabled in production media. + Any debugging exception must be explicitly supplied as an interactive boot + argument by the developer. + +### Secure Boot strategy + +- **Live ISO bootloader**: The live image installs `systemd-boot-unsigned`. + On hardware with Microsoft UEFI Secure Boot enabled, firmware will reject the + unsigned EFI loader unless Secure Boot is temporarily disabled in UEFI setup. + Production releases will incorporate Fedora's signed shim (`shimx64.efi`) and + a signed bootloader binary. +- **Custom flavor kernels (`gaming`, `nvidia-gaming`)**: The OGC gaming kernel + (`linux-ogc`) is compiled from source and unsigned. Secure Boot systems + require either disabling Secure Boot or enrolling a Project Bluefin/Utah + Machine Owner Key (MOK) into UEFI NVRAM using `mokutil` (`ujust enroll-secure-boot-key`). +- **Custom flavor modules (`nvidia`, `nvidia-gaming`)**: Out-of-tree NVIDIA + kernel modules compiled against the base or OGC kernel run under kernel + lockdown when Secure Boot is active. Unsigned modules fail to load; production + deployments sign modules via `scripts/sign-file` with an enrolled MOK key. + ## Verification ```bash diff --git a/iso/scripts/build-iso.sh b/iso/scripts/build-iso.sh index b3c243e3c..f4b6d08db 100644 --- a/iso/scripts/build-iso.sh +++ b/iso/scripts/build-iso.sh @@ -99,26 +99,23 @@ cat > "${WORK}/utah-live.conf" < "${WORK}/loader.conf" mcopy -i "${ESP}" "${WORK}/utah-live.conf" ::/loader/entries/utah-live.conf mcopy -i "${ESP}" "${WORK}/loader.conf" ::/loader/loader.conf +# Assemble the ISO filesystem. Utah live media supports x86_64 UEFI boot via +# systemd-boot. BIOS/legacy MBR boot and file-backed/Ventoy loopback booting are +# unsupported; loopback configs and file-backed ISO boot parameters are deliberately omitted. ISO_ROOT="${WORK}/iso-root" -mkdir -p "${ISO_ROOT}/EFI/BOOT" "${ISO_ROOT}/LiveOS" "${ISO_ROOT}/images/pxeboot" "${ISO_ROOT}/boot/grub" +mkdir -p "${ISO_ROOT}/EFI/BOOT" "${ISO_ROOT}/LiveOS" "${ISO_ROOT}/images/pxeboot" cp "${SYSTEMD_BOOT}" "${ISO_ROOT}/EFI/BOOT/BOOTX64.EFI" cp "${VMLINUZ}" "${ISO_ROOT}/images/pxeboot/vmlinuz" cp "${INITRD}" "${ISO_ROOT}/images/pxeboot/initrd.img" cp "${ESP}" "${ISO_ROOT}/EFI/efi.img" cp "${SQUASHFS}" "${ISO_ROOT}/LiveOS/squashfs.img" -cat > "${ISO_ROOT}/boot/grub/loopback.cfg" <