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+ -->
6 <refentry id=
"bootctl" conditional='ENABLE_EFI'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <productname>systemd
</productname>
14 <refentrytitle>bootctl
</refentrytitle>
15 <manvolnum>1</manvolnum>
19 <refname>bootctl
</refname>
20 <refpurpose>Control the firmware and boot manager settings
</refpurpose>
25 <command>bootctl
</command>
26 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
27 <arg choice=
"req">COMMAND
</arg>
32 <title>Description
</title>
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>
41 <title>Commands
</title>
45 <term><option>status
</option></term>
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>
54 <term><option>install
</option></term>
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>
63 <term><option>update
</option></term>
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>
73 <term><option>remove
</option></term>
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>
80 <term><option>is-installed
</option></term>
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>
89 <term><option>random-seed
</option></term>
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>
100 <para>See
<ulink url=
"https://systemd.io/RANDOM_SEEDS">Random Seeds
</ulink> for further
101 information.
</para></listitem>
105 <term><option>systemd-efi-options
</option> <optional><replaceable>STRING
</replaceable></optional></term>
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>
115 <term><option>reboot-to-firmware
</option> <optional><replaceable>BOOL
</replaceable></optional></term>
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>
126 <term><option>list
</option></term>
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>
135 <term><option>set-default
</option> <replaceable>ID
</replaceable></term>
136 <term><option>set-oneshot
</option> <replaceable>ID
</replaceable></term>
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>
147 <title>Options
</title>
148 <para>The following options are understood:
</para>
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>
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>
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>
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>
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>
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>
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>
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>
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"/>
210 <title>Exit status
</title>
211 <para>On success,
0 is returned, a non-zero failure code otherwise.
</para>
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>
220 <para>Similarly,
<varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=
1</varname> turns off some validation checks for
221 the Extended Boot Loader partition.
</para>
225 <title>See Also
</title>
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>