Partitioning

How Forest OS lays out disks for a real install. Read this before running forinstall.

Warning: forinstall erases the target disk. Step 1/8 (disk_create_partitions) writes a fresh MBR and step 2/8 overwrites raw sectors 0–38 + 54+. There is no undo. Confirm the target with fdisk -l + lsblk before confirming — picking the wrong /dev/sdX wipes that disk.

Related: Disk Tools, Installer, BIOS Boot.

1. MBR layout

All sectors are 512 bytes. Constants: FOREB_STAGE2_SECTOR 1, FOREB_STAGE2_SECTORS 22, FOREB_STAGE3_SECTOR 23, FOREB_STAGE3_SECTORS 16, FOREB_KERNEL_SECTOR 54, FOREB_PARTITION_START 63 (userspace/forinstall/installer.h, mirrors foreboots/bios/config.h).

Sectors	Content
0	MBR: boot code bytes 0–439, partition table bytes 446–509 (4×16 B), signature `0x55AA` bytes 510–511
1–22	ForeB stage 2 (real-mode, 22 sectors)
23–38	ForeB stage 3 (protected-mode loader, 16 sectors)
39–53	Gap — reserved
54+	Kernel ELF (variable length, zero-padded last sector)
past kernel, 16-aligned	Initrd (optional) at `((54 + ksectors + 15) / 16) * 16`
63+	Partition 1 — first usable partition

Rules:

Partition 1 must start at sector 63, not sector 1. Sectors 1–62 are the ForeB gap (stages + reserved + kernel head). A partition starting at LBA 1 overlaps stage2/stage3 and will not boot.
Partition 1 is bootable (boot flag 0x80, shown as * in fdisk -l) and type 0x83 Linux.
MBR signature must read 55aa (last 2 bytes of sector 0). Stage2 magic must read b1fe (0xFEB1 little-endian at offset 2 of sector 1) or boot halts with flashing s2!.

Expected single-partition result:

Disk /dev/sda: <sectors> sectors
Device     Boot   Start      End  Sectors  Size    Type
/dev/sda1  *           63  <end>  <count>  <size>  Linux

2. Entire-disk vs manual

Picked at wizard step 6 (step_partition_scheme, partition_scheme in InstallerConfig). Implemented in disk_create_partitions() (userspace/forinstall/disk.c:150-213).

Entire disk (guided, `scheme == 0`)

One bootable (0x80) type 0x83 Linux partition covering the disk.
Intermediate table writes start LBA 1, length total_sectors - 1; then install_write_foreb_to_disk() clears MBR bytes 446–509, reinstalls one bootable 0x83 partition starting at FOREB_PARTITION_START 63, and restores 0x55AA.
Final on-disk result is sector 63 either way — verify Start == 63 after install.
fstab is hardcoded to /dev/sda1 / ext2|ext4 (adjust if your target is not sda).
Use when: dedicated disk, VM, or you do not need to preserve anything. This is the tested path.

Manual (advanced, `scheme == 1`)

Wizard prompts for root / swap / home device paths (steps 7–9, skipped for guided).
Three partitions, sized from total sectors:

#	Mount	Share	Type	Bootable
1	`/` (root)	60 %	`0x83` Linux	yes (`0x80`)
2	swap	10 %	`0x82` Linux swap	no
3	`/home`	remainder (~30 %)	`0x83` Linux	no

CHS fields are filler (01/01/00 start, FE/FF/FF end); LBA start/count are authoritative.
fstab gets one line per non-empty partition (root / pass 1, swap none swap sw pass 0, home /home pass 2) plus proc/sysfs/tmpfs lines.
Use when: you want isolated /home or swap on spinning disk/SSD. Never put swap on a USB flash stick (wear).

3. Inspect with fdisk

Forest fdisk is inspect-only (userspace/fdisk/fdisk.c, see Disk Tools). It reads the MBR: boot code 0–445, 4 entries at 446/462/478/494, signature 0xAA55 at 510.

fdisk [-lpsv] [-s PARTITION] device

Option	Use
`-l`	List all partitions on the device (start/end/sectors/size/type)
`-p`	Same in parseable CSV format (scripts)
`-s N`	Size of partition N in sectors
`-v`	Version

fdisk -l /dev/sda        # human table — check Start == 63, Boot == *, Type == Linux
fdisk -p /dev/sda        # CSV for scripts
fdisk -s 1 /dev/sda      # size of partition 1 in sectors

Create partitions with host fdisk (start sector 63) or with forinstall itself, then verify with Forest fdisk. Always back up the MBR first:

dd if=/dev/sda of=mbr.bin bs=512 count=1
fdisk -l /dev/sda

4. Partition type bytes

Byte	`fdisk -l` label	Use
`0x83`	Linux	Root and `/home` (ext2/ext4)
`0x82`	Linux swap	Swap partition (manual scheme p2 only)
`0x0C`	FAT32 LBA	ESP / shared / `FOREST-DATA` persistent store — not install root

mkfs stamps the type automatically when run on a whole-disk image (ext2 → 0x83, fat32 → 0x0C). Format the partition (/dev/sda1), not the whole disk (/dev/sda), or you clobber the MBR:

mkfs -t ext2 -L ROOT -v /dev/sda1
mkfs -t fat32 -L ESP -v /dev/sdb1

5. Size guidance

Install type	Size	Notes
Minimal	~500 MB (512 MB min)	Core system only (`step_install_type`)
Full	~2 GB (2 GB recommended)	Default; comfortable root with binaries + kernel + initrd
Root partition (manual)	60 % of disk	Must still meet the minimums above
Swap (manual)	10 % of disk, ~RAM size on HDD/SSD	Skip (or ≤1 GB) on USB flash — wear
`/home` (manual)	remainder (~30 %)	User data; ext2 `0x83`

Monitor after install:

df -hT
du -sh /home

6. Verify before reboot

Run against the target (/dev/sda internal vs /dev/sdb USB — confirm with lsblk first). All read-only:

# 1. Target identity — sizes tell stick vs internal disk apart
lsblk -d -o NAME,SIZE,MODEL,TRAN
fdisk -l /dev/sda
blkid /dev/sda1

# 2. MBR signature, bytes 510-511 of sector 0 -> 55aa
dd if=/dev/sda bs=512 count=1 2>/dev/null | xxd -s 510 -l 2
# expect: 55aa

# 3. Stage2 magic, offset 2 of sector 1 -> b1fe (0xFEB1 LE)
dd if=/dev/sda bs=512 skip=1 count=1 2>/dev/null | xxd -s 2 -l 2
# expect: b1fe

# 4. Kernel ELF magic at sector 54 -> 7f454c46 (7F 'E' 'L' 'F')
dd if=/dev/sda bs=512 skip=54 count=1 2>/dev/null | xxd -l 4
# expect: 7f45 4c46

# 5. Filesystem sanity (read-only)
fsck -n /dev/sda1
df -hT

Failure	Meaning	Fix
(2) wrong	MBR not written	Re-run install or `make -C foreboots install-disk DISK=/dev/sda`
(3) wrong	Stage2 missing/corrupt	Expect `s2!` flash; re-`dd` sectors 1–22
(4) wrong	Kernel missing at 54	`ERROR: Could not load kernel!`; re-`dd` kernel at `seek=54`
`Start != 63`	Partition overlaps ForeB gap	Repartition with start 63, reinstall