Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
56 changes: 54 additions & 2 deletions docs/skills/local-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
Expand Down Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions iso/scripts/build-iso.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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" <<EOF
title ${TITLE}
linux /images/pxeboot/vmlinuz
Expand All @@ -153,19 +156,16 @@ printf 'timeout 5\ndefault utah-live.conf\n' > "${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" <<EOF
menuentry "${TITLE}" {
linux /images/pxeboot/vmlinuz root=live:LABEL=${LABEL} rd.live.image rd.live.overlay.overlayfs=1 enforcing=0 console=ttyS0,115200n8 rd.utah.isofile=\${iso_path}
initrd /images/pxeboot/initrd.img
}
EOF

xorriso -as mkisofs -iso-level 3 -r -J --joliet-long -V "${LABEL}" \
--efi-boot EFI/efi.img -efi-boot-part --efi-boot-image \
Expand Down
10 changes: 10 additions & 0 deletions tests/test_iso_ci.py
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,16 @@ def test_offline_payload_preserves_manifest_digest(self):
self.assertIn('"dir:${PAYLOAD_EXPORT}"', script)
self.assertIn('dir:/payload "containers-storage:$1"', script)

def test_production_boot_args_and_unsupported_paths(self):
script = (ROOT / "iso/scripts/build-iso.sh").read_text()
self.assertIn("enforcing=0", script)
self.assertIn("Documented exception (Issue #22)", script)
self.assertNotIn("rd.utah.isofile", script)
self.assertNotIn("loopback.cfg", script)
self.assertIn("root=live:LABEL=${LABEL}", script)
self.assertIn("rd.live.image", script)
self.assertIn("rd.live.overlay.overlayfs=1", script)

def test_iso_budget_guard_fails_closed_above_ceiling(self):
# The budget guard (#128) is the whole point of the size drift this PR
# closes. Extract the real block and run it with du stubbed so we can
Expand Down
Loading