1SYSTEMD-STUB(7) systemd-stub SYSTEMD-STUB(7)
2
6 systemd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub
7 - 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 8
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 4 (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 8
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 4
97 (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 The following EFI variables are defined, set and read by systemd-stub,
109 under the vendor UUID "4a67b082-0a4c-41cf-b6c7-440b29bb8c4f", for
110 communication between the boot stub and the OS:
111 LoaderDevicePartUUID
113 Contains the partition UUID of the EFI System Partition the EFI
114 image was run from. systemd-gpt-auto-generator(8) uses this
115 information to automatically find the disk booted from, in order to
116 discover various other partitions on the same disk automatically.
117 LoaderFirmwareInfo, LoaderFirmwareType
119 Brief firmware information. Use bootctl(1) to view this data.
120 LoaderImageIdentifier
122 The path of EFI executable, relative to the EFI System Partition's
123 root directory. Use bootctl(1) to view this data.
124 StubInfo
126 Brief stub information. Use bootctl(1) to view this data.
127 Note that some of the variables above may also be set by the boot
129 loader. The stub will only set them if they aren't set already. Some of
130 these variables are defined by the Boot Loader Interface[1].
131
133 In order to assemble an UEFI PE kernel image from various components as
134 described above, use an objcopy(1) command line like this:
135 objcopy \
137 --add-section .osrel=os-release --change-section-vma .osrel=0x20000 \
138 --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \
139 --add-section .dtb=devicetree.dtb --change-section-vma .dtb=0x40000 \
140 --add-section .splash=splash.bmp --change-section-vma .splash=0x100000 \
141 --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \
142 --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \
143 /usr/lib/systemd/boot/efi/linuxx64.efi.stub \
144 foo-unsigned.efi
145 This generates one PE executable file foo-unsigned.efi from the six
147 individual files for OS release information, kernel command line, boot
148 splash image, kernel image, main initrd and UEFI boot stub.
149 To then sign the resulting image for UEFI SecureBoot use an sbsign(1)
151 command like the following:
152 sbsign \
154 --key mykey.pem \
155 --cert mykey.crt \
156 --output foo.efi \
157 foo-unsigned.efi
158 This expects a pair of X.509 private key and certificate as parameters
160 and then signs the UEFI PE executable we generated above for UEFI
161 SecureBoot and generates a signed UEFI PE executable as result.
162
164 systemd-boot(7), systemd.exec(5), systemd-creds(1), systemd-sysext(8),
165 Boot Loader Specification[2], Boot Loader Interface[1], objcopy(1),
166 sbsign(1)
167
169 1. Boot Loader Interface
170 https://systemd.io/BOOT_LOADER_INTERFACE
171 2. Boot Loader Specification
173 https://systemd.io/BOOT_LOADER_SPECIFICATION
174systemd 250 SYSTEMD-STUB(7)