Limine
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 --syncAnd for slower systems, you can reduce the output with:
root #emerge --sync --quiet
Unmasking the Package
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:
/etc/portage/package.accept_keywords/limineUnmasking Limine for installsys-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:
/etc/portage/package.use/limineSpecifying USE flags to exclusively build UEFI AMD64 filessys-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.
With Limine ver 8.x, there is experimental support for ext2/3/4 - this can be useful for those on MBR systems who do not want to use vfat, however issues may occur with the nature of brand new and experimental features. Use at your own risk!
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 $lsblkNAME 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/limineIf 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 /boot partition:
root #cp -v /usr/share/limine/limine-bios.sys /bootNow 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/sdXPhysical 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!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.conf, and can be /boot/limine.conf, /boot/limine/limine.conf or /boot/EFI/BOOT/limine.conf. 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
Since Limine 8.x was released, the config syntax has been revamped with the new syntax being in limine.conf instead of the old limine.cfg. Whilst the old syntax will still be parsed with the .cfg extension and is stated to be supported at least for 8.x's lifecycle, it is highly recommended to update the config if the target system is upgrading from an old Limine version.
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.
/boot/limine.confGeneric Config Exampletimeout: 5
comment: Designates 5 seconds until Limine will auto-boot the first entry if nothing is chosen.
/Gentoo Example
protocol: linux
kernel_path: boot():/vmlinuz-6.6.30-gentoo-dist
module_path: boot():/intel-uc.img
` comment: Replace with amd-uc.img if the target has an AMD CPU.
module_path: boot():/initramfs-6.6.30-gentoo-dist.img
cmdline: root=UUID=$UUID rw rootfstype=btrfs
# replace $UUID with the UUID blkid echoes for the root partition.
Using Limine With ZFS Root
Since Limine 8.x was released, the config syntax has been revamped with the new syntax being in limine.conf instead of the old limine.cfg. Whilst the old syntax will still be parsed with the .cfg extension and is stated to be supported at least for 8.x's lifecycle, it is highly recommended to update the config if the target system is upgrading from an old Limine version.
If ZFS/rootfs is being followed, Limine can also be utilised by editing the config slightly, as showcased:
/boot/limine.confZFS Config Exampletimeout: 5
comment: Designates 5 seconds until Limine will automatically boot the first selected entry if nothing is pressed.
/Gentoo Example
protocol: linux
kernel_path: boot():/vmlinuz-6.6.30-gentoo-dist
module_path: boot():/intel-uc.img
comment: Replace with amd-uc.img if the target has an AMD CPU.
module_path: boot():/initramfs-6.6.30-gentoo-dist.img
cmdline: root=ZFS=/tank/os/gentoo rw modules=zfs 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 argument 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 modules have to be side-loaded with the sys-fs/zfs-kmod package.
Dual-booting with Windows in Limine (UEFI)
Since Limine 8.x was released, the config syntax has been revamped with the new syntax being in limine.conf instead of the old limine.cfg. Whilst the old syntax will still be parsed with the .cfg extension and is stated to be supported at least for 8.x's lifecycle, it is highly recommended to update the config if the target system is upgrading from an old Limine version.
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.
/boot/limine.confDual-Boot Config Exampletimeout: 5
comment: Designates 5 seconds until Limine will automatically boot the first entry if nothing is pressed
/Linux
//Gentoo Example
protocol: linux
kernel_path: boot():/vmlinuz-6.6.30-gentoo-dist
module_path: boot():/intel-uc.img
comment: replace with amd-uc.img if the target has an AMD CPU
module_path: boot():/initramfs-6.6.30-gentoo-dist.img
cmdline: root=UUID=$UUID rw rootfstype=btrfs
comment: Replace $UUID with the UUID blkid echoes for the root partition.
/Windows
//Windows Example
protocol: efi_chainload
module_path: boot():/EFI/Microsoft/bootmgfw.efi
comment: This tells the chainload protocol to call the specified EFI file and load it.
ies another sub-entry deeper than the last. The efi_chainload protocol calls the EFI file to boot windows in UEFI mode, as woul
This example shows off entries and sub-entries, where as one slash extra identifd 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.