Limine - ArchWiki

Jump to content

# Limine

1 language

- 日本語

From ArchWiki

Related articles

- Arch boot process
- Master Boot Record
- GUID Partition Table
- Unified Extensible Firmware Interface

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.

Note: In the entire article `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.

## 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`.

Note: In a Limine config, `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
        path: boot():/vmlinuz-linux
        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.

Tip: If you're booting from an UEFI system with Secure Boot activated then consider securing both Limine config file and resources files like kernels and modules. Indeed everyone that can access the FAT partition that stores the configuration file and the needed resources can alter these file even with SecureBoot.

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#checksum

To 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
        path: boot():/EFI/Microsoft/Boot/bootmgfw.efi

### Booting from another disk

Loading a UKI using the `efi` 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

Note: Keep in mind that the device paths may change with the addition or removal of devices, moving the installation to different machines, and other factors. This may cause the BIOS hook to accidentally install Limine on an unwanted device.

    /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 generating initramfs or UKI. It simplifies kernel management by automating the addition and removal of kernels in the Limine bootloader.

Note: When updating or reinstalling Limine, its EFI's image is automatically deployed to the ESP on UEFI system with x86_64 architecture.

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_PATH` to your ESP path. (or, if `bootctl` automatically detects the ESP, you do not need to configure `ESP_PATH`).
- Set `KERNEL_CMDLINE[default]=` with your preferred kernel parameters.

Tip:

- If `KERNEL_CMDLINE[default]=` or `KERNEL_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"]=` entries correspond 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_FALLBACK` to `no` to disable automatic fallback generation for initramfs or UKI.
- If you prefer to boot with UKI, set `DRACUT_UKI` to `yes`.

Tip: Advantages of UKI:

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

- Set `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-tool-gitAUR 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_PATH` to your ESP path. (or, if `bootctl` automatically detects the ESP, configuring `ESP_PATH` is not required).
- Set `KERNEL_CMDLINE[default]=` with your preferred kernel parameters.

Tip:

- If `KERNEL_CMDLINE[default]=` or `KERNEL_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"]=` entries correspond to kernel entry names 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.

#### Configurations

Note: It is recommended to have an ESP size of more than 1 GiB, depending on how many bootable snapshots and different kernel versions you wish to install.

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

Note:

Choose only one keyword:

- `//Snapshots` goes inside the OS boot entry block. (default, if not set)

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.

2. Edit `/etc/default/limine`, which will override `/etc/limine-snapper-sync.conf`:

- Set `ESP_PATH` to your ESP path (or, if `bootctl` automatically detects the ESP, configuring `ESP_PATH` is not required).
- Set `MAX_SNAPSHOT_ENTRIES` to limit the number of snapshot entries. The default is 8.
- Set `LIMIT_USAGE_PERCENT` to 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_PATH` for the path to your root subvolume. The default is `/@` in most cases.
  - Specify `ROOT_SNAPSHOTS_PATH` for the path to your root snapshots. The default is `/@/.snapshots`, which is the standard Snapper layout for the root subvolume `/@`.

3. Run the command to check if it succeeds or shows an error message:

    # limine-snapper-sync

4. If it works, then enable the systemd service `limine-snapper-watcher.service`, which automatically generates snapshot entries in your boot menu whenever your Snapper list changes.

Tip: for dracut users:

Install limine-dracut-supportAUR to automate the creation of boot entries in `limine.conf` on the ESP. See Dracut support for more details.

For further details, refer to the limine-snapper-sync README and more 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.

## See also

- Limine's website
- Limine's GitHub repository

Category:

- Boot loaders