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 recommended to mount
  49         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> are 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.
  74         </para></listitem>
  75       </varlistentry>
  76
  77       <varlistentry>
  78         <term><option>--no-variables</option></term>
  79         <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
  80       </varlistentry>
  81
  82       <xi:include href="standard-options.xml" xpointer="no-pager"/>
  83       <xi:include href="standard-options.xml" xpointer="help"/>
  84       <xi:include href="standard-options.xml" xpointer="version"/>
  85     </variablelist>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Commands</title>
  90     <variablelist>
  91
  92       <varlistentry>
  93         <term><option>status</option></term>
  94
  95         <listitem><para>Shows brief information about the system firmware, the boot loader that was used to boot the
  96         system, the boot loaders currently available in the ESP, the boot loaders listed in the firmware's list of boot
  97         loaders and the current default boot loader entry. If no command is specified, this is the implied
  98         default.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>install</option></term>
 103
 104         <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
 105         <command>systemd-boot</command> will be stored as the EFI default/fallback loader at
 106         <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added
 107         to the top of the firmware's boot loader list.</para></listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><option>update</option></term>
 112
 113         <listitem><para>Updates all installed versions of
 114         <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
 115         available version is newer than the version installed in the EFI system partition. This also includes the EFI
 116         default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
 117         loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>remove</option></term>
 122
 123         <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
 124         and the firmware's boot loader list.</para></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><option>list</option></term>
 129
 130         <listitem><para>Shows all available boot loader entries implementing the <ulink
 131         url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
 132         Specification</ulink>, as well as any other entries discovered or automatically generated by the boot
 133         loader.</para></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>set-default</option> <replaceable>ID</replaceable></term>
 138         <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
 139
 140         <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string as argument. The
 141         <option>set-oneshot</option> command will set the default entry only for the next boot, the
 142         <option>set-default</option> will set it persistently for all future boots.</para></listitem>
 143       </varlistentry>
 144
 145     </variablelist>
 146   </refsect1>
 147
 148   <refsect1>
 149     <title>Exit status</title>
 150     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 151   </refsect1>
 152
 153   <refsect1>
 154     <title>Environment</title>
 155     <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
 156     relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
 157     any kind of partition.</para>
 158
 159     <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
 160     the Extended Boot Loader partition.</para>
 161   </refsect1>
 162
 163   <refsect1>
 164     <title>See Also</title>
 165     <para>
 166       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 167       <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
 168       <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
 169     </para>
 170   </refsect1>
 171 </refentry>