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

NAME

6       systemd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub
7       - 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 8
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 4 (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 8
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 4
97           (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

EFI VARIABLES

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
112       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
118       LoaderFirmwareInfo, LoaderFirmwareType
119           Brief firmware information. Use bootctl(1) to view this data.
120
121       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
125       StubInfo
126           Brief stub information. Use bootctl(1) to view this data.
127
128       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

ASSEMBLING KERNEL IMAGES

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
136           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
146       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
150       To then sign the resulting image for UEFI SecureBoot use an sbsign(1)
151       command like the following:
152
153           sbsign \
154               --key mykey.pem \
155               --cert mykey.crt \
156               --output foo.efi \
157               foo-unsigned.efi
158
159       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

SEE ALSO

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

NOTES

169        1. Boot Loader Interface
170           https://systemd.io/BOOT_LOADER_INTERFACE
171
172        2. Boot Loader Specification
173           https://systemd.io/BOOT_LOADER_SPECIFICATION
174
175
176
177systemd 250                                                    SYSTEMD-STUB(7)
Impressum