1
0
mirror of https://github.com/systemd/systemd.git synced 2025-01-11 09:18:07 +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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2022-07-01 10:52:12 +02:00
parent 5e193bef89
commit f5f5047ff1

View File

@ -144,6 +144,7 @@
<refsect1> <refsect1>
<title>The <varname>$BOOT</varname> partition</title> <title>The <varname>$BOOT</varname> partition</title>
<para>The partition where the kernels and <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot <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>. Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
<command>kernel-install</command> determines the location of this partition by checking <command>kernel-install</command> determines the location of this partition by checking
@ -173,77 +174,91 @@
<refsect1> <refsect1>
<title>Environment variables</title> <title>Environment variables</title>
<para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be set for <refsect2>
the plugins. They may output additional logs in this case.</para> <title>Environment variables exported for plugins</title>
<para>If <varname>$MACHINE_ID</varname> is set and not empty when <command>kernel-install</command> is <para>If <option>--verbose</option> is used, <varname>$KERNEL_INSTALL_VERBOSE=1</varname> will be
invoked, it will be used as <replaceable>MACHINE-ID</replaceable>, overriding any automatic detection exported for plugins. They may output additional logs in this case.</para>
attempts. The value must be a valid machine ID (32 hexadecimal characters).</para>
<para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired <para><varname>$KERNEL_INSTALL_MACHINE_ID</varname> is set for the plugins to the desired machine-id to
<replaceable>MACHINE-ID</replaceable> to use. It's always a 128bit ID, and typically the ID from use. It's always a 128-bit ID. Normally it's read from <filename>/etc/machine-id</filename>, but it can
<filename>/etc/machine-id</filename> or the one passed in via <varname>$MACHINE_ID</varname>. (If no also be overriden via <varname>$MACHINE_ID</varname> (see below). If not specified via these methods a
machine ID was specified via these methods it might be generated randomly by fallback value will generated by <command>kernel-install</command>, and used only for a single
<command>kernel-install</command>, in which case it only applies to this invocation.)</para> invocation.</para>
<para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry "token" <para><varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> is set for the plugins to the desired entry
to use. It's an identifier that shall be used to identify the local installation, and is often the "token" to use. It's an identifier that shall be used to identify the local installation, and is often
machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a different the machine ID, i.e. same as <varname>$KERNEL_INSTALL_MACHINE_ID</varname>, but might also be a
type of identifier, for example a fixed string or the <varname>ID=</varname>, 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 <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 will be used to name Boot Loader Specification entries, or the directories the kernel image and initial
RAM disk images are placed into. Note that while oftentimes RAM disk images are placed into.</para>
<varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are set
to the same value, the latter is guaranteed to be a valid 32 character ID in lowercase hexadecimals while
the former can be any short string. The entry token to use is read from
<filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a few possible candidates below the
<varname>$BOOT</varname> are searched for Boot Loader Specification Type 1 entry directories, and if
found the entry token is derived from that. If that is not successful the machine ID is used as
fallback.</para>
<para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the <para>Note that while <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and
root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and <varname>$KERNEL_INSTALL_MACHINE_ID</varname> are often set to the same value, the latter is guaranteed
associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The
(EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can be entry token to use is read from <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a
overridden by setting <varname>$BOOT_ROOT</varname>.</para> 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_LAYOUT=bls|other|...</varname> is set for the plugins to specify the <para><varname>$KERNEL_INSTALL_BOOT_ROOT</varname> is set for the plugins to the absolute path of the
installation layout. Defaults to <option>bls</option> if root directory (mount point, usually) of the hierarchy where boot loader entries, kernel images, and
<filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or <option>other</option> associated resources should be placed. This usually is the path where the XBOOTLDR partition or the ESP
otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout, it's (EFI System Partition) are mounted, and also conceptually referred to as <varname>$BOOT</varname>. Can
encouraged to declare its own layout name and configure <varname>layout=</varname> in be overridden by setting <varname>$BOOT_ROOT</varname> (see below).</para>
<filename>install.conf</filename> upon initial installation. The following values are currently
understood:</para>
<variablelist> <para><varname>$KERNEL_INSTALL_LAYOUT=bls|other|...</varname> is set for the plugins to specify the
<varlistentry> installation layout. Defaults to <option>bls</option> if
<term>bls</term> <filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable></filename> exists, or <option>other</option>
<listitem> otherwise. Additional layout names may be defined by convention. If a plugin uses a special layout,
<para>Standard <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader it's encouraged to declare its own layout name and configure <varname>layout=</varname> in
Specification</ulink> Type #1 layout, compatible with <filename>install.conf</filename> upon initial installation. The following values are currently
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>: understood:</para>
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>
<para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> is set for plugins to select the initrd <variablelist>
generator. This may be configured as <varname>initrd_generator=</varname> in <varlistentry>
<filename>install.conf</filename>. See below.</para> <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>
<para><varname>$KERNEL_INSTALL_STAGING_AREA</varname> is set for plugins to a path to a directory. <para><varname>$KERNEL_INSTALL_INITRD_GENERATOR</varname> is set for plugins to select the initrd
Plugins may drop files in that directory, and they will be installed as part of the loader entry, based generator. This may be configured as <varname>initrd_generator=</varname> in
on the file name and extension.</para> <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>
<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>
<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>
<para>Those variables may also be set in <filename>install.conf</filename>. Variables set in the
environment take precedence over the values specified in the config file.</para>
</refsect2>
</refsect1> </refsect1>
<refsect1> <refsect1>
@ -327,8 +342,18 @@
<listitem> <listitem>
<para>Configuration options for <command>kernel-install</command>, as a series of <para>Configuration options for <command>kernel-install</command>, as a series of
<varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell <varname>KEY=</varname><replaceable>VALUE</replaceable> assignments, compatible with shell
syntax. This currently supports two keys: <varname>layout=</varname> and syntax, following the same rules as described in
<varname>initrd_generator=</varname>, for details see the Environment variables section above.</para> <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.
</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>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>