Install on Real Hardware

Step-by-step guide to installing Forest OS on a physical machine from USB. For building the image itself, see ISO Creation; for QEMU-only testing, see Testing.

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

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

Requirements

A Forest OS image: forebo.iso (hybrid, BIOS + UEFI) or forebo.img (raw disk). Build with make iso / make img in fern/.
A USB stick ≥ 256 MiB (any USB 2.0/3.0 stick works; all data on it is erased).
A target PC: x86 or x86_64, BIOS (CSM/Legacy) or UEFI firmware.
A second machine (or the same one booted into Linux/Windows) to write the USB.

1. Write the USB stick

Linux — `dd` (recommended)

# 1. Identify the stick (NOT a partition like sdb1 — the whole disk, e.g. /dev/sdb).
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 image (hybrid ISO and raw IMG both work with dd).
sudo dd if=build/forebo.iso of=/dev/sdX bs=4M status=progress oflag=sync
sync

# 4. Verify: re-read the MBR signature and stage2 magic off the stick.
sudo dd if=/dev/sdX bs=512 count=1 2>/dev/null | xxd -s 510 -l 2
# expect: 55aa
sudo dd if=/dev/sdX bs=512 skip=1 count=1 2>/dev/null | xxd -s 2 -l 2
# expect: b1fe  (stage2 magic 0xFEB1, little-endian on disk)

Replace /dev/sdX with your stick (e.g. /dev/sdb). oflag=sync + sync ensures all data is flushed before you unplug.

Windows — Rufus

Download Rufus, select the USB stick and forebo.iso.
When prompted for ISO mode vs DD mode, choose DD mode (raw write). ISO mode extracts files and breaks the ForeB sector layout — the stick will not boot.
Start, wait for completion, then use "Safely remove" before unplugging.

Verify before you reboot

Stick size looks right in the OS disk manager (a ~10 MiB ForeB image on a large stick shows mostly unallocated space — that is normal).
On Linux, sudo fdisk -l /dev/sdX shows the ForeB MBR partition entry and no errors.

2. Firmware setup (BIOS vs UEFI)

Forest OS boots both ways from the same hybrid ISO:

Path	What the firmware loads	Requirements
BIOS / CSM / Legacy	ForeB stage1 (MBR) → stage2 → stage3 → kernel	CSM/Legacy boot enabled, or an old BIOS-only board
UEFI	`\EFI\BOOT\BOOTX64.EFI` from the ESP	64-bit UEFI, Secure Boot off (see below)

Disable Secure Boot. Forest OS ships an unsigned BOOTX64.EFI; with Secure Boot on, firmware refuses to load it. No signed shim — turning it off is required.
Set SATA to AHCI (not RAID/Optane/IDE) if the option exists. AHCI is the tested path.
Pick your boot mode: UEFI machine: leave UEFI boot on; enable CSM only to test the BIOS path. Old BIOS machine: MBR path is automatic.
Fast Boot / Fast Startup: disable if the stick is not detected; it skips USB enumeration.
Save and exit, then open the one-time boot menu (F12, F8, F9, or Esc) and select the USB stick. On UEFI you may see two entries (UEFI: <stick> and USB: <stick>) — pick the one matching the path you want.

3. Install flow (live boot)

Select the USB stick from the boot menu.
The ForeB boot menu appears (graphical forest theme, or text fallback on limited VBE/GOP hardware):
- Forest OS — normal boot (default).
- Forest OS (no framebuffer) — text mode (nofb cmdline).
- Forest OS (safe mode) — conservative drivers (safe cmdline).
- Reboot. Navigate with Up/Down, Enter to boot, Esc to reset the countdown.
The kernel loads from the stick and drops you at the live session (shell on TTY). Confirm display, keyboard, and network work before installing.
Identify the internal disk from the live session:
```
fdisk -l /dev/sda
blkid
```
Note which device is the USB stick vs the internal disk (sizes in fdisk -l tell them apart). All data on the target disk is erased.

4. Install the bootloader to the internal disk

On BIOS hardware, ForeB lives at fixed LBA sectors (see BIOS Boot):

Sectors	Content
0	Stage 1 (MBR + partition table + `0xAA55`)
1..22	Stage 2 (11264 B, 22 sectors)
23..38	Stage 3 (8 KiB, 16 sectors)
54+	Kernel ELF image (`KERNEL_START_SECTOR`)
past kernel	Optional initrd (`BIOS_INITRD_SECTOR`, ~560)

The supported install is a sector copy from the known-good USB stick to the internal disk, from the live Forest OS shell (or any Linux live USB):

# From the Forest OS live session. sdX = USB stick, sdY = INTERNAL disk.
# Confirm both with `fdisk -l` first — swapping them wipes your installer.

# Copy MBR + stages + kernel + initrd in one pass (first ~16 MiB is plenty):
dd if=/dev/sdX of=/dev/sdY bs=1M count=16
sync

Equivalently, from the build machine directly (no live session needed):

sudo dd if=build/forebo.img of=/dev/sdY bs=4M status=progress oflag=sync
sync

Then verify the target disk before rebooting:

# MBR signature must be 55aa:
dd if=/dev/sdY of=mbr.bin bs=512 count=1
# check bytes 510-511 == 55 AA (xxd/fdisk/blkid per Disk-Tools)
fdisk -l /dev/sdY
blkid /dev/sdY

On UEFI machines the equivalent is copying the ESP contents (EFI/BOOT/BOOTX64.EFI, forebo/kernel.elf, forebo.cfg, initrd) onto a FAT32 EFI System Partition on the internal disk. The BIOS sector-copy above covers the tested bare-metal path; UEFI ESP layout follows ISO Creation.

5. Remove USB and reboot

sync, then shut down: shutdown -h now (or reboot -p).
Wait for power-off, physically remove the USB stick.
Power on, enter the boot menu if needed, and select the internal disk.
ForeB should appear from the internal disk. If it drops to firmware or prints a stage error, see "Boot loops" below and recheck sectors first.

6. 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
ethtool e1000           # link/driver status

Real-hardware NICs vary widely; if no interface appears, that is a missing driver, not a cable problem. See Networking.

Users

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

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, so it needs a working route (or a local mirror). Do not update over an untrusted network — no TLS in the client.

7. Issues and fixes

Symptom	Cause	Fix
USB stick not listed in boot menu	Port/mode problem	Try USB 2.0 port, disable Fast Boot, rewrite in DD mode, re-verify `55aa` per §1
Secure Boot violation	Unsigned loader	Disable Secure Boot — no signed shim; mandatory for UEFI path
No network after install	Missing driver	Check `ip addr` / `ethtool`; enable `ENABLE_NETWORKING` + NIC driver at build time, rebuild, reinstall
Blank screen after ForeB menu	Framebuffer/mode issue	Pick `no framebuffer` (`nofb`) or `safe mode` (`safe`). See BIOS Boot
Boot loops / `s2!` / `ERR:Invalid kernel entry point`	Corrupt or misaligned stages	Recheck: MBR `55aa` at byte 510, stage2 magic `0xFEB1` at sector 1, kernel ELF (`7F 45 4C 46`) at sector 54. Re-`dd` per §4, run `make -C foreboots check`

Still stuck? See Troubleshooting and FAQ.