[thirdparty/systemd.git] / docs / BOOT.md

---
title: systemd-boot UEFI Boot Manager
category: Documentation for Developers
layout: default
SPDX-License-Identifier: LGPL-2.1-or-later
---

# systemd-boot UEFI Boot Manager

systemd-boot is a UEFI boot manager which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu.

systemd-boot operates on the EFI System Partition (ESP) only. Configuration file fragments, kernels, initrds, other EFI images need to reside on the ESP.

Linux kernels need to be built with CONFIG\_EFI\_STUB to be able to be directly executed as an EFI image.

systemd-boot reads simple and entirely generic boot loader configuration files; one file per boot loader entry to select from. All files need to reside on the ESP.

Pressing the Space key (or most other keys actually work too) during bootup will show an on-screen menu with all configured loader entries to select from.

Pressing Enter on the selected entry loads and starts the EFI image.

If no timeout is configured, which is the default setting, and no key pressed during bootup, the default entry is executed right away.

![systemd-boot menu](/assets/systemd-boot-menu.png)

All configuration files are expected to be 7-bit ASCII or valid UTF8. The loader configuration file understands the following keywords:

| Config  |
|---------|------------------------------------------------------------|
| default | pattern to select the default entry in the list of entries |
| timeout | timeout in seconds for how long to show the menu           |


The entry configuration files understand the following keywords:

| Entry  |
|--------|------------------------------------------------------------|
| title | text to show in the menu |
| version | version string to append to the title when the title is not unique |
| machine-id | machine identifier to append to the title when the title is not unique |
| efi | executable EFI image |
| options | options to pass to the EFI image / kernel command line |
| linux | linux kernel image (systemd-boot still requires the kernel to have an EFI stub) |
| initrd | initramfs image (systemd-boot just adds this as option initrd=) |


Examples:
```
/boot/loader/loader.conf
timeout 3
default 6a9857a393724b7a981ebb5b8495b9ea-*

/boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf
title      Fedora 19 (Rawhide)
version    3.8.0-2.fc19.x86_64
machine-id 6a9857a393724b7a981ebb5b8495b9ea
linux      /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
initrd     /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd
options    root=UUID=f8f83f73-df71-445c-87f7-31f70263b83b quiet

/boot/loader/entries/custom-kernel.conf
title      My kernel
efi        /bzImage
options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08

/boot/loader/entries/custom-kernel-initrd.conf
title      My kernel with initrd
linux      /bzImage
initrd     /initrd.img
options    root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet`
```


While the menu is shown, the following keys are active:

| Keys   |
|--------|------------------------------------------------------------|
| Up/Down | Select menu entry |
| Enter | boot the selected entry |
| d | select the default entry to boot (stored in a non-volatile EFI variable) |
| t/T | adjust the timeout (stored in a non-volatile EFI variable) |
| e | edit the option line (kernel command line) for this bootup to pass to the EFI image |
| Q | quit |
| v | show the systemd-boot and UEFI version |
| P | print the current configuration to the console |
| h | show key mapping |

Hotkeys to select a specific entry in the menu, or when pressed during bootup to boot the entry right-away:


| Keys   |
|--------|------------------------------------------------------------|
| l | Linux |
| w | Windows |
| a | OS X |
| s | EFI Shell |
| 1-9 | number of entry |

Some EFI variables control the loader or exported the loaders state to the started operating system. The vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` and the variable names are supposed to be shared across all loaders implementations which follow this scheme of configuration:

| EFI Variables |
|---------------|------------------------|-------------------------------|
| LoaderEntryDefault | entry identifier to select as default at bootup  | non-volatile |
| LoaderConfigTimeout | timeout in seconds to show the menu | non-volatile |
| LoaderEntryOneShot | entry identifier to select at the next and only the next bootup | non-volatile |
| LoaderDeviceIdentifier | list of identifiers of the volume the loader was started from | volatile |
| LoaderDevicePartUUID | partition GPT UUID of the ESP systemd-boot was executed from | volatile |


Links:

[https://github.com/systemd/systemd](https://github.com/systemd/systemd)

[https://uapi-group.org/specifications/specs/boot_loader_specification/](https://uapi-group.org/specifications/specs/boot_loader_specification/)
Commit	Line	Data
163e2c83 MG	1	---
	2	title: systemd-boot UEFI Boot Manager
	3	category: Documentation for Developers
	4	layout: default
	5	SPDX-License-Identifier: LGPL-2.1-or-later
	6	---
	7
	8	# systemd-boot UEFI Boot Manager
	9
	10	systemd-boot is a UEFI boot manager which executes configured EFI images. The default entry is selected by a configured pattern (glob) or an on-screen menu.
	11
e9a55bab	12	systemd-boot operates on the EFI System Partition (ESP) only. Configuration file fragments, kernels, initrds, other EFI images need to reside on the ESP.
	13
	14	Linux kernels need to be built with CONFIG\_EFI\_STUB to be able to be directly executed as an EFI image.
163e2c83 MG	15
	16	systemd-boot reads simple and entirely generic boot loader configuration files; one file per boot loader entry to select from. All files need to reside on the ESP.
	17
e9a55bab	18	Pressing the Space key (or most other keys actually work too) during bootup will show an on-screen menu with all configured loader entries to select from.
	19
	20	Pressing Enter on the selected entry loads and starts the EFI image.
163e2c83 MG	21
	22	If no timeout is configured, which is the default setting, and no key pressed during bootup, the default entry is executed right away.
	23
	24	![systemd-boot menu](/assets/systemd-boot-menu.png)
	25
	26	All configuration files are expected to be 7-bit ASCII or valid UTF8. The loader configuration file understands the following keywords:
	27
	28	\| Config \|
	29	\|---------\|------------------------------------------------------------\|
	30	\| default \| pattern to select the default entry in the list of entries \|
	31	\| timeout \| timeout in seconds for how long to show the menu \|
	32
	33
	34	The entry configuration files understand the following keywords:
	35
	36	\| Entry \|
	37	\|--------\|------------------------------------------------------------\|
	38	\| title \| text to show in the menu \|
	39	\| version \| version string to append to the title when the title is not unique \|
	40	\| machine-id \| machine identifier to append to the title when the title is not unique \|
	41	\| efi \| executable EFI image \|
	42	\| options \| options to pass to the EFI image / kernel command line \|
	43	\| linux \| linux kernel image (systemd-boot still requires the kernel to have an EFI stub) \|
	44	\| initrd \| initramfs image (systemd-boot just adds this as option initrd=) \|
	45
	46
	47	Examples:
	48	```
	49	/boot/loader/loader.conf
	50	timeout 3
	51	default 6a9857a393724b7a981ebb5b8495b9ea-*
	52
	53	/boot/loader/entries/6a9857a393724b7a981ebb5b8495b9ea-3.8.0-2.fc19.x86_64.conf
	54	title Fedora 19 (Rawhide)
	55	version 3.8.0-2.fc19.x86_64
	56	machine-id 6a9857a393724b7a981ebb5b8495b9ea
	57	linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
	58	initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd
	59	options root=UUID=f8f83f73-df71-445c-87f7-31f70263b83b quiet
	60
	61	/boot/loader/entries/custom-kernel.conf
	62	title My kernel
	63	efi /bzImage
	64	options root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08
	65
	66	/boot/loader/entries/custom-kernel-initrd.conf
	67	title My kernel with initrd
	68	linux /bzImage
	69	initrd /initrd.img
	70	options root=PARTUUID=084917b7-8be2-4e86-838d-f771a9902e08 quiet`
	71	```
	72
	73
	74	While the menu is shown, the following keys are active:
	75
	76	\| Keys \|
	77	\|--------\|------------------------------------------------------------\|
	78	\| Up/Down \| Select menu entry \|
	79	\| Enter \| boot the selected entry \|
	80	\| d \| select the default entry to boot (stored in a non-volatile EFI variable) \|
	81	\| t/T \| adjust the timeout (stored in a non-volatile EFI variable) \|
	82	\| e \| edit the option line (kernel command line) for this bootup to pass to the EFI image \|
	83	\| Q \| quit \|
	84	\| v \| show the systemd-boot and UEFI version \|
85	\| P \| print the current configuration to the console \|
86	\| h \| show key mapping \|
87
88	Hotkeys to select a specific entry in the menu, or when pressed during bootup to boot the entry right-away:
89
90
91
92	\| Keys \|
93	\|--------\|------------------------------------------------------------\|
94	\| l \| Linux \|
95	\| w \| Windows \|
96	\| a \| OS X \|
97	\| s \| EFI Shell \|
98	\| 1-9 \| number of entry \|
99
100	Some EFI variables control the loader or exported the loaders state to the started operating system. The vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f` and the variable names are supposed to be shared across all loaders implementations which follow this scheme of configuration:
101
102	\| EFI Variables \|
103	\|---------------\|------------------------\|-------------------------------\|
104	\| LoaderEntryDefault \| entry identifier to select as default at bootup \| non-volatile \|
105	\| LoaderConfigTimeout \| timeout in seconds to show the menu \| non-volatile \|
106	\| LoaderEntryOneShot \| entry identifier to select at the next and only the next bootup \| non-volatile \|
107	\| LoaderDeviceIdentifier \| list of identifiers of the volume the loader was started from \| volatile \|
108	\| LoaderDevicePartUUID \| partition GPT UUID of the ESP systemd-boot was executed from \| volatile \|
109
110
111	Links:
112
113	[https://github.com/systemd/systemd](https://github.com/systemd/systemd)
114
5f1b83d2	115	[https://uapi-group.org/specifications/specs/boot_loader_specification/](https://uapi-group.org/specifications/specs/boot_loader_specification/)