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 reduce the output with:

root #emerge --sync --quiet

Unmasking the Package

Warning
Packages that are masked for testing are masked for a reason! Please report all bugs to https://bugs.gentoo.org

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

It is possible to configure sys-boot/limine for only the target system#s method, 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.

Note
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 $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 /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.

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

Warning
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.

FILE /boot/limine.confGeneric Config Example
timeout: 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

Warning
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:

FILE /boot/limine.confZFS Config Example
timeout: 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)

Warning
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.

FILE /boot/limine.confDual-Boot Config Example
timeout: 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.

Retrieved from "https://wiki.gentoo.org/index.php?title=Limine&oldid=1314650"