Booster - ArchWiki

Jump to content

# Booster

From ArchWiki

Related articles

- Kernel modules
- Minimal initramfs
- Boot debugging
- mkinitcpio
- dracut
- Clevis

Booster is a fast initramfs generator similar to mkinitcpio and dracut. Booster is inspired by the "distri" project and aims to create a small and fast init image.

Booster provides the `/usr/bin/booster` user-space tool, responsible for initramfs image generation. The generated images are located at `/boot/` by default.

## Install

Install booster. The package installation hook will generate initramfs images, one per installed kernel (e.g. for linux, linux-lts). The images are located under `/boot` directory:

    $ ls -lh /boot/booster*

    -rwxr-xr-x 1 root root 4.0M Dec 16 16:20 /boot/booster-linux.img

## Usage

When configuration is done to Booster, the initramfs images need to be regenerated for the changes to take affect. To do so, see the examples below.

Booster offers a convenience script that iterates over all installed kernels and generates an image for each of them:

    # /usr/lib/booster/regenerate_images

Alternatively, you can generate images manually by calling booster directly with the build argument:

    $ booster build mybooster.img

This will build an initramfs image in your current directory. Do note that it may require elevated privileges depending on where it is being run on the file system.

## Configuration

Booster's generator configuration file is located at `/etc/booster.yaml`. If there is no configuration file then the default configuration (host-specific images, no network) is used.

The configuration file helps to override the default behaviour. See booster(1) § CONFIG FILE for detailed information.

### Early module loading

You can load some modules at initramfs stage forcibly.

For example, if you need Kernel mode setting#Early KMS start to avoid graphical session run before NVIDIA GPU is initialized, use the following configuration setting:

    /etc/booster.yaml

    modules_force_load: nvidia,nvidia_modeset,nvidia_uvm,nvidia_drm

And then regenerate booster images.

### Encryption

Booster supports LUKS based full-disk encryption out-of-the-box like Clevis. The generator does not need any extra configuration. Yet, for the initramfs you need to append information about the LUKS partition where the root resides. This is done with either `rd.luks.uuid=LUKSUUID` or `rd.luks.name=LUKSUUID=LUKSNAME` kernel parameter that need to be specified in the boot loader configuration file. `LUKSUUID` specifies the UUID of the encrypted LUKS partition that needs to be unlocked by Booster. The booster(1) § UUID parameters manual recommends that the UUID does not contain any quotes. `LUKSNAME` specifies name of the unlocked partition (as in `/dev/mapper/LUKSNAME`). See booster(1) § BOOT TIME KERNEL PARAMETERS for related options.

No image rebuild is required. Once the boot loader configuration is done, reboot the computer. After that you will see a `Enter passphrase for YOURROOT:` prompt at boot time asking for a password for the encrypted root partition.

#### systemd style binding

Booster also supports partitions bound with systemd such as `systemd-fido2` and `systemd-tpm2`.

If you use `systemd-fido2` then please install libfido2 package and add fido2-assert to the image using following configuration:

    /etc/booster.yaml

    extra_files: fido2-assert

Regenerate the booster images. Booster will detect this configuration during boot and use the present YubiKey to unlock the drive.

Note Before commit 1b65577, it has been reported Booster may not load some necessary kernel modules early enough to unlock encrypted partitions with a FIDO2 key. In this case, add the following modules to be forcibly loaded:

    /etc/booster.yaml

    modules_force_load: usbhid,hid_sensor_hub
    extra_files: fido2-assert

### Removing modules

You can remove modules from initramfs via the `-` sign. An example to choose every modules manually and doing as same as Mkinitcpio/Minimal initramfs to improve boot performance is

    /etc/booster.yaml

    modules: -*,btrfs,nvme

### Stripping modules

You can reduce size of by initramfs by stripping modules.

    /etc/booster.yaml

    strip: true

Note The setting removes signatures of modules required by kernel lockdown.

### Compression

Booster supports compression of initramfs, by default using the `zstd` algorithm. Currently supported algorithms are `zstd`, `xz`, `gzip`, `lz4` or `none`.

    /etc/booster.yaml

    compression: zstd

## Boot loader configuration

Once the image is generated it is time to configure the boot loader.

### Microcode updates

Unlike mkinitcpio and dracut, Booster does not support including microcode updates into generated images; see Microcode#Microcode in a separate initramfs file for details on how to configure your boot loader to additionally load the appropriate microcode image.

### rEFInd

If the configuration relies on automatic detection already, no additional configuration change is necessary. rEFInd supports initramfs files named booster*.

If you specify the initramfs path manually, either in refind.conf or in manual boot stanzas, make sure to use the correct files names. I.e. `booster-linux.img` instead of `initramfs-linux.img`.

### systemd-boot

To enable the new initramfs image with systemd-boot simply create a new boot loader entry like this one:

    /boot/loader/entries/booster.conf

    title Arch Linux with booster
    linux /vmlinuz-linux
    initrd /intel-ucode.img
    initrd /booster-linux.img
    options root=UUID=08f83949-bcbb-47bb-bc17-089aaa59e17e rw

Where the root filesystem is referenced by `UUID=08f83949-bcbb-47bb-bc17-089aaa59e17e`. To find your root device UUID run `blkid /dev/ROOTDEVICE`.

## Troubleshooting

### Debug

If Booster has issues and does not work as expected, enable debug output that provides extra information about what is going on:

- for generator there is a `-debug` command line flag: `booster -debug`.
- for init there is a `booster.debug` kernel parameter.

If you believe it is an issue with Booster itself, then please file a ticket on GitHub.

### Booster generator fails with "too many open files" error

If you enabled `strip` and `universal` and see an error like `/usr/lib/modules/glue_helper.ko: pipe2: too many open files`, then you need to increase per-process limit for open files. See Limits.conf#nofile.

## See also

- upstream README

Categories:

- Initramfs
- Kernel

Booster
Add topic