mirror of
https://github.com/morgan9e/systemd
synced 2026-04-14 08:25:20 +09:00
9420a0e6cb
The bless-boot logic currently assumes that if the name of the boot entry reported via the EFI var matches the name on disk that the state is "indeterminate", as we haven't counted down the counter (to mark it bad) or drop the counter (to mark it good) yet. But there's one corner case we so far didn't care about: what if the entry already reached 0 left tries in a previous boot, i.e. if the user invoked an entry already known to be completely bad. In that case we'd still return "indeterminate", but that's kinda misleading, because we *know* the currently booted entry is bad, however we inherited that fact from a previous boot, we didn't determine it on the current. hence, let's introduce a new status we report in this case, that is both distinct from "bad" (which indicates whether the *current* boot is bad) and "indirect" (which indicates the current boot has not been decided on yet): "dirty". Why "dirty"? To mirror "clean" which we already have, which indicates a boot already marked good in a previous boot, which is a relatively symmetric state. This is a really weak api break of sorts, because it introduces a new state we never reported before, but I think it's fine, because the old reporting was just wrong, and in a way this is bugfix, that we now report correctly something where previously returned kind of rubbish (though systematic rubbish). Replaces: #37350
130 lines
6.7 KiB
XML
130 lines
6.7 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refentry id="systemd-bless-boot.service" conditional='ENABLE_BOOTLOADER HAVE_BLKID'
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
|
|
<refentryinfo>
|
|
<title>systemd-bless-boot.service</title>
|
|
<productname>systemd</productname>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>systemd-bless-boot.service</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>systemd-bless-boot.service</refname>
|
|
<refname>systemd-bless-boot</refname>
|
|
<refpurpose>Mark current boot process as successful</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<para><filename>systemd-bless-boot.service</filename></para>
|
|
<para><filename>/usr/lib/systemd/systemd-bless-boot</filename></para>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para><filename>systemd-bless-boot.service</filename> is a system service that marks the current boot process as
|
|
successful. It's automatically pulled into the initial transaction when
|
|
<citerefentry><refentrytitle>systemd-bless-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
|
|
detects that <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> style
|
|
boot counting is used.</para>
|
|
|
|
<para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable (of the
|
|
vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</constant>), which is passed from the boot loader to the
|
|
OS. It contains a file system path (relative to the EFI system partition) of the <ulink
|
|
url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> compliant boot loader entry
|
|
file or unified kernel image file that was used to boot up the
|
|
system. <command>systemd-bless-boot.service</command> removes the two "tries done" and "tries left" numeric boot
|
|
counters from the filename, which indicates to future invocations of the boot loader that the entry has completed
|
|
booting successfully at least once. (This service will hence rename the boot loader entry file or unified kernel
|
|
image file on the first successful boot.)</para>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>The <filename>/usr/lib/systemd/systemd-bless-boot</filename> executable may also be invoked from the
|
|
command line, taking one of the following command arguments:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>status</option></term>
|
|
|
|
<listitem><para>The current status of the boot loader entry file or unified kernel image file is
|
|
shown. This outputs one of <literal>good</literal>, <literal>bad</literal>,
|
|
<literal>indeterminate</literal>, <literal>clean</literal>, <literal>dirty</literal>, depending on
|
|
the state and previous invocations of the command. The string <literal>indeterminate</literal> is
|
|
shown initially after boot, before it has been marked as "good" or "bad". The string
|
|
<literal>good</literal> is shown after the boot was marked as "good" with the <option>good</option>
|
|
command below, and "bad" conversely after the <option>bad</option> command was invoked. The string
|
|
<literal>clean</literal> is returned when boot counting is currently not in effect (which includes
|
|
the case where the current entry was already marked as persistently good). The string
|
|
<literal>dirty</literal> is returned when the system is booted up with a known-bad kernel (i.e. one
|
|
where the tries left counter has previously reached zero already).</para>
|
|
|
|
<para>This command is implied if no command argument is specified.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>good</option></term>
|
|
|
|
<listitem><para>When invoked, the current boot loader entry file or unified kernel image file will be marked as
|
|
"good", executing the file rename operation described above. This command is intended to be invoked at the end
|
|
of a successful boot. The <filename>systemd-bless-boot.service</filename> unit invokes this
|
|
command.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>bad</option></term>
|
|
|
|
<listitem><para>When called the "tries left" counter in the boot loader entry file name or unified kernel image
|
|
file name is set to zero, marking the boot loader entry or kernel image as "bad", so that the boot loader will not
|
|
consider it anymore on future boots (at least as long as there are other entries available that are not marked
|
|
"bad" yet). This command is normally not executed, but can be used to instantly put an end to the boot counting
|
|
logic if a problem is detected and persistently mark the boot entry as bad.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>indeterminate</option></term>
|
|
|
|
<listitem><para>This command undoes any marking of the current boot loader entry file or unified
|
|
kernel image file as good or bad. This is implemented by renaming the boot loader entry file or
|
|
unified kernel image file back to the path encoded in the <varname>LoaderBootCountPath</varname> EFI
|
|
variable. Note that operation will fail if the current kernel is not booted with boot counting
|
|
enabled (i.e. if the EFI variable is not set). If the boot counter already reached zero tries left on
|
|
a previous boot this operation will fail too: once an entry is marked <option>bad</option> it can
|
|
only be reset to <option>good</option> again, but not to <option>indeterminate</option>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
|
|
</varlistentry>
|
|
|
|
<xi:include href="standard-options.xml" xpointer="help" />
|
|
<xi:include href="standard-options.xml" xpointer="version" />
|
|
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
<para><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|