Limine
Limine is an advanced, portable, multiprotocol boot loader originally developed as the reference implementation for the Limine boot protocol, but also supporting the ability to boot Linux as well as to chainload other boot loaders.
esp denotes the mountpoint of the EFI system partition aka ESP.Supported file systems
Limine supports FAT12, FAT16, FAT32 and ISO9660. The list of supported file systems is intentionally limited per Limine's design philosophy.
Installation
Install the limine package. This will install the limine command line tool, and it will also install all the Limine files, needed for setting up a bootable system for various architectures, in /usr/share/limine. Note that that directory is just going to serve as a repository of Limine files, but the bootloader has not been deployed for use just yet.
Deploying the boot loader
UEFI systems
Deploying Limine on UEFI systems involves copying the /usr/share/limine/BOOTX64.EFI file to an EFI system partition, usually to esp/EFI/limine/BOOTX64.EFI, but it can be given other filenames, as long as the UEFI BIOS is aware of them. Unlike GRUB, Limine does not add an entry for the bootloader in the NVRAM automatically. Use efibootmgr to setup an entry for Limine.
To do so, one can do the following:
# efibootmgr \
--create \
--disk /dev/sdX \
--part Y \
--label "Arch Linux Limine Bootloader" \
--loader '\EFI\limine\BOOTX64.EFI' \
--unicode \
--verbose
-
/dev/sdXis the disk (not a partition) where the ESP is located on. For example/dev/sdaor/dev/nvme0n1. See Device file#Block device names for a description of the block device naming scheme. -
Yis the partition index of the ESP, so if the ESP is/dev/sda1, thenYshould be1.
Once all this is done, one can move on to #Configuration directly.
BIOS systems
Deploying Limine on BIOS systems involves copying the /usr/share/limine/limine-bios.sys file, which contains stage 3 code that Limine needs to boot, to either the root, a /boot, a /limine, or a /boot/limine directory of any partition on the disk onto which Limine will be deployed, as long as the filesystem is supported. This usually means having to use a FAT partition for /boot, and copying the limine-bios.sys file to /boot/limine.
For example:
# mkdir -p /boot/limine # cp /usr/share/limine/limine-bios.sys /boot/limine/
Then stage 1 and 2 need to be deployed to the disk:
# limine bios-install /dev/sdX
-
/dev/sdXis the disk (not a partition) where Limine is to be installed. For example/dev/sdaor/dev/nvme0n1. This has to be the disk hosting the/bootpartition. See Device file#Block device names for a description of the block device naming scheme.
UEFI + BIOS bootable drives
As long as a drive is MBR formatted, and it contains an EFI system partition (which can be the same as the /boot partition used for BIOS systems), it is possible to follow both the BIOS and UEFI deployment procedures in order to create a drive capable of booting on both legacy BIOS as well as UEFI systems. This is useful, for example, for installing an operating system on a USB flash drive which is to be used on multiple systems which may or may not support UEFI, or to ease moving hard drives across systems.
Configuration
limine does not ship a default configuration file, it is therefore necessary to create one. This file is necessary to teach Limine which operating systems are available for boot. The configuration file has a lot of options as Limine allows for a fair degree of customisation. A detailed documentation of the configuration file, its format, and its options can be found here.
The configuration file needs to reside on either the root, a /boot, a /limine, or a /boot/limine directory of a partition on the drive on which Limine is deployed, as long as the file system of said partition is supported. For UEFI systems, it may also reside on esp/EFI/BOOT or on esp/EFI/limine (the recommended location). The configuration file has to be named limine.conf.
boot():/ represents the partition on which limine.conf is located.Here follows a simple example configuration that contains 1 boot menu entry that describes a typical Arch Linux kernel and initramfs:
limine.conf
timeout: 5
/Arch Linux
protocol: linux
path: boot():/vmlinuz-linux
cmdline: root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw
module_path: boot():/initramfs-linux.img
-
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxis the root file system's UUID.
In case the /boot partition, where the kernel and initramfs are, and the partition of the limine.conf file do not match (such as, for example, on UEFI systems with an extra /boot partition which is not the same as the ESP, and limine.conf is placed on the ESP), it may be necessary to replace boot():/ in the configuration file with uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):/, where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx represents the PARTUUID of the /boot FAT partition.
To prevent this you should first embed the b2sum checksum of every resource file in the configuration. Limine file paths have an optional field containing the b2sum checksum of the file. This field can be specified by appending the # character and then the 128 characters checksum:
boot():/path#checksumTo protect the config file you should embed its
b2sum in the EFI executable with limine enroll-config command.Windows entry (UEFI)
In order to be able to boot windows we need to know the path of bootmgfw.efi in the ESP. This can be done by going inside the ESP and using the following command:
$ find -name "bootmgfw.efi"
./EFI/Microsoft/Boot/bootmgfw.efi
All we need to do now is adding the following to the configuration:
limine.conf
/Windows
protocol: efi
path: boot():/EFI/Microsoft/Boot/bootmgfw.efi
Alternatively replacing boot():/ with uuid(xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx):/, where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is the PARTUUID of the ESP, if limine.conf is not on the ESP.
pacman hook
While not mandatory, it may be useful to set up a pacman hook to deploy Limine whenever it is upgraded.
UEFI
/etc/pacman.d/hooks/99-limine.hook
[Trigger] Operation = Install Operation = Upgrade Type = Package Target = limine [Action] Description = Deploying Limine after upgrade... When = PostTransaction Exec = /usr/bin/cp /usr/share/limine/BOOTX64.EFI esp/EFI/limine/
BIOS
/etc/pacman.d/hooks/99-limine.hook
[Trigger] Operation = Install Operation = Upgrade Type = Package Target = limine [Action] Description = Deploying Limine after upgrade... When = PostTransaction Exec = /bin/sh -c "/usr/bin/limine bios-install /dev/sdX && /usr/bin/cp /usr/share/limine/limine-bios.sys /boot/limine/"
-
/dev/sdXis the disk (not a partition) where Limine was installed to in the previous steps.
Tips and tricks
Boot entry automation
Dracut support
limine-dracut-supportAUR is designed for users who prefer Dracut for generating initramfs or UKI. It simplifies kernel management by automating the addition and removal of kernels in the Limine bootloader.
When updating or reinstalling Limine, its EFI's image is automatically deployed to the ESP on UEFI system with x86_64 architecture.
This tool requires jdk17-openjdk or newer.
Check your Java version with
$ archlinux-java status
If your system is using an older version, install a newer one and set it as the default by running:
# archlinux-java set <java-17-openjdk or newer>
Configurations:
Instead of editing /etc/limine-entry-tool.conf, modify /etc/default/limine, which takes precedence over /etc/limine-entry-tool.conf.
1. Edit /etc/default/limine
- Set
ESP_PATHto your ESP path. (or, ifbootctl --print-esp-pathautomatically detects the ESP, you do not need to configureESP_PATH). - Set
KERNEL_CMDLINE[default]=with your preferred kernel parameters.
- If
KERNEL_CMDLINE[default]=orKERNEL_CMDLINE=is not set, the tool will first try to read from the file/etc/kernel/cmdline. If unavailable, it will fall back to reading from/proc/cmdline. - Optionally,
KERNEL_CMDLINE[fallback]=applies to kernel entries containing the name fallback. - Additionally,
KERNEL_CMDLINE["kernel name"]=corresponds to kernel entry name in the boot menu, allowing unique kernel cmdline/parameters per kernel entry. For example,KERNEL_CMDLINE["linux-lts"]=for linux-lts kernel entry.
- To save ESP space, set
DRACUT_FALLBACKtonoto disable automatic fallback generation for initramfs or UKI. - If you prefer to boot with UKI, set
DRACUT_UKItoyes.
- systemd-boot or rEFInd can automatically load UKIs generated by the tool.
- If sbctl is installed and enabled, the tool can automatically sign the UKI with your Secure Boot key when updating or installing kernel.
FIND_BOOTLOADERS to yes to detect and add systemd-boot, rEFInd, or the default EFI loader to Limine if they are present in the same ESP.2. Run the following command to generate an initramfs or UKI and update esp/limine.conf.
# limine-update
For more configuration options, refer to the configuration of limine-entry-tool
mkinitcpio or another initramfs tool
limine-entry-toolAUR does not include an initramfs tool and pacman hooks for automating the addition and removal of kernels.
1. Edit /etc/default/limine to override any settings in /etc/limine-entry-tool.conf
- Set
ESP_PATHto your ESP path. (or, ifbootctl --print-esp-pathautomatically detects the ESP, configuringESP_PATHis not required). - Set
KERNEL_CMDLINE[default]=with your preferred kernel parameters.
- If
KERNEL_CMDLINE[default]=orKERNEL_CMDLINE=is not set, the tool will first attempt to read from the file/etc/kernel/cmdline. If unavailable, it will fall back to reading from/proc/cmdline. - Optionally,
KERNEL_CMDLINE["kernel name"]=corresponds to kernel entry name in the boot menu, allowing unique kernel cmdline/parameters per kernel entry.
2. Install an initramfs tool of your choice (e.g., mkinitcpio, dracut, booster, or another preferred tool).
3. Write a script, such as pacman hooks to automate kernel addition and removal using the limine-entry-tool command with desired options for managing boot entries in Limine boot menu.
For further details, refer to limine-entry-tool README.
Snapper snapshot integration for Btrfs
limine-snapper-syncAUR tool provides integration between Snapper and the Limine bootloader. It is useful for:
- Supports booting into selected Snapper snapshot.
- Offers two different methods for restoring a system snapshot: rsync or btrfs.
- After restoring a snapshot, a "backup" entry is added to the Limine bootloader, providing an easy way to revert to the "backup" if needed.
- Automatically repairs corrupted bootable files from old snapshots on the ESP when a new snapshot with the same bootable files is created.
- Automatically logs error messages about potential hardware issues if two hashes of the same bootable file do not match on the ESP.
- Testing read-only snapshots: Use overlayfs to test any installed packages on an immutable-like system without modifying the original data. Note that this does not mean testing the boot partition or a separate home subvolume/partition.
The OverlayFS functionality is available through limine-dracut-supportAUR for dracut.
For mkinitcpio, use the grub-btrfs-overlayfs hook, which is provided by grub-btrfs. Avoid using the systemd hook, as it is incompatible with grub-btrfs-overlayfs.
Configurations
It is recommended to have an ESP size of more than 2 GiB, depending on how many bootable snapshots and different kernel versions you wish to install.
This tool requires jdk17-openjdk or newer.
Check your Java version with
$ archlinux-java status
If your system is using an older version, install a newer one and set it as the default by running:
# archlinux-java set <java-17-openjdk or newer>
1. Configure esp/limine.conf to include either the //Snapshots or /Snapshots keyword for auto-generated snapshot entries.
An example:
limine.conf
/+Arch Linux
comment: Any comment
comment: machine-id=yyyyyyyyyyyyyyyyyy
//Linux
protocol: linux
path: boot():/vmlinuz-linux
cmdline: root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw rootflags=subvol=/@
module_path: boot():/initramfs-linux.img
//Snapshots
Choose only one keyword:
-
//Snapshotsgoes inside the OS boot entry block. (default, if not set)
or
-
/Snapshotsgoes outside the block.
Including the machine-ID from /etc/machine-id is optional but helpful for automatic identification. Renaming the boot entry will not affect the tool.
Bootable files must be placed in the same ESP as limine.conf, as only the boot(): function is supported.
2. Edit /etc/default/limine, which will override /etc/limine-snapper-sync.conf:
- Set
ESP_PATHto your ESP path (or, ifbootctl --print-esp-pathautomatically detects the ESP, configuringESP_PATHis not required). - Set
MAX_SNAPSHOT_ENTRIESto limit the number of snapshot entries. The default is 8. - Set
LIMIT_USAGE_PERCENTto stop creating new snapshot entries when the limit of ESP usage is exceeded. The default is 80.
- If using custom Snapper layout, make sure to configure the following:
- Specify
ROOT_SUBVOLUME_PATHfor the path to your root subvolume. The default is/@in most cases. - Specify
ROOT_SNAPSHOTS_PATHfor the path to your root snapshots. The default is/@/.snapshots, which is the standard Snapper layout for the root subvolume/@.
- Specify
3. Run the command to check if it succeeds or shows an error message:
# limine-snapper-sync
limine-snapper-sync shows an error that command limine-reset-enroll and limine-enroll-config not found, these commands are provided by limine-dracut-supportAUR or limine-entry-tool-gitAUR, which is not installed.
This error can be safely ignored if you do not use them. Alternatively, to prevent this error, edit /etc/limine-snapper-sync.conf to remove COMMANDS_BEFORE_SAVE="limine-reset-enroll" and COMMANDS_AFTER_SAVE="limine-enroll-config"
4. If everything works, then enable limine-snapper-sync.service to automatically synchronize boot entries with the Snapper snapshot list.
# systemctl enable --now limine-snapper-sync.service
5. Optionally, install snap-pac. It triggers Snapper to create snapshots during system updates, which limine-snapper-sync then synchronizes to generate related snapshot entries in Limine.
Install limine-dracut-supportAUR to automatically manage boot entries in limine.conf on the ESP when installing, updating, or uninstalling kernels. See Dracut support for more details.
For further details, refer to the limine-snapper-sync README and more configuration options.
Commands
-
limine-snapper-syncsynchronizes Limine snapshot entries with the Snapper list. -
limine-snapper-listdisplays the current Limine snapshot entries. -
limine-snapper-infoprovides detailed information about versions, the total number of bootable snapshots, and verifies bootable files. -
limine-snapper-restorerestores your system, including matching kernel versions, from a selected bootable snapshot.
Known limitations
- Supports only any Snapper layouts, not arbitrary Btrfs layouts without Snapper.
- Cannot generate bootable snapshot entries for old snapshots created before the tool was installed, as these snapshots typically no longer have their corresponding kernel versions.