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>Options</title>
  42     <para>The following options are understood:</para>
  43
  44     <variablelist>
  45       <varlistentry>
  46         <term><option>--esp-path=</option></term>
  47         <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>,
  48         <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn.  It is
  49         recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
  50       </varlistentry>
  51
  52       <varlistentry>
  53         <term><option>--boot-path=</option></term>
  54         <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink
  55         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not
  56         specified, <filename>/boot/</filename> is checked.  It is recommended to mount the Extended Boot
  57         Loader partition to <filename>/boot/</filename>, if possible.</para></listitem>
  58       </varlistentry>
  59
  60       <varlistentry>
  61         <term><option>-p</option></term>
  62         <term><option>--print-esp-path</option></term>
  63         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
  64         to the EFI System Partition (ESP) to standard output and exits.</para></listitem>
  65       </varlistentry>
  66
  67       <varlistentry>
  68         <term><option>-x</option></term>
  69         <term><option>--print-boot-path</option></term>
  70         <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
  71         to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard
  72         output and exit. This command is useful to determine where to place boot loader entries, as they are
  73         preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para>
  74
  75         <para>Boot Loader Specification Type #1 entries should generally be placed in the directory
  76         <literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as
  77         indication that boot loader entry support is available on the system. Similarly, Boot Loader
  78         Specification Type #2 entries should be placed in the directory <literal>$(bootctl
  79         -x)/EFI/Linux/</literal>.</para>
  80
  81         <para>Note that this option (similar to the <option>--print-booth-path</option> option mentioned
  82         above), is available independently from the boot loader used, i.e. also without
  83         <command>systemd-boot</command> being installed.</para></listitem>
  84       </varlistentry>
  85
  86       <varlistentry>
  87         <term><option>--no-variables</option></term>
  88         <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
  89       </varlistentry>
  90
  91       <xi:include href="standard-options.xml" xpointer="no-pager"/>
  92       <xi:include href="standard-options.xml" xpointer="help"/>
  93       <xi:include href="standard-options.xml" xpointer="version"/>
  94     </variablelist>
  95   </refsect1>
  96
  97   <refsect1>
  98     <title>Commands</title>
  99     <variablelist>
 100
 101       <varlistentry>
 102         <term><option>status</option></term>
 103
 104         <listitem><para>Shows brief information about the system firmware, the boot loader that was used to boot the
 105         system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot
 106         loaders and the current default boot loader entry. If no command is specified, this is the implied
 107         default.</para></listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><option>install</option></term>
 112
 113         <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
 114         <command>systemd-boot</command> will be stored as the EFI default/fallback loader at
 115         <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added
 116         to the top of the firmware's boot loader list.</para></listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term><option>update</option></term>
 121
 122         <listitem><para>Updates all installed versions of
 123         <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
 124         available version is newer than the version installed in the EFI system partition. This also includes the EFI
 125         default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
 126         loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><option>remove</option></term>
 131
 132         <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
 133         and the firmware's boot loader list.</para></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>random-seed</option></term>
 138
 139         <listitem><para>Generates a random seed and stores it in the EFI System Partition, for use by the
 140         <command>systemd-boot</command> boot loader. Also, generates a random 'system token' and stores it
 141         persistently as an EFI variable, if one has not been set before. If the boot loader finds the random
 142         seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the
 143         OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS
 144         is credited to the kernel's entropy pool by the system manager during early boot, and permits
 145         userspace to boot up with an entropy pool fully initialized very early on. Also see
 146         <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 147
 148         <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
 149         information.</para></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><option>is-installed</option></term>
 154
 155         <listitem><para>Checks whether <command>systemd-boot</command> is installed in the ESP. Note that a
 156         single ESP might host multiple boot loaders; this hence checks whether
 157         <command>systemd-boot</command> is one (of possibly many) installed boot loaders — and neither
 158         whether it is the default nor whether it is registered in any EFI variables.</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><option>list</option></term>
 163
 164         <listitem><para>Shows all available boot loader entries implementing the <ulink
 165         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
 166         Specification</ulink>, as well as any other entries discovered or automatically generated by the boot
 167         loader.</para></listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><option>set-default</option> <replaceable>ID</replaceable></term>
 172         <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
 173
 174         <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string as argument. The
 175         <option>set-oneshot</option> command will set the default entry only for the next boot, the
 176         <option>set-default</option> will set it persistently for all future boots.</para></listitem>
 177       </varlistentry>
 178
 179     </variablelist>
 180   </refsect1>
 181
 182   <refsect1>
 183     <title>Exit status</title>
 184     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 185   </refsect1>
 186
 187   <refsect1>
 188     <title>Environment</title>
 189     <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
 190     relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
 191     any kind of partition.</para>
 192
 193     <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
 194     the Extended Boot Loader partition.</para>
 195   </refsect1>
 196
 197   <refsect1>
 198     <title>See Also</title>
 199     <para>
 200       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 201       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
 202       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
 203       <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 204     </para>
 205   </refsect1>
 206 </refentry>