2018-07-02 21:15:39 +00:00
<?xml version='1.0'?>
2019-03-14 13:40:58 +00: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 04:23:58 +00:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2013-02-22 16:18:47 +00:00
2019-03-07 19:49:30 +00:00
<refentry id= "kernel-install"
xmlns:xi="http://www.w3.org/2001/XInclude">
2013-02-22 16:18:47 +00:00
<refentryinfo >
<title > kernel-install</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > kernel-install</refentrytitle>
<manvolnum > 8</manvolnum>
</refmeta>
<refnamediv >
<refname > kernel-install</refname>
<refpurpose > Add and remove kernel and initramfs images to and from /boot</refpurpose>
</refnamediv>
<refsynopsisdiv >
<cmdsynopsis >
2013-05-03 04:55:20 +00:00
<command > kernel-install</command>
<arg choice= "plain" > COMMAND</arg>
2019-03-07 19:49:30 +00:00
<arg choice= "opt" rep= "repeat" > OPTIONS</arg>
2013-05-03 04:55:20 +00:00
<arg choice= "plain" > <replaceable > KERNEL-VERSION</replaceable> </arg>
2018-12-29 19:01:10 +00:00
<arg choice= "plain" > <replaceable > KERNEL-IMAGE</replaceable> </arg>
2019-01-17 18:06:09 +00:00
<arg choice= "opt" rep= "repeat" > <replaceable > INITRD-FILE</replaceable> </arg>
2013-02-22 16:18:47 +00:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
2019-03-08 18:21:54 +00:00
<para > <command > kernel-install</command> is used to install and remove kernel and initramfs images to and
from the boot loader partition, referred to as <varname > $BOOT</varname> here. It will usually be one of
2020-07-06 08:49:59 +00:00
<filename > /boot/</filename> , <filename > /efi/</filename> , or <filename > /boot/efi/</filename> , see below.
2013-02-22 16:18:47 +00:00
</para>
2013-05-03 04:55:20 +00:00
<para > <command > kernel-install</command> will execute the files
located in the directory <filename > /usr/lib/kernel/install.d/</filename>
2013-02-22 16:18:47 +00:00
and the local administration directory <filename > /etc/kernel/install.d/</filename> .
2013-05-03 04:55:20 +00:00
All files are collectively sorted and executed in lexical order, regardless of the directory in
2013-06-27 19:51:44 +00:00
which they live. However, files with identical filenames replace each other.
2013-02-22 16:18:47 +00:00
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> ,
2016-09-24 13:03:54 +00:00
pointing to <filename > /dev/null</filename> , disables the executable entirely. Executables must have the
2013-07-02 03:44:04 +00:00
extension <literal > .install</literal> ; other extensions are ignored.</para>
2013-02-22 16:18:47 +00:00
2016-09-24 13:03:54 +00:00
<para > An executable 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 16:18:47 +00:00
</refsect1>
<refsect1 >
<title > Commands</title>
<para > The following commands are understood:</para>
<variablelist >
<varlistentry >
2019-01-17 18:06:09 +00:00
<term > <command > add <replaceable > KERNEL-VERSION</replaceable> <replaceable > KERNEL-IMAGE</replaceable> [<replaceable > INITRD-FILE</replaceable> ...]</command> </term>
2013-02-22 16:18:47 +00:00
<listitem >
2018-06-22 16:14:22 +00:00
<para > This command expects a kernel version string and a path to a kernel image file as
2019-03-07 20:18:56 +00:00
arguments. <command > kernel-install</command> calls the executables from
<filename > /usr/lib/kernel/install.d/*.install</filename> and
2018-06-22 16:14:22 +00:00
<filename > /etc/kernel/install.d/*.install</filename> with the following arguments:
2019-03-08 18:21:54 +00:00
<programlisting > add <replaceable > KERNEL-VERSION</replaceable> <filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> <replaceable > KERNEL-IMAGE</replaceable> [<replaceable > INITRD-FILE</replaceable> ...]</programlisting>
2013-05-03 04:55:20 +00:00
</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 15:47:34 +00:00
<para > Two default plugins execute the following operations in this case:</para>
2018-06-22 16:14:22 +00: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 15:47:34 +00:00
<listitem > <para > <command > kernel-install</command> creates
<filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> </filename> ,
if enabled (see <varname > $KERNEL_INSTALL_LAYOUT=</varname> ).</para> </listitem>
2018-06-22 16:14:22 +00:00
<listitem > <para > <filename > 50-depmod.install</filename> runs
2020-06-25 12:37:24 +00:00
<citerefentry project= 'man-pages' > <refentrytitle > depmod</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> for the
2018-06-22 16:14:22 +00:00
<replaceable > KERNEL-VERSION</replaceable> .</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 15:47:34 +00:00
<listitem > <para > <filename > 90-loaderentry.install</filename>
copies <replaceable > KERNEL-IMAGE</replaceable> to
2019-03-08 18:21:54 +00:00
<filename > $BOOT/<replaceable > MACHINE-ID</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 15:47:34 +00:00
If <replaceable > INITRD-FILE</replaceable> s are provided, it also copies them to
2019-03-08 18:21:54 +00:00
<filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL_VERSION</replaceable> /<replaceable > INITRD-FILE</replaceable> </filename> .
2018-06-22 16:14:22 +00:00
It also creates a boot loader entry according to the <ulink
url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> in
2019-03-08 18:21:54 +00:00
<filename > $BOOT/loader/entries/<replaceable > MACHINE-ID</replaceable> -<replaceable > KERNEL-VERSION</replaceable> .conf</filename> .
2018-06-22 16:14:22 +00:00
The title of the entry is the <replaceable > PRETTY_NAME</replaceable> parameter specified in
<filename > /etc/os-release</filename> or <filename > /usr/lib/os-release</filename> (if the former is
2019-03-07 20:18:56 +00:00
missing), or "Linux <replaceable > KERNEL-VERSION</replaceable> ", if unset.</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 15:47:34 +00:00
<para > If <varname > $KERNEL_INSTALL_LAYOUT=</varname> is not "bls", this plugin does nothing.</para> </listitem>
2018-06-22 16:14:22 +00:00
</itemizedlist>
2013-02-22 16:18:47 +00:00
</listitem>
</varlistentry>
<varlistentry >
2013-04-30 16:01:47 +00:00
<term > <command > remove <replaceable > KERNEL-VERSION</replaceable> </command> </term>
2013-05-03 04:55:20 +00:00
<listitem >
2018-06-22 16:14:22 +00: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:
2019-03-08 18:21:54 +00:00
<programlisting > remove <replaceable > KERNEL-VERSION</replaceable> <filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> </programlisting>
2013-05-03 04:55:20 +00:00
</para>
2018-06-22 16:14:22 +00:00
<para > Afterwards, <command > kernel-install</command> removes the directory
2019-03-08 18:21:54 +00:00
<filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename>
2018-06-22 16:14:22 +00:00
and its contents.</para>
<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
2019-03-08 18:21:54 +00:00
<filename > $BOOT/loader/entries/<replaceable > MACHINE-ID</replaceable> -<replaceable > KERNEL-VERSION</replaceable> .conf</filename> .</para> </listitem>
2013-04-30 16:01:47 +00: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 15:47:34 +00:00
<listitem > <para > <command > kernel-install</command> removes
<filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> </filename> ,
if enabled (see <varname > $KERNEL_INSTALL_LAYOUT=</varname> ).</para> </listitem>
</itemizedlist>
2013-02-22 16:18:47 +00:00
</listitem>
</varlistentry>
</variablelist>
2019-03-08 18:21:54 +00:00
</refsect1>
2013-02-22 16:18:47 +00:00
2019-03-08 18:21:54 +00:00
<refsect1 >
<title > The <varname > $BOOT</varname> partition</title>
<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
2020-07-06 08:49:59 +00:00
<filename > /efi/</filename> , <filename > /boot/</filename> , and <filename > /boot/efi/</filename>
2019-03-08 18:21:54 +00:00
in turn. The first location where <filename > $BOOT/loader/entries/</filename> or
<filename > $BOOT/$MACHINE_ID/</filename> exists is used.</para>
2013-02-22 16:18:47 +00:00
</refsect1>
2019-03-07 19:49:30 +00: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" />
</variablelist>
</refsect1>
<refsect1 >
<title > Environment variables</title>
2021-03-16 16:38:20 +00:00
2019-03-07 19:49:30 +00:00
<para > If <option > --verbose</option> is used, <varname > $KERNEL_INSTALL_VERBOSE=1</varname> will be set for
the plugins. They may output additional logs in this case.</para>
2021-03-16 16:38:20 +00:00
<para > If <varname > MACHINE_ID=</varname> is set and not empty, it will be used as <replaceable > MACHINE-ID</replaceable> ,
overriding any automatic detection attempts. The value must be a valid machine ID (32 hexadecimal characters).</para>
2021-03-16 16:42:28 +00:00
<para > <varname > KERNEL_INSTALL_MACHINE_ID=</varname> is set for the plugins to the desired <replaceable > MACHINE-ID</replaceable> –
either 32 hexadecimal characters or the special value <literal > Default</literal> .</para>
<para > <varname > KERNEL_INSTALL_BOOT_ROOT=</varname> is set for the plugins to the root directory (mount point, usually) of the hierarchy
2021-12-09 18:52:45 +00:00
where boot-loader entries, kernel images, and associated resources should be placed. Can be overridden by setting <varname > BOOT_ROOT=</varname> .</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 15:47:34 +00:00
2022-01-18 16:40:13 +00:00
<para > <varname > KERNEL_INSTALL_LAYOUT=bls|other|...</varname> is set for the plugins to specify the installation layout.
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 15:47:34 +00:00
Defaults to <option > bls</option> if <filename > $BOOT/<replaceable > MACHINE-ID</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.</para>
2022-01-18 16:40:13 +00:00
<para > <varname > KERNEL_INSTALL_INITRD_GENERATOR=...</varname> is set for plugins to select the initrd generator.
This should be configured as <varname > initrd_generator=</varname> in <filename > install.conf</filename> .
</para>
2022-01-19 11:20:22 +00:00
<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>
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 15:47:34 +00:00
<variablelist >
<varlistentry >
<term > bls</term>
<listitem >
<para > Standard <ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot Loader Specification</ulink> layout,
compatible with <citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> : entries in
<filename > $BOOT/loader/entries/<replaceable > MACHINE-ID</replaceable> -<replaceable > KERNEL-VERSION</replaceable> [+<replaceable > TRIES</replaceable> ].conf</filename> ,
kernel and initrds under <filename > $BOOT/<replaceable > MACHINE-ID</replaceable> /<replaceable > KERNEL-VERSION</replaceable> /</filename> </para>
<para > Provided 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>
2019-03-07 19:49:30 +00:00
</refsect1>
2013-02-22 16:18:47 +00:00
<refsect1 >
<title > Exit status</title>
2016-11-04 12:40:58 +00:00
<para > If every executable returns 0 or 77, 0 is returned, and a non-zero failure code otherwise.</para>
2013-02-22 16:18:47 +00: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 03:44:04 +00:00
<para > Drop-in files which are executed by kernel-install.</para>
2013-02-22 16:18:47 +00:00
</listitem>
</varlistentry>
2013-02-25 18:29:16 +00:00
<varlistentry >
<term >
2021-03-16 16:39:56 +00:00
<filename > /usr/lib/kernel/cmdline</filename>
2013-02-25 18:29:16 +00:00
<filename > /etc/kernel/cmdline</filename>
<filename > /proc/cmdline</filename>
</term>
<listitem >
2018-06-22 16:14:22 +00:00
<para > Read by <filename > 90-loaderentry.install</filename> . The content of the file
<filename > /etc/kernel/cmdline</filename> specifies the kernel command line to use. If that file does not
2021-03-16 16:39:56 +00:00
exist, <filename > /usr/lib/kernel/cmdline</filename> is used. If that also does not exist,
<filename > /proc/cmdline</filename> is used.</para>
2018-06-22 16:14:22 +00: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 18:21:54 +00:00
<filename > $BOOT/loader/entries/<replaceable > MACHINE-ID</replaceable> -<replaceable > KERNEL-VERSION</replaceable> +<replaceable > TRIES</replaceable> .conf</filename> . This
2018-06-22 16:14:22 +00:00
is useful for boot loaders such as
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> which
implement boot attempt counting with a counter embedded in the entry file name.</para>
2013-02-25 18:29:16 +00:00
</listitem>
</varlistentry>
<varlistentry >
<term >
<filename > /etc/machine-id</filename>
</term>
<listitem >
2020-08-06 20:56:36 +00:00
<para > The content of this file specifies the machine identification
2021-03-16 16:38:20 +00:00
<replaceable > MACHINE-ID</replaceable> . If <filename > /etc/machine-id</filename>
cannot be read or is temporary (backed by a file on <constant > tmpfs</constant> ),
<command > kernel-install</command> will use <literal > Default</literal> instead.</para>
2013-02-25 18:29:16 +00:00
</listitem>
</varlistentry>
2021-12-14 16:09:08 +00:00
<varlistentry >
<term >
<filename > /etc/machine-info</filename>
</term>
<listitem >
<para > If this file contains the <varname > KERNEL_INSTALL_MACHINE_ID</varname> variable,
<command > kernel-install</command> will use it as <replaceable > MACHINE-ID</replaceable> instead of
the contents of <filename > /etc/machine-id</filename> . If the variable is not found in
<filename > /etc/machine-info</filename> , <command > kernel-install</command> will try to save the
machine ID it uses to install to <varname > $BOOT</varname> to this file.</para>
</listitem>
</varlistentry>
2013-02-25 18:29:16 +00:00
<varlistentry >
<term >
<filename > /etc/os-release</filename>
2014-06-13 17:45:52 +00:00
<filename > /usr/lib/os-release</filename>
2013-02-25 18:29:16 +00:00
</term>
<listitem >
2021-03-16 16:46:33 +00:00
<para > Read by <filename > 90-loaderentry.install</filename> .
If available, <varname > PRETTY_NAME</varname> is read from these files and used as the title of the boot menu entry.
Otherwise, <literal > Linux <replaceable > KERNEL-VERSION</replaceable> </literal> will be used.</para>
2013-02-25 18:29:16 +00: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 15:47:34 +00:00
<varlistentry >
<term >
<filename > /usr/lib/kernel/install.conf</filename>
<filename > /etc/kernel/install.conf</filename>
</term>
<listitem >
<para > Configuration options for <command > kernel-install</command> ,
as a series of <varname > KEY=</varname> <replaceable > VALUE</replaceable> assignments,
compatible with shell syntax.
See the Environment variables section for supported keys.</para>
</listitem>
</varlistentry>
2013-02-22 16:18:47 +00:00
</variablelist>
</refsect1>
<refsect1 >
<title > See Also</title>
<para >
2013-02-25 18:29:16 +00:00
<citerefentry > <refentrytitle > machine-id</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
<citerefentry > <refentrytitle > os-release</refentrytitle> <manvolnum > 5</manvolnum> </citerefentry> ,
2020-06-25 12:37:24 +00:00
<citerefentry project= 'man-pages' > <refentrytitle > depmod</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> ,
2018-06-22 16:14:22 +00:00
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> ,
2018-10-12 12:00:20 +00:00
<ulink url= "https://systemd.io/BOOT_LOADER_SPECIFICATION" > Boot Loader Specification</ulink>
2013-02-22 16:18:47 +00:00
</para>
</refsect1>
</refentry>
