shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-27 03:21:32 +03:00
Code
e228d48b9e
systemd-stable/man/kernel-install.xml

388 lines
21 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
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">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
man: properly conditionalize kernel-install man page Change f887eab1da85d0053321d43228042d90720eb77e conditionalized the building of ther kenel-install man page in the generated meson output, instead of the source in the XML markup. Thus, whenever the rules file is updated the conditionalization is lost. Correct that. Follow-up for: f887eab1da85d0053321d43228042d90720eb77e
2022-04-04 16:38:33 +03:00
<refentry id="kernel-install" conditional='ENABLE_KERNEL_INSTALL'
kernel-install: add --verbose This makes it easier to see what is going on. Documentation for --verbose and --help is added to the man page. Our plugins are updated to also log a bit.
2019-03-07 22:49:30 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
kernel-install: add kernel-install tool
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>
<refpurpose>Add and remove kernel and initramfs images to and from /boot</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
man: add various filenames to the index Everything which is an absolute filename marked with <filename></filename> lands in the index, unless noindex= attribute is present. Should make it easier for people to find stuff when they are looking at a file on disk. Various formatting errors in manpages are fixed, kernel-install(1) is restored to formatting sanity.
2013-05-03 08:55:20 +04:00
<command>kernel-install</command>
<arg choice="plain">COMMAND</arg>
kernel-install: add --verbose This makes it easier to see what is going on. Documentation for --verbose and --help is added to the man page. Our plugins are updated to also log a bit.
2019-03-07 22:49:30 +03:00
<arg choice="opt" rep="repeat">OPTIONS</arg>
man: add various filenames to the index Everything which is an absolute filename marked with <filename></filename> lands in the index, unless noindex= attribute is present. Should make it easier for people to find stuff when they are looking at a file on disk. Various formatting errors in manpages are fixed, kernel-install(1) is restored to formatting sanity.
2013-05-03 08:55:20 +04:00
<arg choice="plain"><replaceable>KERNEL-VERSION</replaceable></arg>
Improve kernel-install support for initrd files. (#11281) The current support in kernel-install for initrd images doesn't copy over the initrd file or allow a means for it to be specified (it requires a specific filename in a particular directory). This patchset adds support for (optionally) providing the name of initial ramdisk file to copied over and used by kernel-install.
2018-12-29 22:01:10 +03:00
<arg choice="plain"><replaceable>KERNEL-IMAGE</replaceable></arg>
Add multiple initrd file support to kernel-install Instead of having just a single INITRD field, add support for all additional parameters being INITRD fields in order. Signed-off-by: Mike Auty <mike.auty@gmail.com>
2019-01-17 21:06:09 +03:00
<arg choice="opt" rep="repeat"><replaceable>INITRD-FILE</replaceable></arg>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
man: say $BOOT not /boot in kernel-install(8)
2019-03-08 21:21:54 +03: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
tree-wide: fixes for assorted grammar and spelling issues Fixes #16363. Also includes some changes where I generalized the pattern.
2020-07-06 11:49:59 +03:00
<filename>/boot/</filename>, <filename>/efi/</filename>, or <filename>/boot/efi/</filename>, see below.
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</para>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</refsect1>
<refsect1>
<title>Commands</title>
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
Add multiple initrd file support to kernel-install Instead of having just a single INITRD field, add support for all additional parameters being INITRD fields in order. Signed-off-by: Mike Auty <mike.auty@gmail.com>
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
<listitem>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
<para>This command expects a kernel version string and a path to a kernel image file as
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
arguments. Optionally, one or more initial RAM disk 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
<filename>/etc/kernel/install.d/*.install</filename> (i.e. the plugins) with the following
arguments:</para>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
<para>The third argument directly refers to the path where to place kernel images, initial RAM disk
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>
man: add various filenames to the index Everything which is an absolute filename marked with <filename></filename> lands in the index, unless noindex= attribute is present. Should make it easier for people to find stuff when they are looking at a file on disk. Various formatting errors in manpages are fixed, kernel-install(1) is restored to formatting sanity.
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>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
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
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
<listitem><para><filename>50-depmod.install</filename> runs
man: fix links to various external man pages In cases where we used both die-net and man-pages for the same reference, I switched to use man-pages everywhere.
2020-06-25 15:37:24 +03:00
<citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry> for the
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
<replaceable>KERNEL-VERSION</replaceable>.</para></listitem>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
It also creates a boot loader entry according to the <ulink
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>.
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
kernel-install: create the entry directory only if $BOOT/$MACHINE_ID exists Things are currently fairly ugly in Fedora: we create $BOOT/$MACHINE_ID/$KERNEL_VERSION/, and then 20-grub.install that is installed by grub2-common.rpm wants to remove that directory before 50-dracut.install get a chance to run. 50-dracut.install checks for the presence of that directory to decide where to install the kernel. So let's make the creation of the directory conditional. Previous commit changes bootctl install to create $BOOT/$MACHINE_ID, and this commit makes kernel-install not create it. In effect, the entry directory will only be created if 'bootctl install' or something else created the parent directory. https://bugzilla.redhat.com/show_bug.cgi?id=1648907
2019-03-07 23:18:56 +03:00
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<para>If <varname>$KERNEL_INSTALL_LAYOUT</varname> is not "bls", this plugin does nothing.</para></listitem>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
</itemizedlist>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
<varlistentry>
kernel-install: add default install scripts Do the depmod in the kernel-install hooks, so hooks can produce/install kernel modules and be part of the depmod. Also move the basic boot loader entry creation and removal to a plugin script. If PRETTY_NAME is not defined in /etc/os-release, fallback to PRETTY_NAME="Linux $KERNEL_VERSION". Add documentation for everything in the man page.
2013-04-30 20:01:47 +04:00
<term><command>remove <replaceable>KERNEL-VERSION</replaceable></command></term>
man: add various filenames to the index Everything which is an absolute filename marked with <filename></filename> lands in the index, unless noindex= attribute is present. Should make it easier for people to find stuff when they are looking at a file on disk. Various formatting errors in manpages are fixed, kernel-install(1) is restored to formatting sanity.
2013-05-03 08:55:20 +04:00
<listitem>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
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:
man: add various filenames to the index Everything which is an absolute filename marked with <filename></filename> lands in the index, unless noindex= attribute is present. Should make it easier for people to find stuff when they are looking at a file on disk. Various formatting errors in manpages are fixed, kernel-install(1) is restored to formatting sanity.
2013-05-03 08:55:20 +04:00
</para>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
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
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</variablelist>
man: say $BOOT not /boot in kernel-install(8)
2019-03-08 21:21:54 +03:00
</refsect1>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
man: say $BOOT not /boot in kernel-install(8)
2019-03-08 21:21:54 +03:00
<refsect1>
<title>The <varname>$BOOT</varname> partition</title>
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
2022-07-01 11:52:12 +03:00
man: say $BOOT not /boot in kernel-install(8)
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
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</refsect1>
kernel-install: add --verbose This makes it easier to see what is going on. Documentation for --verbose and --help is added to the man page. Our plugins are updated to also log a bit.
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" />
meson: make kernel-install a template file, add --version, add to tests In --help output, change "$0" → "kernel-install". We generally don't include the full path in --help output, and let's not do this here either. kernel-install is now in build/ directly, not in the subdirectory.
2022-04-05 19:18:56 +03:00
<xi:include href="standard-options.xml" xpointer="version" />
kernel-install: add --verbose This makes it easier to see what is going on. Documentation for --verbose and --help is added to the man page. Our plugins are updated to also log a bit.
2019-03-07 22:49:30 +03:00
</variablelist>
</refsect1>
<refsect1>
<title>Environment variables</title>
kernel-install: respect $MACHINE_ID and ignore /etc/machine-id if on tmpfs Confer https://github.com/systemd/systemd/pull/19006#issuecomment-800234022: On some systems it's the admin's explicit choice not to to have the machine ID leak into the ESP On some systems the machine ID is transient, generated at every boot, and hence should not be written to the ESP
2021-03-16 19:38:20 +03:00
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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
tree-wide: fix typo
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
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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>
kernel-install: add "$KERNEL_INSTALL_STAGING_AREA" directory The general approach of kernel-install was that each plugin would drop in some files into the entry directory. But this doesn't scale well, because if we have multiple initrd generators, or multiple initrds, each generator would need to recreate the logic to put the generated files in the right place. Also, effective cleanup is impossible if anything goes wrong on the way, so we could end up with unused files in $BOOT. So let's invert the process: plugins drop files into $KERNEL_INSTALL_STAGING_AREA, and at the end 90-loaderentry.install DTRT with those files. This allow new plugins like 50-mkosi-initrd.install to be significantly simpler.
2022-01-19 14:20:22 +03:00
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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>
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
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>
kernel-install: allow overriding the plugin list too The use of IFS=<newline> is dropped. Let's just iterate over the list, using any whitespace as separator.
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>
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
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
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
2022-07-01 11:52:12 +03:00
environment take precedence over the values specified in the config file.</para>
</refsect2>
kernel-install: add --verbose This makes it easier to see what is going on. Documentation for --verbose and --help is added to the man page. Our plugins are updated to also log a bit.
2019-03-07 22:49:30 +03:00
</refsect1>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
<refsect1>
<title>Exit status</title>
man: update kernel-install(8) to match reality (#4563)
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>
kernel-install: add kernel-install tool
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>
man: more grammar improvements - place commas - expand contractions (this is written prose :) - add some missing words
2013-07-02 07:44:04 +04:00
<para>Drop-in files which are executed by kernel-install.</para>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</listitem>
</varlistentry>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
<varlistentry>
<term>
kernel-install: note that 90-loaderentry will also use /usr/lib/k/cmdline
2021-03-16 19:39:56 +03:00
<filename>/usr/lib/kernel/cmdline</filename>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
<filename>/etc/kernel/cmdline</filename>
<filename>/proc/cmdline</filename>
</term>
<listitem>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
<para>Read by <filename>90-loaderentry.install</filename>. The content of the file
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
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>
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
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
man: say $BOOT not /boot in kernel-install(8)
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
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
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
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
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>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
</listitem>
</varlistentry>
<varlistentry>
<term>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<filename>/etc/kernel/entry-token</filename>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
</term>
<listitem>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
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>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
</listitem>
</varlistentry>
kernel-install: Introduce KERNEL_INSTALL_MACHINE_ID in /etc/machine-info If KERNEL_INSTALL_MACHINE_ID is defined in /etc/machine-info, prefer it over the machine ID from /etc/machine-id. If a machine ID is defined in neither /etc/machine-info nor in /etc/machine-id, generate a new UUID and try to write it to /etc/machine-info as KERNEL_INSTALL_MACHINE_ID and use it as the machine ID if writing it to /etc/machine-info succeeds. In practice, this means we have a more robust fallback if there's no machine ID in /etc/machine-id than just using "Default" and allows image builders to force kernel-install to use KERNEL_INSTALL_MACHINE_ID by simply writing it to /etc/machine-info themselves.
2021-12-14 19:09:08 +03:00
<varlistentry>
<term>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<filename>/etc/machine-id</filename>
kernel-install: Introduce KERNEL_INSTALL_MACHINE_ID in /etc/machine-info If KERNEL_INSTALL_MACHINE_ID is defined in /etc/machine-info, prefer it over the machine ID from /etc/machine-id. If a machine ID is defined in neither /etc/machine-info nor in /etc/machine-id, generate a new UUID and try to write it to /etc/machine-info as KERNEL_INSTALL_MACHINE_ID and use it as the machine ID if writing it to /etc/machine-info succeeds. In practice, this means we have a more robust fallback if there's no machine ID in /etc/machine-id than just using "Default" and allows image builders to force kernel-install to use KERNEL_INSTALL_MACHINE_ID by simply writing it to /etc/machine-info themselves.
2021-12-14 19:09:08 +03:00
</term>
<listitem>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<para>The content of this file specifies the machine identification
<replaceable>MACHINE-ID</replaceable>.</para>
kernel-install: Introduce KERNEL_INSTALL_MACHINE_ID in /etc/machine-info If KERNEL_INSTALL_MACHINE_ID is defined in /etc/machine-info, prefer it over the machine ID from /etc/machine-id. If a machine ID is defined in neither /etc/machine-info nor in /etc/machine-id, generate a new UUID and try to write it to /etc/machine-info as KERNEL_INSTALL_MACHINE_ID and use it as the machine ID if writing it to /etc/machine-info succeeds. In practice, this means we have a more robust fallback if there's no machine ID in /etc/machine-id than just using "Default" and allows image builders to force kernel-install to use KERNEL_INSTALL_MACHINE_ID by simply writing it to /etc/machine-info themselves.
2021-12-14 19:09:08 +03:00
</listitem>
</varlistentry>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
<varlistentry>
<term>
<filename>/etc/os-release</filename>
os-release: define /usr/lib/os-release as fallback for /etc/os-release The file should have been in /usr/lib/ in the first place, since it describes the OS container in /usr (and not the configuration in /etc), hence, let's support os-release files in /usr/lib as fallback if no version in /etc exists, following the usual override logic. A prior commit already enabled tmpfiles to create /etc/os-release as a symlink to /usr/lib/os-release should it be missing, thus providing nice compatibility with applications only checking in /etc. While it's probably a good idea if all apps check both locations via a fallback logic, it is only necessary in the early boot process, as long as the /etc/os-release symlink has not been restored, in case we boot with an empty /etc.
2014-06-13 21:45:52 +04:00
<filename>/usr/lib/os-release</filename>
kernel-install(8): add documentation about the configuration files used
2013-02-25 22:29:16 +04:00
</term>
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
2022-02-10 17:27:45 +03:00
<listitem>
kernel-install: note the default $PRETTY_NAME if os-release wasn't found and that only 90-loaderentry uses it
2021-03-16 19:46:33 +03:00
<para>Read by <filename>90-loaderentry.install</filename>.
man: document recent changes This drops documentation of KERNEL_INSTALL_MACHINE_ID as machine-info field (though we'll still read it for compat). This updates the kernel-install man page to always say "ENTRY-TOKEN" instead of "MACHINE-ID" where appropriate, to clear the confusion up between the two. This also tries to fix how we denote env vars (always prefix with $ and without = suffix), and other vars (without $ but with = suffix) Other fixes.
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.
kernel-install: note the default $PRETTY_NAME if os-release wasn't found and that only 90-loaderentry uses it
2021-03-16 19:46:33 +03:00
Otherwise, <literal>Linux <replaceable>KERNEL-VERSION</replaceable></literal> will be used.</para>
kernel-install(8): add documentation about the configuration files used
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>
kernel-install: list fields we honour in /etc/kernel/install.conf
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
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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.
kernel-install: allow overriding the path to config files It's pretty hard to write tests without this. I started out by adding separate variables for each of the files we read, but there's a bunch, and in practice it's good enough to just override the directory.
2022-07-01 11:58:01 +03:00
<varname>$KERNEL_INSTALL_CONF_ROOT</varname> may be used to override the path.
man: rework documentation of kernel-install config Variables read by kernel-install and those exported by it were described without any clear separation. So in particular it was pretty hard to answer a question like "what variables can be set in install.conf". The in- and out-variables are now split into two separate subsections.
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>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
kernel-install(8): add documentation about the configuration files used
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>,
man: fix links to various external man pages In cases where we used both die-net and man-pages for the same reference, I switched to use man-pages everywhere.
2020-06-25 15:37:24 +03:00
<citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
man: update kernel-install(8) documentation Many general updates, but most importantly, document the /etc/kernel/tries logic briefly.
2018-06-22 19:14:22 +03:00
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
man: change all github links to use systemd.io domain instead We shouldn't push people towards the git UI, but instead just refernce the public version on the systemd.io domain.
2018-10-12 15:00:20 +03:00
<ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>
kernel-install: add kernel-install tool
2013-02-22 20:18:47 +04:00
</para>
</refsect1>
</refentry>
Copy Permalink