diff --git a/man/kernel-install.xml b/man/kernel-install.xml
index 685617863ec..5ec76999ad5 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-VERSIONKERNEL-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 4467c59c94c..fddcfb6a6c4 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=