1LOADER.CONF(5)                    loader.conf                   LOADER.CONF(5)
2
3
4

NAME

6       loader.conf - Configuration file for systemd-boot
7

SYNOPSIS

9       ESP/loader/loader.conf, ESP/loader/entries/*.conf
10       XBOOTLDR/loader/entries/*.conf
11

DESCRIPTION

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
18       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
24       Boolean arguments may be written as "yes"/"y"/"true"/"t"/"on"/"1" or
25       "no"/"n"/"false"/"f"/"off"/"0".
26

OPTIONS

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
32       The following configuration are supported by the loader.conf
33       configuration file:
34
35       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
41           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
45           Table 1. Automatically detected entries will use the following
46           names:
47           ┌──────────────────────────────┬──────────────────────┐
48Name                          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
68       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
74           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
80       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
85           0
86               Standard UEFI 80x25 mode
87
88           1
89               80x50 mode, not supported by all devices
90
91           2
92               the first non-standard mode provided by the device firmware, if
93               any
94
95           auto
96               Pick a suitable mode automatically using heuristics
97
98           max
99               Pick the highest-numbered available mode
100
101           keep
102               Keep the mode selected by firmware (the default)
103
104       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
109       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
115       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
120       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
126       secure-boot-enroll
127           Danger: this feature might soft-brick your device if used
128           improperly.
129
130           Controls enrollment of secure boot keys found on the ESP if the
131           system is in setup mode:
132
133           off
134               No action is taken.
135
136           manual
137               Boot entries for found secure boot keys are created that allow
138               manual enrollment.
139
140           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
146           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
151           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
156           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
163           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
168               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
175               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
180               # Optionally add Microsoft Windows Production CA 2011 (needed to boot into Windows).
181               cat MicWinProPCA2011_2011-10-19.esl >>db.esl
182
183               # 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
188               # 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
193               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
198
199           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
206       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
210           Work around BitLocker requiring a recovery key when the boot loader
211           was updated (disabled by default).
212
213           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
221           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

EXAMPLE

232           # /boot/efi/loader/loader.conf
233           timeout 0
234           default 01234567890abcdef1234567890abdf0-*
235           editor no
236
237
238       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

SEE ALSO

247       systemd-boot(7), bootctl(1)
248

NOTES

250        1. Boot Loader Specification
251           https://uapi-group.org/specifications/specs/boot_loader_specification
252
253        2. UEFI specification
254           https://uefi.org/specifications
255
256        3. EDK2 documentation
257           https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/uefi_secure_boot
258
259        4. Secure Boot and Option ROMs
260           https://github.com/Foxboron/sbctl/wiki/FAQ#option-rom
261
262
263
264systemd 253                                                     LOADER.CONF(5)
Impressum