man/bootctl.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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   5
   6 <refentry id="bootctl" conditional='ENABLE_EFI'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>bootctl</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>bootctl</refentrytitle>
  15     <manvolnum>1</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>bootctl</refname>
  20     <refpurpose>Control the firmware and boot manager settings</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <cmdsynopsis>
  25       <command>bootctl</command>
  26       <arg choice="opt" rep="repeat">OPTIONS</arg>
  27       <arg choice="req">COMMAND</arg>
  28     </cmdsynopsis>
  29   </refsynopsisdiv>
  30
  31   <refsect1>
  32     <title>Description</title>
  33
  34     <para><command>bootctl</command> can check the EFI boot loader status, list available boot loaders and boot loader
  35     entries, and install, update, or remove the
  36     <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot loader on the
  37     current system.</para>
  38   </refsect1>
  39
  40   <refsect1>
  41     <title>Commands</title>
  42     <variablelist>
  43
  44       <varlistentry>
  45         <term><option>status</option></term>
  46
  47         <listitem><para>Shows brief information about the system firmware, the boot loader that was used to boot the
  48         system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot
  49         loaders and the current default boot loader entry. If no command is specified, this is the implied
  50         default.</para></listitem>
  51       </varlistentry>
  52
  53       <varlistentry>
  54         <term><option>install</option></term>
  55
  56         <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
  57         <command>systemd-boot</command> will be stored as the EFI default/fallback loader at
  58         <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added
  59         to the top of the firmware's boot loader list.</para></listitem>
  60       </varlistentry>
  61
  62       <varlistentry>
  63         <term><option>update</option></term>
  64
  65         <listitem><para>Updates all installed versions of
  66         <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
  67         available version is newer than the version installed in the EFI system partition. This also includes the EFI
  68         default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
  69         loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
  70       </varlistentry>
  71
  72       <varlistentry>
  73         <term><option>remove</option></term>
  74
  75         <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
  76         and the firmware's boot loader list.</para></listitem>
  77       </varlistentry>
  78
  79       <varlistentry>
  80         <term><option>is-installed</option></term>
  81
  82         <listitem><para>Checks whether <command>systemd-boot</command> is installed in the ESP. Note that a
  83         single ESP might host multiple boot loaders; this hence checks whether
  84         <command>systemd-boot</command> is one (of possibly many) installed boot loaders — and neither
  85         whether it is the default nor whether it is registered in any EFI variables.</para></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>random-seed</option></term>
  90
  91         <listitem><para>Generates a random seed and stores it in the EFI System Partition, for use by the
  92         <command>systemd-boot</command> boot loader. Also, generates a random 'system token' and stores it
  93         persistently as an EFI variable, if one has not been set before. If the boot loader finds the random
  94         seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the
  95         OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS
  96         is credited to the kernel's entropy pool by the system manager during early boot, and permits
  97         userspace to boot up with an entropy pool fully initialized very early on. Also see
  98         <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  99
 100         <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
 101         information.</para></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><option>systemd-efi-options</option> <optional><replaceable>STRING</replaceable></optional></term>
 106
 107         <listitem><para>When called without the optional argument, prints the current value of the
 108         <literal>SystemdOptions</literal> EFI variable. When called with an argument, sets the
 109         variable to that value. See
 110         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 111         for the meaning of that variable.</para></listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
 116
 117         <listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
 118         boolean argument which controls whether to show the firmware setup on next system reboot. If the
 119         argument is omitted shows the current status of the flag, or whether the flag is supported. This
 120         controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more
 121         low-level and allows setting the flag independently from actually requesting a
 122         reboot.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>list</option></term>
 127
 128         <listitem><para>Shows all available boot loader entries implementing the <ulink
 129         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
 130         Specification</ulink>, as well as any other entries discovered or automatically generated by the boot
 131         loader.</para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><option>set-default</option> <replaceable>ID</replaceable></term>
 136         <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
 137
 138         <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string as argument. The
 139         <option>set-oneshot</option> command will set the default entry only for the next boot, the
 140         <option>set-default</option> will set it persistently for all future boots.</para></listitem>
 141       </varlistentry>
 142
 143     </variablelist>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Options</title>
 148     <para>The following options are understood:</para>
 149
 150     <variablelist>
 151       <varlistentry>
 152         <term><option>--esp-path=</option></term>
 153         <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>,
 154         <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn.  It is
 155         recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>--boot-path=</option></term>
 160         <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink
 161         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not
 162         specified, <filename>/boot/</filename> is checked.  It is recommended to mount the Extended Boot
 163         Loader partition to <filename>/boot/</filename>, if possible.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>-p</option></term>
 168         <term><option>--print-esp-path</option></term>
 169         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
 170         to the EFI System Partition (ESP) to standard output and exits.</para></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><option>-x</option></term>
 175         <term><option>--print-boot-path</option></term>
 176         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
 177         to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard
 178         output and exit. This command is useful to determine where to place boot loader entries, as they are
 179         preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para>
 180
 181         <para>Boot Loader Specification Type #1 entries should generally be placed in the directory
 182         <literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as
 183         indication that boot loader entry support is available on the system. Similarly, Boot Loader
 184         Specification Type #2 entries should be placed in the directory <literal>$(bootctl
 185         -x)/EFI/Linux/</literal>.</para>
 186
 187         <para>Note that this option (similar to the <option>--print-booth-path</option> option mentioned
 188         above), is available independently from the boot loader used, i.e. also without
 189         <command>systemd-boot</command> being installed.</para></listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term><option>--no-variables</option></term>
 194         <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><option>--graceful</option></term>
 199         <listitem><para>Ignore failure when the EFI System Partition cannot be found, or when EFI variables
 200         cannot be written. Currently only applies to random seed operations.</para></listitem>
 201       </varlistentry>
 202
 203       <xi:include href="standard-options.xml" xpointer="no-pager"/>
 204       <xi:include href="standard-options.xml" xpointer="help"/>
 205       <xi:include href="standard-options.xml" xpointer="version"/>
 206     </variablelist>
 207   </refsect1>
 208
 209   <refsect1>
 210     <title>Exit status</title>
 211     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 212   </refsect1>
 213
 214   <refsect1>
 215     <title>Environment</title>
 216     <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
 217     relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
 218     any kind of partition.</para>
 219
 220     <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
 221     the Extended Boot Loader partition.</para>
 222   </refsect1>
 223
 224   <refsect1>
 225     <title>See Also</title>
 226     <para>
 227       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 228       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
 229       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
 230       <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 231     </para>
 232   </refsect1>
 233 </refentry>