From 10119357855c1b2b5c6c405ef7008435b7821bb7 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 15 Feb 2022 14:19:40 +0100 Subject: docs: add new "sort-key" field to boot loader spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This allows snippet generators to explicitly order entries: any string can be set as an entry's "sort key". If set, sd-boot will use it to sort entries on display. New logic is hence (ignore the boot counting logic) sort-key is set → primary sort key: sort-key (lexicographically increasing order) → secondary sort key: machine-id (also increasing order) → tertiary sort key: version (lexicographically decreasing order!) sort-key is not set → primary sort key: entry filename (aka id), lexicographically increasing order) With this scheme we can order OSes by their names from A-Z but then put within the same OS still the newest version first. This should clean up the order to match expectations more. Based on discussions here: https://github.com/systemd/systemd/pull/22391#issuecomment-1040092633 --- docs/BOOT_LOADER_SPECIFICATION.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) (limited to 'docs/BOOT_LOADER_SPECIFICATION.md') diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md index 8653a5bc00..7f15a23164 100644 --- a/docs/BOOT_LOADER_SPECIFICATION.md +++ b/docs/BOOT_LOADER_SPECIFICATION.md @@ -232,6 +232,16 @@ spaces from its value. The following keys are known: other installed operating systems. This ID shall be formatted as 32 lower case hexadecimal characters (i.e. without any UUID formatting). This key is optional. Example: `4098b3f648d74c13b1f04ccfba7798e8`. +* `sort-key` shall contain a short string used for sorting entries on + display. This can be defined freely though should typically be initialized + from `IMAGE_ID=` or `ID=` from `/etc/os-release` of the relevant entry, + possibly suffixed. This field is optional. If set, it is used as primary + sorting key for the entries on display (lexicographically increasing). It + does not have to be unique (and usually is not). If non-unique the the + `machine-id` (lexicographically increasing) and `version` (lexicographically + decreasing, i.e. newest version first) fields described above are used as + secondary/ternary sorting keys. If this field is not set entries are + typically sorted by the `.conf` file name of the entry. * `linux` refers to the Linux kernel to spawn and shall be a path relative to `$BOOT`. It is recommended that every distribution creates a machine id and version specific subdirectory below `$BOOT` and places its kernels and @@ -269,8 +279,9 @@ key and is otherwise not valid. Here's an example for a complete drop-in file: # /boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf title Fedora 19 (Rawhide) - version 3.8.0-2.fc19.x86_64 + sort-key fedora machine-id 6a9857a393724b7a981ebb5b8495b9ea + version 3.8.0-2.fc19.x86_64 options root=UUID=6d3376e4-fc93-4509-95ec-a21d68011da2 architecture x64 linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux @@ -358,10 +369,10 @@ simply reads all files `$BOOT/loader/entries/*.conf`, and populates its boot menu with this. On EFI, it then extends this with any unified kernel images found in `$BOOT/EFI/Linux/*.efi`. It may also add additional entries, for example a "Reboot into firmware" option. Optionally it may sort the menu based -on the `machine-id` and `version` fields, and possibly others. It uses the file -name to identify specific items, for example in case it supports storing away -default entry information somewhere. A boot loader should generally not modify -these files. +on the `sort-key`, `machine-id` and `version` fields, and possibly others. It +uses the file name to identify specific items, for example in case it supports +storing away default entry information somewhere. A boot loader should +generally not modify these files. For "Boot Loader Specification Entries" (Type #1), the _kernel package installer_ installs the kernel and initrd images to `$BOOT` (it is recommended -- cgit v1.2.1