DOCSEARCHbyAlgolia
Submit Docs

Limine Bootloader Documentation

repository·v12.x·Indexed 24 days ago

https://github.com/limine-bootloader/limine

A modern, secure, and portable multiprotocol bootloader and boot manager supporting x86, ARM64, RISC-V, and LoongArch architectures. It serves as the reference implementation for the Limine boot protocol and supports Linux, Multiboot 1, Multiboot 2, and chainloading. Documentation covers installation, the limine host tool, configuration file structure (limine.conf), global and protocol-specific options, and path syntax for various storage resources.

Tokens
4.5K
Snippets
9
Records
26
Agent score
86%

What's inside Limine

  1. Overview of Limine Bootloader

    v12.x

    Limine is a modern, secure, portable, multiprotocol bootloader and boot manager. It also serves as the reference implementation for the Limine boot protocol.

    Supported Architectures

    • IA-32 (32-bit x86) - Requires Pentium Pro (i686) class CPUs or newer.
    • x86-64
    • aarch64 (arm64)
    • riscv64
    • loongarch64 (UEFI)

    Supported Boot Protocols

    • Linux
    • Limine
    • Multiboot 1
    • Multiboot 2
    • Chainloading

    Supported Partitioning and Filesystems

    • Partitioning: MBR, GPT, Unpartitioned media.
    • Filesystems: FAT12/16/32, ISO9660 (CDs/DVDs).

  2. Create a BIOS/UEFI hybrid ISO

    v12.x

    To create a hybrid ISO, organize your files in a root directory as follows:

    1. Place limine-uefi-cd.bin, limine-bios-cd.bin, limine-bios.sys, and limine.conf in the root directory.
      • limine-bios.sys and limine.conf can also reside in limine, boot, or boot/limine.
      • limine-uefi-cd.bin and limine-bios-cd.bin can reside anywhere.
    2. Create an EFI/BOOT directory in the root and copy the relevant Limine EFI executables (e.g., BOOTX64.EFI) into it.
    3. Run xorriso to generate the ISO image.
    4. Run limine bios-install on the resulting image.

    Example Workflow:

    # Assuming files are in <root_dir>
xorriso -as mkisofs -R -r -J -b <relative path of limine-bios-cd.bin> \
        -no-emul-boot -boot-load-size 4 -boot-info-table -hfsplus \
        -apm-block-size 2048 --efi-boot <relative path of limine-uefi-cd.bin> \
        -efi-boot-part --efi-boot-image --protective-msdos-label \
        <root directory> -o image.iso

limine bios-install image.iso

  3. Obtain and Build the limine host tool

    v12.x

    The limine host tool is required for installation and management. Binaries are available via GitHub releases (look for limine-binary-* files).

    If you need to build the host tool from source (available in the binary release package or standalone):

    1. Ensure you have a C99 compatible compiler.
    2. For UNIX-like systems, run make in the unpacked directory.

    Windows x86 host tool binaries are included in the binary release packages.

    make

  5. Structure of the Limine configuration file

    v12.x

    The Limine configuration file consists of menu entries and options.

    Menu Entries

    • Entry Title: A line starting with / followed by a newline-terminated string defines the title shown in the boot menu.
    • Sub-entries: To create a hierarchy (directory), prepend multiple / characters to the entry title. Each additional / represents one level of depth.
    • Expanded Directories: To ensure a directory is expanded by default in the menu, insert a + between the / characters and the title (e.g., /+/Sub-menu).
    • Local Options: Any option appearing after a menu entry and before the next entry or the end of the file is considered a local option belonging to that entry.

    Options

    • Format: option_name: string... (case-insensitive).
    • Global Options: Can appear anywhere, typically at the start of the file. They affect the entire bootloader behavior.
    • Local Options: Belong to a specific menu entry. These can be non-protocol specific or specific to a chosen protocol (e.g., linux, limine, efi).

    Comments

    Comments start with # and must be on their own lines.

  6. Install Limine on BIOS/GPT devices

    v12.x

    For GPT-formatted devices, you must create a 'BIOS boot' partition of at least 32KiB. Pass the 1-based partition number as the second argument to limine bios-install. The device must contain limine-bios.sys and limine.conf in a supported directory (boot/limine, boot, limine, or root).

    limine bios-install <path to device/image> <1-based stage 2 partition number>

  7. Locate the Limine configuration file

    v12.x

    Limine searches for its configuration file (limine.conf) in a specific order depending on the boot mode. Once a valid configuration file is found, Limine uses it and stops searching; any subsequent candidates are ignored.

    EFI Boot

    1. Limine first checks for <EFI app path>/limine.conf.
    2. If not found, it scans the boot drive partitions sequentially (starting with the partition containing the Limine EFI executable).

    BIOS Boot

    Limine scans all partitions of the boot drive sequentially (first partition to last) for the following file paths in this exact order:

    1. /boot/limine/limine.conf
    2. /boot/limine.conf
    3. /limine/limine.conf
    4. /limine.conf

    Note: Ensure your intended configuration file is not shadowed by another file matching these paths on an earlier partition or directory.

  8. Enable and configure UEFI Secure Boot

    v12.x

    Limine supports UEFI Secure Boot if the executable is signed and the key is in the firmware's keychain. To enforce integrity, you must enroll the BLAKE2B hash of the limine.conf file into the Limine EFI executable using the limine enroll-config program.

    When Secure Boot is active and a config checksum is enrolled, the following policies are enforced:

    • The config file is verified against the enrolled checksum on every boot; a mismatch causes a panic.
    • All file paths (kernels, modules, DTBs, fonts, etc.) must have a BLAKE2B hash appended (e.g., boot():/kernel#<hash>). Loading a file without a hash causes a panic (except for EFI chainloading).
    • Wallpaper and font files without hashes are silently skipped.
    • The config editor is disabled.
    • hash_mismatch_panic is forced to yes.

    If no config checksum is enrolled, Limine treats Secure Boot as inactive and provides no integrity guarantees beyond the firmware.

  9. Secure the boot sequence on UEFI with Secure Boot

    v12.x

    To protect against malicious modifications to the configuration file on UEFI systems, you can bake the BLAKE2B checksum of the config file directly into the Limine EFI executable. Once the EFI executable is signed with a key in the firmware's keychain, the configuration file cannot be modified without detection.

    When UEFI Secure Boot is active and a config checksum has been enrolled, Limine enforces the following:

    1. All loaded files must have BLAKE2B hashes specified in their paths.
    2. The config editor is disabled.

    Note: Enrolling a checksum is an explicit opt-in. Without an enrolled checksum, Secure Boot enforcement is not applied. Refer to USAGE.md for specific enrollment instructions.

  10. Install Limine for UEFI systems

    v12.x
    To install Limine on a UEFI system, copy the BOOT*.EFI files (found in ${PREFIX}/share/) to the /EFI/BOOT directory of a FAT-formatted EFI System Partition (ESP). These files can coexist with a BIOS installation on the same disk. A valid limine.conf must also be provided.

  11. Install Limine on BIOS/MBR devices

    v12.x

    To install Limine on an MBR device or a raw image file, use the limine bios-install command. The boot device must contain limine-bios.sys and limine.conf in one of the following directories: boot/limine, boot, limine, or the root directory.

    limine bios-install <path to device/image>

  12. Configure Limine via SMBIOS

    v12.x

    Limine can be configured using SMBIOS OEM String entries (Type 11). This method takes precedence over file-based configuration.

    To use this method, provide an SMBIOS entry where the first string starts with the prefix limine:config:. The remainder of that string is treated as the path to the configuration file.

    Behavioral differences when using SMBIOS:

    • If an SMBIOS configuration is found, Limine performs no further scanning for files.
    • On BIOS: The boot(): drive is undefined.
    • On UEFI: The boot(): drive is set to the boot device of Limine.