booster-um

Booster UKI Manager - A simple bash script to manage UKI (Unified Kernel Image) files generated by booster and systemd-ukify. The script can only be used on Arch Linux.

Table of Contents

• Dependencies
• Installation
• Default configuration
• Config file
• First run
• Usage (help output)

Dependencies

• Required:
  • booster - Generate initramfs
  • go-yq - Parse booster and booster-um configs
  • systemd-ukify - Generate UKI files
  • util-linux - Miscellaneous system utilities for Linux
• Optional:
  • sbctl - Sign UKI files
  • sbsigntools - Sign UKI files with sbsign
  • efibootmgr - Manage EFI entries

Installation

If you are using an Arch-based distribution, install booster-um or booster-um-git package from the AUR. After that you are free to remove mkinitcpio.

Default configuration

• booster-um by default:

  • Signs generated UKI files with sbctl if installed
  • Uses default splash /usr/share/systemd/bootctl/splash-arch.bmp
  • Detects the XBOOTLDR partition if it exists and is mounted on /boot
  • Uses default configuration if the /etc/booster-um.yaml config is not valid
  • Generates UKI in esp/EFI/Linux dir. If this directory does not exist, it will be created
  • Removes vmlinuz-* and booster-* leftovers from /boot dir (microcode image will not be deleted)
  • Will only create fallback images if universal flag is enabled in /etc/booster.yaml config
  • Will not generate EFI entries or fallback UKI files.
  • Will not regenerate initramfs files on kernel and extramodule installations/upgrades (they are already generated by booster hook)
  • Removes known EFI entries (Example: \EFI\LINUX\ARCH-LINUX.EFI) if efibootmgr is installed. To prevent this, enable efistub in config

• booster-um libalpm hooks by default:

  • Remove EFI entries on kernel removal
  • Remove UKI files from the ESP and the sbctl database on kernel removal
  • Regenerate UKI files for all installed kernels when booster, microcode, dkms or firmware files are installed, updated, or removed
  • Will always sign UKI files on kernel upgrades
  • Will not sign generated UKI files on microcode, extramodules (nvidia, nvidia-lts etc.) and kernel updates, sbctl hook will do that
  • Will always sign newly created UKI files if they do not exists in the sbctl database. You don't need to manually sign or add UKI files in the sbctl database

• Default booster-um -G output and /boot|/esp/EFI/LINUX content:

  • Generation of UKI files

    

  • /boot and /esp/EFI/LINUX content

    

Config file

For information about configuration, read this documentation.

First run

• Define the cmdline in /etc/booster-um.yaml config file or create and edit the /etc/kernel/cmdline file. Take care to remove entries pointing to microcode, vmlinuz and initramfs. Here is a simple cmdline example (Change the root= parameter to reflect your Linux root partitions):

  root=UUID=0a3407de-014b-458b-b5c1-848e92a327a3 rw quiet splash

• Edit the /etc/booster-um.yaml config if needed (the default configuration will be used if the config file is empty):
  • If you intend to use EFISTUB boot, add the efistub: true to the config. If you want to set kernel to always boot into by default, specify the kernel package name in default_entry
  • If you don't have secureboot keys and sbctl is installed, generate them with sbctl before generating the UKI files. booster-um will by default sign the UKI files with sbctl tool if it is installed. If you don't want that, set the sign_uki: false to the config.
  • If you want to use the manually generated keys, use the sbsign tools instead of the sbctl. Install the sbsigntools and set the sbsign: true to the config. The sign_uki must not be disabled and you will need to provide the appropriate key paths within the sbsign_config node (usually secureboot_private_key and secureboot_certificate fields need to be configured)
  • For more information on creating secureboot keys, see the UEFI/Secure Boot article
• Optionally you can delete the initramfs files of other generators, as well as the entire esp/EFI/Linux directory, simply by running booster-um -C
• Regenerate all images with booster-um -G
• If you have enabled the creation of EFI entries, you may need to change the boot order after generating the UKI files. You can change it like this (put your boot numbers here): efibootmgr -o 3,1,0
• systemd-boot will, if installed, detect UKI files generated by booster-um. For more information about booting, see the Unified kernel image - Booting article

Usage (help output)

Usage: booster-um [OPTIONS] <package>

Manage UKI files generated by booster and systemd-ukify.

Options:
    -h, --help    Show this help message
    -v, --version Print version

Generate options:
    -g <package>  Generate UKI file for specified kernel package name
    -G            Generate UKI files for all installed kernels

Remove options:
    -o            Remove orphaned EFI entries
    -r <package>  Remove UKI file for specified kernel package name
    -C            Remove initramfs*, booster*, vmlinuz* files, entire esp/EFI/Linux dir and other leftovers
    -R            Remove known booster*, vmlinuz*, UKI files and other leftovers for all installed kernels

Examples: booster-um -g linux
          booster-um -g linux linux-lts
          booster-um -r linux-zen linux-lts
          booster-um -G
          booster-um -R
          booster-um -C