USB Persistence: Live vs Persistent vs Full Install

Three ways to run Forest OS from USB. They differ only in where writes go.

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

Status note: FAT12/16/32 is the only production read/write disk filesystem. ISO9660/UDF/exFAT are probe/mount-only, tmpfs/initrd are RAM-only, and kernel ext2/3/4 is read-only (see Filesystems). mkfs creates fat32 and ext2 only. So today: persistence store = FAT32, full-install root = ext2 via the installer/mkfs (verify ext2 boot support for your config first).

1. Live USB — read-only + RAM, nothing persists

How it works

ISO9660/UDF volume (read-only) ──► kernel + initrd loaded to RAM
                                         │
initrd (ustar, read-only) ──► root filesystem in RAM
tmpfs (/tmp, mounts) ──► RAM only, freed on reboot

• Boot medium is ISO9660 (or hybrid ISO on USB). The kernel detects the CD001 volume descriptor at sector 16 but never writes to it. UDF (NSR02/NSR03) is the same: mount-only.
• Root at boot is the initrd: a ustar tarball (initrd.tar) loaded by ForeB as a Multiboot module (BIOS: fixed sector ~560; UEFI: /forebo/initrd.tar). Unpacked to RAM, read-only.
• All writes land on tmpfs/ramdisk — /tmp, edited files, installed packages, live-created users all vanish on power-off.
• Live is the installer source: forinstall reads the boot blob from /boot/forebo/forebo.img, /cdrom/boot/forebo/forebo.img, etc., and copies it to the target.

Make a live USB

# 1. Identify the stick. WRONG of= DESTROYS DATA.
lsblk

# 2a. From hybrid ISO (BIOS + UEFI, recommended):
sudo dd if=build/forebo.iso of=/dev/sdX bs=4M status=progress oflag=sync

# 2b. From raw disk image (BIOS):
sudo dd if=build/forebo.img of=/dev/sdX bs=4M status=progress oflag=sync

See ISO Creation for make iso / make img / make esp. Boot, try things, reboot — the stick is unchanged. Writing the stick is covered step-by-step in Install on Real Hardware.

2. Persistent USB — read-only system + writable data partition

How it works

Partition 1: ISO9660 / FAT ESP (Forest OS system, read-only at runtime)
Partition 2: FAT32 "FOREST-DATA" (writable store)
                ├── mounted at /home  → persists
                ├── mounted at /etc/overlay or /data → configs persist*
                └── tmpfs at /tmp, /proc, /sys, /dev → never persist

• The system still boots from the read-only image. A second FAT32 partition holds everything you keep.
• At boot/login (or via /etc/fstab + mount -a) the data partition is mounted over /home (and optionally a config dir).
• This is an overlay in the operational sense (writable mount over the RAM root), not a kernel overlayfs driver: files outside a persistent mount are RAM-only.

What persists / what does not

To keep a system config, store a copy on the data partition and copy/symlink it at startup (e.g. from /etc/init.d/rcS).

Why FAT32, not exFAT

• FAT32: use this. Full read/write, mkfs -t fat32 + mount -t vfat/fat, portable with Linux/Windows/macOS.
• exFAT: do not use for persistence yet. Probe/mount-only, no write path, no mkfs support. It mounts but you cannot save to it from Forest OS.

Bootable + persistent setup (step by step)

Layout for an 8 GB+ stick (/dev/sdX):

p1: ~1 GB  ISO9660/FAT  boot/live system (from forebo.iso/img)
p2: rest    FAT32        FOREST-DATA      persistent store

lsblk                          # confirm /dev/sdX is the stick
fdisk -l /dev/sdX              # inspect current table

# 1. Write the live system to the stick (occupies the front)
sudo dd if=build/forebo.iso of=/dev/sdX bs=4M status=progress oflag=sync

# 2. Create a second partition in the leftover space (type 0x0C FAT32 LBA),
#    then format it:
sudo mkfs.vfat -F 32 -n FOREST-DATA /dev/sdX2   # on a Linux host, or:
mkfs -t fat32 -L FOREST-DATA /dev/sdX2          # Forest mkfs

# 3. Verify
blkid /dev/sdX2
fsck -n /dev/sdX2

# Manual mount (Forest shell)
mkdir -p /home /data
mount -t vfat /dev/sdX2 /data
mount --bind /data/home /home        # or mount the partition directly at /home

cat /etc/fstab

Example fstab fragment (adjust device names — prefer labels/UUIDs where supported):

# <device>    <mount>  <type>  <options>        <dump> <pass>
 /dev/sdb2     /home    vfat    defaults           0      2
 /dev/sdb2     /data    vfat    defaults,noatime   0      2
 proc          /proc    proc    defaults           0      0
 sysfs         /sys     sysfs   defaults           0      0
 tmpfs         /tmp     tmpfs   defaults           0      0

mount -a        # mounts all fstab entries not marked noauto
df -hT          # confirm /home is vfat on /dev/sdX2
du -sh /home    # how much persistent space is used

Reboot test: create /home/hello.txt, reboot without reformatting, check it is still there. Create /tmp/scratch, reboot, confirm it is gone.

3. Full USB install — the stick IS the disk

A full install treats the USB stick exactly like an internal hard disk: ForeB stages on raw sectors, kernel at its fixed sector, root on a native partition.

Sector 0      Stage 1 (MBR + partition table + 0xAA55)
Sectors 1-22  Stage 2 (real-mode menu, E820, VBE)
Sectors 23-38 Stage 3 (protected-mode ELF loader)
Sector 54+    Kernel ELF
Past kernel   initrd (16-sector aligned)
Sector 63+    Partition 1: ext2 root (type 0x83), / + /home + /etc all native

• Bootloader on USB. BIOS boots sector 0 via INT 13h LBA; UEFI boots BOOTX64.EFI from the ESP on USB.
• Everything persists (subject to filesystem support): /home, /etc, users, packages — root itself is writable.
• Portable but hardware-bound by device names: installer fstab references /dev/sda1-style names. Moving the stick can rename devices; keep a ForeB shell / recovery USB handy to fix fstab.
• Wear: flash wears faster than SSD/HDD. Use noatime, avoid swap on the stick, unmount cleanly.

During-install behavior: target USB vs internal disk

The installer does the same steps regardless of target — only the picked device differs. Picking the USB stick (e.g. /dev/sdb) installs everything there; picking /dev/sda installs internally. Double-check with lsblk / fdisk -l. Full flow (target disk, filesystem, users, ForeB) is documented in Install on a VM §9 (forinstall); raw sector-copy details in Install on Hardware §4.

# DANGER: writes ForeB stages to the target's MBR region. Triple-check DISK.
lsblk
make -C foreboots install-disk DISK=/dev/sdX

Boot without USB/disc after an internal install

• BIOS: firmware loads internal sector 0 → stages 2/3 (sectors 1–38) → kernel (sector 54+) → root per fstab. No USB needed. Flashing s2! = bad stage2 magic (0xFEB1) or MBR 55AA — re-run install or make check.
• UEFI: firmware loads \EFI\BOOT\BOOTX64.EFI from the internal ESP → \forebo\kernel.elf + forebo.cfg. Set the internal drive first in boot order.
• "Only boots with USB inserted" = stages went to the USB (wrong target) or firmware prefers USB. Reinstall targeting the internal disk, or fix boot order.

4. mkfs / mount / fstab cheat sheet

mkfs -t fat32 -L FOREST-DATA /dev/sdb2      # persistent data partition
mkfs -t fat32 -v /dev/sdb2                  # verbose variant
mkfs -t ext2 -L FOREST-ROOT /dev/sdb1       # full-install root on USB
mkfs -t ext2 -b 4096 -i 32768 /dev/sda1     # custom block size / inode count
blkid /dev/sdb1                             # confirm TYPE/LABEL/UUID
fsck -n /dev/sdb1                           # read-only check before mounting
fsck -a /dev/sdb1                           # auto-fix safe errors

mkdir -p /mnt/usb
mount -t vfat /dev/sdb2 /data               # FAT32 data partition
mount -t ext2 /dev/sdb1 /mnt/usb            # ext2 USB root elsewhere
mount -o loop forest.img /mnt/img           # image file via /dev/loop*
mount -a                                    # mount everything in fstab
mount                                       # list mounted filesystems
umount /data                                # detach (umount -l for lazy/busy)

# Full install on USB stick (root on ext2, no swap on flash)
/dev/sdb1   /       ext2    defaults,noatime   0  1
proc        /proc   proc    defaults           0  0
sysfs       /sys    sysfs   defaults           0  0
tmpfs       /tmp    tmpfs   defaults           0  0

# Persistent live: system is read-only ISO, data on FAT32
/dev/sdb2   /home   vfat    defaults           0  2
/dev/sdb2   /data   vfat    defaults,noatime   0  2

# Internal install with separate home + swap (spinning disk/SSD example)
/dev/sda1   /       ext2    defaults           0  1
/dev/sda2   none    swap    sw                 0  0
/dev/sda3   /home   ext2    defaults           0  2

See Disk Tools for dd/fdisk/mkfs/mount/blkid/fsck reference.

5. Size guidance

6. Troubleshooting

Further reading

• ISO Creation — make iso/img/esp, hybrid layout, dd to USB
• Disk Tools — dd/fdisk/mkfs/mount/blkid/fsck reference
• Filesystems — FAT vs exFAT/ISO9660/UDF/tmpfs status
• ForeB Overview — BIOS vs UEFI boot paths
• BIOS Boot — sector layout, stage magic, error catalog
• Initrd Builder — /etc/fstab seed, initrd contents
• Install on a VM — forinstall walkthrough
• Install on Real Hardware — writing the USB stick, firmware setup

← Back to Wiki