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>system-options</option> <optional><replaceable>VALUE</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>list</option></term>
 116
 117         <listitem><para>Shows all available boot loader entries implementing the <ulink
 118         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
 119         Specification</ulink>, as well as any other entries discovered or automatically generated by the boot
 120         loader.</para></listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>set-default</option> <replaceable>ID</replaceable></term>
 125         <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
 126
 127         <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string as argument. The
 128         <option>set-oneshot</option> command will set the default entry only for the next boot, the
 129         <option>set-default</option> will set it persistently for all future boots.</para></listitem>
 130       </varlistentry>
 131
 132     </variablelist>
 133   </refsect1>
 134
 135   <refsect1>
 136     <title>Options</title>
 137     <para>The following options are understood:</para>
 138
 139     <variablelist>
 140       <varlistentry>
 141         <term><option>--esp-path=</option></term>
 142         <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>,
 143         <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn.  It is
 144         recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
 145       </varlistentry>
 146
 147       <varlistentry>
 148         <term><option>--boot-path=</option></term>
 149         <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink
 150         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not
 151         specified, <filename>/boot/</filename> is checked.  It is recommended to mount the Extended Boot
 152         Loader partition to <filename>/boot/</filename>, if possible.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><option>-p</option></term>
 157         <term><option>--print-esp-path</option></term>
 158         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
 159         to the EFI System Partition (ESP) to standard output and exits.</para></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><option>-x</option></term>
 164         <term><option>--print-boot-path</option></term>
 165         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
 166         to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard
 167         output and exit. This command is useful to determine where to place boot loader entries, as they are
 168         preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para>
 169
 170         <para>Boot Loader Specification Type #1 entries should generally be placed in the directory
 171         <literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as
 172         indication that boot loader entry support is available on the system. Similarly, Boot Loader
 173         Specification Type #2 entries should be placed in the directory <literal>$(bootctl
 174         -x)/EFI/Linux/</literal>.</para>
 175
 176         <para>Note that this option (similar to the <option>--print-booth-path</option> option mentioned
 177         above), is available independently from the boot loader used, i.e. also without
 178         <command>systemd-boot</command> being installed.</para></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><option>--no-variables</option></term>
 183         <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
 184       </varlistentry>
 185
 186       <xi:include href="standard-options.xml" xpointer="no-pager"/>
 187       <xi:include href="standard-options.xml" xpointer="help"/>
 188       <xi:include href="standard-options.xml" xpointer="version"/>
 189     </variablelist>
 190   </refsect1>
 191
 192   <refsect1>
 193     <title>Exit status</title>
 194     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 195   </refsect1>
 196
 197   <refsect1>
 198     <title>Environment</title>
 199     <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
 200     relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
 201     any kind of partition.</para>
 202
 203     <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
 204     the Extended Boot Loader partition.</para>
 205   </refsect1>
 206
 207   <refsect1>
 208     <title>See Also</title>
 209     <para>
 210       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 211       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
 212       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
 213       <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 214     </para>
 215   </refsect1>
 216 </refentry>