1LOADER.CONF(5) loader.conf LOADER.CONF(5)
2
6 loader.conf - Configuration file for systemd-boot
7
9 ESP/loader/loader.conf, ESP/loader/entries/*.conf
10 XBOOTLDR/loader/entries/*.conf
11
13 systemd-boot(7) will read ESP/loader/loader.conf, and any files with
14 the ".conf" extension under ESP/loader/entries/ on the EFI system
15 partition (ESP), and XBOOTLDR/loader/entries/ on the extended boot
16 loader partition (XBOOTLDR) as defined by Boot Loader Specification[1].
17 Each of these configuration files must consist of series of newline
19 (i.e. ASCII code 10) separated lines, each consisting of an option
20 name, followed by whitespace, and the option value. "#" may be used to
21 start a comment line. Empty and comment lines are ignored. The files
22 use UTF-8 encoding.
23 Boolean arguments may be written as "yes"/"y"/"true"/"t"/"on"/"1" or
25 "no"/"n"/"false"/"f"/"off"/"0".
26
28 The configuration options supported by ESP/loader/entries/*.conf and
29 XBOOTLDR/loader/entries/*.conf files are defined as part of the Boot
30 Loader Specification[1].
31 The following configuration are supported by the loader.conf
33 configuration file:
34 default
36 A glob pattern to select the default entry. The default entry may
37 be changed in the boot menu itself, in which case the name of the
38 selected entry will be stored as an EFI variable, overriding this
39 option.
40 If set to "@saved" the chosen entry will be saved as an EFI
42 variable on every boot and automatically selected the next time the
43 boot loader starts.
44 Table 1. Automatically detected entries will use the following
46 names:
47 ┌──────────────────────────────┬──────────────────────┐
48 │Name │ Description │
49 ├──────────────────────────────┼──────────────────────┤
50 │auto-efi-default │ EFI Default Loader │
51 ├──────────────────────────────┼──────────────────────┤
52 │auto-efi-shell │ EFI Shell │
53 ├──────────────────────────────┼──────────────────────┤
54 │auto-osx │ macOS │
55 ├──────────────────────────────┼──────────────────────┤
56 │auto-reboot-to-firmware-setup │ Reboot Into Firmware │
57 │ │ Interface │
58 ├──────────────────────────────┼──────────────────────┤
59 │auto-windows │ Windows Boot Manager │
60 └──────────────────────────────┴──────────────────────┘
61 Supported glob wildcard patterns are "?", "*", and "[...]"
62 (including ranges). Note that these patterns use the same syntax as
63 glob(7), but do not support all features. In particular, set
64 negation and named character classes are not supported. The
65 matching is done case-insensitively on the entry ID (as shown by
66 bootctl list).
67 timeout
69 How long the boot menu should be shown before the default entry is
70 booted, in seconds. This may be changed in the boot menu itself and
71 will be stored as an EFI variable in that case, overriding this
72 option.
73 If set to "menu-hidden" or "0" (the default) no menu is shown and
75 the default entry will be booted immediately. The menu can be shown
76 by pressing and holding a key before systemd-boot is launched.
77 Setting this to "menu-force" disables the timeout while always
78 showing the menu.
79 console-mode
81 This option configures the resolution of the console. Takes a
82 number or one of the special values listed below. The following
83 values may be used:
84 0
86 Standard UEFI 80x25 mode
87 1
89 80x50 mode, not supported by all devices
90 2
92 the first non-standard mode provided by the device firmware, if
93 any
94 auto
96 Pick a suitable mode automatically using heuristics
97 max
99 Pick the highest-numbered available mode
100 keep
102 Keep the mode selected by firmware (the default)
103 editor
105 Takes a boolean argument. Enable (the default) or disable the
106 editor. The editor should be disabled if the machine can be
107 accessed by unauthorized persons.
108 auto-entries
110 Takes a boolean argument. Enable (the default) or disable entries
111 for other boot entries found on the boot partition. In particular,
112 this may be useful when loader entries are created to show
113 replacement descriptions for those entries.
114 auto-firmware
116 A boolean controlling the presence of the "Reboot into firmware"
117 entry (enabled by default). If this is disabled, the firmware
118 interface may still be reached by using the f key.
119 beep
121 Takes a boolean argument. If timeout enabled beep every second,
122 otherwise beep n times when n-th entry in boot menu is selected
123 (default disabled). Currently, only x86 is supported, where it uses
124 the PC speaker.
125 secure-boot-enroll
127 Danger: this feature might soft-brick your device if used
128 improperly.
129 Controls enrollment of secure boot keys found on the ESP if the
131 system is in setup mode:
132 off
134 No action is taken.
135 manual
137 Boot entries for found secure boot keys are created that allow
138 manual enrollment.
139 if-safe
141 Same behavior as manual, but will try to automatically enroll
142 the key "auto" if it is considered to be safe. Currently, this
143 is only the case if the system is running inside a virtual
144 machine.
145 force
147 Always enroll the "auto" key if found. Note that a warning
148 message with a timeout will still be shown if this operation is
149 unknown to be safe.
150 The different sets of variables can be set up under
152 /loader/keys/NAME where NAME is the name that is going to be used
153 as the name of the entry. This allows one to ship multiple sets of
154 Secure Boot variables and choose which one to enroll at runtime.
155 Supported Secure Boot variables are one database for authorized
157 images, one for the key exchange key (KEK) and one for the platform
158 key (PK). For more information, refer to the UEFI specification[2],
159 under Secure Boot and Driver Signing. Another resource that
160 describe the interplay of the different variables is the EDK2
161 documentation[3].
162 A complete set of UEFI variable includes db.auth, KEK.auth and
164 PK.auth. Note that these files need to be authenticated UEFI
165 variables. See below for an example of how to generate them from
166 regular X.509 keys.
167 uuid=$(systemd-id128 new --uuid)
169 for key in PK KEK db; do
170 openssl req -new -x509 -subj "/CN=${key}/" -keyout "${key}.key" -out "${key}.crt"
171 openssl x509 -outform DER -in "${key}.crt" -out "${key}.der"
172 sbsiglist --owner "${uuid}" --type x509 --output "${key}.esl" "${key}.der"
173 done
174 for key in MicWinProPCA2011_2011-10-19.crt MicCorUEFCA2011_2011-06-27.crt MicCorKEKCA2011_2011-06-24.crt; do
176 curl "https://www.microsoft.com/pkiops/certs/${key}" --output "${key}"
177 sbsiglist --owner 77fa9abd-0359-4d32-bd60-28f4e78f784b --type x509 --output "${key%crt}esl" "${key}"
178 done
179 # Optionally add Microsoft Windows Production CA 2011 (needed to boot into Windows).
181 cat MicWinProPCA2011_2011-10-19.esl >>db.esl
182 # Optionally add Microsoft Corporation UEFI CA 2011 for firmware drivers / option ROMs
184 # and third-party boot loaders (including shim). This is highly recommended on real
185 # hardware as not including this may soft-brick your device (see next paragraph).
186 cat MicCorUEFCA2011_2011-06-27.esl >>db.esl
187 # Optionally add Microsoft Corporation KEK CA 2011. Recommended if either of the
189 # Microsoft keys is used as the official UEFI revocation database is signed with this
190 # key. The revocation database can be updated with fwupdmgr(1).
191 cat MicCorKEKCA2011_2011-06-24.esl >>KEK.esl
192 attr=NON_VOLATILE,RUNTIME_ACCESS,BOOTSERVICE_ACCESS,TIME_BASED_AUTHENTICATED_WRITE_ACCESS
194 sbvarsign --attr ${attr} --key PK.key --cert PK.crt --output PK.auth PK PK.esl
195 sbvarsign --attr ${attr} --key PK.key --cert PK.crt --output KEK.auth KEK KEK.esl
196 sbvarsign --attr ${attr} --key KEK.key --cert KEK.crt --output db.auth db db.esl
197 This feature is considered dangerous because even if all the
200 required files are signed with the keys being loaded, some files
201 necessary for the system to function properly still won't be. This
202 is especially the case with Option ROMs (e.g. for storage
203 controllers or graphics cards). See Secure Boot and Option ROMs[4]
204 for more details.
205 reboot-for-bitlocker
207 Caveat: This feature is experimental, and is likely to be changed
208 (or removed in its current form) in a future version of systemd.
209 Work around BitLocker requiring a recovery key when the boot loader
211 was updated (disabled by default).
212 Try to detect BitLocker encrypted drives along with an active TPM.
214 If both are found and Windows Boot Manager is selected in the boot
215 menu, set the "BootNext" EFI variable and restart the system. The
216 firmware will then start Windows Boot Manager directly, leaving the
217 TPM PCRs in expected states so that Windows can unseal the
218 encryption key. This allows systemd-boot(7) to be updated without
219 having to provide the recovery key for BitLocker drive unlocking.
220 Note that the PCRs that Windows uses can be configured with the
222 "Configure TPM platform validation profile for native UEFI firmware
223 configurations" group policy under "Computer
224 Configuration\Administrative Templates\Windows Components\BitLocker
225 Drive Encryption". When Secure Boot is enabled, changing this to
226 PCRs "0,2,7,11" should be safe. The TPM key protector needs to be
227 removed and then added back for the PCRs on an already encrypted
228 drive to change. If PCR 4 is not measured, this setting can be
229 disabled to speed up booting into Windows.
230
232 # /boot/efi/loader/loader.conf
233 timeout 0
234 default 01234567890abcdef1234567890abdf0-*
235 editor no
236 The menu will not be shown by default (the menu can still be shown by
239 pressing and holding a key during boot). One of the entries with files
240 with a name starting with "01234567890abcdef1234567890abdf0-" will be
241 selected by default. If more than one entry matches, the one with the
242 highest priority will be selected (generally the one with the highest
243 version number). The editor will be disabled, so it is not possible to
244 alter the kernel command line.
245
247 systemd-boot(7), bootctl(1)
248
250 1. Boot Loader Specification
251 https://uapi-group.org/specifications/specs/boot_loader_specification
252 2. UEFI specification
254 https://uefi.org/specifications
255 3. EDK2 documentation
257 https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot
258 4. Secure Boot and Option ROMs
260 https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom
261systemd 254 LOADER.CONF(5)