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-or-later -->
5
6<refentry id="bootctl" conditional='HAVE_GNU_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 EFI firmware boot settings and manage boot loader</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 firmware and boot loader status, list and manage
35    available boot loaders and boot loader entries, and install, update, or remove the
36    <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> boot
37    loader on the current system.</para>
38  </refsect1>
39
40  <refsect1>
41    <title>Generic EFI Firmware/Boot Loader Commands</title>
42
43    <para>These commands are available on any EFI system, regardless of the boot loader used.</para>
44
45    <variablelist>
46      <varlistentry>
47        <term><option>status</option></term>
48
49        <listitem><para>Shows brief information about the system firmware, the boot loader that was used to
50        boot the system, the boot loaders currently available in the ESP, the boot loaders listed in the
51        firmware's list of boot loaders and the current default boot loader entry. If no command is
52        specified, this is the implied default.</para>
53
54        <para>See the example below for details of the output.</para>
55        </listitem>
56      </varlistentry>
57
58      <varlistentry>
59        <term><option>reboot-to-firmware</option> <optional><replaceable>BOOL</replaceable></optional></term>
60
61        <listitem><para>Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI firmware. Takes a
62        boolean argument which controls whether to show the firmware setup on next system reboot. If the
63        argument is omitted shows the current status of the flag, or whether the flag is supported. This
64        controls the same flag as <command>systemctl reboot --firmware-setup</command>, but is more low-level
65        and allows setting the flag independently from actually requesting a reboot.</para>
66
67        <para>Hint: use <command>systemctl reboot --firmware-setup</command> to reboot into firmware setup
68        once. See
69        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
70        for details.</para></listitem>
71      </varlistentry>
72
73      <varlistentry>
74        <term><option>systemd-efi-options</option> <optional><replaceable>STRING</replaceable></optional></term>
75
76        <listitem><para>When called without the optional argument, prints the current value of the
77        <literal>SystemdOptions</literal> EFI variable. When called with an argument, sets the variable to
78        that value. See
79        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> for the
80        meaning of that variable.</para></listitem>
81      </varlistentry>
82    </variablelist>
83  </refsect1>
84
85  <refsect1>
86    <title>Boot Loader Specification Commands</title>
87
88    <para>These commands are available for all boot loaders that implement the <ulink
89    url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> and/or the <ulink
90    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, such as
91    <command>systemd-boot</command>.</para>
92
93    <variablelist>
94      <varlistentry>
95        <term><option>list</option></term>
96
97        <listitem><para>Shows all available boot loader entries implementing the <ulink
98        url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, as well as any
99        other entries discovered or automatically generated by a boot loader implementing the <ulink
100        url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.
101        JSON output may be requested with <option>--json=</option>.</para>
102
103        <para>See the example below for details of the output.</para>
104        </listitem>
105      </varlistentry>
106
107      <varlistentry>
108        <term><option>set-default</option> <replaceable>ID</replaceable></term>
109        <term><option>set-oneshot</option> <replaceable>ID</replaceable></term>
110
111        <listitem><para>Sets the default boot loader entry. Takes a single boot loader entry ID string or a glob
112        pattern as argument. The <option>set-oneshot</option> command will set the default entry only for the next boot,
113        the <option>set-default</option> will set it persistently for all future boots.</para>
114
115        <para><command>bootctl list</command> can be used to list available boot loader entries and their
116        IDs.</para>
117
118        <para>In addition, the boot loader entry ID may be specified as one of: <option>@default</option>,
119        <option>@oneshot</option> or <option>@current</option>, which correspond to the current default boot loader
120        entry for all future boots, the current default boot loader entry for the next boot, and the currently booted
121        boot loader entry. These special IDs are resolved to the current values of the EFI variables
122        <varname>LoaderEntryDefault</varname>, <varname>LoaderEntryOneShot</varname> and <varname>LoaderEntrySelected</varname>,
123        see <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> for details.
124        These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader
125        entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot
126        loader entry for all future boots, but may be used for other operations too.</para>
127
128        <para>If set to <option>@saved</option> the chosen entry will be saved as an EFI variable
129        on every boot and automatically selected the next time the boot loader starts.</para>
130
131        <para>When an empty string ("") is specified as the ID, then the corresponding EFI variable will be
132        unset.</para>
133
134        <para>Hint: use <command>systemctl reboot --boot-loader-entry=<replaceable>ID</replaceable></command>
135        to reboot into a specific boot entry and
136        <command>systemctl reboot --boot-loader-menu=<replaceable>timeout</replaceable></command>
137        to reboot into the boot loader menu once. See
138        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
139        for details.</para></listitem>
140      </varlistentry>
141
142      <varlistentry>
143        <term><option>set-timeout</option> <replaceable>TIMEOUT</replaceable></term>
144        <term><option>set-timeout-oneshot</option> <replaceable>TIMEOUT</replaceable></term>
145
146        <listitem><para>Sets the boot loader menu timeout in seconds. The <option>set-timeout-oneshot</option>
147        command will set the timeout only for the next boot. See
148        <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>
149        for details about the syntax of time spans.</para>
150
151        <para>If this is set to <option>menu-hidden</option> or <option>0</option> no menu is shown and
152        the default entry will be booted immediately, while setting this to <option>menu-force</option>
153        disables the timeout while always showing the menu. When an empty string ("") is specified the
154        bootloader will revert to its default menu timeout.</para></listitem>
155      </varlistentry>
156    </variablelist>
157  </refsect1>
158
159  <refsect1>
160    <title><command>systemd-boot</command> Commands</title>
161
162    <para>These commands manage the <command>systemd-boot</command> EFI boot loader, and do not work in
163    conjunction with other boot loaders.</para>
164
165    <variablelist>
166      <varlistentry>
167        <term><option>install</option></term>
168
169        <listitem><para>Installs <command>systemd-boot</command> into the EFI system partition. A copy of
170        <command>systemd-boot</command> will be stored as the EFI default/fallback loader at
171        <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot loader is then added
172        to the top of the firmware's boot loader list.</para></listitem>
173      </varlistentry>
174
175      <varlistentry>
176        <term><option>update</option></term>
177
178        <listitem><para>Updates all installed versions of
179        <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, if the
180        available version is newer than the version installed in the EFI system partition. This also includes the EFI
181        default/fallback loader at <filename><replaceable>ESP</replaceable>/EFI/BOOT/BOOT*.EFI</filename>. The boot
182        loader is then added to end of the firmware's boot loader list if missing.</para></listitem>
183      </varlistentry>
184
185      <varlistentry>
186        <term><option>remove</option></term>
187
188        <listitem><para>Removes all installed versions of <command>systemd-boot</command> from the EFI system partition
189        and the firmware's boot loader list.</para></listitem>
190      </varlistentry>
191
192      <varlistentry>
193        <term><option>is-installed</option></term>
194
195        <listitem><para>Checks whether <command>systemd-boot</command> is installed in the ESP. Note that a
196        single ESP might host multiple boot loaders; this hence checks whether
197        <command>systemd-boot</command> is one (of possibly many) installed boot loaders — and neither
198        whether it is the default nor whether it is registered in any EFI variables.</para></listitem>
199      </varlistentry>
200
201      <varlistentry>
202        <term><option>random-seed</option></term>
203
204        <listitem><para>Generates a random seed and stores it in the EFI System Partition, for use by the
205        <command>systemd-boot</command> boot loader. Also, generates a random 'system token' and stores it
206        persistently as an EFI variable, if one has not been set before. If the boot loader finds the random
207        seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the
208        OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS
209        is credited to the kernel's entropy pool by the system manager during early boot, and permits
210        userspace to boot up with an entropy pool fully initialized very early on. Also see
211        <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
212
213        <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
214        information.</para></listitem>
215      </varlistentry>
216
217    </variablelist>
218  </refsect1>
219
220  <refsect1>
221    <title>Options</title>
222    <para>The following options are understood:</para>
223
224    <variablelist>
225      <varlistentry>
226        <term><option>--esp-path=</option></term>
227        <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>,
228        <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn.  It is
229        recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem>
230      </varlistentry>
231
232      <varlistentry>
233        <term><option>--boot-path=</option></term>
234        <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink
235        url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not
236        specified, <filename>/boot/</filename> is checked.  It is recommended to mount the Extended Boot
237        Loader partition to <filename>/boot/</filename>, if possible.</para></listitem>
238      </varlistentry>
239
240      <varlistentry>
241        <term><option>-p</option></term>
242        <term><option>--print-esp-path</option></term>
243        <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
244        to the EFI System Partition (ESP) to standard output and exits.</para></listitem>
245      </varlistentry>
246
247      <varlistentry>
248        <term><option>-x</option></term>
249        <term><option>--print-boot-path</option></term>
250        <listitem><para>This option modifies the behaviour of <command>status</command>. Only prints the path
251        to the Extended Boot Loader partition if it exists, and the path to the ESP otherwise to standard
252        output and exit. This command is useful to determine where to place boot loader entries, as they are
253        preferably placed in the Extended Boot Loader partition if it exists and in the ESP otherwise.</para>
254
255        <para>Boot Loader Specification Type #1 entries should generally be placed in the directory
256        <literal>$(bootctl -x)/loader/entries/</literal>. Existence of that directory may also be used as
257        indication that boot loader entry support is available on the system. Similarly, Boot Loader
258        Specification Type #2 entries should be placed in the directory <literal>$(bootctl
259        -x)/EFI/Linux/</literal>.</para>
260
261        <para>Note that this option (similar to the <option>--print-booth-path</option> option mentioned
262        above), is available independently from the boot loader used, i.e. also without
263        <command>systemd-boot</command> being installed.</para></listitem>
264      </varlistentry>
265
266      <varlistentry>
267        <term><option>--no-variables</option></term>
268        <listitem><para>Do not touch the firmware's boot loader list stored in EFI variables.</para></listitem>
269      </varlistentry>
270
271      <varlistentry>
272        <term><option>--graceful</option></term>
273        <listitem><para>Ignore failure when the EFI System Partition cannot be found, when EFI variables
274        cannot be written, or a different or newer boot loader is already installed. Currently only applies
275        to <command>is-installed</command>, <command>update</command>, and <command>random-seed</command>
276        verbs.</para></listitem>
277      </varlistentry>
278
279      <varlistentry>
280        <term><option>-q</option></term>
281        <term><option>--quiet</option></term>
282
283        <listitem><para>Suppress printing of the results of various commands and also the hints about ESP
284        being unavailable.</para></listitem>
285      </varlistentry>
286
287      <varlistentry>
288        <term><option>--make-entry-directory=yes|no</option></term>
289        <listitem><para>Controls creation and deletion of the <ulink
290        url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> Type #1 entry
291        directory on the file system containing resources such as kernel images and initial RAM disk images
292        during <option>install</option> and <option>remove</option>, respectively. The directory is named
293        after the entry token, as specified with <option>--entry-token=</option> parameter described below,
294        and is placed immediately below the <varname>$BOOT</varname> root directory (i.e. beneath the file
295        system returned by the <option>--print-boot-path</option> option, see above). Defaults to
296        <literal>no</literal>.</para></listitem>
297      </varlistentry>
298
299      <varlistentry>
300        <term><option>--entry-token=</option></term>
301
302        <listitem><para>Controls how to name and identify boot loader entries for this OS
303        installation. Accepted during <option>install</option>, and takes one of <literal>auto</literal>,
304        <literal>machine-id</literal>, <literal>os-id</literal>, <literal>os-image-id</literal> or an
305        arbitrary string prefixed by <literal>literal:</literal> as argument.</para>
306
307        <para>If set to <option>machine-id</option> the entries are named after the machine ID of the running
308        system (e.g. <literal>b0e793a9baf14b5fa13ecbe84ff637ac</literal>). See
309        <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
310        details about the machine ID concept and file.</para>
311
312        <para>If set to <option>os-id</option> the entries are named after the OS ID of the running system,
313        i.e. the <varname>ID=</varname> field of
314        <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>
315        (e.g. <literal>fedora</literal>). Similar, if set to <option>os-image-id</option> the entries are
316        named after the OS image ID of the running system, i.e. the <varname>IMAGE_ID=</varname> field of
317        <filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para>
318
319        <para>If set to <option>auto</option> (the default), the <filename>/etc/kernel/entry-token</filename>
320        file will be read if it exists, and the stored value used.  Otherwise if the local machine ID is
321        initialized it is used. Otherwise <varname>IMAGE_ID=</varname> from <filename>os-release</filename>
322        will be used, if set.  Otherwise, <varname>ID=</varname> from <filename>os-release</filename> will be
323        used, if set.</para>
324
325        <para>Unless set to <literal>machine-id</literal>, or when
326        <option>--make-entry-directory=yes</option> is used the selected token string is written to a file
327        <filename>/etc/kernel/entry-token</filename>, to ensure it will be used for future entries. This file
328        is also read by
329        <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
330        in order to identify under which name to generate boot loader entries for newly installed kernels, or
331        to determine the entry names for removing old ones.</para>
332
333        <para>Using the machine ID for naming the entries is generally preferable, however there are cases
334        where using the other identifiers is a good option. Specifically: if the identification data that the
335        machine ID entails shall not be stored on the (unencrypted) <varname>$BOOT</varname> partition, or if
336        the ID shall be generated on first boot and is not known when the entries are prepared. Note that
337        using the machine ID has the benefit that multiple parallel installations of the same OS can coexist
338        on the same medium, and they can update their boot loader entries independently. When using another
339        identifier (such as the OS ID or the OS image ID), parallel installations of the same OS would try to
340        use the same entry name. To support parallel installations, the installer must use a different entry
341        token when adding a second installation.</para></listitem>
342      </varlistentry>
343
344      <xi:include href="standard-options.xml" xpointer="no-pager"/>
345      <xi:include href="standard-options.xml" xpointer="json" />
346      <xi:include href="standard-options.xml" xpointer="help"/>
347      <xi:include href="standard-options.xml" xpointer="version"/>
348    </variablelist>
349  </refsect1>
350
351  <refsect1>
352    <title>Signed .efi files</title>
353    <para><command>bootctl</command> <option>install</option> and <option>update</option> will look for a
354    <command>systemd-boot</command> file ending with the <literal>.efi.signed</literal> suffix first, and copy
355    that instead of the normal <literal>.efi</literal> file. This allows distributions or end-users to provide
356    signed images for UEFI SecureBoot.</para>
357  </refsect1>
358
359  <refsect1>
360    <title>Exit status</title>
361    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
362  </refsect1>
363
364  <refsect1>
365    <title>Environment</title>
366    <para>If <varname>$SYSTEMD_RELAX_ESP_CHECKS=1</varname> is set the validation checks for the ESP are
367    relaxed, and the path specified with <option>--esp-path=</option> may refer to any kind of file system on
368    any kind of partition.</para>
369
370    <para>Similarly, <varname>$SYSTEMD_RELAX_XBOOTLDR_CHECKS=1</varname> turns off some validation checks for
371    the Extended Boot Loader partition.</para>
372  </refsect1>
373
374  <refsect1>
375    <title>Examples</title>
376
377    <example>
378      <title>Output from <command>status</command> and <command>list</command></title>
379
380      <programlisting>$ <command>bootctl status</command>
381System:
382     Firmware: UEFI 2.40 (<replaceable>firmware-version</replaceable>)  ← firmware vendor and version
383  Secure Boot: disabled (setup)              ← secure boot status
384 TPM2 Support: yes
385 Boot into FW: supported                     ← does the firmware support booting into itself
386
387Current Boot Loader:                         ← details about sd-boot or another boot loader
388      Product: systemd-boot <replaceable>version</replaceable>            implementing the <ulink
389    url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>
390     Features: ✓ Boot counting
391               ✓ Menu timeout control
392               ✓ One-shot menu timeout control
393               ✓ Default entry control
394               ✓ One-shot entry control
395               ✓ Support for XBOOTLDR partition
396               ✓ Support for passing random seed to OS
397               ✓ Load drop-in drivers
398               ✓ Boot loader sets ESP information
399          ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000
400         File: └─/EFI/systemd/systemd-bootx64.efi
401
402Random Seed:                                 ← random seed used for entropy in early boot
403 Passed to OS: yes
404 System Token: set
405       Exists: yes
406
407Available Boot Loaders on ESP:
408          ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
409         File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251
410         File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251
411
412Boot Loaders Listed in EFI Variables:
413        Title: Linux Boot Manager
414           ID: 0x0001
415       Status: active, boot-order
416    Partition: /dev/disk/by-partuuid/…
417         File: └─/EFI/systemd/systemd-bootx64.efi
418
419        Title: Fedora
420           ID: 0x0000
421       Status: active, boot-order
422    Partition: /dev/disk/by-partuuid/…
423         File: └─/EFI/fedora/shimx64.efi
424
425        Title: Linux-Firmware-Updater
426           ID: 0x0002
427       Status: active, boot-order
428    Partition: /dev/disk/by-partuuid/…
429         File: └─/EFI/fedora/fwupdx64.efi
430
431Boot Loader Entries:
432        $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
433
434Default Boot Loader Entry:
435         type: Boot Loader Specification Type #1 (.conf)
436        title: Fedora Linux 36 (Workstation Edition)
437           id: …
438       source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
439      version: <replaceable>kernel-version</replaceable>
440   machine-id: …
441        linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
442       initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
443      options: root=…
444</programlisting>
445
446      <programlisting>$ <command>bootctl list</command>
447Boot Loader Entries:
448         type: Boot Loader Specification Type #1 (.conf)
449        title: Fedora Linux 36 (Workstation Edition) (default) (selected)
450           id: …
451       source: /boot/efi/loader/entries/<replaceable>entry-token</replaceable>-<replaceable>kernel-version</replaceable>.conf
452      version: <replaceable>kernel-version</replaceable>
453   machine-id: …
454        linux: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/linux
455       initrd: /<replaceable>entry-token</replaceable>/<replaceable>kernel-version</replaceable>/initrd
456      options: root=…
457
458         type: Boot Loader Specification Type #2 (.efi)
459        title: Fedora Linux 35 (Workstation Edition)
460           id: …
461       source: /boot/efi/EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
462      version: <replaceable>kernel-version</replaceable>
463   machine-id: …
464        linux: /EFI/Linux/fedora-<replaceable>kernel-version</replaceable>.efi
465      options: root=…
466
467         type: Automatic
468        title: Reboot Into Firmware Interface
469           id: auto-reboot-to-firmware-setup
470       source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
471</programlisting>
472
473       <para>In the listing, <literal>(default)</literal> specifies the entry that will be
474       used by default, and <literal>(selected)</literal> specifies the entry that was
475       selected the last time (i.e. is currently running).</para>
476    </example>
477  </refsect1>
478
479  <refsect1>
480    <title>See Also</title>
481    <para>
482      <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
483      <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>,
484      <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>,
485      <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
486    </para>
487  </refsect1>
488</refentry>
489