diff --git a/Justfile b/Justfile index c7a5a4c89..85806976d 100644 --- a/Justfile +++ b/Justfile @@ -68,6 +68,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 'Documented exception (Issue #22)' iso/scripts/build-iso.sh + if grep -q 'rd.utah.isofile' iso/scripts/build-iso.sh; then echo "rd.utah.isofile found in build-iso.sh" >&2; exit 1; fi + if grep -q 'loopback.cfg' iso/scripts/build-iso.sh; then echo "loopback.cfg found in build-iso.sh" >&2; exit 1; fi 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 e94fdd294..458c5c27d 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,16 @@ 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`). As a documented exception + (Issue #22), live media runs SELinux in Permissive mode (`enforcing=0`) + because rootless container squashfs generation cannot preserve SELinux xattrs; + installed target systems boot Enforcing normally. 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. - **Cross-vendor switch and update timers (`bootc-fetch-apply-updates`).** Switching to Utah from Bluefin or other bootc images carries Bluefin's `/etc/systemd/system/timers.target.wants/bootc-fetch-apply-updates.timer` diff --git a/docs/skills/index.json b/docs/skills/index.json index 93d6db3e7..3902b3938 100644 --- a/docs/skills/index.json +++ b/docs/skills/index.json @@ -105,7 +105,7 @@ "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-18", "doc_type": "runbook" diff --git a/docs/skills/local-testing.md b/docs/skills/local-testing.md index c4c26f613..616f57046 100644 --- a/docs/skills/local-testing.md +++ b/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 --- @@ -137,6 +137,58 @@ 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 enforcing=0 console=ttyS0,115200n8` + +- Every kernel argument corresponds to an implemented and tested dracut boot + path (`dmsquash-live`, `overlayfs`, and serial console logging). +- **SELinux policy (Documented Exception)**: The live session runs with + SELinux in **Permissive** mode (`enforcing=0`) as an approved documented + exception (Issue #22). The squashfs live rootfs is assembled rootless inside + `podman unshare`, where `security.selinux` extended attributes cannot be + written without root privilege, leaving rootfs files unlabeled. Booting an + unlabeled live root in Enforcing mode causes denials in systemd and GDM that + hang the live session. Permissive mode remains in place for live media until + xattr-preserving squashfs build tooling lands. Installed target systems boot + in **Enforcing** mode. + +### 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 manually enrolling a Machine Owner Key + (MOK) into UEFI NVRAM using `mokutil` (planned tooling; no automated helper + currently exists in-tree). +- **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; signing + modules with an enrolled MOK key (e.g. via the kernel's `sign-file` utility) + is planned for future release pipelines, but currently module signing is not + implemented in-tree and Secure Boot must remain disabled. + ## Verification ### Encrypted install and screenshot harness diff --git a/iso/scripts/build-iso.sh b/iso/scripts/build-iso.sh index b1da18c93..06c19e5af 100644 --- a/iso/scripts/build-iso.sh +++ b/iso/scripts/build-iso.sh @@ -142,6 +142,9 @@ mmd -i "${ESP}" ::/EFI ::/EFI/BOOT ::/loader ::/loader/entries ::/images ::/imag mcopy -i "${ESP}" "${SYSTEMD_BOOT}" ::/EFI/BOOT/BOOTX64.EFI mcopy -i "${ESP}" "${VMLINUZ}" ::/images/pxeboot/vmlinuz mcopy -i "${ESP}" "${INITRD}" ::/images/pxeboot/initrd.img +# Documented exception (Issue #22): rootless podman unshare cannot write security.selinux +# xattrs into the squashfs root, leaving it unlabeled. enforcing=0 is required for live boot +# to avoid systemd/GDM denials until xattr-preserving rootfs assembly is implemented. 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" <