1SYSTEMD-STUB(7) systemd-stub SYSTEMD-STUB(7)
2
6 systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub,
7 linuxaa64.efi.stub - A simple UEFI kernel boot stub
8
10 /usr/lib/systemd/boot/efi/linuxx64.efi.stub
11 /usr/lib/systemd/boot/efi/linuxia32.efi.stub
13 /usr/lib/systemd/boot/efi/linuxaa64.efi.stub
15 ESP/.../foo.efi.extra.d/*.cred
17 ESP/.../foo.efi.extra.d/*.raw
19 ESP/loader/credentials/*.cred
21
23 systemd-stub (stored in per-architecture files linuxx64.efi.stub,
24 linuxia32.efi.stub, linuxaa64.efi.stub on disk) is a simple UEFI boot
25 stub. An UEFI boot stub is attached to a Linux kernel binary image, and
26 is a piece of code that runs in the UEFI firmware environment before
27 transitioning into the Linux kernel environment. The UEFI boot stub
28 ensures a Linux kernel is executable as regular UEFI binary, and is
29 able to do various preparations before switching the system into the
30 Linux world.
31 The UEFI boot stub looks for various resources for the kernel
33 invocation inside the UEFI PE binary itself. This allows combining
34 various resources inside a single PE binary image, which may then be
35 signed via UEFI SecureBoot as a whole, covering all individual
36 resources at once. Specifically it may include:
37 • The ELF Linux kernel images will be looked for in the ".linux" PE
39 section of the executed image.
40 • The initial RAM disk (initrd) will be looked for in the ".initrd"
42 PE section.
43 • A compiled binary DeviceTree will be looked for in the ".dtb" PE
45 section.
46 • The kernel command line to pass to the invoked kernel will be
48 looked for in the ".cmdline" PE section.
49 • A boot splash (in Windows .BMP format) to show on screen before
51 invoking the kernel will be looked for in the ".splash" PE section.
52 If UEFI SecureBoot is enabled and the ".cmdline" section is present in
54 the executed image, any attempts to override the kernel command line by
55 passing one as invocation parameters to the EFI binary are ignored.
56 Thus, in order to allow overriding the kernel command line, either
57 disable UEFI SecureBoot, or don't include a kernel command line PE
58 section in the kernel image file. If a command line is accepted via EFI
59 invocation parameters to the EFI binary it is measured into TPM PCR 12
60 (if a TPM is present).
61 If a DeviceTree is embedded in the ".dtb" section, it replaces an
63 existing DeviceTree in the corresponding EFI configuration table.
64 systemd-stub will ask the firmware via the "EFI_DT_FIXUP_PROTOCOL" for
65 hardware specific fixups to the DeviceTree.
66
68 The systemd-stub UEFI boot stub automatically collects two types of
69 auxiliary companion files optionally placed in drop-in directories on
70 the same partition as the EFI binary, dynamically generates cpio initrd
71 archives from them, and passes them to the kernel. Specifically:
72 • For a kernel binary called foo.efi, it will look for files with the
74 .cred suffix in a directory named foo.efi.extra.d/ next to it. A
75 cpio archive is generated from all files found that way, placing
76 them in the /.extra/credentials/ directory of the initrd file
77 hierarchy. The main initrd may then access them in this directory.
78 This is supposed to be used to store auxiliary, encrypted,
79 authenticated credentials for use with LoadCredentialEncrypted= in
80 the UEFI System Partition. See systemd.exec(5) and systemd-creds(1)
81 for details on encrypted credentials. The generated cpio archive is
82 measured into TPM PCR 12 (if a TPM is present).
83 • Similarly, files foo.efi.extra.d/*.raw are packed up in a cpio
85 archive and placed in the /.extra/sysext/ directory in the initrd
86 file hierarchy. This is supposed to be used to pass additional
87 system extension images to the initrd. See systemd-sysext(8) for
88 details on system extension images. The generated cpio archive
89 containing these system extension images is measured into TPM PCR 4
90 (if a TPM is present).
91 • Files /loader/credentials/*.cred are packed up in a cpio archive
93 and placed in the /.extra/global_credentials/ directory of the
94 initrd file hierarchy. This is supposed to be used to pass
95 additional credentials to the initrd, regardless of the kernel
96 being booted. The generated cpio archive is measured into TPM PCR
97 12 (if a TPM is present)
98 These mechanisms may be used to parameterize and extend trusted (i.e.
100 signed), immutable initrd images in a reasonably safe way: all data
101 they contain is measured into TPM PCRs. On access they should be
102 further validated: in case of the credentials case by
103 encrypting/authenticating them via TPM, as exposed by systemd-creds
104 encrypt -T (see systemd-creds(1) for details); in case of the system
105 extension images by using signed Verity images.
106
108 Note that when a unified kernel using systemd-stub is invoked the
109 firmware will measure it as a whole to TPM PCR 4, covering all embedded
110 resources, such as the stub code itself, the core kernel, the embedded
111 initrd and kernel command line (see above for a full list).
112 Also note that the Linux kernel will measure all initrds it receives
114 into TPM PCR 9. This means every type of initrd will be measured twice:
115 the initrd embedded in the kernel image will be measured to both PCR 4
116 and PCR 9; the initrd synthesized from credentials will be measured to
117 both PCR 12 and PCR 9; the initrd synthesized from system extensions
118 will be measured to both PCR 4 and PCR 9. Let's summarize the OS
119 resources and the PCRs they are measured to:
120 Table 1. OS Resource PCR Summary
122 ┌───────────────────────────┬─────────────────┐
123 │OS Resource │ Measurement PCR │
124 ├───────────────────────────┼─────────────────┤
125 │systemd-stub code (the │ 4 │
126 │entry point of the unified │ │
127 │PE binary) │ │
128 ├───────────────────────────┼─────────────────┤
129 │Boot splash (embedded in │ 4 │
130 │the unified PE binary) │ │
131 ├───────────────────────────┼─────────────────┤
132 │Core kernel code (embedded │ 4 │
133 │in unified PE binary) │ │
134 ├───────────────────────────┼─────────────────┤
135 │Main initrd (embedded in │ 4 + 9 │
136 │unified PE binary) │ │
137 ├───────────────────────────┼─────────────────┤
138 │Default kernel command │ 4 │
139 │line (embedded in unified │ │
140 │PE binary) │ │
141 ├───────────────────────────┼─────────────────┤
142 │Overridden kernel command │ 12 │
143 │line │ │
144 ├───────────────────────────┼─────────────────┤
145 │Credentials (synthesized │ 12 + 9 │
146 │initrd from companion │ │
147 │files) │ │
148 ├───────────────────────────┼─────────────────┤
149 │System Extensions │ 4 + 9 │
150 │(synthesized initrd from │ │
151 │companion files) │ │
152 └───────────────────────────┴─────────────────┘
153
155 The following EFI variables are defined, set and read by systemd-stub,
156 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
157 communication between the boot stub and the OS:
158 LoaderDevicePartUUID
160 Contains the partition UUID of the EFI System Partition the EFI
161 image was run from. systemd-gpt-auto-generator(8) uses this
162 information to automatically find the disk booted from, in order to
163 discover various other partitions on the same disk automatically.
164 LoaderFirmwareInfo, LoaderFirmwareType
166 Brief firmware information. Use bootctl(1) to view this data.
167 LoaderImageIdentifier
169 The path of EFI executable, relative to the EFI System Partition's
170 root directory. Use bootctl(1) to view this data.
171 StubInfo
173 Brief stub information. Use bootctl(1) to view this data.
174 Note that some of the variables above may also be set by the boot
176 loader. The stub will only set them if they aren't set already. Some of
177 these variables are defined by the Boot Loader Interface[1].
178
180 In order to assemble an UEFI PE kernel image from various components as
181 described above, use an objcopy(1) command line like this:
182 objcopy \
184 --add-section .osrel=os-release --change-section-vma .osrel=0x20000 \
185 --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
186 --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
187 --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
188 --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
189 --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
190 /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
191 foo-unsigned.efi
192 This generates one PE executable file foo-unsigned.efi from the six
194 individual files for OS release information, kernel command line, boot
195 splash image, kernel image, main initrd and UEFI boot stub.
196 To then sign the resulting image for UEFI SecureBoot use an sbsign(1)
198 command like the following:
199 sbsign \
201 --key mykey.pem \
202 --cert mykey.crt \
203 --output foo.efi \
204 foo-unsigned.efi
205 This expects a pair of X.509 private key and certificate as parameters
207 and then signs the UEFI PE executable we generated above for UEFI
208 SecureBoot and generates a signed UEFI PE executable as result.
209
211 systemd-boot(7), systemd.exec(5), systemd-creds(1), systemd-sysext(8),
212 Boot Loader Specification[2], Boot Loader Interface[1], objcopy(1),
213 sbsign(1)
214
216 1. Boot Loader Interface
217 https://systemd.io/BOOT_LOADER_INTERFACE
218 2. Boot Loader Specification
220 https://systemd.io/BOOT_LOADER_SPECIFICATION
221systemd 251 SYSTEMD-STUB(7)