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.

Dependencies:

• Required:
  • booster - Generate initramfs
  • go-yq - Parse booster and booster-um configs
  • system-ukify - Generate UKI files
  • util-linux - Miscellaneous system utilities for Linux
• Optional:
  • sbctl - Sign UKI files
  • sbsigntools - Sign UKI files with sbsign
  • efibootmgr - Create 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
  • Creates the empty /etc/kernel/cmdline if it does not exist.
  • Uses the /proc/cmdline if the cmdline files (/etc/kernel/cmdline or per kernel cmdline files) are empty or have only white spaces.
  • 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 not create separate fallback images if universal flag is enabled in /etc/booster.yaml config
  • Will not generate EFI entries or fallback UKI files. EFI entries and fallback UKI files are treated as leftovers.
  • 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 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

booster-um config file is located at /etc/booster-um.yaml. It is empty by default, here is an example configuration:

sign_uki: true
remove_leftovers: true
cmdline_per_kernel: false
splash: /usr/share/systemd/bootctl/splash-arch.bmp

generate_fallback: false
initramfs_config:
  default_types: [default, fallback]
  linux: [default, fallback]
  linux-lts: [fallback]
  linux-zen: [default]

efistub: false
efistub_config:
  default_entry: linux
  append_entries: true

sbsign: false
sbsign_config:
  pcr_banks: sha1,sha256,sha384,sha512
  pcr_private_key: /path/to/pcr-private-key.pem
  pcr_public_key: /path/to/pcr-public-key.pem
  secureboot_private_key: /path/to/DB.key
  secureboot_certificate: /path/to/DB.crt

• sign_uki manages the UKI signing. If enabled, sbctl (or sbsign), will sign generated UKI files. If it is not specified, its value is set to true

• remove_leftovers manages the removal of leftovers when generating the UKI files. Besides the vmlinuz and booster files, EFI entries, fallback images and kernel cmdlines are treated as leftovers, they will be removed if efistub, cmdline_per_kernel, generate_fallback options are disabled. If enabled, leftovers will always be removed after generating UKI files. Leftovers will always be removed if you manually delete the UKI for the specified kernel or all installed kernels (booster-um -r <package> or booster-um -R/booster-um -C). If it is not specified, its value is set to true

• cmdline_per_kernel manages the creation of the cmdline per kernel. If enabled, booster-um will use the kernel parameters from the /etc/kernel/$pkgbase.cmdline file. $pkgbase is the name of the pacman kernel package name (linux, linux-lts, linux-zen etc.). If this file doesn't exist, booster-um will create it. The default /etc/kernel/cmdline will be used as a shared cmdline for all kernels. If it is not specified, its value is set to false

• splash a picture to display during boot. The argument is a path to a BMP file. The default /usr/share/systemd/bootctl/splash-arch.bmp picture will be used if this path is invalid or not specified.

• generate_fallback manages the creation of fallback (universal) UKI files. Separate fallback images will not be created if universal flag is enabled in the /etc/booster.yaml config. If it is not specified, its value is set to false

• initramfs_config node provides initramfs type configuration. Under this node, you can specify up to two types, default and fallback, for:

  • Selected kernel package name (linux, linux-lts, linux-zen, linux-rt, linux-xanmod, etc.)
  • default_types - all other unspecified kernels. By default this array has default and fallback types.

  Note: If you specified fallback type, you must enable generate_fallback, otherwise it will generate default images.

• efistub manages EFI entries. If enabled, booster-um will create a new EFI entry. If it is not specified, its value is set to false

• efistub_config node provides additional efistub configuration:

  • default_entry makes sure that the EFI entry of the specified kernel is the first in the EFI boot order. If fallback UKI is generated for the specified kernel, its EFI entry will be added after the default entry. After changing its value, it is enough to regenerate all images (booster-um -G)
  • append_entries takes care of where new EFI entries will be added to the boot order. If enabled , newly created EFI entries will be added to the end of the boot order, otherwise they will be added to the beginning. If it is not specified, its value is set to true

• sbsign manages UKI signing using the sbsign tool. If enabled, sbsign will be used instead of sbctl. After enabling this type of signing, the options in the sbsign_config node can be set arbitrarily. If it is not specified, its value is set to false

• sbsign_config node provides sbsign configuration:

  • pcr_banks a comma separated list of PCR banks to sign a policy for
  • pcr_private_key a path to a private key to use for signing PCR policies
  • pcr_public_key a path to public key to use for signing PCR policies
  • secureboot_private_key a path to a private key to use for signing of the UKI file
  • secureboot_certificate a path to a certificate to use for signing of UKI file

First run

• 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 use the EFISTUB booting, 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 append_entries
  • 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 like 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.

Help options:
    -h, --help  Show this help message

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

Remove options:
    -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 -r linux
          booster-um -G
          booster-um -R
          booster-um -C