From f5f5047ff1d4008687186a45066f94f5b3a830fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Fri, 1 Jul 2022 10:52:12 +0200 Subject: [PATCH] man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections. --- man/kernel-install.xml | 155 ++++++++++++++++++++++++----------------- 1 file changed, 90 insertions(+), 65 deletions(-) diff --git a/man/kernel-install.xml b/man/kernel-install.xml index 5ae86aca18..bb22443854 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -144,6 +144,7 @@ The <varname>$BOOT</varname> partition + The partition where the kernels and Boot Loader Specification snippets are located is called $BOOT. kernel-install determines the location of this partition by checking @@ -173,77 +174,91 @@ Environment variables - If is used, $KERNEL_INSTALL_VERBOSE=1 will be set for - the plugins. They may output additional logs in this case. + + Environment variables exported for plugins - If $MACHINE_ID is set and not empty when kernel-install is - invoked, it will be used as MACHINE-ID, overriding any automatic detection - attempts. The value must be a valid machine ID (32 hexadecimal characters). + If is used, $KERNEL_INSTALL_VERBOSE=1 will be + exported for plugins. They may output additional logs in this case. - $KERNEL_INSTALL_MACHINE_ID is set for the plugins to the desired - MACHINE-ID to use. It's always a 128bit ID, and typically the ID from - /etc/machine-id or the one passed in via $MACHINE_ID. (If no - machine ID was specified via these methods it might be generated randomly by - kernel-install, in which case it only applies to this invocation.) + $KERNEL_INSTALL_MACHINE_ID is set for the plugins to the desired machine-id to + use. It's always a 128-bit ID. Normally it's read from /etc/machine-id, but it can + also be overriden via $MACHINE_ID (see below). If not specified via these methods a + fallback value will generated by kernel-install, and used only for a single + invocation. - $KERNEL_INSTALL_ENTRY_TOKEN is set for the plugins to the desired entry "token" - to use. It's an identifier that shall be used to identify the local installation, and is often the - machine ID, i.e. same as $KERNEL_INSTALL_MACHINE_ID, but might also be a different - type of identifier, for example a fixed string or the ID=, - IMAGE_ID= values from /etc/os-release. The string passed here - will be used to name Boot Loader Specification entries, or the directories the kernel image and initial - RAM disk images are placed into. Note that while oftentimes - $KERNEL_INSTALL_ENTRY_TOKEN and $KERNEL_INSTALL_MACHINE_ID are set - to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while - the former can be any short string. The entry token to use is read from - /etc/kernel/entry-token, if it exists. Otherwise a few possible candidates below the - $BOOT are searched for Boot Loader Specification Type 1 entry directories, and if - found the entry token is derived from that. If that is not successful the machine ID is used as - fallback. + $KERNEL_INSTALL_ENTRY_TOKEN is set for the plugins to the desired entry + "token" to use. It's an identifier that shall be used to identify the local installation, and is often + the machine ID, i.e. same as $KERNEL_INSTALL_MACHINE_ID, but might also be a + different type of identifier, for example a fixed string or the ID=, + IMAGE_ID= values from /etc/os-release. The string passed here + will be used to name Boot Loader Specification entries, or the directories the kernel image and initial + RAM disk images are placed into. - $KERNEL_INSTALL_BOOT_ROOT is set for the plugins to the absolute path of the - root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and - associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP - (EFI System Partition) are mounted, and also conceptually referred to as $BOOT. Can be - overridden by setting $BOOT_ROOT. + Note that while $KERNEL_INSTALL_ENTRY_TOKEN and + $KERNEL_INSTALL_MACHINE_ID are often set to the same value, the latter is guaranteed + to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The + entry token to use is read from /etc/kernel/entry-token, if it exists. Otherwise a + few possible candidates below $BOOT are checked for Boot Loader Specification Type 1 + entry directories, and if found the entry token is derived from that. If that is not successful, + $KERNEL_INSTALL_MACHINE_ID is used as fallback. - $KERNEL_INSTALL_LAYOUT=bls|other|... is set for the plugins to specify the - installation layout. Defaults to if - $BOOT/ENTRY-TOKEN exists, or - otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout, it's - encouraged to declare its own layout name and configure layout= in - install.conf upon initial installation. The following values are currently - understood: + $KERNEL_INSTALL_BOOT_ROOT is set for the plugins to the absolute path of the + root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and + associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP + (EFI System Partition) are mounted, and also conceptually referred to as $BOOT. Can + be overridden by setting $BOOT_ROOT (see below). - - - bls - - Standard Boot Loader - Specification Type #1 layout, compatible with - systemd-boot7: - entries in - $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf, - kernel and initrds under - $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ - Implemented by 90-loaderentry.install. - - - - other - - Some other layout not understood natively by kernel-install. - - - + $KERNEL_INSTALL_LAYOUT=bls|other|... is set for the plugins to specify the + installation layout. Defaults to if + $BOOT/ENTRY-TOKEN exists, or + otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout, + it's encouraged to declare its own layout name and configure layout= in + install.conf upon initial installation. The following values are currently + understood: - $KERNEL_INSTALL_INITRD_GENERATOR is set for plugins to select the initrd - generator. This may be configured as initrd_generator= in - install.conf. See below. + + + bls + + Standard Boot Loader + Specification Type #1 layout, compatible with + systemd-boot7: + entries in + $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION[+TRIES].conf, + kernel and initrds under + $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ + Implemented by 90-loaderentry.install. + + + + other + + Some other layout not understood natively by kernel-install. + + + - $KERNEL_INSTALL_STAGING_AREA is set for plugins to a path to a directory. - Plugins may drop files in that directory, and they will be installed as part of the loader entry, based - on the file name and extension. + $KERNEL_INSTALL_INITRD_GENERATOR is set for plugins to select the initrd + generator. This may be configured as initrd_generator= in + install.conf, see below. + + $KERNEL_INSTALL_STAGING_AREA is set for plugins to a path to a directory. + Plugins may drop files in that directory, and they will be installed as part of the loader entry, based + on the file name and extension. + + + + Environment variables understood by <command>kernel-install</command> + + $MACHINE_ID can be set for kernel-install to override + $KERNEL_INSTALL_MACHINE_ID, the machine ID. + + $BOOT_ROOT can be set for kernel-install to override + $KERNEL_INSTALL_BOOT_ROOT, the installation location for boot entries. + + Those variables may also be set in install.conf. Variables set in the + environment take precedence over the values specified in the config file. + @@ -327,8 +342,18 @@ Configuration options for kernel-install, as a series of KEY=VALUE assignments, compatible with shell - syntax. This currently supports two keys: layout= and - initrd_generator=, for details see the Environment variables section above. + syntax, following the same rules as described in + os-release5. + /etc/kernel/install.conf will be read if present, and + /usr/lib/kernel/install.conf otherwise. This file is optional. + + + Currently, the following keys are supported: + MACHINE_ID=, + BOOT_ROOT=, + layout=, + initrd_generator=. + See the Environment variables section above for details.