diff --git a/man/kernel-install.xml b/man/kernel-install.xml index 685617863e..5ec76999ad 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -39,21 +39,21 @@ /boot/, /efi/, or /boot/efi/, see below. - kernel-install will execute the files - located in the directory /usr/lib/kernel/install.d/ - and the local administration directory /etc/kernel/install.d/. - All files are collectively sorted and executed in lexical order, regardless of the directory in - which they live. However, files with identical filenames replace each other. - Files in /etc/kernel/install.d/ take precedence over files with the same name - in /usr/lib/kernel/install.d/. This can be used to override a system-supplied - executables with a local file if needed; a symbolic link in /etc/kernel/install.d/ - with the same name as an executable in /usr/lib/kernel/install.d/, - pointing to /dev/null, disables the executable entirely. Executables must have the - extension .install; other extensions are ignored. + kernel-install will run the executable files ("plugins") located in the + directory /usr/lib/kernel/install.d/ and the local administration directory + /etc/kernel/install.d/. All files are collectively sorted and executed in lexical + order, regardless of the directory in which they live. However, files with identical filenames replace + each other. Files in /etc/kernel/install.d/ take precedence over files with the + same name in /usr/lib/kernel/install.d/. This can be used to override a + system-supplied executables with a local file if needed; a symbolic link in + /etc/kernel/install.d/ with the same name as an executable in + /usr/lib/kernel/install.d/, pointing to /dev/null, disables the + executable entirely. Executables must have the extension .install; other extensions + are ignored. - An executable should return 0 on success. It may also - return 77 to cause the whole operation to terminate - (executables later in lexical order will be skipped). + An executable placed in these directories should return 0 on success. It may + also return 77 to cause the whole operation to terminate (executables later in + lexical order will be skipped). @@ -64,37 +64,45 @@ add KERNEL-VERSION KERNEL-IMAGE [INITRD-FILE ...] This command expects a kernel version string and a path to a kernel image file as - arguments. kernel-install calls the executables from - /usr/lib/kernel/install.d/*.install and - /etc/kernel/install.d/*.install with the following arguments: + arguments. Optionally, one or more initial RAM disk images may be specified as well (note that + plugins might generate additional ones). kernel-install calls the executable + files from /usr/lib/kernel/install.d/*.install and + /etc/kernel/install.d/*.install (i.e. the plugins) with the following + arguments: - add KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...] - + add KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ KERNEL-IMAGE [INITRD-FILE ...] + + The third argument directly refers to the path where to place kernel images, initial RAM disk + images and other resources for Boot + Loader Specification Type #1 entries (the "entry directory"). If other boot loader schemes + are used the parameter may be ignored. The ENTRY-TOKEN string is + typically the machine ID and is supposed to identify the local installation on the system. For + details see below. Two default plugins execute the following operations in this case: kernel-install creates - $BOOT/MACHINE-ID/KERNEL-VERSION, - if enabled (see $KERNEL_INSTALL_LAYOUT=). + $BOOT/ENTRY-TOKEN/KERNEL-VERSION, + if enabled (see $KERNEL_INSTALL_LAYOUT). 50-depmod.install runs depmod8 for the KERNEL-VERSION. - 90-loaderentry.install - copies KERNEL-IMAGE to - $BOOT/MACHINE-ID/KERNEL-VERSION/linux. + 90-loaderentry.install copies + KERNEL-IMAGE to + $BOOT/ENTRY-TOKEN/KERNEL-VERSION/linux. If INITRD-FILEs are provided, it also copies them to - $BOOT/MACHINE-ID/KERNEL_VERSION/INITRD-FILE. + $BOOT/ENTRY-TOKEN/KERNEL_VERSION/INITRD-FILE. It also creates a boot loader entry according to the Boot Loader Specification in - $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf. + url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification (Type #1) in + $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. The title of the entry is the PRETTY_NAME parameter specified in - /etc/os-release or /usr/lib/os-release (if the former is - missing), or "Linux KERNEL-VERSION", if unset. + /etc/os-release or /usr/lib/os-release (if the former + is missing), or "Linux KERNEL-VERSION", if unset. - If $KERNEL_INSTALL_LAYOUT= is not "bls", this plugin does nothing. + If $KERNEL_INSTALL_LAYOUT is not "bls", this plugin does nothing. @@ -104,13 +112,13 @@ This command expects a kernel version string as single argument. This calls executables from /usr/lib/kernel/install.d/*.install and /etc/kernel/install.d/*.install with the following arguments: - - remove KERNEL-VERSION $BOOT/MACHINE-ID/KERNEL-VERSION/ - Afterwards, kernel-install removes the directory - $BOOT/MACHINE-ID/KERNEL-VERSION/ - and its contents. + remove KERNEL-VERSION $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ + + Afterwards, kernel-install removes the entry directory + $BOOT/ENTRY-TOKEN/KERNEL-VERSION/ + and its contents, if it exists. Two default plugins execute the following operations in this case: @@ -118,14 +126,18 @@ 50-depmod.install removes the files generated by depmod for this kernel again. 90-loaderentry.install removes the file - $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION.conf. - - kernel-install removes - $BOOT/MACHINE-ID/KERNEL-VERSION, - if enabled (see $KERNEL_INSTALL_LAYOUT=). + $BOOT/loader/entries/ENTRY-TOKEN-KERNEL-VERSION.conf. + + inspect + + Shows the various paths and parameters configured or auto-detected. In particular shows the + values of the various $KERNEL_INSTALL_* environment variables listed + below. + + @@ -135,9 +147,9 @@ 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 - /efi/, /boot/, and /boot/efi/ - in turn. The first location where $BOOT/loader/entries/ or - $BOOT/$MACHINE_ID/ exists is used. + /efi/, /boot/, and /boot/efi/ in turn. The + first location where $BOOT/loader/entries/ or + $BOOT/ENTRY-TOKEN/ exists is used. @@ -163,36 +175,57 @@ If is used, $KERNEL_INSTALL_VERBOSE=1 will be set for the plugins. They may output additional logs in this case. - If MACHINE_ID= is set and not empty, it will be used as MACHINE-ID, - overriding any automatic detection attempts. The value must be a valid machine ID (32 hexadecimal characters). + 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). - KERNEL_INSTALL_MACHINE_ID= is set for the plugins to the desired MACHINE-ID – - either 32 hexadecimal characters or the special value Default. - KERNEL_INSTALL_BOOT_ROOT= is set for the plugins to the root directory (mount point, usually) of the hierarchy - where boot-loader entries, kernel images, and associated resources should be placed. Can be overridden by setting BOOT_ROOT=. + $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_LAYOUT=bls|other|... is set for the plugins to specify the installation layout. - Defaults to if $BOOT/MACHINE-ID 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. + $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_INITRD_GENERATOR=... is set for plugins to select the initrd generator. - This should be configured as initrd_generator= in install.conf. - + $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. - 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_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: bls - Standard Boot Loader Specification layout, - compatible with systemd-boot7: entries in - $BOOT/loader/entries/MACHINE-ID-KERNEL-VERSION[+TRIES].conf, - kernel and initrds under $BOOT/MACHINE-ID/KERNEL-VERSION/ - Provided by 90-loaderentry.install. + 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. @@ -202,6 +235,15 @@ + + $KERNEL_INSTALL_INITRD_GENERATOR is set for plugins to select the initrd + generator. This should be configured as initrd_generator= in + install.conf. + + + $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. @@ -249,25 +291,21 @@ - /etc/machine-id + /etc/kernel/entry-token - The content of this file specifies the machine identification - MACHINE-ID. If /etc/machine-id - cannot be read or is temporary (backed by a file on tmpfs), - kernel-install will use Default instead. + If this file exists it is read and used as "entry token" for this system, i.e. is used for + naming Boot Loader Specification entries, see + $KERNEL_INSTALL_ENTRY_TOKEN above for details. - /etc/machine-info + /etc/machine-id - If this file contains the KERNEL_INSTALL_MACHINE_ID variable, - kernel-install will use it as MACHINE-ID instead of - the contents of /etc/machine-id. If the variable is not found in - /etc/machine-info, kernel-install will try to save the - machine ID it uses to install to $BOOT to this file. + The content of this file specifies the machine identification + MACHINE-ID. @@ -275,9 +313,9 @@ /etc/os-release /usr/lib/os-release - + Read by 90-loaderentry.install. - If available, PRETTY_NAME is read from these files and used as the title of the boot menu entry. + If available, PRETTY_NAME= is read from these files and used as the title of the boot menu entry. Otherwise, Linux KERNEL-VERSION will be used. diff --git a/man/machine-info.xml b/man/machine-info.xml index 4467c59c94..fddcfb6a6c 100644 --- a/man/machine-info.xml +++ b/man/machine-info.xml @@ -129,17 +129,6 @@ - - KERNEL_INSTALL_MACHINE_ID= - - Specifies the installation-specific installation directory - kernel-install should use. The value must be a valid machine ID (32 hexadecimal - characters). This would generally be the original machine-id that was used when the boot loader - entries for this installation were first added. When not set, the current value of - machine-id5 - will be used. - - VENDOR=