.Dd October 12, 2026
.Dt BOOTLOADER 7
.Os
.Sh NAME
.Nm bootloader
.Nd how an installed rawnix system boots, and checking it
.Sh DESCRIPTION
An installed rawnix system boots with Limine from the EFI system
partition, mounted at
.Pa /boot/efi .
The kernel and the initramfs,
.Pa tinyrd.img ,
are also kept there.
.Pp
Nothing installs a boot loader by hand.
The limine package puts Limine on the EFI system partition at
.Pa EFI/BOOT/BOOTX64.EFI ,
the fallback path every UEFI firmware looks at.
.Ic limine-sync
writes the menu,
.Pa limine.conf ,
from the kernels in
.Pa /boot
and the command line in
.Pa /etc/limine-sync.conf .
It runs by itself whenever a kernel is installed or removed.
.Pp
This is why the order in
.Xr installation 7
matters:
.Xr setup-boot 8
writes
.Pa /etc/limine-sync.conf ,
the EFI system partition is mounted, and only then is the kernel
installed.
.Ss Before rebooting
From the installer, with the new system under
.Pa /mnt :
.Bd -literal -offset indent
# cat /mnt/boot/efi/limine.conf
# ls /mnt/boot/efi
# cat /mnt/etc/crypttab
.Ed
.Pp
.Pa limine.conf
should list the kernel, and on an encrypted system the command line
should contain
.Li cryptroot= .
The EFI system partition should hold
.Pa vmlinuz- Ns Ar version ,
.Pa tinyrd.img
and
.Pa EFI/ .
.Pa /etc/crypttab
exists only if there are encrypted partitions besides root.
.Ss A boot entry in the firmware
Most firmware boots the fallback path by itself.
Some only boots what is listed in its boot menu; add an entry with
.Xr efibootmgr 8 .
It needs
.Pa /sys/firmware/efi/efivars ;
.Xr enter-chroot 8
mounts it, or in the installer:
.Bd -literal -offset indent
# mount -t efivarfs efivarfs /sys/firmware/efi/efivars
.Ed
.Pp
Then list the entries and add one, naming the disk and the number of
the EFI system partition:
.Bd -literal -offset indent
# efibootmgr
# efibootmgr -c -d /dev/sdX -p 1 -L rawnix -l '\eEFI\eBOOT\eBOOTX64.EFI'
# efibootmgr -v
.Ed
.Ss Changing the command line
Edit
.Li CMDLINE=
in
.Pa /etc/limine-sync.conf ,
then run
.Ic limine-sync .
The file describes its other settings.
.Ss A serial console
A server reached through a serial console \(em a VPS provider's console,
.Ic qemu -nographic
\(em needs the kernel to write there as well:
.Bd -literal -offset indent
CMDLINE=... console=tty0 console=ttyS0,115200
.Ed
.Pp
in
.Pa /etc/limine-sync.conf ,
then
.Ic limine-sync .
The last
.Li console=
is the one that receives init's output.
A login prompt on
.Pa ttyS0
needs nothing: runit's
.Li agetty-ttyS0
runs by default wherever a serial port exists.
On a desktop, leave the serial console out; it only slows the boot
messages down.
.Ss Legacy BIOS
A machine without UEFI firmware \(em Hetzner Cloud, or
.Xr qemu 1
without OVMF \(em boots the same installed system through Limine's
BIOS stages.
Limine reads only FAT, so the kernels, the initramfs and
.Pa limine.conf
stay on the EFI system partition exactly as under UEFI, and
.Ic limine-sync
writes them the same way.
Two steps are done by hand, and one thing needs remembering.
.Pp
The disk needs a 1 MiB BIOS boot partition, as partition 1, ahead of
the EFI system partition; in
.Xr fdisk 8 :
a GPT label, then a 1 MiB partition of type
.Dq BIOS boot ,
then the EFI system partition, then root.
.Pp
After the install, inside
.Xr enter-chroot 8 ,
Limine's boot code goes onto the disk, and its BIOS loader onto the
EFI system partition:
.Bd -literal -offset indent
# limine bios-install /dev/sdX 1
# cp /usr/share/limine/limine-bios.sys /boot/efi/
.Ed
.Pp
.Ar /dev/sdX
is the disk, not a partition; the 1 is the BIOS boot partition.
.Xr genfstab 8
leaves out the
.Li efivarfs
line by itself when the installer was booted through BIOS.
.Pp
The boot code on the disk and
.Pa limine-bios.sys
must come from the same version of Limine.
.Ic limine-sync
does not touch either, so after updating the limine package on such a
machine, repeat both commands \(em or keep it at one version with
.Ic pkg lock limine .
.Sh FILES
.Bl -tag -width Ds
.It Pa /boot/efi/limine.conf
The boot menu, written by
.Ic limine-sync .
.It Pa /etc/limine-sync.conf
The kernel command line for the menu, written by
.Xr setup-boot 8 .
.It Pa /etc/limine.conf.in
The hand-written part of the menu.
.El
.Sh SEE ALSO
.Xr qemu 1 ,
.Xr encryption 7 ,
.Xr installation 7 ,
.Xr partition 7 ,
.Xr efibootmgr 8 ,
.Xr enter-chroot 8 ,
.Xr fdisk 8 ,
.Xr genfstab 8 ,
.Xr setup-boot 8