2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2013-02-22 20:18:47 +04:00
2022-04-04 16:38:33 +03:00
<refentry id= "kernel-install" conditional= 'ENABLE_KERNEL_INSTALL'
2019-03-07 22:49:30 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
2013-02-22 20:18:47 +04:00
<refentryinfo >
<title > kernel-install</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > kernel-install</refentrytitle>
<manvolnum > 8</manvolnum>
</refmeta>
<refnamediv >
<refname > kernel-install</refname>
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
<refpurpose > Add and remove kernel and initrd images to and from /boot</refpurpose>
2013-02-22 20:18:47 +04:00
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
2013-05-03 08:55:20 +04:00
<command > kernel-install</command>
2019-03-07 22:49:30 +03:00
<arg choice= "opt" rep= "repeat" > OPTIONS</arg>
2022-09-21 02:21:20 +03:00
<arg choice= "plain" > COMMAND</arg>
2013-05-03 08:55:20 +04:00
<arg choice= "plain" > <replaceable > KERNEL-VERSION</replaceable> </arg>
2018-12-29 22:01:10 +03:00
<arg choice= "plain" > <replaceable > KERNEL-IMAGE</replaceable> </arg>
2019-01-17 21:06:09 +03:00
<arg choice= "opt" rep= "repeat" > <replaceable > INITRD-FILE</replaceable> </arg>
2013-02-22 20:18:47 +04:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
<para > <command > kernel-install</command> is used to install and remove kernel and initrd images
<footnote >
<para > Nowadays actually CPIO archives used as an "initramfs", rather than "initrd". See
<citerefentry > <refentrytitle > bootup</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> for an
explanation.</para>
</footnote>
to and from the boot loader partition, referred to as <varname > $BOOT</varname> here. It will usually be
one of <filename > /boot/</filename> , <filename > /efi/</filename> , or <filename > /boot/efi/</filename> , see
below.</para>
2013-02-22 20:18:47 +04:00
2022-02-10 17:27:45 +03:00
<para > <command > kernel-install</command> will run the executable files ("plugins") located in the
directory <filename > /usr/lib/kernel/install.d/</filename> and the local administration directory
<filename > /etc/kernel/install.d/</filename> . 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 <filename > /etc/kernel/install.d/</filename> take precedence over files with the
same name in <filename > /usr/lib/kernel/install.d/</filename> . This can be used to override a
system-supplied executables with a local file if needed; a symbolic link in
<filename > /etc/kernel/install.d/</filename> with the same name as an executable in
<filename > /usr/lib/kernel/install.d/</filename> , pointing to <filename > /dev/null</filename> , disables the
executable entirely. Executables must have the extension <literal > .install</literal> ; other extensions
are ignored.</para>
<para > An executable placed in these directories should return <constant > 0</constant> on success. It may
also return <constant > 77</constant> to cause the whole operation to terminate (executables later in
lexical order will be skipped).</para>
2013-02-22 20:18:47 +04:00
</refsect1>
<refsect1 >
<title > Commands</title>
<para > The following commands are understood:</para>
<variablelist >
<varlistentry >
2019-01-17 21:06:09 +03:00
<term > <command > add <replaceable > KERNEL-VERSION</replaceable> <replaceable > KERNEL-IMAGE</replaceable> [<replaceable > INITRD-FILE</replaceable> ...]</command> </term>
2013-02-22 20:18:47 +04:00
<listitem >
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
<para > This command expects a kernel version string and a path to a kernel image file as arguments.
Optionally, one or more initrd images may be specified as well (note that plugins might generate
additional ones). <command > kernel-install</command> calls the executable files from
<filename > /usr/lib/kernel/install.d/*.install</filename> and
2022-02-10 17:27:45 +03:00
<filename > /etc/kernel/install.d/*.install</filename> (i.e. the plugins) with the following
arguments:</para>
2018-06-22 19:14:22 +03:00
2022-02-10 17:27:45 +03:00
<programlisting > add <replaceable > KERNEL-VERSION</replaceable> <filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> <replaceable > KERNEL-IMAGE</replaceable> [<replaceable > INITRD-FILE</replaceable> ...]</programlisting>
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
<para > The third argument directly refers to the path where to place kernel images, initrd
2022-02-10 17:27:45 +03:00
images and other resources for <ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot
Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes
are used the parameter may be ignored. The <replaceable > ENTRY-TOKEN</replaceable> string is
typically the machine ID and is supposed to identify the local installation on the system. For
details see below.</para>
2013-05-03 08:55:20 +04:00
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
<para > Two default plugins execute the following operations in this case:</para>
2018-06-22 19:14:22 +03:00
<itemizedlist >
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
<listitem > <para > <command > kernel-install</command> creates
2022-02-10 17:27:45 +03:00
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> </filename> ,
if enabled (see <varname > $KERNEL_INSTALL_LAYOUT</varname> ).</para> </listitem>
2018-06-22 19:14:22 +03:00
<listitem > <para > <filename > 50-depmod.install</filename> runs
2020-06-25 15:37:24 +03:00
<citerefentry project= 'man-pages' > <refentrytitle > depmod</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> for the
2018-06-22 19:14:22 +03:00
<replaceable > KERNEL-VERSION</replaceable> .</para> </listitem>
2022-02-10 17:27:45 +03:00
<listitem > <para > <filename > 90-loaderentry.install</filename> copies
<replaceable > KERNEL-IMAGE</replaceable> to
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /linux</filename> .
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
If <replaceable > INITRD-FILE</replaceable> s are provided, it also copies them to
2022-02-10 17:27:45 +03:00
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL_VERSION</replaceable> /<replaceable > INITRD-FILE</replaceable> </filename> .
2018-06-22 19:14:22 +03:00
It also creates a boot loader entry according to the <ulink
2022-02-10 17:27:45 +03:00
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> (Type #1) in
<filename > $BOOT/loader/entries/<replaceable > ENTRY-TOKEN</replaceable> -<replaceable > KERNEL-VERSION</replaceable> .conf</filename> .
2018-06-22 19:14:22 +03:00
The title of the entry is the <replaceable > PRETTY_NAME</replaceable> parameter specified in
2022-02-10 17:27:45 +03:00
<filename > /etc/os-release</filename> or <filename > /usr/lib/os-release</filename> (if the former
is missing), or "Linux <replaceable > KERNEL-VERSION</replaceable> ", if unset.</para>
2019-03-07 23:18:56 +03:00
2022-02-10 17:27:45 +03:00
<para > If <varname > $KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para> </listitem>
2018-06-22 19:14:22 +03:00
</itemizedlist>
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
<varlistentry >
2013-04-30 20:01:47 +04:00
<term > <command > remove <replaceable > KERNEL-VERSION</replaceable> </command> </term>
2013-05-03 08:55:20 +04:00
<listitem >
2018-06-22 19:14:22 +03:00
<para > This command expects a kernel version string as single argument. This calls executables from
<filename > /usr/lib/kernel/install.d/*.install</filename> and
<filename > /etc/kernel/install.d/*.install</filename> with the following arguments:
2013-05-03 08:55:20 +04:00
</para>
2022-02-10 17:27:45 +03:00
<programlisting > remove <replaceable > KERNEL-VERSION</replaceable> <filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> </programlisting>
<para > Afterwards, <command > kernel-install</command> removes the entry directory
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename>
and its contents, if it exists.</para>
2018-06-22 19:14:22 +03:00
<para > Two default plugins execute the following operations in this case:</para>
<itemizedlist >
<listitem > <para > <filename > 50-depmod.install</filename> removes the files generated by <command > depmod</command> for this kernel again.</para> </listitem>
<listitem > <para > <filename > 90-loaderentry.install</filename> removes the file
2022-02-10 17:27:45 +03:00
<filename > $BOOT/loader/entries/<replaceable > ENTRY-TOKEN</replaceable> -<replaceable > KERNEL-VERSION</replaceable> .conf</filename> .</para> </listitem>
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
</itemizedlist>
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
2022-02-10 17:27:45 +03:00
<varlistentry >
<term > <command > inspect</command> </term>
<listitem >
<para > Shows the various paths and parameters configured or auto-detected. In particular shows the
values of the various <varname > $KERNEL_INSTALL_*</varname> environment variables listed
below.</para>
</listitem>
</varlistentry>
2013-02-22 20:18:47 +04:00
</variablelist>
2019-03-08 21:21:54 +03:00
</refsect1>
2013-02-22 20:18:47 +04:00
2019-03-08 21:21:54 +03:00
<refsect1 >
<title > The <varname > $BOOT</varname> partition</title>
2022-07-01 11:52:12 +03:00
2019-03-08 21:21:54 +03:00
<para > The partition where the kernels and <ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot
Loader Specification</ulink> snippets are located is called <varname > $BOOT</varname> .
<command > kernel-install</command> determines the location of this partition by checking
2022-02-10 17:27:45 +03:00
<filename > /efi/</filename> , <filename > /boot/</filename> , and <filename > /boot/efi/</filename> in turn. The
first location where <filename > $BOOT/loader/entries/</filename> or
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /</filename> exists is used.</para>
2013-02-22 20:18:47 +04:00
</refsect1>
2019-03-07 22:49:30 +03:00
<refsect1 >
<title > Options</title>
<para > The following options are understood:</para>
<variablelist >
<varlistentry >
<term > <option > -v</option> </term>
<term > <option > --verbose</option> </term>
<listitem >
<para > Output additional information about operations being performed.</para>
</listitem>
</varlistentry>
<xi:include href= "standard-options.xml" xpointer= "help" />
2022-04-05 19:18:56 +03:00
<xi:include href= "standard-options.xml" xpointer= "version" />
2019-03-07 22:49:30 +03:00
</variablelist>
</refsect1>
<refsect1 >
<title > Environment variables</title>
2021-03-16 19:38:20 +03:00
2022-07-01 11:52:12 +03:00
<refsect2 >
<title > Environment variables exported for plugins</title>
<para > If <option > --verbose</option> is used, <varname > $KERNEL_INSTALL_VERBOSE=1</varname> will be
exported for plugins. They may output additional logs in this case.</para>
<para > <varname > $KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired machine-id to
use. It's always a 128-bit ID. Normally it's read from <filename > /etc/machine-id</filename> , but it can
2022-07-20 07:15:37 +03:00
also be overridden via <varname > $MACHINE_ID</varname> (see below). If not specified via these methods a
2022-07-01 11:52:12 +03:00
fallback value will generated by <command > kernel-install</command> , and used only for a single
invocation.</para>
<para > <varname > $KERNEL_INSTALL_ENTRY_TOKEN</varname> 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 <varname > $KERNEL_INSTALL_MACHINE_ID</varname> , but might also be a
different type of identifier, for example a fixed string or the <varname > ID=</varname> ,
<varname > IMAGE_ID=</varname> values from <filename > /etc/os-release</filename> . 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.</para>
<para > Note that while <varname > $KERNEL_INSTALL_ENTRY_TOKEN</varname> and
<varname > $KERNEL_INSTALL_MACHINE_ID</varname> 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 <filename > /etc/kernel/entry-token</filename> , if it exists. Otherwise a
few possible candidates below <varname > $BOOT</varname> 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,
<varname > $KERNEL_INSTALL_MACHINE_ID</varname> is used as fallback.</para>
<para > <varname > $KERNEL_INSTALL_BOOT_ROOT</varname> 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 <varname > $BOOT</varname> . Can
be overridden by setting <varname > $BOOT_ROOT</varname> (see below).</para>
<para > <varname > $KERNEL_INSTALL_LAYOUT=bls|other|...</varname> is set for the plugins to specify the
installation layout. Defaults to <option > bls</option> if
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> </filename> exists, or <option > other</option>
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 <varname > layout=</varname> in
<filename > install.conf</filename> upon initial installation. The following values are currently
understood:</para>
<variablelist >
<varlistentry >
<term > bls</term>
<listitem >
<para > Standard <ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot Loader
Specification</ulink> Type #1 layout, compatible with
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> :
entries in
<filename > $BOOT/loader/entries/<replaceable > ENTRY-TOKEN</replaceable> -<replaceable > KERNEL-VERSION</replaceable> [+<replaceable > TRIES</replaceable> ].conf</filename> ,
kernel and initrds under
<filename > $BOOT/<replaceable > ENTRY-TOKEN</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> </para>
<para > Implemented by <filename > 90-loaderentry.install</filename> .</para>
</listitem>
</varlistentry>
<varlistentry >
<term > other</term>
<listitem >
<para > Some other layout not understood natively by <command > kernel-install</command> .</para>
</listitem>
</varlistentry>
</variablelist>
2022-01-19 14:20:22 +03:00
2022-07-01 11:52:12 +03:00
<para > <varname > $KERNEL_INSTALL_INITRD_GENERATOR</varname> is set for plugins to select the initrd
generator. This may be configured as <varname > initrd_generator=</varname> in
<filename > install.conf</filename> , see below.</para>
<para > <varname > $KERNEL_INSTALL_STAGING_AREA</varname> 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.</para>
</refsect2>
<refsect2 >
<title > Environment variables understood by <command > kernel-install</command> </title>
2022-07-01 11:58:01 +03:00
<para > <varname > $KERNEL_INSTALL_CONF_ROOT</varname> can be set to override the location of the
configuration files read by <command > kernel-install</command> . When set,
<filename > install.conf</filename> , <filename > entry-token</filename> , and other files will be
read from this directory.</para>
2022-07-01 13:55:32 +03:00
<para > <varname > $KERNEL_INSTALL_PLUGINS</varname> can be set to override the list of plugins executed by
<command > kernel-install</command> . The argument is a whitespace-separated list of paths.
<literal > KERNEL_INSTALL_PLUGINS=:</literal> may be used to prevent any plugins from running.
</para>
2022-07-01 11:52:12 +03:00
<para > <varname > $MACHINE_ID</varname> can be set for <command > kernel-install</command> to override
<varname > $KERNEL_INSTALL_MACHINE_ID</varname> , the machine ID.</para>
2022-02-10 17:27:45 +03:00
2022-07-01 11:52:12 +03:00
<para > <varname > $BOOT_ROOT</varname> can be set for <command > kernel-install</command> to override
<varname > $KERNEL_INSTALL_BOOT_ROOT</varname> , the installation location for boot entries.</para>
2022-02-10 17:27:45 +03:00
2022-07-01 11:58:01 +03:00
<para > The last two variables may also be set in <filename > install.conf</filename> . Variables set in the
2022-07-01 11:52:12 +03:00
environment take precedence over the values specified in the config file.</para>
</refsect2>
2019-03-07 22:49:30 +03:00
</refsect1>
2013-02-22 20:18:47 +04:00
<refsect1 >
<title > Exit status</title>
2016-11-04 15:40:58 +03:00
<para > If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
2013-02-22 20:18:47 +04:00
</refsect1>
<refsect1 >
<title > Files</title>
<variablelist >
<varlistentry >
<term >
<filename > /usr/lib/kernel/install.d/*.install</filename>
<filename > /etc/kernel/install.d/*.install</filename>
</term>
<listitem >
2013-07-02 07:44:04 +04:00
<para > Drop-in files which are executed by kernel-install.</para>
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
2013-02-25 22:29:16 +04:00
<varlistentry >
<term >
2021-03-16 19:39:56 +03:00
<filename > /usr/lib/kernel/cmdline</filename>
2013-02-25 22:29:16 +04:00
<filename > /etc/kernel/cmdline</filename>
<filename > /proc/cmdline</filename>
</term>
<listitem >
2018-06-22 19:14:22 +03:00
<para > Read by <filename > 90-loaderentry.install</filename> . The content of the file
2022-07-01 11:58:01 +03:00
<filename > /etc/kernel/cmdline</filename> specifies the kernel command line to use. If that file
does not exist, <filename > /usr/lib/kernel/cmdline</filename> is used. If that also does not
exist, <filename > /proc/cmdline</filename> is used. <varname > $KERNEL_INSTALL_CONF_ROOT</varname>
may be used to override the path.</para>
2018-06-22 19:14:22 +03:00
</listitem>
</varlistentry>
<varlistentry >
<term >
<filename > /etc/kernel/tries</filename>
</term>
<listitem >
<para > Read by <filename > 90-loaderentry.install</filename> . If this file exists a numeric value is read from
it and the naming of the generated entry file is slightly altered to include it as
2019-03-08 21:21:54 +03:00
<filename > $BOOT/loader/entries/<replaceable > MACHINE-ID</replaceable> -<replaceable > KERNEL-VERSION</replaceable> +<replaceable > TRIES</replaceable> .conf</filename> . This
2018-06-22 19:14:22 +03:00
is useful for boot loaders such as
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> which
2022-07-01 11:58:01 +03:00
implement boot attempt counting with a counter embedded in the entry file name.
<varname > $KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the path.</para>
2013-02-25 22:29:16 +04:00
</listitem>
</varlistentry>
<varlistentry >
<term >
2022-02-10 17:27:45 +03:00
<filename > /etc/kernel/entry-token</filename>
2013-02-25 22:29:16 +04:00
</term>
<listitem >
2022-02-10 17:27:45 +03:00
<para > If this file exists it is read and used as "entry token" for this system, i.e. is used for
2022-07-01 11:58:01 +03:00
naming Boot Loader Specification entries, see <varname > $KERNEL_INSTALL_ENTRY_TOKEN</varname>
above for details. <varname > $KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the
path.</para>
2013-02-25 22:29:16 +04:00
</listitem>
</varlistentry>
2021-12-14 19:09:08 +03:00
<varlistentry >
<term >
2022-02-10 17:27:45 +03:00
<filename > /etc/machine-id</filename>
2021-12-14 19:09:08 +03:00
</term>
<listitem >
2022-02-10 17:27:45 +03:00
<para > The content of this file specifies the machine identification
<replaceable > MACHINE-ID</replaceable> .</para>
2021-12-14 19:09:08 +03:00
</listitem>
</varlistentry>
2013-02-25 22:29:16 +04:00
<varlistentry >
<term >
<filename > /etc/os-release</filename>
2014-06-13 21:45:52 +04:00
<filename > /usr/lib/os-release</filename>
2013-02-25 22:29:16 +04:00
</term>
2022-02-10 17:27:45 +03:00
<listitem >
2021-03-16 19:46:33 +03:00
<para > Read by <filename > 90-loaderentry.install</filename> .
2022-02-10 17:27:45 +03:00
If available, <varname > PRETTY_NAME=</varname> is read from these files and used as the title of the boot menu entry.
2021-03-16 19:46:33 +03:00
Otherwise, <literal > Linux <replaceable > KERNEL-VERSION</replaceable> </literal> will be used.</para>
2013-02-25 22:29:16 +04:00
</listitem>
</varlistentry>
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
<varlistentry >
<term >
<filename > /usr/lib/kernel/install.conf</filename>
<filename > /etc/kernel/install.conf</filename>
</term>
<listitem >
2022-03-17 19:20:07 +03:00
<para > Configuration options for <command > kernel-install</command> , as a series of
<varname > KEY=</varname> <replaceable > VALUE</replaceable> assignments, compatible with shell
2022-07-01 11:52:12 +03:00
syntax, following the same rules as described in
<citerefentry > <refentrytitle > os-release</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> .
<filename > /etc/kernel/install.conf</filename> will be read if present, and
<filename > /usr/lib/kernel/install.conf</filename> otherwise. This file is optional.
2022-07-01 11:58:01 +03:00
<varname > $KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the path.
2022-07-01 11:52:12 +03:00
</para>
<para > Currently, the following keys are supported:
<varname > MACHINE_ID=</varname> ,
<varname > BOOT_ROOT=</varname> ,
<varname > layout=</varname> ,
<varname > initrd_generator=</varname> .
See the Environment variables section above for details.</para>
kernel-install: replace 00-entry-directory with K_I_LAYOUT in k-i
341890de866f2ee34919a47ce3fc6c8cd3c1924c made "bootctl install" create
ESP\MID, in preparation of cf73f650890b56a59bfb713c4c82b4e29daa7316 that
followed it and created 00-entry-directory.install to make ESP\MID\KVER
if ESP\MID existed ‒ this meant that "bootctl install" followed by
"kernel-install $(uname -r) /boot/vml*$(uname -r) /boot/ini*$(uname -r)"
actually installed the kernel correctly.
Later, 31e57550b552e113bd3d44355b237c41e42beb58 reverted the first
commit, meaning, that now running those two commands first installs
sd-boot, but then does nothing. Everything appears to work right,
nothing errors out, but no changes are actually done. To the untrained
eye (all of them), even running with -v appears to work:
all the hooks are run, as is depmod, but, again, nothing happens.
This is horrible. Nothing in either manpage suggests what to do
(nor should it, really), but the user is left with a bootloader that
appears fully funxional, since nothing suggests a failure in the output,
but with an unbootable machine, /no way to boot it/, even if they drop
to an EFI shell, since the boot bundle isn't present on the ESP,
and no real recourse even if they boot into a recovery system,
apart from installing like GRUB or whatever.
00- is purely instrumentation for 90-,
and separating one from the other has led to downstream dissatisfaxion
(indeed, the last mentioned commit cited cited exactly that as the
reversion reason), while creating $ENTRY_DIR_ABS is only required
for bootloaders using the BLS, and shouldn't itself toggle anything.
To that end, introduce an /{e,l}/k/install.conf file that allows
overriding the detected layout, and detect it as "bls" if
$BOOT_ROOT/$MACHINE_ID ($ENTRY_DIR_ABS/..) exists, otherwise "other" ‒
if a user wishes to select a different bootloader,
like GRUB, they (or, indeed, the postinst script) can specify
layout=grub. This disables 90- and $ENTRY_DIR_ABS manipulation.
2021-03-16 18:47:34 +03:00
</listitem>
</varlistentry>
2013-02-22 20:18:47 +04:00
</variablelist>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
2013-02-25 22:29:16 +04:00
<citerefentry > <refentrytitle > machine-id</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > os-release</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
2020-06-25 15:37:24 +03:00
<citerefentry project= 'man-pages' > <refentrytitle > depmod</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2018-06-22 19:14:22 +03:00
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> ,
2018-10-12 15:00:20 +03:00
<ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot Loader Specification</ulink>
2013-02-22 20:18:47 +04:00
</para>
</refsect1>
</refentry>
