Initial RAM disk

The boot script lives at /var/ironforge/initrd/init. It prepares the root filesystem, mounts the selected system images, and starts dinit.

Build and install

The current build tooling assembles the initrd from Ironforge package outputs: BusyBox, cryptsetup and its libraries, and the live filesystem skeleton. The builder requires local outputs for basic, busybox, cpio, cryptsetup, lvm2, jsonc, and popt.

cd /var/ironforge/initrd
make check
make install

make check builds and validates the archive. make install copies it to /boot/EFI/ironforge/initrd.img; the EFI system partition must be mounted at /boot. Rebuilding the file in the source directory alone does not update the installed boot image.

Installed boot

The installer prepares the persistent root filesystem, including /etc, /root, /var, and the directories needed for runtime mounts. At boot, the initrd:

Opens the LUKS device when cryptroot= is supplied, then mounts the root device. An unencrypted installation supplies root= directly.
Resolves /var/ironforge/images/current and mounts its usr.sqfs and opt.sqfs read-only at /usr and /opt. The default layout requires both files and resolves the selected directory once for the pair.
Mounts the virtual filesystems, including temporary writable /run, /tmp, and /dev/shm.
Switches to the installed root and starts /usr/bin/dinit.

The installed root and /etc remain writable and persistent. The initrd does not replace /etc with the live-system skeleton during an installed boot.

Boot arguments

Argument	Meaning
`root=`	Root device path or `UUID=`, `LABEL=`, `PARTUUID=`, or `PARTLABEL=` reference. `root=live` selects live mode.
`cryptroot=`	LUKS device to unlock. Unless another root is specified, the unlocked device becomes the root.
`crypttarget=`	LUKS mapper name; defaults to `rootfs`.
`sqfs=`	Path on the root filesystem to the `/usr` image; defaults to `/var/ironforge/images/current/usr.sqfs`.
`optsqfs=`	Path on the root filesystem to the `/opt` image; defaults to `/var/ironforge/images/current/opt.sqfs`.
`init=`	Init executable; defaults to `/usr/bin/dinit`.
`nosplash` or `splash=0`	Use the text console and cryptsetup prompt.
`splash=desktop`	Keep the graphical splash through dinit until an integrated Anvil presents its first frame. Requires the bootsplash service/launcher integration.
`debug`	Enable verbose boot logging and use the text console.

For example, an encrypted installation can use:

cryptroot=/dev/nvme0n1p2 crypttarget=root

No image aliases at / or the /var/ironforge top level are needed. Explicit sqfs= and optsqfs= arguments override the defaults, so old boot entries must be updated when moving images. For rollback, point both arguments at the same directory beneath /var/ironforge/images/releases/, or use the normal release selection workflow.

The script also supports optional bcache registration, a separate kernel module tree, and a writable source overlay. Their arguments and defaults are documented at the top of initrd/init.

Graphical boot

The initrd includes the standalone static bootsplash program by default. Its 1920×1080 master uses VGA UI colors and Anvil's embedded font, with smooth edges. It letterboxes 16:10 displays and fits the whole master into early framebuffers; at 640×480 this produces a centered 640×360 image. It discovers DRM devices and retains a framebuffer fallback. Use make WITH_BOOTSPLASH=0 to build without it.

The default lifetime ends before switch_root. With splash=desktop, the initrd preserves its daemon, socket and runtime state, allowing it to follow the native GPU as its driver loads. The dinit integration guards setfont and coordinates display ownership with Anvil's first presented frame. Escape before that handoff stops desktop startup and opens a recovery console. Configuration and service templates are documented in /var/ironforge/bootsplash/README.md and bootsplash/integration/.

The splash receives explicit status messages; it does not own every service's stdin/stdout. Initrd output is retained in /run/ironforge/boot.log. Extended boots additionally retain /run/bootsplash/events.log with display and handoff transitions. Passwords are never included in those logs.

Firmware

Firmware is packaged inside usr.sqfs at /usr/lib/firmware. The firmware package supplies selected Linux firmware and the wireless regulatory database; nvidia-utils supplies NVIDIA GSP firmware. There is no separate firmware SquashFS or firmware mount in the current boot flow.

Firmware becomes available with the /usr mount. The current initrd builder does not copy the firmware package into the initrd, so hardware that needs firmware before the root filesystem can be reached requires additional initrd support.

Live boot

When no root device or encrypted root is specified, the initrd creates a writable temporary root from its embedded skeleton. It discovers the live media and mounts /ironforge/usr.sqfs from it, plus /ironforge/opt.sqfs when present. It also supports a directly attached /usr SquashFS device for VM testing. Changes to the temporary root disappear when the live system stops.