diff --git a/man/rules/meson.build b/man/rules/meson.build index c6f343d8e5..f9c69f1846 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -954,6 +954,10 @@ manpages = [ ['systemd-sleep.conf', '5', ['sleep.conf.d'], ''], ['systemd-socket-activate', '1', [], ''], ['systemd-socket-proxyd', '8', [], ''], + ['systemd-stub', + '7', + ['linuxaa64.efi.stub', 'linuxia32.efi.stub', 'linuxx64.efi.stub'], + 'ENABLE_EFI'], ['systemd-suspend.service', '8', ['systemd-hibernate.service', diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 8685ed50ff..83b95efa3e 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -102,6 +102,12 @@ may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate description files compliant with the Boot Loader Specification. + + systemd-stub7 + may be used as UEFI boot stub for executed kernels, which is useful to show graphical boot splashes + before transitioning into the Linux world. It is also capable of automatically picking up auxiliary + credential files (for boot parameterization) and system extension images, as companion files to the + booted kernel images. @@ -493,6 +499,7 @@ systemd-bless-boot.service8, systemd-boot-system-token.service8, kernel-install8, + systemd-stub7, Boot Loader Specification, Boot Loader Interface diff --git a/man/systemd-stub.xml b/man/systemd-stub.xml new file mode 100644 index 0000000000..2edc64ce17 --- /dev/null +++ b/man/systemd-stub.xml @@ -0,0 +1,204 @@ + + + + + + + systemd-stub + systemd + + + + systemd-stub + 7 + + + + systemd-stub + linuxx64.efi.stub + linuxia32.efi.stub + linuxaa64.efi.stub + A simple UEFI kernel boot stub + + + + /usr/lib/systemd/boot/efi/linuxx64.efi.stub + /usr/lib/systemd/boot/efi/linuxia32.efi.stub + /usr/lib/systemd/boot/efi/linuxaa64.efi.stub + + + + Description + + systemd-stub (stored in per-architecture files + linuxx64.efi.stub, linuxia32.efi.stub, + linuxaa64.efi.stub on disk) is a simple UEFI boot stub. An UEFI boot stub is + attached to a Linux kernel binary image, and is a piece of code that runs in the UEFI firmware + environment before transitioning into the Linux kernel environment. The UEFI boot stub ensures a Linux + kernel is executable as regular UEFI binary, and is able to do various preparations before switching the + system into the Linux world. + + The UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE binary + itself. This allows combining various resources inside a single PE binary image, which may then be signed + via UEFI SecureBoot as a whole, covering all individual resources at once. Specifically it may + include: + + + The ELF Linux kernel images will be looked for in the .linux PE + section of the executed image. + + The initial RAM disk (initrd) will be looked for in the .initrd PE + section. + + The kernel command line to pass to the invoked kernel will be looked for in the + .cmdline PE section. + + A boot splash (in Windows .BMP format) to show on screen before + invoking the kernel will be looked for in the .splash PE section. + + + If UEFI SecureBoot is enabled and the .cmdline section is present in the executed + image, any attempts to override the kernel command line by passing one as invocation parameters to the + EFI binary are ignored. Thus, in order to allow overriding the kernel command line, either disable UEFI + SecureBoot, or don't include a kernel command line PE section in the kernel image file. If a command line + is accepted via EFI invocation parameters to the EFI binary it is measured into TPM PCR 8 (if a TPM is + present). + + + + Companion Files + + The systemd-stub UEFI boot stub automatically collects two types of auxiliary + companion files optionally placed in a drop-in directory next to the EFI binary and dynamically generates + cpio initrd archives from them, and passes them to the kernel. Specifically: + + + For a kernel binary called foo.efi it + will look for files with the .cred suffix in a directory named + foo.efi.extra.d/, next to it. A cpio + archive is generated from all files found that way, placing them in the + /.extra/credentials/ directory of the initrd file hierarchy. The main initrd may + then access them in this directory. This is supposed to be used to store auxiliary, encrypted, + authenticated credentials for use with LoadCredentialEncrypted= in the UEFI System + Partition. See + systemd.exec5 for + details on encrypted credentials. The generated cpio archive is measured into TPM + PCR 4 (if a TPM is present) + + Similar, files foo.efi.extra.d/*.raw + are packed up as cpio archive and placed in the /.extra/sysext/ + directory in the initrd file hierarchy. This is supposed to be used to pass additional system extension + images to the initrd. See + systemd-sysext8 for + details on system extension images. The generated cpio archive containing these + system extension images is measured into TPM PCR 8 (if a TPM is present). + + + Both mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable initrd + images in a reasonably safe way: all data they contain is measured into TPM PCRs. On access they should be + further validated: in case of the credentials case by encrypting/authenticating them via TPM, as exposed + by systemd-creds encrypt -T (see + systemd-creds1 for + details); in case of the system extension images by using signed Verity images. + + + + EFI Variables + + The following EFI variables are defined, set and read by systemd-stub, under the + vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f, for communication between the boot + stub and the OS: + + + + LoaderDevicePartUUID + + Contains the partition UUID of the EFI System Partition the EFI image was run + from. systemd-gpt-auto-generator8 + uses this information to automatically find the disk booted from, in order to discover various other + partitions on the same disk automatically. + + + + LoaderFirmwareInfo + LoaderFirmwareType + + Brief firmware information. Use + bootctl1 to view this + data. + + + + LoaderImageIdentifier + + The path of EFI executable, relative to the EFI System Partition's root + directory. Use + bootctl1 to view + this data. + + + + StubInfo + + Brief stub information. Use + bootctl1 to view + this data. + + + + Note that some of the variables above may also be set by the boot loader. The stub will only set + them if they aren't set already. Some of these variables are defined by the Boot Loader Interface. + + + + Assembling Kernel Images + + In order to assemble an UEFI PE kernel image from various components as described above, use an + objcopy1 command line + like this: + + objcopy \ + --add-section .osrel=os-release --change-section-vma .osrel=0x20000 \ + --add-section .cmdline=cmdline.txt --change-section-vma .cmdline=0x30000 \ + --add-section .splash=splash.bmp --change-section-vma .splash=0x40000 \ + --add-section .linux=vmlinux --change-section-vma .linux=0x2000000 \ + --add-section .initrd=initrd.cpio --change-section-vma .initrd=0x3000000 \ + /usr/lib/systemd/boot/efi/linuxx64.efi.stub \ + foo-unsigned.efi + + This generates one PE executable file foo-unsigned.efi from the six individual + files for OS release information, kernel command line, boot splash image, kernel image, main initrd and + UEFI boot stub. + + To then sign the resulting image for UEFI SecureBoot use an + sbsign1 command like + the following: + + sbsign \ + --key mykey.pem \ + --cert mykey.crt \ + --output foo.efi \ + foo-unsigned.efi + + This expects a pair of X.509 private key and certificate as parameters and then signs the UEFI PE + executable we generated above for UEFI SecureBoot and generates a signed UEFI PE executable as + result. + + + + See Also + + systemd-boot7, + systemd.exec5, + systemd-creds1, + systemd-sysext8, + Boot Loader Specification, + Boot Loader Interface, + objcopy1, + sbsign1 + + +