man/systemd-bless-boot.service.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-bless-boot.service" conditional='ENABLE_BOOTLOADER'
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>systemd-bless-boot.service</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>systemd-bless-boot.service</refentrytitle>
  16     <manvolnum>8</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>systemd-bless-boot.service</refname>
  21     <refname>systemd-bless-boot</refname>
  22     <refpurpose>Mark current boot process as successful</refpurpose>
  23   </refnamediv>
  24
  25   <refsynopsisdiv>
  26     <para><filename>systemd-bless-boot.service</filename></para>
  27     <para><filename>/usr/lib/systemd/systemd-bless-boot</filename></para>
  28   </refsynopsisdiv>
  29
  30   <refsect1>
  31     <title>Description</title>
  32
  33     <para><filename>systemd-bless-boot.service</filename> is a system service that marks the current boot process as
  34     successful. It's automatically pulled into the initial transaction when
  35     <citerefentry><refentrytitle>systemd-bless-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  36     detects that <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> style
  37     boot counting is used.</para>
  38
  39     <para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable (of the
  40     vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4</constant>), which is passed from the boot loader to the
  41     OS. It contains a file system path (relative to the EFI system partition) of the <ulink
  42     url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> compliant boot loader entry
  43     file or unified kernel image file that was used to boot up the
  44     system. <command>systemd-bless-boot.service</command> removes the two 'tries done' and 'tries left' numeric boot
  45     counters from the filename, which indicates to future invocations of the boot loader that the entry has completed
  46     booting successfully at least once. (This service will hence rename the boot loader entry file or unified kernel
  47     image file on the first successful boot.)</para>
  48   </refsect1>
  49
  50   <refsect1>
  51     <title>Options</title>
  52
  53     <para>The <filename>/usr/lib/systemd/systemd-bless-boot</filename> executable may also be invoked from the
  54     command line, taking one of the following command arguments:</para>
  55
  56     <variablelist>
  57       <varlistentry>
  58         <term><option>status</option></term>
  59
  60         <listitem><para>The current status of the boot loader entry file or unified kernel image file is shown. This
  61         outputs one of <literal>good</literal>, <literal>bad</literal>, <literal>indeterminate</literal>,
  62         <literal>clean</literal>, depending on the state and previous invocations of the command. The string
  63         <literal>indeterminate</literal> is shown initially after boot, before it has been marked as "good" or
  64         "bad". The string <literal>good</literal> is shown after the boot was marked as "good" with the
  65         <option>good</option> command below, and "bad" conversely after the <option>bad</option> command was
  66         invoked. The string <literal>clean</literal> is returned when boot counting is currently not in effect.</para>
  67
  68         <para>This command is implied if no command argument is specified.</para>
  69
  70         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
  71       </varlistentry>
  72
  73       <varlistentry>
  74         <term><option>good</option></term>
  75
  76         <listitem><para>When invoked, the current boot loader entry file or unified kernel image file will be marked as
  77         "good", executing the file rename operation described above. This command is intended to be invoked at the end
  78         of a successful boot. The <filename>systemd-bless-boot.service</filename> unit invokes this
  79         command.</para>
  80
  81         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
  82       </varlistentry>
  83
  84       <varlistentry>
  85         <term><option>bad</option></term>
  86
  87         <listitem><para>When called the 'tries left' counter in the boot loader entry file name or unified kernel image
  88         file name is set to zero, marking the boot loader entry or kernel image as "bad", so that the boot loader won't
  89         consider it anymore on future boots (at least as long as there are other entries available that are not marked
  90         "bad" yet). This command is normally not executed, but can be used to instantly put an end to the boot counting
  91         logic if a problem is detected and persistently mark the boot entry as bad.</para>
  92
  93         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
  94       </varlistentry>
  95
  96       <varlistentry>
  97         <term><option>indeterminate</option></term>
  98
  99         <listitem><para>This command undoes any marking of the current boot loader entry file or unified kernel image
 100         file as good or bad. This is implemented by renaming the boot loader entry file or unified kernel image file
 101         back to the path encoded in the <varname>LoaderBootCountPath</varname> EFI variable.</para>
 102
 103         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 104       </varlistentry>
 105
 106       <xi:include href="standard-options.xml" xpointer="help" />
 107       <xi:include href="standard-options.xml" xpointer="version" />
 108
 109     </variablelist>
 110   </refsect1>
 111
 112   <refsect1>
 113     <title>See Also</title>
 114     <para><simplelist type="inline">
 115       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 116       <member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 117       <member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 118     </simplelist></para>
 119   </refsect1>
 120
 121 </refentry>