system: add UEFI installer ISO builder
This commit is contained in:
139
docs/reports/phase18-installer-iso-freebsd.md
Normal file
139
docs/reports/phase18-installer-iso-freebsd.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Phase 18.3: bootable Fruix installer ISO on FreeBSD
|
||||
|
||||
Date: 2026-04-04
|
||||
|
||||
## Goal
|
||||
|
||||
Phase 18.3 extends the Phase 18.2 installer-environment work from a disk-image-style installer into a UEFI-bootable ISO artifact.
|
||||
|
||||
The intended first ISO is deliberately narrow:
|
||||
|
||||
- UEFI only
|
||||
- serial-console-friendly
|
||||
- non-interactive install flow reused from Phase 18.1/18.2
|
||||
- target disk installation still performed by the same Fruix-managed in-guest installer logic
|
||||
|
||||
## Implementation
|
||||
|
||||
### New API
|
||||
|
||||
Added in `modules/fruix/system/freebsd.scm`:
|
||||
|
||||
- `operating-system-installer-iso-spec`
|
||||
- `materialize-installer-iso`
|
||||
|
||||
The system module split done immediately before this phase was also exercised during this work.
|
||||
|
||||
### New CLI action
|
||||
|
||||
Added in `scripts/fruix.scm`:
|
||||
|
||||
- `fruix system installer-iso`
|
||||
|
||||
This action emits metadata for:
|
||||
|
||||
- ISO store path
|
||||
- ISO image path
|
||||
- EFI boot image path
|
||||
- installer root image path
|
||||
- installer and target closure paths
|
||||
- installer state/log paths
|
||||
- declared/materialized FreeBSD source metadata
|
||||
- store closure counts
|
||||
|
||||
### ISO boot model
|
||||
|
||||
The ISO does not try to run the Fruix installer directly from a read-only cd9660 root.
|
||||
|
||||
Instead it uses a small UEFI El Torito boot image plus an in-memory installer root image:
|
||||
|
||||
1. a small FAT EFI boot image contains `EFI/BOOT/BOOTX64.EFI`
|
||||
2. the ISO root contains real boot assets under `/boot`
|
||||
3. the ISO root also contains `/boot/root.img`
|
||||
4. `loader.conf` on the ISO is augmented with:
|
||||
- `mdroot_load="YES"`
|
||||
- `mdroot_type="md_image"`
|
||||
- `mdroot_name="/boot/root.img"`
|
||||
- `rootdev="ufs:/dev/md0"`
|
||||
- `vfs.root.mountfrom="ufs:/dev/md0"`
|
||||
- `vfs.root.mountfrom.options="rw"`
|
||||
|
||||
This preserves the existing Fruix installer environment semantics while avoiding the need to make the whole installer operate directly from a read-only ISO root.
|
||||
|
||||
### Installer root image contents
|
||||
|
||||
`materialize-installer-iso` stages the same installer payload model already validated in Phase 18.2:
|
||||
|
||||
- installer closure
|
||||
- target closure
|
||||
- target store closure
|
||||
- staged target rootfs under `/var/lib/fruix/installer/target-rootfs`
|
||||
- installer plan and state files under `/var/lib/fruix/installer`
|
||||
- installer helper scripts:
|
||||
- `/usr/local/libexec/fruix-installer-run`
|
||||
- `/usr/local/etc/rc.d/fruix-installer`
|
||||
|
||||
The ISO root image is then built as a UFS image and embedded as `/boot/root.img`.
|
||||
|
||||
### Split-regression fixes found during this work
|
||||
|
||||
While exercising the refactored split modules, two issues surfaced and were fixed:
|
||||
|
||||
1. `string-hash` name-clash warnings
|
||||
- the old helper name collided with Guile/SRFI bindings
|
||||
- it was renamed to `sha256-string`
|
||||
2. missing `prefix-materializer-version`
|
||||
- this constant was accidentally omitted when `modules/fruix/system/freebsd.scm` was split
|
||||
- the missing definition was restored in `modules/fruix/system/freebsd/build.scm`
|
||||
|
||||
## Current validation status
|
||||
|
||||
### Completed smoke validation
|
||||
|
||||
A host-side smoke build was completed successfully for the new ISO builder using a host-staged operating-system definition:
|
||||
|
||||
- command pattern:
|
||||
- `fruix system installer-iso ...`
|
||||
- result:
|
||||
- successful ISO materialization in a temporary store
|
||||
- artifact checks performed:
|
||||
- `etdump` reports an EFI El Torito boot entry
|
||||
- the ISO contains:
|
||||
- `boot/kernel/kernel`
|
||||
- `boot/kernel/linker.hints`
|
||||
- `boot/loader.conf`
|
||||
- `boot/loader.efi`
|
||||
- `boot/root.img`
|
||||
- `boot/loader.conf` inside the ISO contains the expected `mdroot_*` and `vfs.root.mountfrom` entries
|
||||
|
||||
Example smoke-build metadata:
|
||||
|
||||
```text
|
||||
action=installer-iso
|
||||
iso_volume_label=FRUIX_INSTALLER
|
||||
iso_store_path=/tmp/...-fruix-installer-iso-fruix-freebsd-installer
|
||||
iso_image=/tmp/...-fruix-installer-iso-fruix-freebsd-installer/installer.iso
|
||||
boot_efi_image=/tmp/...-fruix-installer-iso-fruix-freebsd-installer/efiboot.img
|
||||
root_image=/tmp/...-fruix-installer-iso-fruix-freebsd-installer/root.img
|
||||
installer_closure_path=/tmp/...-fruix-system-fruix-freebsd-installer
|
||||
target_closure_path=/tmp/...-fruix-system-fruix-freebsd
|
||||
```
|
||||
|
||||
### Validation harness added
|
||||
|
||||
Added:
|
||||
|
||||
- `tests/system/run-phase18-installer-iso.sh`
|
||||
|
||||
This harness is intended to validate the full Phase 18.3 flow:
|
||||
|
||||
1. build installer ISO
|
||||
2. boot it under QEMU/UEFI/TCG
|
||||
3. install onto a second disk from inside the booted ISO environment
|
||||
4. boot the installed target
|
||||
|
||||
## Status
|
||||
|
||||
Phase 18.3 implementation is now in place, with successful build-smoke validation and a dedicated end-to-end harness added.
|
||||
|
||||
The remaining step is full end-to-end boot/install validation of the ISO path under QEMU/UEFI/TCG and, if practical, the broader validated virtualization path.
|
||||
Reference in New Issue
Block a user