Installing Forest OS on a Virtual Machine

Step-by-step install on QEMU, VirtualBox, and VMware — from image download through forinstall to first boot from disk.

Install guides: VM · Install on Real Hardware · USB Persistence

Contents

1. Prerequisites
2. Step 1 — Get an Image
3. Step 2 — Verify the Image
4. Step 3 — Create a Target Disk
5. Step 4 — QEMU: BIOS Boot
6. Step 5 — QEMU: UEFI Boot (OVMF)
7. Step 6 — VirtualBox Setup
8. Step 7 — VMware Setup
9. Step 8 — Boot Menu Entries
10. Step 9 — Install with forinstall
11. Step 10 — First Boot from Disk
12. Guest Additions: What Works and Limits
13. Issues and Fixes

1. Prerequisites

# QEMU (test, install target, rescue)
sudo apt install qemu-system-x86 qemu-utils ovmf xorriso mtools

# Verify KVM (strongly recommended — install without it is ~10x slower)
ls -la /dev/kvm
sudo usermod -aG kvm $USER   # re-login after

# Verify OVMF firmware files (paths vary by distro)
ls /usr/share/edk2/x64/OVMF_CODE.4m.fd /usr/share/edk2/x64/OVMF_VARS.4m.fd
# Debian/Ubuntu alt paths:
ls /usr/share/ovmf/OVMF.fd
ls /usr/share/OVMF/OVMF_CODE.fd

ARM/AArch64/RISC-V guests boot with -kernel directly (no ForeB) and are serial-only. This guide covers x86/x86_64 VM installs.

2. Step 1 — Get an Image (Download or Build)

Option A — Build from source (canonical)

cd forest/fern
./conf.sh --defconfig && ./conf.sh --generate
make all        # kernel + userspace + initrd + ForeB hybrid ISO + raw IMG

ls -lh ../foreboots/build/
# forebo.iso   # hybrid BIOS+UEFI ISO  <- use this for VM install
# forebo.img   # raw BIOS disk image (10 MiB, MBR layout)
# esp.img      # FAT16 EFI System Partition (~48 MiB)

Config triple matters: ARCH=32|64, BOOT_MODE=bios|uefi. For a VM install that must boot everywhere, build the hybrid ISO (make iso).

Option B — Download a release ISO

wget https://github.com/Enclica-Forest/Forest/releases/latest/download/forebo.iso
wget https://github.com/Enclica-Forest/Forest/releases/latest/download/forebo.iso.sha256

sha256sum -c forebo.iso.sha256
# expected: forebo.iso: OK

If only a .img is published, it is a raw MBR disk — boot it as a hard disk (-drive), not as a CD (-cdrom).

3. Step 2 — Verify the Image

Do this before creating the VM. A corrupt image produces exactly the symptoms in Issues and Fixes.

ISO=../foreboots/build/forebo.iso
IMG=../foreboots/build/forebo.img
ESP=../foreboots/build/esp.img

# 1. ISO has both El Torito entries (BIOS + UEFI)
xorriso -indev "$ISO" -report_el_torito as_mkisofs
# expect: -b boot/forebo/forebo.img ... -eltorito-alt-boot -e boot/efi/esp.img

# 2. List ISO contents
isoinfo -l -i "$ISO"

# 3. MBR signature on the raw image (bytes 510-511 = 55 AA)
xxd -s 510 -l 2 "$IMG"
# expect: 55aa

# 4. Kernel ELF magic at sector 48 (offset 48*512 = 7F 45 4C 46)
xxd -s $((48*512)) -l 4 "$IMG"
# expect: 7f45 4c46  (".ELF")

# 5. Stage size constraints
make -C ../foreboots check
# stage1: exactly 512 B | stage2/3: <= 8192 B each

# 6. ESP sanity (UEFI path only)
mdir -i "$ESP" ::/EFI/BOOT/
# expect: BOOTX64.EFI
mdir -i "$ESP" ::/forebo/
# expect: kernel.elf  forebo.cfg  initrd.tar

Rebuild if any check fails: make clean && make all in fern/, then make -C ../foreboots check.

4. Step 3 — Create a Target Disk

# QEMU: 2 GiB raw target (grow later with qemu-img resize)
qemu-img create -f raw forest-disk.raw 2G
qemu-img info forest-disk.raw

# QEMU alt: qcow2 (snapshots, thin-provisioned — slower on Forest's ATA path)
qemu-img create -f qcow2 forest-disk.qcow2 2G

• VirtualBox: VM Settings → Storage → Controller IDE/SATA → Create → VDI, dynamically allocated, 2 GiB+.
• VMware: New VM → Custom → SCSI (LSI Logic) or SATA → new virtual disk, 2 GiB+, single file or split.

Attach both devices before first power-on: ISO on optical + empty disk on HDD-0. Boot order must put optical first for install, disk first afterwards (see First Boot).

5. Step 4 — QEMU: BIOS Boot

qemu-system-x86_64 \
  -machine q35 -cpu qemu64 -m 512 \
  -enable-kvm \
  -drive file=forest-disk.raw,format=raw,index=0,media=disk \
  -cdrom ../foreboots/build/forebo.iso \
  -boot order=dc,menu=on \
  -vga std \
  -serial stdio

32-bit variant: use qemu-system-i386 -cpu qemu32 with the same drives.

# Headless / logging variant:
qemu-system-x86_64 -machine q35 -cpu qemu64 -m 512 -enable-kvm \
  -drive file=forest-disk.raw,format=raw,index=0,media=disk \
  -cdrom ../foreboots/build/forebo.iso -boot order=dc \
  -vga std -serial file:/tmp/forest-install.log -display none
tail -f /tmp/forest-install.log

# make shortcuts (build + launch in one step):
cd forest/fern
make run                # current config (serial on stdio, -vga std)
make run-bios           # force BIOS path
make QEMU_MEMORY=1024 run

6. Step 5 — QEMU: UEFI Boot (OVMF)

UEFI install boots the same hybrid ISO under OVMF. QEMU needs split CODE + writable VARS pflash drives — never point both at the same read-only file.

# 1. Per-VM writable NVRAM copy (once per VM)
cp /usr/share/edk2/x64/OVMF_VARS.4m.fd ./OVMF_VARS.local.fd
# Debian/Ubuntu alt source: /usr/share/ovmf/OVMF_VARS.fd

# 2. Boot installer ISO in UEFI mode
qemu-system-x86_64 \
  -machine q35 -cpu qemu64 -m 512 \
  -enable-kvm \
  -drive if=pflash,format=raw,readonly=on,file=/usr/share/edk2/x64/OVMF_CODE.4m.fd \
  -drive if=pflash,format=raw,file=./OVMF_VARS.local.fd \
  -drive file=forest-disk.raw,format=raw,index=0,media=disk \
  -cdrom ../foreboots/build/forebo.iso \
  -boot order=dc,menu=on \
  -device qemu-xhci -device usb-tablet -device usb-kbd \
  -vga std \
  -serial stdio

cd forest/fern
make run-uefi            # ESP-based UEFI boot with OVMF
make BOOT_MODE=uefi QEMU_MEMORY=512 run

7. Step 6 — VirtualBox Setup

1. New VM: Type Other/Unknown, 64-bit. RAM 512 MiB+. 1–2 vCPUs, enable VT-x/AMD-V, PAE/NX.
2. Storage: Controller IDE (best compatibility) or SATA/AHCI. IDE Primary Master → forest-disk.vdi (2 GiB+); optical → forebo.iso. Boot order: optical first for install.
3. Display: VBoxVGA (BGA path — works). Avoid VBoxSVGA (framebuffer fallback, slower). 32 MiB+ video memory, 3D off.
4. Network: NAT or Bridged, NIC Intel PRO/1000 (e1000) or AMD PCNet. VirtIO-net only if ENABLE_VIRTIO_NET is built in.
5. Audio/Input: ICH AC97; PS/2 keyboard + mouse, or USB tablet for the ForeB pointer.
6. Boot: Start → ForeB menu → boot entries → forinstall.

Post-install: remove the ISO (or move HDD-0 above optical in boot order), then boot.

8. Step 7 — VMware Setup

1. New VM: Guest OS Other → Other 64-bit. Firmware: BIOS for MBR installs, UEFI for ESP installs.
2. Storage: LSI Logic SCSI or SATA/AHCI, new virtual disk 2 GiB+. Attach forebo.iso to CD/DVD, Connect at power on.
3. Display: Default SVGA is fine (Fern SVGA-II driver, else framebuffer fallback). No VMware Tools needed.
4. Network: e1000 (safest) or VMXNET3 (only if the driver is enabled). NAT or Bridged.
5. CPU/RAM: 1–2 vCPUs, 512 MiB+ RAM.
6. Boot: Power on → ForeB menu → forinstall → power off → disconnect ISO → boot from disk.

9. Step 8 — Boot Menu Entries

ForeB shows a graphical forest-themed menu (GOP framebuffer, mouse + keyboard). Default timeout=10; any key cancels auto-boot.

Keys: Up/Down move, Enter boots, Esc/Left back, S Theme/Settings, U UEFI variables. See Boot Menu and Configuration.

# Pre-install sanity from the Shell entry (optional but cheap):
fsprobe hd0
ls (cd0)/forebo/
cat (cd0)/forebo/forebo.cfg

10. Step 9 — Install with forinstall

Boot Forest OS from the installer ISO, wait for the shell/login prompt, then run:

forinstall

Six screens in order. Defaults are in [brackets] — Enter accepts.

Language

Pick installer + system locale (en default). Sets /etc/locale, console keymap, TTY font page.

Target disk

 0  hd0   2048 MiB   QEMU HARDDISK / ATA
 1  cd0   <iso size>  QEMU DVD-ROM (installer — do NOT pick this)
Select target disk [0]:

• Pick the empty disk from Step 3, never cd0. Confirm the destructive-write warning (YES).
• If the disk is missing: run ls /dev/hd* /dev/sd* and check storage wiring (IDE vs AHCI vs virtio — enable the matching ENABLE_DRIVER_* driver).

Filesystem — ext2 vs FAT

fdisk /dev/hd0            # MBR table: 1 primary bootable partition
mkfs -t ext2 /dev/hd0p1   # or: mkfs -t fat32 /dev/hd0p1
mount /dev/hd0p1 /mnt

Keep root ≥ 512 MiB; the base system + initrd wants ~100–200 MiB free after install (df -h).

Users

Root password × 2, then a user account (e.g. forest) + password × 2. Skipping the user leaves a root-only system (add users later via System Tools).

ForeB (bootloader install)

• BIOS target: stage1 (MBR + 55AA), stage2 (LBA 1–16), stage3 (LBA 17–32), kernel at sector 48, initrd 16-sector aligned (~sector 560).
• UEFI target: FAT ESP (/EFI/BOOT/BOOTX64.EFI), kernel.elf + forebo.cfg + initrd.tar in /forebo/, NVRAM boot entry.

Confirm + copy

Final screen summarizes language / disk / fs / users / ForeB target. Confirm to format + mount, copy kernel, initrd, base userspace, /etc skeleton, forebo.cfg, install ForeB, fsck, then INSTALL OK — remove install media and reboot. On failure the log stays on serial — copy the last 20 lines into a bug report.

11. Step 10 — First Boot from Disk

1. Detach the installer ISO: QEMU: remove -cdrom …, switch to -boot order=c,menu=on:

   qemu-system-x86_64 -machine q35 -cpu qemu64 -m 512 -enable-kvm \
     -drive file=forest-disk.raw,format=raw,index=0,media=disk \
     -boot order=c,menu=on -vga std -serial stdio

   UEFI: keep both pflash drives + writable OVMF_VARS.local.fd (it now holds BootOrder). VirtualBox/VMware: disconnect ISO / HDD-0 first in boot order.
2. Power on. ForeB menu should appear from the disk. Default entry boots in ~10 s.
3. Log in as the created user (or root). Expect kernel banners on serial, TUI/GUI on display, shell on both.
4. Smoke test:

   uname -a
   df -hT          # root mounted, space free
   ls /bin | head
   ip addr         # NIC if ENABLE_NETWORKING + NAT adapter

5. Snapshot now (QEMU savevm, VirtualBox/VMware snapshot) before experimenting.

12. Guest Additions: What Works and Limits

Rule of thumb: configure emulated hardware (IDE/AHCI, e1000/PCNet, AC97, PS/2 or USB-tablet). Enable paravirt only after confirming the matching ENABLE_* driver is compiled in (make show-config | grep -i virtio). Resolution is fixed at DISPLAY_DEFAULT_WIDTH×HEIGHT×BPP (default 1024×768×32).

13. Issues and Fixes

Still stuck? See Troubleshooting, Testing with QEMU, and Boot Menu.

See Also

• Boot Flow — power-on to login
• Boot Menu — keys, themes, submenus
• Bootloader Configuration — forebo.cfg reference
• ISO Creation — hybrid ISO / IMG / ESP internals
• Testing with QEMU — make run, serial, GDB
• Troubleshooting — full issue catalog
• Disk Tools — fdisk, mkfs, mount, fsck
• Install on Real Hardware — bare-metal USB install
• USB Persistence — live vs persistent vs full USB install

← Back to Wiki