Install Guide (UEFI)

UEFI install for Forest OS on real hardware (and UEFI VMs). Uses GPT, a FAT EFI System Partition (ESP), and the ForeB UEFI loader (BOOTX64.EFI). UEFI install walkthrough: GPT partitioning, EFI System Partition layout, Secure Boot notes, the forinstall wizard, and first boot from the internal disk. For legacy MBR machines see the BIOS guide; for hypervisors see Install on a VM.

For legacy machines see Install-Guide-BIOS. For what "install" means see Overview.

Prerequisites

• A Forest OS image: forebo.iso (hybrid, BIOS + UEFI — use this) or esp.img (FAT ESP only). Build with make all / make iso / make esp in fern/.
• 64-bit UEFI machine (x86_64), booted from the Forest OS live ISO/USB.
• Target disk: internal HDD/SSD/NVMe (or a full-install USB stick) ≥ 512 MiB (2 GiB+ recommended: FAT ESP + ext2/ext4 root + ~100–200 MiB free after install).
• A USB stick ≥ 256 MiB (any USB 2.0/3.0 stick works; all data on it is erased).
• Backup anything important on the target disk — partitioning erases data.
• Know your target disk name (/dev/sda, /dev/nvme0n1, …). Check with lsblk.
• A second machine (or the same one booted into Linux/Windows) to write the USB.

Warning: dd to the wrong device destroys data. Triple-check of= with lsblk / fdisk -l before every write.

Contents

1. Prerequisites
2. Prepare boot media
3. Firmware setup (UEFI) — Secure Boot OFF
4. Partition the target (GPT + ESP + root)
5. Boot the live session
6. Run forinstall (UEFI flow)
7. What gets staged on the ESP
8. Boot entry order
9. Verify before reboot
10. Remove USB, boot internal ESP
11. Post-install
12. Troubleshooting

2. Prepare boot media

Get an image

cd forest/fern
./conf.sh --defconfig && ./conf.sh --generate
make all
ls -lh ../foreboots/build/
# forebo.iso   # hybrid BIOS+UEFI ISO  <- use this for UEFI install
# esp.img      # FAT EFI System Partition (~48 MiB)

Verify before you write

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

# 1. Both El Torito entries present (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. ESP contents
mdir -i "$ESP" ::/EFI/BOOT/
# expect: BOOTX64.EFI
mdir -i "$ESP" ::/forebo/
# expect: kernel.elf  forebo.cfg  initrd.tar

file "$ESP"
# expect: DOS/MBR boot sector ... FAT (16 bit)

Write the USB stick (Linux — dd, recommended)

# 1. Identify the stick (whole disk, e.g. /dev/sdb — NOT a partition like sdb1).
lsblk -d -o NAME,SIZE,MODEL,TRAN

# 2. Unmount anything auto-mounted from it.
sudo umount /dev/sdX* 2>/dev/null; true

# 3. Write the hybrid ISO (works for UEFI + BIOS).
sudo dd if=build/forebo.iso of=/dev/sdX bs=4M status=progress oflag=sync
sync

Windows: use Rufus, select forebo.iso, and when prompted choose DD mode (raw write). ISO mode extracts files and breaks the ForeB layout — the stick will not boot.

3. Firmware setup (UEFI)

On UEFI the firmware loads \EFI\BOOT\BOOTX64.EFI from the ESP (no MBR stage chain). Do this once in firmware setup (usually Del, F2, or F10 at power-on):

1. Disable Secure Boot — mandatory. Forest OS ships an unsigned BOOTX64.EFI; with Secure Boot on, firmware refuses to load it (Verification failed: (0x1A) Security Violation). There is no signed shim or MOK to enroll — turning it off is required, not optional.
2. Leave UEFI boot on; leave CSM off unless you specifically want to test the BIOS path. (BIOS/CSM loads ForeB stage1 from the MBR instead — different guide.)
3. Set SATA to AHCI (not RAID/Optane/RST/IDE) if the option exists. Proprietary RAID modes hide disks from the kernel.
4. Disable Fast Boot / Fast Startup if the USB stick is not detected; it skips USB enumeration.
5. Save and exit, then open the one-time boot menu (F12, F8, F9, or Esc) and select the USB stick. You may see two entries for the same stick (UEFI: <stick> and USB: <stick>) — pick the UEFI: one.

4. Partition the target (GPT + ESP + root)

Boot the live session, open a terminal. UEFI boots from a FAT EFI System Partition; the Forest root lives beside it. Typical single-disk layout:

Example with gdisk / mkfs (replace /dev/sda with your target):

gdisk /dev/sda
# o (new GPT) → n (part 1, +512M, EF00) → n (part 2, rest, 8300) → w (write)

mkfs -t fat32 /dev/sda1
mkfs -t ext4 /dev/sda2

mount /dev/sda2 /mnt
mkdir -p /mnt/boot/efi
mount /dev/sda1 /mnt/boot/efi

Rules:

• ESP must be FAT (mkfs -t fat32) — firmware only reads FAT.
• ESP mount point is /boot/efi.
• Keep the ESP at the start of the disk, flagged as EFI System Partition.
• Use GPT on UEFI machines (protective MBR + EFI PART at LBA 1). forinstall guided mode handles partitioning for you; manual mode asks for root/swap/home paths.
• Keep the ESP FAT — firmware cannot read ext2/ext4. See Filesystems for the FAT-vs-ext2 write-support notes.
• Dual-boot: never delete or rename the other OS's EFI/ directory — give Forest its own loader entry/directory on the shared ESP, and back up first.

5. Boot the live session

1. Select the UEFI: <stick> entry from the one-time boot menu.
2. The ForeB boot menu appears (graphical forest theme on GOP, text fallback on limited hardware):
   • Forest OS — normal boot (default, pick this for install).
   • Forest OS (no framebuffer) — text mode (nofb).
   • Forest OS (safe mode) — conservative drivers (safe).
   • Reboot. Navigate with Up/Down, Enter to boot, Esc to reset the countdown.
3. The kernel loads and drops you at the live session (shell on TTY). Confirm display, keyboard, and (if needed) network work before installing.
4. Identify the disks from the live session (sizes tell USB stick vs internal disk apart). All data on the target disk is erased.

   fdisk -l
   blkid
   lsblk -d -o NAME,SIZE,MODEL,TRAN

6. Run forinstall (UEFI flow)

From the live session:

forinstall

UEFI flow:

1. Select target disk (/dev/sda, …).
2. Select partition scheme: GPT / UEFI.
3. Confirm ESP partition and root partition (or let forinstall create the layout from step 4).
4. Confirm ESP mountpoint: /boot/efi.
5. Confirm install — forinstall formats (if asked), copies the live system to root, and stages the bootloader (next step).
6. When prompted for bootloader location, choose the ESP (/boot/efi), not MBR.

Do not interrupt the copy. Wait for the success message.

Guided 23-step wizard (ANSI text UI). Defaults are in [brackets] — Enter accepts. Cancelling at the final confirmation makes zero changes.

• Language / keyboard: installer + system locale (en default), layout US/UK/DE/FR/ES/Dvorak. Sets /etc/locale, console keymap, TTY font page.
• Target disk: pick the internal disk (empty, from §5), never the installer media (cd0 / the USB stick). Confirm the destructive-write warning (YES — all target data is erased).
• Partition scheme: Entire disk (guided, default) or Manual (root/swap/home paths).
• Filesystem: ext4 (journaling, default) or ext2. Note the kernel ext2/3/4 driver is currently read-only — keep a FAT partition alongside if you need firmware-readable writable storage. The ESP itself stays FAT regardless.
• Hostname / timezone / network: hostname default forest; 10 named zones + custom UTC offset; DHCP (default) or static IP/gateway/DNS (DNS defaults to 8.8.8.8).
• Users: primary user (default user) + password × 2, then root password × 2. Skipping the user leaves a root-only system.
• ForeB (UEFI target): writes the ESP files + registers the NVRAM boot entry (BootOrder). Accept the default target (the disk chosen above). Installing to the ISO device is rejected.
• Confirm + copy: formats + mounts the target, copies kernel, initrd, base userspace, /etc skeleton and forebo.cfg, installs ForeB, runs fsck, then prints INSTALL OK — remove install media and reboot. On failure the log stays on serial — copy the last 20 lines into a bug report.

Full step table and file map: Installer.

7. What gets staged on the ESP

forinstall stages these four files (verify they exist):

/boot/efi/
  EFI/
    BOOT/
      BOOTX64.EFI   # ForeB UEFI loader (fallback boot path)
  forebo/
    kernel.elf      # Forest kernel
    forebo.cfg      # boot menu config
    initrd.tar      # initial ramdisk / modules

Depending on build, paths may appear as \EFI\BOOT\BOOTX64.EFI + \forebo\kernel.elf + \forebo\forebo.cfg + \forebo\initrd.tar — same set, FAT case-insensitive.

If any of BOOTX64.EFI + kernel.elf + forebo.cfg + initrd.tar is missing, the entry will fail — re-run forinstall or copy the missing file from the live media.

/                          FAT root of the ESP
  EFI/
    BOOT/
      BOOTX64.EFI            ForeB UEFI application (PE32+, unsigned)
  forebo/
    kernel.elf               Forest kernel ELF
    forebo.cfg               ForeB configuration
    initrd.tar               Initrd tarball (multiboot module)
    bg.bmp                   Menu background image
    icons/                   Menu icons (TGA format)

Default forebo.cfg entry (written by the installer; edit paths only if you moved files):

timeout=5
default=0

menuentry "Forest OS" {
    type=forest
    kernel=/forebo/kernel.elf
    module=/forebo/initrd.tar
    cmdline="root=/dev/sda1 ro"
    icon=os
}

The installer also registers the loader in firmware NVRAM (Boot#### + BootOrder). QEMU/OVMF note: keep the writable per-VM OVMF_VARS.local.fd attached — it holds that entry; a read-only or shared VARS file loses BootOrder on reboot. See UEFI Boot and Configuration.

Boot entry order

UEFI boots by NVRAM entries plus the fallback path:

1. forinstall registers a Forest OS / ForeB Boot#### entry pointing at \EFI\BOOT\BOOTX64.EFI on the internal ESP.
2. The fallback \EFI\BOOT\BOOTX64.EFI also boots even with no NVRAM entry (most firmware tries it automatically).
3. Enter firmware boot menu / Boot Order and move the internal disk (or the Forest OS entry) above USB / network / Windows Boot Manager.
4. Save.

Tip: from the ForeB shell you can inspect entries with bootvars / efivars.

Verify before reboot

Still in the live session, with target mounted at /mnt:

mdir -i /dev/sda1 ::/EFI/BOOT/
mdir -i /dev/sda1 ::/FOREBO/
# expect: BOOTX64.EFI, kernel.elf, forebo.cfg, initrd.tar

cat /mnt/boot/efi/forebo/forebo.cfg
cat /mnt/forebo/forebo.cfg   # alternate location on some builds — one must exist

efibootmgr -v   # or: bootvars in ForeB shell — expect a Forest/ForeB Boot#### + BootOrder

Checks:

• mdir ESP listing shows all four staged files.
• forebo.cfg has a menuentry "Forest OS" with kernel=/forebo/kernel.elf and module=/forebo/initrd.tar.
• Boot vars (efibootmgr -v / bootvars) list the new entry and BootOrder includes it.

Only reboot when all three pass.

8. Remove USB, boot internal ESP

1. Power off / reboot.
2. Remove the USB install media.
3. Boot — select the internal disk / Forest OS entry (or let the default BootOrder run).
4. ForeB menu appears from the internal ESP → select Forest OS.
5. Continue with First-Boot and Post-Install.

1. sync, shut down, then physically remove the USB stick (VMs: detach the ISO / put HDD-0 first in boot order).
2. Power on; pick the internal disk (or the Forest Boot#### entry) if the firmware asks. The ForeB menu should appear from disk — default entry boots in ~10 s.
3. Log in as the created user (or root). Expect kernel banners on serial, framebuffer TUI/GUI on display, shell prompt on both.
4. Smoke test:

   uname -a
   df -hT          # root mounted, space free
   ls /bin | head
   ip addr         # NIC if networking is enabled

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

9. Post-install

Network

ip addr                 # list interfaces
ip link set e1000 up    # bring the interface up (name varies by driver)
ip addr add 10.0.2.15/24 dev e1000
ip route add default via 10.0.2.2 dev e1000
ping -c 4 10.0.2.2

If no interface appears it is a missing driver, not a cable problem — rebuild with ENABLE_NETWORKING plus your NIC driver and reinstall. See Networking.

Users

id                      # confirm uid/gid
hostname forest-node-01 # name this machine
su -                    # switch identity / test login shell

Users/groups come from /etc/passwd, /etc/group, /etc/shadow; see Initrd Builder. Set hostname and passwords before putting the machine on a network.

Updates

pac list
pac update              # update everything installed
pac update <pkg>        # update one package
pac history             # audit what changed

pac speaks plain HTTP to the servers in /etc/pacservers — it needs a working route (or a local mirror). Do not update over an untrusted network; there is no TLS in the client.

Troubleshooting

Stuck? See Troubleshooting, FAQ, and Bootloader Overview.

See Also

• UEFI Boot — ESP layout, forebo.cfg, chainloading
• Boot Menu — menu entries and keys
• Bootloader Configuration — forebo.cfg reference
• ISO Creation — hybrid ISO / IMG / ESP internals + QEMU one-liners
• Install on a VM — QEMU / VirtualBox / VMware via forinstall
• Install on Real Hardware — bare-metal USB install
• USB Persistence — live vs persistent vs full USB install
• Installer — forinstall + forupdate reference
• Disk Tools — fdisk, mkfs, mount, fsck
• Filesystems — FAT vs ext2/3/4 status

← Back to Wiki