1BOOTCTL(1) bootctl BOOTCTL(1)
2
6 bootctl - Control EFI firmware boot settings and manage boot loader
7
9 bootctl [OPTIONS...] {COMMAND}
10
12 bootctl can check the EFI firmware and boot loader status, list and
13 manage available boot loaders and boot loader entries, and install,
14 update, or remove the systemd-boot(7) boot loader on the current
15 system.
16
18 These commands are available on any EFI system, regardless of the boot
19 loader used.
20 status
22 Shows brief information about the system firmware, the boot loader
23 that was used to boot the system, the boot loaders currently
24 available in the ESP, the boot loaders listed in the firmware's
25 list of boot loaders and the current default boot loader entry. If
26 no command is specified, this is the implied default.
27 See the example below for details of the output.
29 reboot-to-firmware [BOOL]
31 Query or set the "Reboot-Into-Firmware-Setup" flag of the EFI
32 firmware. Takes a boolean argument which controls whether to show
33 the firmware setup on next system reboot. If the argument is
34 omitted shows the current status of the flag, or whether the flag
35 is supported. This controls the same flag as systemctl reboot
36 --firmware-setup, but is more low-level and allows setting the flag
37 independently from actually requesting a reboot.
38 Hint: use systemctl reboot --firmware-setup to reboot into firmware
40 setup once. See systemctl(1) for details.
41 systemd-efi-options [STRING]
43 When called without the optional argument, prints the current value
44 of the "SystemdOptions" EFI variable. When called with an argument,
45 sets the variable to that value. See systemd(1) for the meaning of
46 that variable.
47
49 These commands are available for all boot loaders that implement the
50 Boot Loader Specification[1] and/or the Boot Loader Interface[2], such
51 as systemd-boot.
52 list
54 Shows all available boot loader entries implementing the Boot
55 Loader Specification[1], as well as any other entries discovered or
56 automatically generated by a boot loader implementing the Boot
57 Loader Interface[2]. JSON output may be requested with --json=.
58 See the example below for details of the output.
60 set-default ID, set-oneshot ID
62 Sets the default boot loader entry. Takes a single boot loader
63 entry ID string or a glob pattern as argument. The set-oneshot
64 command will set the default entry only for the next boot, the
65 set-default will set it persistently for all future boots.
66 bootctl list can be used to list available boot loader entries and
68 their IDs.
69 In addition, the boot loader entry ID may be specified as one of:
71 @default, @oneshot or @current, which correspond to the current
72 default boot loader entry for all future boots, the current default
73 boot loader entry for the next boot, and the currently booted boot
74 loader entry. These special IDs are resolved to the current values
75 of the EFI variables LoaderEntryDefault, LoaderEntryOneShot and
76 LoaderEntrySelected, see Boot Loader Specification[1] for details.
77 These special IDs are primarily useful as a quick way to
78 persistently make the currently booted boot loader entry the
79 default choice, or to upgrade the default boot loader entry for the
80 next boot to the default boot loader entry for all future boots,
81 but may be used for other operations too.
82 If set to @saved the chosen entry will be saved as an EFI variable
84 on every boot and automatically selected the next time the boot
85 loader starts.
86 When an empty string ("") is specified as the ID, then the
88 corresponding EFI variable will be unset.
89 Hint: use systemctl reboot --boot-loader-entry=ID to reboot into a
91 specific boot entry and systemctl reboot --boot-loader-menu=timeout
92 to reboot into the boot loader menu once. See systemctl(1) for
93 details.
94 set-timeout TIMEOUT, set-timeout-oneshot TIMEOUT
96 Sets the boot loader menu timeout in seconds. The
97 set-timeout-oneshot command will set the timeout only for the next
98 boot. See systemd.time(7) for details about the syntax of time
99 spans.
100 If this is set to menu-hidden or 0 no menu is shown and the default
102 entry will be booted immediately, while setting this to menu-force
103 disables the timeout while always showing the menu. When an empty
104 string ("") is specified the bootloader will revert to its default
105 menu timeout.
106
108 These commands manage the systemd-boot EFI boot loader, and do not work
109 in conjunction with other boot loaders.
110 install
112 Installs systemd-boot into the EFI system partition. A copy of
113 systemd-boot will be stored as the EFI default/fallback loader at
114 ESP/EFI/BOOT/BOOT*.EFI. The boot loader is then added to the top of
115 the firmware's boot loader list.
116 update
118 Updates all installed versions of systemd-boot(7), if the available
119 version is newer than the version installed in the EFI system
120 partition. This also includes the EFI default/fallback loader at
121 ESP/EFI/BOOT/BOOT*.EFI. The boot loader is then added to end of the
122 firmware's boot loader list if missing.
123 remove
125 Removes all installed versions of systemd-boot from the EFI system
126 partition and the firmware's boot loader list.
127 is-installed
129 Checks whether systemd-boot is installed in the ESP. Note that a
130 single ESP might host multiple boot loaders; this hence checks
131 whether systemd-boot is one (of possibly many) installed boot
132 loaders — and neither whether it is the default nor whether it is
133 registered in any EFI variables.
134 random-seed
136 Generates a random seed and stores it in the EFI System Partition,
137 for use by the systemd-boot boot loader. Also, generates a random
138 'system token' and stores it persistently as an EFI variable, if
139 one has not been set before. If the boot loader finds the random
140 seed in the ESP and the system token in the EFI variable it will
141 derive a random seed to pass to the OS and a new seed to store in
142 the ESP from the combination of both. The random seed passed to the
143 OS is credited to the kernel's entropy pool by the system manager
144 during early boot, and permits userspace to boot up with an entropy
145 pool fully initialized very early on. Also see systemd-boot-system-
146 token.service(8).
147 See Random Seeds[3] for further information.
149
151 The following options are understood:
152 --esp-path=
154 Path to the EFI System Partition (ESP). If not specified, /efi/,
155 /boot/, and /boot/efi/ are checked in turn. It is recommended to
156 mount the ESP to /efi/, if possible.
157 --boot-path=
159 Path to the Extended Boot Loader partition, as defined in the Boot
160 Loader Specification[1]. If not specified, /boot/ is checked. It is
161 recommended to mount the Extended Boot Loader partition to /boot/,
162 if possible.
163 -p, --print-esp-path
165 This option modifies the behaviour of status. Only prints the path
166 to the EFI System Partition (ESP) to standard output and exits.
167 -x, --print-boot-path
169 This option modifies the behaviour of status. Only prints the path
170 to the Extended Boot Loader partition if it exists, and the path to
171 the ESP otherwise to standard output and exit. This command is
172 useful to determine where to place boot loader entries, as they are
173 preferably placed in the Extended Boot Loader partition if it
174 exists and in the ESP otherwise.
175 Boot Loader Specification Type #1 entries should generally be
177 placed in the directory "$(bootctl -x)/loader/entries/". Existence
178 of that directory may also be used as indication that boot loader
179 entry support is available on the system. Similarly, Boot Loader
180 Specification Type #2 entries should be placed in the directory
181 "$(bootctl -x)/EFI/Linux/".
182 Note that this option (similar to the --print-booth-path option
184 mentioned above), is available independently from the boot loader
185 used, i.e. also without systemd-boot being installed.
186 --no-variables
188 Do not touch the firmware's boot loader list stored in EFI
189 variables.
190 --graceful
192 Ignore failure when the EFI System Partition cannot be found, when
193 EFI variables cannot be written, or a different or newer boot
194 loader is already installed. Currently only applies to
195 is-installed, update, and random-seed verbs.
196 -q, --quiet
198 Suppress printing of the results of various commands and also the
199 hints about ESP being unavailable.
200 --make-entry-directory=yes|no
202 Controls creation and deletion of the Boot Loader Specification[1]
203 Type #1 entry directory on the file system containing resources
204 such as kernel images and initial RAM disk images during install
205 and remove, respectively. The directory is named after the entry
206 token, as specified with --entry-token= parameter described below,
207 and is placed immediately below the $BOOT root directory (i.e.
208 beneath the file system returned by the --print-boot-path option,
209 see above). Defaults to "no".
210 --entry-token=
212 Controls how to name and identify boot loader entries for this OS
213 installation. Accepted during install, and takes one of "auto",
214 "machine-id", "os-id", "os-image-id" or an arbitrary string
215 prefixed by "literal:" as argument.
216 If set to machine-id the entries are named after the machine ID of
218 the running system (e.g. "b0e793a9baf14b5fa13ecbe84ff637ac"). See
219 machine-id(5) for details about the machine ID concept and file.
220 If set to os-id the entries are named after the OS ID of the
222 running system, i.e. the ID= field of os-release(5) (e.g.
223 "fedora"). Similar, if set to os-image-id the entries are named
224 after the OS image ID of the running system, i.e. the IMAGE_ID=
225 field of os-release (e.g. "vendorx-cashier-system").
226 If set to auto (the default), the /etc/kernel/entry-token file will
228 be read if it exists, and the stored value used. Otherwise if the
229 local machine ID is initialized it is used. Otherwise IMAGE_ID=
230 from os-release will be used, if set. Otherwise, ID= from
231 os-release will be used, if set.
232 Unless set to "machine-id", or when --make-entry-directory=yes is
234 used the selected token string is written to a file
235 /etc/kernel/entry-token, to ensure it will be used for future
236 entries. This file is also read by kernel-install(8), in order to
237 identify under which name to generate boot loader entries for newly
238 installed kernels, or to determine the entry names for removing old
239 ones.
240 Using the machine ID for naming the entries is generally
242 preferable, however there are cases where using the other
243 identifiers is a good option. Specifically: if the identification
244 data that the machine ID entails shall not be stored on the
245 (unencrypted) $BOOT partition, or if the ID shall be generated on
246 first boot and is not known when the entries are prepared. Note
247 that using the machine ID has the benefit that multiple parallel
248 installations of the same OS can coexist on the same medium, and
249 they can update their boot loader entries independently. When using
250 another identifier (such as the OS ID or the OS image ID), parallel
251 installations of the same OS would try to use the same entry name.
252 To support parallel installations, the installer must use a
253 different entry token when adding a second installation.
254 --no-pager
256 Do not pipe output into a pager.
257 --json=MODE
259 Shows output formatted as JSON. Expects one of "short" (for the
260 shortest possible output without any redundant whitespace or line
261 breaks), "pretty" (for a pretty version of the same, with
262 indentation and line breaks) or "off" (to turn off JSON output, the
263 default).
264 -h, --help
266 Print a short help text and exit.
267 --version
269 Print a short version string and exit.
270
272 bootctl install and update will look for a systemd-boot file ending
273 with the ".efi.signed" suffix first, and copy that instead of the
274 normal ".efi" file. This allows distributions or end-users to provide
275 signed images for UEFI SecureBoot.
276
278 On success, 0 is returned, a non-zero failure code otherwise.
279
281 If $SYSTEMD_RELAX_ESP_CHECKS=1 is set the validation checks for the ESP
282 are relaxed, and the path specified with --esp-path= may refer to any
283 kind of file system on any kind of partition.
284 Similarly, $SYSTEMD_RELAX_XBOOTLDR_CHECKS=1 turns off some validation
286 checks for the Extended Boot Loader partition.
287
289 Example 1. Output from status and list
290 $ bootctl status
292 System:
293 Firmware: UEFI 2.40 (firmware-version) ← firmware vendor and version
294 Secure Boot: disabled (setup) ← secure boot status
295 TPM2 Support: yes
296 Boot into FW: supported ← does the firmware support booting into itself
297 Current Boot Loader: ← details about sd-boot or another boot loader
299 Product: systemd-boot version implementing the Boot Loader Interface[2]
300 Features: ✓ Boot counting
301 ✓ Menu timeout control
302 ✓ One-shot menu timeout control
303 ✓ Default entry control
304 ✓ One-shot entry control
305 ✓ Support for XBOOTLDR partition
306 ✓ Support for passing random seed to OS
307 ✓ Load drop-in drivers
308 ✓ Boot loader sets ESP information
309 ESP: /dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000
310 File: └─/EFI/systemd/systemd-bootx64.efi
311 Random Seed: ← random seed used for entropy in early boot
313 Passed to OS: yes
314 System Token: set
315 Exists: yes
316 Available Boot Loaders on ESP:
318 ESP: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
319 File: └─/EFI/systemd/systemd-bootx64.efi (systemd-boot 251
320 File: └─/EFI/BOOT/BOOTX64.EFI (systemd-boot 251
321 Boot Loaders Listed in EFI Variables:
323 Title: Linux Boot Manager
324 ID: 0x0001
325 Status: active, boot-order
326 Partition: /dev/disk/by-partuuid/...
327 File: └─/EFI/systemd/systemd-bootx64.efi
328 Title: Fedora
330 ID: 0x0000
331 Status: active, boot-order
332 Partition: /dev/disk/by-partuuid/...
333 File: └─/EFI/fedora/shimx64.efi
334 Title: Linux-Firmware-Updater
336 ID: 0x0002
337 Status: active, boot-order
338 Partition: /dev/disk/by-partuuid/...
339 File: └─/EFI/fedora/fwupdx64.efi
340 Boot Loader Entries:
342 $BOOT: /boot/efi (/dev/disk/by-partuuid/01234567-89ab-cdef-dead-beef00000000)
343 Default Boot Loader Entry:
345 type: Boot Loader Specification Type #1 (.conf)
346 title: Fedora Linux 36 (Workstation Edition)
347 id: ...
348 source: /boot/efi/loader/entries/entry-token-kernel-version.conf
349 version: kernel-version
350 machine-id: ...
351 linux: /entry-token/kernel-version/linux
352 initrd: /entry-token/kernel-version/initrd
353 options: root=...
354 $ bootctl list
356 Boot Loader Entries:
357 type: Boot Loader Specification Type #1 (.conf)
358 title: Fedora Linux 36 (Workstation Edition) (default) (selected)
359 id: ...
360 source: /boot/efi/loader/entries/entry-token-kernel-version.conf
361 version: kernel-version
362 machine-id: ...
363 linux: /entry-token/kernel-version/linux
364 initrd: /entry-token/kernel-version/initrd
365 options: root=...
366 type: Boot Loader Specification Type #2 (.efi)
368 title: Fedora Linux 35 (Workstation Edition)
369 id: ...
370 source: /boot/efi/EFI/Linux/fedora-kernel-version.efi
371 version: kernel-version
372 machine-id: ...
373 linux: /EFI/Linux/fedora-kernel-version.efi
374 options: root=...
375 type: Automatic
377 title: Reboot Into Firmware Interface
378 id: auto-reboot-to-firmware-setup
379 source: /sys/firmware/efi/efivars/LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
380 In the listing, "(default)" specifies the entry that will be used by
382 default, and "(selected)" specifies the entry that was selected the
383 last time (i.e. is currently running).
384
386 systemd-boot(7), Boot Loader Specification[1], Boot Loader
387 Interface[2], systemd-boot-system-token.service(8)
388
390 1. Boot Loader Specification
391 https://systemd.io/BOOT_LOADER_SPECIFICATION
392 2. Boot Loader Interface
394 https://systemd.io/BOOT_LOADER_INTERFACE
395 3. Random Seeds
397 https://systemd.io/RANDOM_SEEDS
398systemd 251 BOOTCTL(1)