1SYSTEMD-STUB(7)                  systemd-stub                  SYSTEMD-STUB(7)
2
3
4

NAME

6       systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub,
7       linuxaa64.efi.stub - A simple UEFI kernel boot stub
8

SYNOPSIS

10       /usr/lib/systemd/boot/efi/linuxx64.efi.stub
11
12       /usr/lib/systemd/boot/efi/linuxia32.efi.stub
13
14       /usr/lib/systemd/boot/efi/linuxaa64.efi.stub
15
16       ESP/.../foo.efi.extra.d/*.cred
17
18       ESP/.../foo.efi.extra.d/*.raw
19
20       ESP/loader/credentials/*.cred
21

DESCRIPTION

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
32       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
38       •   The ELF Linux kernel images will be looked for in the ".linux" PE
39           section of the executed image.
40
41       •   The initial RAM disk (initrd) will be looked for in the ".initrd"
42           PE section.
43
44       •   A compiled binary DeviceTree will be looked for in the ".dtb" PE
45           section.
46
47       •   The kernel command line to pass to the invoked kernel will be
48           looked for in the ".cmdline" PE section.
49
50       •   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
53       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
62       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

COMPANION FILES

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
73       •   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
84       •   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
92       •   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
99       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

TPM2 PCR NOTES

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
113       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
121       Table 1. OS Resource PCR Summary
122       ┌───────────────────────────┬─────────────────┐
123OS Resource                Measurement PCR 
124       ├───────────────────────────┼─────────────────┤
125systemd-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

EFI VARIABLES

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
159       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
165       LoaderFirmwareInfo, LoaderFirmwareType
166           Brief firmware information. Use bootctl(1) to view this data.
167
168       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
172       StubInfo
173           Brief stub information. Use bootctl(1) to view this data.
174
175       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

ASSEMBLING KERNEL IMAGES

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
183           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
193       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
197       To then sign the resulting image for UEFI SecureBoot use an sbsign(1)
198       command like the following:
199
200           sbsign \
201               --key mykey.pem \
202               --cert mykey.crt \
203               --output foo.efi \
204               foo-unsigned.efi
205
206       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

SEE ALSO

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

NOTES

216        1. Boot Loader Interface
217           https://systemd.io/BOOT_LOADER_INTERFACE
218
219        2. Boot Loader Specification
220           https://systemd.io/BOOT_LOADER_SPECIFICATION
221
222
223
224systemd 251                                                    SYSTEMD-STUB(7)
Impressum