Legacy (CBM) schema specification tracker issue

[ermo]

This issue is intended to be the focal point for the discussion surrounding how to replace CBM in Solus with the blsctl tool being developed as part of the blsforme project in Serpent.

Status: legacy schema is being agreed upon

Stakeholders: @ikeycode @ReillyBrogan @silkeh

Related issues:

• clr-boot-manager: Update freestanding initrd dir getsolus/packages#3257

---

The legacy schema is implemented by clr-boot-manager (CBM). The schema does not cover all features used by CBM, only the ones that are used by Solus.

Configuration

• /etc/kernel/cmdline.d/*.conf, /usr/lib64/kernel/cmdline.d/*.conf:

  A set of files that will be used to modify the kernel commandline. The files can also be used to mask the vendor cmdline if the filename matches a vendor configuration file and is linked to /dev/null. The vendor configuration files are /usr/lib/kernel/cmdline-* and /usr/lib64/kernel/cmdline.d/*.conf.
  The files should be in plain text format and each line will be appended directly to the kernel commandline.
  Commented lines (#) are ignored.

• /etc/kernel/cmdline-removal.d/*.conf:

  A set of files that will be used to modify the kernel commandline by removing string matches from the final consolidated commandline (removal happens after the content from cmdline and cmd‐line.d/*.conf files are added). The matches are made on a per line basis so multiple different removals should be placed on their own line or file

• /etc/kernel/update_efi_vars:

  A system-wide configuration to avoid clr-boot-manager changing efi variables when using shim-systemd backend (see flag --no-efi-update). This configuration file will be applied every time clr-boot-manager is called - even when called by a external tool non interactively. Possible values are: no, false.

• /etc/kernel/initrd.d/*, /usr/lib64/kernel/initrd.d:

  A set of files that will be used as additional user's freestanding initrd files. Additional initrd arguments will be added to the kernel argument list, if desired the user may mask out system installed initrd files by creating symbolic links within /etc/kernel/initrd.d pointing to /dev/null with same name of system installed files.
  To support early microcode updates, clr-boot-manager will identify the first file it finds named *-ucode.cpio, and ensure that is the first initrd loaded by the boot manager. There is currently no deterministic sorting, however, a matching file in /etc/kernel/initrd.d will take precedence over the system-provided microcode initrd in /usr/lib64/kernel/initrd.d.

• /etc/kernel/timeout: bootloader menu timeout in seconds. Only contains values >0.

• /etc/kernel/console_mode: console mode for systemd-boot, see Add commands for configuring systemd console-mode getsolus/clr-boot-manager#5.

Kernels

Kernels are identified using <project>.<variant>.<version>-<release>. For example com.solus-project.current.6.9.8-294. Higher releases represent newer versions in the project and variant. Multiple variants can exist at the same time (eg: current, lts).

A kernel and kernel-related packages provide the following files in /usr/lib64/kernel/:

• cmdline-<version>-<release>.<variant>: additional cmdline values for this kernel.
• config-<version>-<release>.<variant>: kernel config with which it was built.
• <project>.<variant>.<version>-<release>: the kernel.
• initrd-<project>.<variant>.<version>-<release>: the main initrd.
• initrd-<project>.<variant>.<version>-<release>.*: optional initrd extensions

Additionally, the following paths are provided:

• /usr/lib64/modules/<version>-<release>.<variant>/: kernel modules.

These files are removed by CBM when the kernel is cleaned up.

Boot loaders

Supported boot loaders are Grub (without secure boot) and systemd-boot with secure boot shim.

Grub

Grub is only used for BIOS systems. The following partition layouts are used:

• Partitionless: MBR with a single Solus partition.
• Boot partition: MBR with a separate /boot partition.
• Fancy boot partition: Hybrid GPT/MBR with separate /boot partition.

TODO: document where files are placed exactly and how Grub config looks

Systemd boot

Only used for EFI. A single layout is used with a separate EFI

TODO: expand on supported configurations and secure boot.

CLI

From the manpage:

OPTIONS
       The following options are understood:

       -h, --help, help
           Prints a help message.

       -p, --path
           Set the base path for boot management operations.

       -i, --image
           Force clr-boot-manager to run in image mode.

       -n, --no-efi-update
           Force clr-boot-manager to skip efi variables update (when using shim-systemd backend).

       -v, --version, version
           Print the version of clr-boot-manager  and exit.

COMMANDS
       The following commands are understood:

       report-booted
           Report the current kernel as successfully booted. Ideally this should be invoked from the accompanying  systemd  unit  upon  boot,  in  order  for
           clr-boot-manager to track known-booting kernels.

       update
           Perform  an  update  operation  on the configured boot directory. This will analyze kernels available from the software distribution that are cur‐
           rently installed, and pick the ideal candidates for installation.

           This includes the current vendor selection for each kernel type, the currently running kernel, and the most recent successfully booted  kernel  of
           each type currently installed.

           All  other  kernels  not fitting these parameters are then removed in accordance with vendor policy, and removed from the boot directory. For UEFI
           systems this is the EFI System Partition..

       set-timeout [TIMEOUT IN SECONDS]
           Configure the timeout that will be used when next writing the boot loader configuration, i.e. when clr-boot-manager  update  is  called.   Setting
           this to a value of 0 will remove the timout entirely.

       get-timeout
           Returns the currently configured timeout as set by clr-boot-manager set-timeout.

       list-kernels
           Display kernels currently available for booting that were provisioned by clr-boot-manager.

           This command will present a sorted list of kernels with the kernel that is selected for the next boot highlighted with a * prefix.

       set-kernel
           Configure the default booting kernel.

           This command will not prevent the update command from changing the default kernel.

       remove-kernel
           Remove a kernel from the system (both /boot and /usr locations).

           Warning: This can remove the only kernel from the system, ensure you have a default kernel set after running this command.

Services

CBM provides the following services:

• clr-boot-manager-mount-boot.service (disabled by default), on which services can depend if they expect /boot to be mounted:

  [Unit]
  Description=mount /boot using clr-boot-manager
  
  [Service]
  Type=oneshot
  RemainAfterExit=yes
  ExecStart=/usr/bin/clr-boot-manager mount-boot
  ExecStop=/usr/bin/umount /boot
  
  [Install]
  WantedBy=multi-user.target
  

• clr-boot-manager-booted.service (enabled by default), that is used to mark a kernel as being booted correctly:

  [Unit]
  Description=clr-boot-manager tracking kernel boot success
  
  [Service]
  Type=oneshot
  ExecStart=/usr/bin/clr-boot-manager report-booted
  
  [Install]
  WantedBy=multi-user.target