Bootloader Configuration

Updated

October 30, 2026

Bootloader Configuration

To make our ISO bootable across both legacy BIOS and modern 64-bit UEFI machines, we configure GRUB 2 with dual payload support.

+-----------------------------------------------------------+
|                   ISO Bootloader Staging                  |
|                                                           |
| $BYOL_ROOT/iso-staging/                                   |
| ├── boot/                                                 |
| │   ├── vmlinuz                                           |
| │   ├── initramfs.img                                     |
| │   └── grub/                                             |
| │       ├── grub.cfg (Boot menu definition)               |
| │       ├── bios.img (BIOS El Torito boot image)          |
| │       └── boot.cat                                      |
| ├── EFI/                                                  |
| │   └── boot/                                             |
| │       └── efiboot.img (Embedded FAT32 ESP image)        |
| └── byol/                                                 |
|     └── rootfs.squashfs                                   |
+-----------------------------------------------------------+

Step 1: Writing grub.cfg

Create the GRUB configuration file:

# $BYOL_ROOT/iso-staging/boot/grub/grub.cfg
set timeout=5
set default=0

menuentry "BYOL Linux 1.0 (Live Environment)" {
    set gfxpayload=keep
    linux /boot/vmlinuz quiet console=tty0 console=ttyS0,115200
    initrd /boot/initramfs.img
}

menuentry "BYOL Linux 1.0 (Rescue Debug Shell)" {
    set gfxpayload=keep
    linux /boot/vmlinuz debug init=/bin/sh console=tty0 console=ttyS0,115200
    initrd /boot/initramfs.img
}

Step 2: Creating the UEFI ESP Floppy Image (efiboot.img)

UEFI motherboards read the El Torito boot catalog and expect an embedded FAT filesystem containing /EFI/BOOT/BOOTX64.EFI:

$ mkdir -p "$BYOL_ROOT/iso-staging/EFI/boot"

# 1. Create a 10 MB blank image formatted as FAT16
$ dd if=/dev/zero of="$BYOL_ROOT/iso-staging/EFI/boot/efiboot.img" bs=1M count=10
$ mkfs.vfat "$BYOL_ROOT/iso-staging/EFI/boot/efiboot.img"

# 2. Mount the image temporarily
$ mkdir -p /tmp/esp
$ mount -o loop "$BYOL_ROOT/iso-staging/EFI/boot/efiboot.img" /tmp/esp

# 3. Generate standalone GRUB UEFI binary using host grub-mkstandalone:
$ mkdir -p /tmp/esp/EFI/BOOT
$ grub-mkstandalone -O x86_64-efi \
    -o /tmp/esp/EFI/BOOT/BOOTX64.EFI \
    "boot/grub/grub.cfg=$BYOL_ROOT/iso-staging/boot/grub/grub.cfg"

# 4. Unmount the image
$ umount /tmp/esp

Step 3: Generating the BIOS Boot Image

Generate the legacy BIOS El Torito boot image:

$ grub-mkstandalone -O i386-pc \
    -o "$BYOL_ROOT/iso-staging/boot/grub/bios.img" \
    "boot/grub/grub.cfg=$BYOL_ROOT/iso-staging/boot/grub/grub.cfg"

The bootloader staging tree is now prepared for ISO authoring.