Skip to content
Closed
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 @@ -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
Expand Down
7 changes: 7 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/skills/index.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"generated_at": "2026-09-05",
"generated_at": "2026-09-11",
"schema_version": "1.0",
"skills": [
{
Expand Down Expand Up @@ -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"
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
|---|---|---|---|
Expand Down
50 changes: 47 additions & 3 deletions docs/skills/local-testing.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 @@ -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
Expand Down
13 changes: 5 additions & 8 deletions iso/scripts/build-iso.sh
Original file line number Diff line number Diff line change
Expand Up @@ -99,26 +99,23 @@ cat > "${WORK}/utah-live.conf" <<EOF
title ${TITLE}
linux /images/pxeboot/vmlinuz
initrd /images/pxeboot/initrd.img
options root=live:LABEL=${LABEL} rd.live.image rd.live.overlay.overlayfs=1 enforcing=0 console=ttyS0,115200n8
options root=live:LABEL=${LABEL} rd.live.image rd.live.overlay.overlayfs=1 console=ttyS0,115200n8
EOF
sed -i 's/^ //' "${WORK}/utah-live.conf"
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