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. Additionally experimental support for ext2 through ext4 is present, albeit with limited upstream support. The list of supported file systems is intentionally limited per Limine's design philosophy.
Installation
Installing the Limine boot loader
BIOS systems
Both MBR and GPT partitioned devices are supported, with a very similar installation procedure.
Deployment
Core bootloader files are in /usr/share/limine/
. Most important for installing to BIOS systems is the limine-bios.sys
file, which contains stage 3 code that Limine needs to boot. This file needs to reside on 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.
For example:
# cp /usr/share/limine/limine-bios.sys /boot/
Then stage 1 and 2 need to be deployed on disk. The installation is identical regardless of whether MBR or GPT is used, as it will auto-detect what scheme is used and install itself appropriately:
# limine bios-install /dev/sdX
where /dev/sdX
is the disk (not a partition) where Limine is to be installed. For example /dev/sda
or /dev/nvme0n1
. See Device file#Block device names for a description of the block device naming scheme.
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/BOOT/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: use efibootmgr to setup an entry for Limine.
UEFI+BIOS bootable drives
As long as a drive is GPT formatted, and it contains an EFI system partition, 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, just like limine-bios.sys
, 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. The configuration file has to be named limine.conf
.
boot():/
represents the partition on which limine.conf
is located. In case there is no separate /boot
partition, and limine.conf
resides on the root partition instead, then, in the following example, boot():/
should instead be boot():/boot/
.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 kernel_path: boot():/vmlinuz-linux kernel_cmdline: root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw module_path: boot():/initramfs-linux.img
where xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
is the root file system's UUID.
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
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_chainload image_path: boot():/EFI/Microsoft/Boot/bootmgfw.efi
Booting from another disk
Loading a UKI using the efi_chainload
protocol and specifying the path with uuid(partition UUID):
, refer to UKI#Limine.
pacman hook
While not mandatory, it may be useful to set up a pacman hook to deploy Limine whenever it is upgraded.
The following are just examples. Edit paths and devices to match the system's configuration.
BIOS
/etc/pacman.d/hooks/liminedeploy.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/"
UEFI
/etc/pacman.d/hooks/liminedeploy.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 /boot/EFI/BOOT/
Tips and Tricks
Boot entry automation
Dracut support
limine-dracut-supportAUR is designed for users who prefer Dracut for initramfs generation. It simplifies kernel management by automating the installation and removal of kernels in the Limine bootloader.
Edit /etc/limine-entry-tool.conf
- Set
KERNEL_CMDLINE
with your preferred kernel parameters.
KERNEL_CMDLINE
is not set, the tool will first attempt to read from the file /etc/kernel/cmdline
. If that file is also unavailable, it will fall back to reading from /proc/cmdline
.- To save ESP space, set
DRACUT_FALLBACK
tono
to disable the automatic generation of initramfs fallbacks.
After editing the configuration, run the following command with root permissions to generate an initramfs and update esp/limine.conf
.
# dracut-rebuild
Alternatively, you can use the alias of the command:
# limine-update
For more information, see the limine-entry-tool README and configuration options
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.
- Testing read-only snapshots: Use overlayfs to experiment with an immutable system and reproduce issues without modifying the original data in the system.
- 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.
Setup
1. Ensure your Snapper has a configuration name for your root subvolume.
2. 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 kernel_path: boot():/vmlinuz-linux kernel_cmdline: root=UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx rw rootflags=subvol=/@ module_path: boot():/initramfs-linux.img //Snapshots
Choose only one keyword:
//Snapshots
goes inside the OS boot entry block.
or
/Snapshots
goes 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.
If using custom flat Snapper layout, make sure to adjust the config file /etc/limine-snapper-sync.conf
:
- Specify
ROOT_SUBVOLUME_PATH
for the path to your root subvolume. - Specify
ROOT_SNAPSHOTS_PATH
for the path to your root snapshots.
3. Then, enable the systemd service limine-snapper-watcher.service
, which automatically generates snapshot entries in your boot menu whenever your Snapper list changes.
To receive a desktop notifications for one-click restoration in an X11 or Wayland environment after booting from a snapshot, install dunst.
For dracut users:
1. Install limine-dracut-supportAUR to automate the creation of boot entries in limine.conf
on the ESP. See Dracut support for more details.
2. Modify esp/limine.conf
to include either the //Snapshots
or /Snapshots
keyword for auto-generated snapshot entries.
For further details, refer to the limine-snapper-sync README and configuration options.
Commands
limine-snapper-sync
synchronizes Limine snapshot entries with the Snapper list.limine-snapper-list
displays the current Limine snapshot entries.limine-snapper-info
provides detailed information about versions, the total number of bootable snapshots, and verifies bootable files.limine-snapper-restore
restores 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.