fruix/docs/reports/phase8-bhyve-image-freebsd.md

Phase 8.1: Reproducible bhyve-compatible disk image generation on FreeBSD

Date: 2026-04-01

Summary

This step adds the first reproducible raw disk-image build path for the FreeBSD Fruix prototype. The target format is intentionally simple and debuggable:

• raw disk image
• GPT partition map
• UEFI boot
• FreeBSD UFS root partition
• serial-console-friendly loader configuration

Added file:

• tests/system/run-phase8-bhyve-image.sh

Validation command

Run command:

METADATA_OUT=/tmp/phase8-bhyve-image-metadata.txt \
./tests/system/run-phase8-bhyve-image.sh

What the harness does

The harness:

1. reuses the Phase 7 rootfs materialization path
2. discovers the generated system closure under /frx/store
3. creates an image-oriented staging rootfs
4. copies the closure and its recursively declared store references into:
   • rootfs/frx/store
5. builds:
   • a FAT EFI system partition image containing EFI/BOOT/BOOTX64.EFI
   • a UFS root partition image from the staged rootfs
   • a final GPT raw disk image with labeled partitions
6. rebuilds the same image a second time with fixed timestamps and filesystem parameters
7. verifies that both resulting raw images have the same SHA256
8. attaches the raw image through mdconfig and validates its partition/filesystem structure

Observed results

Observed metadata included:

• raw_sha256=08605d738021cb6fb5b87c270e1eafde57e1acb5159d3a2257aad4c560e2efc5
• image_size_bytes=335578624
• esp_fstype=msdosfs
• root_fstype=ufs
• run_current_system_target=/frx/store/...-fruix-system-fruix-freebsd
• boot_loader_target=/run/current-system/boot/loader
• boot_loader_conf_target=/run/current-system/boot/loader.conf
• rc_conf_target=/run/current-system/etc/rc.conf
• rc_script_target=/run/current-system/usr/local/etc/rc.d/fruix-shepherd
• store_item_count=13
• boot_mode=uefi
• image_format=raw
• partition_scheme=gpt
• root_partition_label=fruix-root
• efi_partition_label=efiboot
• serial_console=comconsole

Important findings

• the current Fruix FreeBSD track now has a reproducible raw disk-image build path suitable for later bhyve work
• the earlier Phase 7 rootfs tree was not sufficient by itself for an installable image because it referenced /frx/store content that was still only present on the host; the image builder therefore had to stage the closure and its store references inside the image rootfs under /frx/store
• fixed timestamps and explicit filesystem parameters were sufficient to make repeated image builds byte-for-byte reproducible on this host
• boot-structure sanity checks succeeded for:
  • GPT partitioning
  • EFI partition population
  • UFS root partition creation
  • serial-console loader configuration
  • preserved run/current-system system-link topology

Conclusion

Phase 8.1 is satisfied on the current FreeBSD prototype track:

• a reproducible bhyve-compatible raw disk image can now be generated from the Fruix system outputs
• the resulting image passes static boot-structure sanity checks
• the next step is to move this image builder into the Fruix system-composition layer so image generation becomes an output of the declarative system description itself