Limine

From Gentoo Wiki
Jump to:navigation Jump to:search
Resources

Limine is a modern, advanced, portable, multiprotocol bootloader and boot manager which also provides the reference implementation of the Limine boot protocol.

This guide is designed to be followed alongside the installation Handbook and the ZFS root guide if so desired, though the config file examples are of course universal to all.

Installation

Enabling the Repository

Limine is within the ::guru repository, and is also masked for testing. To install Limine, the ::guru repository needs to be enabled, as well as unmasking the package.

To begin, emerge app-eselect/eselect-repository alongside dev-vcs/git if the latter is not already installed:

root #emerge --ask --verbose dev-vcs/git app-eselect/eselect-repository


Once emerge is finished installing the above packages and their dependencies, ::guru can be enabled through eselect:

root #eselect repository enable guru


After enabling the ::guru repository, syncing the repositories is needed in order to view the new packages that can now be installed from ::guru with the following command:

root #emerge --sync

And for slower systems, you can reduce the output with:

root #emerge --sync --quiet


Unmasking the Package

Warning
Packages that are masked for testing are masked for a reason! Ensure that you know where and how to report potential bugs and problems if and when they occur!

Unmasking the package is a relatively simple process, to do so, the allowed keywords variable needs to be edited, in which the following needs to be appended utilising a preferred editor:

FILE /etc/portage/package.accept_keywords/limineUnmasking Limine for install
sys-boot/limine ~amd64


Optional: USE flags

If an extra step is wanted to be taken to build exclusively the bootloader files for the target architecture, it may be done so by specifying USE flags, assuming the target is an AMD64 UEFI system, the required USE flags would be:

FILE /etc/portage/package.use/limineSpecifying USE flags to exclusively build UEFI AMD64 files
sys-boot/limine -* uefi64

The other USE flags may be viewed with the following command:

user $emerge --pretend --verbose sys-boot/limine


Emerging the Package

Once all the above steps are completed, Limine can be installed to the target:

root #emerge --ask --verbose sys-boot/limine


Setting up the Bootloader

Now that Limine is installed on the target system, configuring the bootloader can begin.

To configure the bootloader, differing files will be utilised depending on target architecture and whether the target is using BIOS or UEFI.

Copying the Bootloader Files

In order for Limine to boot, Limine requires there to be a mounted vfat partition as /boot, which will be your ESP on UEFI systems, and simply a normal extra partition formatted as vfat on BIOS systems.

The bootloader files are stored in /usr/share/limine and are named after their respective architectures, excluding the BIOS file, which is universal for both x86 and amd64 BIOS systems.

It is a good idea initially to check if /boot is mounted, this can be done by simply running the lsblk command:

user $lsblk
NAME        MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
zram0       252:0    0     2G  0 disk [SWAP]
zram1       252:1    0     2G  0 disk /tmp
nvme0n1     259:0    0 238.5G  0 disk
├─nvme0n1p1 259:1    0   400M  0 part /boot
└─nvme0n1p2 259:2    0 238.1G  0 part /

After confirming /boot is mounted, the architecture files can be copied across.


For UEFI

For UEFI, there is no need for sys-boot/efibootmgr 99% of the time, using the default directory structure will get picked up by the firmware.

root #mkdir -p /boot/EFI/BOOT/

After creating this directory, the respective .EFI firmware file can be copied across, assuming the target is an AMD64 UEFI system, the correct command would be:

root #cp -v /usr/share/limine/BOOTX64.EFI /boot/EFI/BOOT/

If the target is not AMD64 EFI, and rather RISCV, AARCH64 or x86, their respective files can be located by listing the contents of /usr/share/limine:

user $ls /usr/share/limine
Important
If USE flags were specified as demonstrated in section 1.3, the other files will not exist! If in doubt, always use default USE flags.

For BIOS

For BIOS systems, the bootloader file can be copied to the root of the vfat /boot partition:

root #cp -v /usr/share/limine/limine-bios.sys /boot

Now the BIOS file is in place, Limine can be installed to the MBR of the drive, so that BIOS firmware can pick up and boot Limine on the next boot:

root #limine bios-install /dev/sdX
Physical block size of 512 bytes.
Installing to MBR.
Stage 2 to be located at 0x200 and 0x2600.
Reminder: Remember to copy the limine-bios.sys file in either
          the root, /boot, /limine, or /boot/limine directories of
          one of the partitions on the device, or boot will fail!
Limine BIOS stages installed successfully!
Important
Don't forget to replace sdX with the drive you're installing to! NVMe, SATA and eMMC devices are all supported by this command, as long as they have a DOS partition table.

If all went well, this is the output you'll be greeted with, and you can move onto configuring what Limine will see.


Writing the Config File

Limine's configuration file to find kernels, initramfs' and microcode is entirely manually written. There's a lot of customisation that can be done within the config file, but for simplicity's sake, only the basics will be covered here. Limine's config file needs to be called limine.cfg, and can be /boot/limine.cfg, /boot/limine/limine.cfg or /boot/EFI/BOOT/limine.cfg. For a more detailed explanation of Limine's config, Limine's official CONFIG.md file can be viewed.

The config has a pretty simple syntax to follow, with boot:/// being the root of the partition all the boot files are inside of. The CMDLINE variable is a standard command line to be parsed to the kernel when it loads, this is required, so the kernel knows what to mount as the root, and can also be used to pre-load modules that might be needed very early on.

Generic Config Example

The following config example will likely fit most users, it assumes the target system is running the sys-kernel/gentoo-kernel or sys-kernel/gentoo-kernel-bin distribution kernel, and are on BTRFS, but can be easily edited to specific needs.

FILE /boot/limine.cfgGeneric Config Example
# Designates 5 seconds until Limine will auto-boot the first entry if nothing is chosen.
TIMEOUT=5

:Gentoo Example
        PROTOCOL=linux
        KERNEL_PATH=boot:///vmlinuz-6.6.30-gentoo-dist
        # Replace with amd-uc.img if the target has an AMD CPU.
        MODULE_PATH=boot:///intel-uc.img
        MODULE_PATH=boot:///initramfs-6.6.30-gentoo-dist.img
        # replace $UUID with the UUID blkid echoes for the root partition.
        CMDLINE=root=UUID=$UUID rw rootfstype=btrfs


Using Limine With ZFS Root

If ZFS/rootfs is being followed, Limine can also be utilised by editing the config slightly, as showcased:

FILE /boot/limine.cfgZFS Config Example
# Designates 5 seconds until Limine will auto-boot the first entry if nothing is chosen.
TIMEOUT=5

:Gentoo Example
        PROTOCOL=linux
        KERNEL_PATH=boot:///vmlinuz-6.6.30-gentoo-dist
        # Replace with amd-uc.img if the target has an AMD CPU.
        MODULE_PATH=boot:///intel-uc.img
        MODULE_PATH=boot:///initramfs-6.6.30-gentoo-dist.img
        CMDLINE=root=ZFS=/tank/os/gentoo rw rootfstype=zfs

In this config, the root filesystem variable has been changed to tell the kernel to look for a ZFS root partition, and the modules variable tells the kernel to preload the ZFS module, so there is not any issues with the rootfs support not being built into the kernel, as ZFS has to be sideloaded with the sys-fs/zfs-kmod package.


Dual-booting with Windows in Limine (UEFI)

Unlike sys-boot/grub, Limine does not require sys-boot/os-prober to find other operating systems, Limine can find other EFI files, and has the ability to chainload them when manually pointed to the other EFI file.

FILE /boot/limine.cfgGeneric Config Example
# Designates 5 seconds until Limine will auto-boot the first entry if nothing is chosen.
TIMEOUT=5

:Linux
::Gentoo Example
        PROTOCOL=linux
        KERNEL_PATH=boot:///vmlinuz-6.6.30-gentoo-dist
        # replace with amd-uc.img if the target has an AMD CPU
        MODULE_PATH=boot:///intel-uc.img 
        MODULE_PATH=boot:///initramfs-6.6.30-gentoo-dist.img
        # replace $UUID with the UUID blkid echoes for the root partition.
        CMDLINE=root=UUID=$UUID rw rootfstype=btrfs 

:Windows
:: Windows Example
        PROTOCOL=efi_chainload
        # This tells the chainload protocol to call the specified EFI file and load it.
        MODULE_PATH=boot:///EFI/Microsoft/bootmgfw.efi

This example shows off entries and sub-entries, where as one colon deeper identifies another sub-entry below the last. The efi_chainload protocol calls the EFI file to boot windows in UEFI mode, as would the "Windows Boot Manager" entry in the targets UEFI firmware. It may be needed to double-check the location of the Windows' EFI file to make sure Limine is pointing to the right location.

Finalising

Now, Limine is entirely setup and ready to boot to. Extra eye-candy can be found and applied by revising the official configuration file documentation. Any issues can be reported on the official GitHub, and the official Limine discord, both of which can be found on their website linked at the top of the page.