{
    "mode": "man",
    "parameter": "sd-stub",
    "section": "7",
    "url": "https://www.chedong.com/phpMan.php/man/sd-stub/7/json",
    "generated": "2026-10-07T22:38:02Z",
    "synopsis": "/usr/lib/systemd/boot/efi/linuxx64.efi.stub\n/usr/lib/systemd/boot/efi/linuxia32.efi.stub\n/usr/lib/systemd/boot/efi/linuxaa64.efi.stub\nESP/.../foo.efi.extra.d/*.addon.efi\nESP/.../foo.efi.extra.d/*.cred\nESP/.../foo.efi.extra.d/*.raw\nESP/loader/addons/*.addon.efi\nESP/loader/credentials/*.cred",
    "sections": {
        "NAME": {
            "content": "systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub - A simple\nUEFI kernel boot stub\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "/usr/lib/systemd/boot/efi/linuxx64.efi.stub\n\n/usr/lib/systemd/boot/efi/linuxia32.efi.stub\n\n/usr/lib/systemd/boot/efi/linuxaa64.efi.stub\n\nESP/.../foo.efi.extra.d/*.addon.efi\n\nESP/.../foo.efi.extra.d/*.cred\n\nESP/.../foo.efi.extra.d/*.raw\n\nESP/loader/addons/*.addon.efi\n\nESP/loader/credentials/*.cred\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "systemd-stub (stored in per-architecture files linuxx64.efi.stub, linuxia32.efi.stub,\nlinuxaa64.efi.stub on disk) is a simple UEFI boot stub. An UEFI boot stub is attached to a\nLinux kernel binary image, and is a piece of code that runs in the UEFI firmware environment\nbefore transitioning into the Linux kernel environment. The UEFI boot stub ensures a Linux\nkernel is executable as regular UEFI binary, and is able to do various preparations before\nswitching the system into the Linux world.\n\nThe UEFI boot stub looks for various resources for the kernel invocation inside the UEFI PE\nbinary itself. This allows combining various resources inside a single PE binary image\n(usually called \"Unified Kernel Image\", or \"UKI\" for short), which may then be signed via\nUEFI SecureBoot as a whole, covering all individual resources at once. Specifically it may\ninclude:\n\n•   A \".linux\" section with the ELF Linux kernel image.\n\n•   An \".osrel\" section with OS release information, i.e. the contents of the os-release(5)\nfile of the OS the kernel belongs to.\n\n•   A \".cmdline\" section with the kernel command line to pass to the invoked kernel.\n\n•   An \".initrd\" section with the initrd.\n\n•   A \".splash\" section with an image (in the Windows .BMP format) to show on screen before\ninvoking the kernel.\n\n•   A \".dtb\" section with a compiled binary DeviceTree.\n\n•   A \".uname\" section with the kernel version information, i.e. the output of uname -r for\nthe kernel included in the \".linux\" section.\n\n•   An \".sbat\" section with SBAT[1] revocation metadata.\n\n•   A \".pcrsig\" section with a set of cryptographic signatures for the expected TPM2 PCR\nvalues after the kernel has been booted, in JSON format. This is useful for implementing\nTPM2 policies that bind disk encryption and similar to kernels that are signed by a\nspecific key.\n\n•   A \".pcrpkey\" section with a public key in the PEM format matching the signature data in\nthe the \".pcrsig\" section.\n\nIf UEFI SecureBoot is enabled and the \".cmdline\" section is present in the executed image,\nany attempts to override the kernel command line by passing one as invocation parameters to\nthe EFI binary are ignored. Thus, in order to allow overriding the kernel command line,\neither disable UEFI SecureBoot, or don't include a kernel command line PE section in the\nkernel image file. If a command line is accepted via EFI invocation parameters to the EFI\nbinary it is measured into TPM PCR 12 (if a TPM is present).\n\nIf a DeviceTree is embedded in the \".dtb\" section, it replaces an existing DeviceTree in the\ncorresponding EFI configuration table. systemd-stub will ask the firmware via the\n\"EFIDTFIXUPPROTOCOL\" for hardware specific fixups to the DeviceTree.\n\nThe contents of eight of these nine sections are measured into TPM PCR 11. It is otherwise\nnot used and thus the result can be pre-calculated without too much effort. The \".pcrsig\"\nsection is not included in this PCR measurement, since it is supposed to contain signatures\nfor the output of the measurement operation, and thus cannot also be input to it.\n\nWhen \".pcrsig\" and/or \".pcrpkey\" sections are present in a unified kernel image their\ncontents are passed to the booted kernel in an synthetic initrd cpio archive that places them\nin the /.extra/tpm2-pcr-signature.json and /.extra/tpm2-pcr-public-key.pem files. Typically,\na tmpfiles.d(5) line then ensures they are copied into /run/systemd/tpm2-pcr-signature.json\nand /run/systemd/tpm2-pcr-public-key.pem where they remain accessible even after the system\ntransitions out of the initrd environment into the host file system. Tools such systemd-\ncryptsetup@.service(8), systemd-cryptenroll(1) and systemd-creds(1) will automatically use\nfiles present under these paths to unlock protected resources (encrypted storage or\ncredentials) or bind encryption to booted kernels.\n\nFor further details about the UKI concept, see the UKI specification[2].\n",
            "subsections": []
        },
        "COMPANION FILES": {
            "content": "The systemd-stub UEFI boot stub automatically collects three types of auxiliary companion\nfiles optionally placed in drop-in directories on the same partition as the EFI binary,\ndynamically generates cpio initrd archives from them, and passes them to the kernel.\nSpecifically:\n\n•   For a kernel binary called foo.efi, it will look for files with the .cred suffix in a\ndirectory named foo.efi.extra.d/ next to it. If the kernel binary uses a counter for the\npurpose of Automatic Boot Assessment[3], this counter will be ignored. For example,\nfoo+3-0.efi will look in directory foo.efi.extra.d/. A cpio archive is generated from all\nfiles found that way, placing them in the /.extra/credentials/ directory of the initrd\nfile hierarchy. The main initrd may then access them in this directory. This is supposed\nto be used to store auxiliary, encrypted, authenticated credentials for use with\nLoadCredentialEncrypted= in the UEFI System Partition. See systemd.exec(5) and systemd-\ncreds(1) for details on encrypted credentials. The generated cpio archive is measured\ninto TPM PCR 12 (if a TPM is present).\n\n•   Similarly, files foo.efi.extra.d/*.raw are packed up in a cpio archive and placed in the\n/.extra/sysext/ directory in the initrd file hierarchy. This is supposed to be used to\npass additional system extension images to the initrd. See systemd-sysext(8) for details\non system extension images. The generated cpio archive containing these system extension\nimages is measured into TPM PCR 13 (if a TPM is present).\n\n•   Similarly, files foo.efi.extra.d/*.addon.efi are loaded and verified as PE binaries, and\na \".cmdline\" section is parsed from them. Addons are supposed to be used to pass\nadditional kernel command line parameters or Devicetree blobs, regardless of the kernel\nimage being booted, for example to allow platform vendors to ship platform-specific\nconfiguration.\n\nIn case Secure Boot is enabled, these files will be validated using keys in UEFI DB,\nShim's DB or Shim's MOK, and will be rejected otherwise. Additionally, if the both the\naddon and the UKI contain a a \".uname\" section, the addon will be rejected if they do not\nmatch exactly. It is recommended to always add a \".sbat\" section to all signed addons, so\nthat they may be revoked with a SBAT policy update, without requiring blocklisting via\nDBX/MOKX. The ukify(1) tool will add a SBAT policy by default if none is passed when\nbuilding addons. For more information on SBAT see Shim documentation[1].\n\nAddon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and\nappended to the kernel command line. UKI command line options are listed first, then\noptions from addons in /loader/addons/*.addon.efi, and finally UKI-specific addons.\nDevice tree blobs are loaded and measured following the same algorithm. Addons are always\nloaded in the same order based on the filename, so that, given the same set of addons,\nthe same set of measurements can be expected in PCR12. However, note that the filename is\nnot protected by the PE signature, and as such an attacker with write access to the ESP\ncould potentially rename these files to change the order in which they are loaded, in a\nway that could alter the functionality of the kernel, as some options might be\norder-dependent. If you sign such addons, you should pay attention to the PCR12 values\nand make use of an attestation service so that improper use of your signed addons can be\ndetected and dealt with using one of the aforementioned revocation mechanisms.\n\n•   Files /loader/credentials/*.cred are packed up in a cpio archive and placed in the\n/.extra/globalcredentials/ directory of the initrd file hierarchy. This is supposed to\nbe used to pass additional credentials to the initrd, regardless of the kernel being\nbooted. The generated cpio archive is measured into TPM PCR 12 (if a TPM is present).\n\n•   Additionally, files /loader/addons/*.addon.efi are loaded and verified as PE binaries,\nand \".cmdline\" and/or \".dtb\" sections are parsed from them. This is supposed to be used\nto pass additional command line parameters or Devicetree blobs to the kernel, regardless\nof the kernel being booted.\n\nThese mechanisms may be used to parameterize and extend trusted (i.e. signed), immutable\ninitrd images in a reasonably safe way: all data they contain is measured into TPM PCRs. On\naccess they should be further validated: in case of the credentials case by\nencrypting/authenticating them via TPM, as exposed by systemd-creds encrypt -T (see systemd-\ncreds(1) for details); in case of the system extension images by using signed Verity images.\n",
            "subsections": []
        },
        "TPM PCR NOTES": {
            "content": "Note that when a unified kernel using systemd-stub is invoked the firmware will measure it as\na whole to TPM PCR 4, covering all embedded resources, such as the stub code itself, the core\nkernel, the embedded initrd and kernel command line (see above for a full list).\n\nAlso note that the Linux kernel will measure all initrds it receives into TPM PCR 9. This\nmeans every type of initrd will be measured two or three times: the initrd embedded in the\nkernel image will be measured to PCR 4, PCR 9 and PCR 11; the initrd synthesized from\ncredentials will be measured to both PCR 9 and PCR 12; the initrd synthesized from system\nextensions will be measured to both PCR 4 and PCR 9. Let's summarize the OS resources and the\nPCRs they are measured to:\n",
            "subsections": [
                {
                    "name": "Table 1. OS Resource PCR Summary",
                    "content": "┌───────────────────────────────────┬─────────────────┐\n│ OS Resource                       │ Measurement PCR │\n├───────────────────────────────────┼─────────────────┤\n│ systemd-stub code (the entry      │ 4               │\n│ point of the unified PE binary)   │                 │\n├───────────────────────────────────┼─────────────────┤\n│ Core kernel code (embedded in     │ 4 + 11          │\n│ unified PE binary)                │                 │\n├───────────────────────────────────┼─────────────────┤\n│ OS release information (embedded  │ 4 + 11          │\n│ in the unified PE binary)         │                 │\n├───────────────────────────────────┼─────────────────┤\n│ Main initrd (embedded in unified  │ 4 + 9 + 11      │\n│ PE binary)                        │                 │\n├───────────────────────────────────┼─────────────────┤\n│ Default kernel command line       │ 4 + 11          │\n│ (embedded in unified PE binary)   │                 │\n├───────────────────────────────────┼─────────────────┤\n│ Overridden kernel command line    │ 12              │\n├───────────────────────────────────┼─────────────────┤\n│ Boot splash (embedded in the      │ 4 + 11          │\n│ unified PE binary)                │                 │\n├───────────────────────────────────┼─────────────────┤\n│ TPM2 PCR signature JSON (embedded │ 4 + 9           │\n│ in unified PE binary, synthesized │                 │\n│ into initrd)                      │                 │\n├───────────────────────────────────┼─────────────────┤\n│ TPM2 PCR PEM public key (embedded │ 4 + 9 + 11      │\n│ in unified PE binary, synthesized │                 │\n│ into initrd)                      │                 │\n├───────────────────────────────────┼─────────────────┤\n│ Credentials (synthesized initrd   │ 9 + 12          │\n│ from companion files)             │                 │\n├───────────────────────────────────┼─────────────────┤\n│ System Extensions (synthesized    │ 9 + 13          │\n│ initrd from companion files)      │                 │\n└───────────────────────────────────┴─────────────────┘\n\n"
                }
            ]
        },
        "EFI VARIABLES": {
            "content": "The following EFI variables are defined, set and read by systemd-stub, under the vendor UUID\n\"4a67b082-0a4c-41cf-b6c7-440b29bb8c4f\", for communication between the boot stub and the OS:\n\nLoaderDevicePartUUID\nContains the partition UUID of the EFI System Partition the EFI image was run from.\nsystemd-gpt-auto-generator(8) uses this information to automatically find the disk booted\nfrom, in order to discover various other partitions on the same disk automatically.\n\nAdded in version 250.\n\nLoaderFirmwareInfo, LoaderFirmwareType\nBrief firmware information. Use bootctl(1) to view this data.\n\nAdded in version 250.\n\nLoaderImageIdentifier\nThe path of EFI executable, relative to the EFI System Partition's root directory. Use\nbootctl(1) to view this data.\n\nAdded in version 250.\n\nStubInfo\nBrief stub information. Use bootctl(1) to view this data.\n\nAdded in version 250.\n\nStubPcrKernelImage\nThe PCR register index the kernel image, initrd image, boot splash, devicetree database,\nand the embedded command line are measured into, formatted as decimal ASCII string (e.g.\n\"11\"). This variable is set if a measurement was successfully completed, and remains\nunset otherwise.\n\nAdded in version 252.\n\nStubPcrKernelParameters\nThe PCR register index the kernel command line and credentials are measured into,\nformatted as decimal ASCII string (e.g.  \"12\"). This variable is set if a measurement was\nsuccessfully completed, and remains unset otherwise.\n\nAdded in version 252.\n\nStubPcrInitRDSysExts\nThe PCR register index the systemd extensions for the initrd, which are picked up from\nthe file system the kernel image is located on. Formatted as decimal ASCII string (e.g.\n\"13\"). This variable is set if a measurement was successfully completed, and remains\nunset otherwise.\n\nAdded in version 252.\n\nNote that some of the variables above may also be set by the boot loader. The stub will only\nset them if they aren't set already. Some of these variables are defined by the Boot Loader\nInterface[4].\n",
            "subsections": []
        },
        "INITRD RESOURCES": {
            "content": "The following resources are passed as initrd cpio archives to the booted kernel, and thus\nmake up the initial file system hierarchy in the initrd execution environment:\n\n/\nThe main initrd from the \".initrd\" PE section of the unified kernel image.\n\nAdded in version 252.\n\n/.extra/credentials/*.cred\nCredential files (suffix \".cred\") that are placed next to the unified kernel image (as\ndescribed above) are copied into the /.extra/credentials/ directory in the initrd\nexecution environment.\n\nAdded in version 252.\n\n/.extra/globalcredentials/*.cred\nSimilarly, credential files in the /loader/credentials/ directory in the file system the\nunified kernel image is placed in are copied into the /.extra/globalcredentials/\ndirectory in the initrd execution environment.\n\nAdded in version 252.\n\n/.extra/sysext/*.raw\nSystem extension image files (suffix \".raw\") that are placed next to the unified kernel\nimage (as described above) are copied into the /.extra/sysext/ directory in the initrd\nexecution environment.\n\nAdded in version 252.\n\n/.extra/tpm2-pcr-signature.json\nThe TPM2 PCR signature JSON object included in the \".pcrsig\" PE section of the unified\nkernel image is copied into the /.extra/tpm2-pcr-signature.json file in the initrd\nexecution environment.\n\nAdded in version 252.\n\n/.extra/tpm2-pcr-pkey.pem\nThe PEM public key included in the \".pcrpkey\" PE section of the unified kernel image is\ncopied into the /.extra/tpm2-pcr-public-key.pem file in the initrd execution environment.\n\nAdded in version 252.\n\nNote that all these files are located in the \"tmpfs\" file system the kernel sets up for the\ninitrd file hierarchy and are thus lost when the system transitions from the initrd execution\nenvironment into the host file system. If these resources shall be kept around over this\ntransition they need to be copied to a place that survives the transition first, for example\nvia a suitable tmpfiles.d(5) line. By default, this is done for the TPM2 PCR signature and\npublic key files.\n",
            "subsections": []
        },
        "SMBIOS TYPE 11 STRINGS": {
            "content": "systemd-stub can be configured using SMBIOS Type 11 strings. Applicable strings consist of a\nname, followed by \"=\", followed by the value.  systemd-stub will search the table for a\nstring with a specific name, and if found, use its value. The following strings are read:\n\nio.systemd.stub.kernel-cmdline-extra\nIf set, the value of this string is added to the list of kernel command line arguments\nthat are measured in PCR12 and passed to the kernel.\n\nAdded in version 254.\n",
            "subsections": []
        },
        "ASSEMBLING KERNEL IMAGES": {
            "content": "In order to assemble a bootable Unified Kernel Image from various components as described\nabove, use ukify(1).\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "systemd-boot(7), systemd.exec(5), systemd-creds(1), systemd-sysext(8), Boot Loader\nSpecification[5], Boot Loader Interface[4], ukify(1), systemd-measure(1), TPM2 PCR\nMeasurements Made by systemd[6]\n",
            "subsections": []
        },
        "NOTES": {
            "content": "1. SBAT\nhttps://github.com/rhboot/shim/blob/main/SBAT.md\n\n2. UKI specification\nhttps://uapi-group.org/specifications/specs/unifiedkernelimage/\n\n3. Automatic Boot Assessment\nhttps://systemd.io/AUTOMATICBOOTASSESSMENT\n\n4. Boot Loader Interface\nhttps://systemd.io/BOOTLOADERINTERFACE\n\n5. Boot Loader Specification\nhttps://uapi-group.org/specifications/specs/bootloaderspecification\n\n6. TPM2 PCR Measurements Made by systemd\nhttps://systemd.io/TPM2PCRMEASUREMENTS\n\nsystemd 255                                                                          SYSTEMD-STUB(7)",
            "subsections": []
        }
    },
    "summary": "systemd-stub, sd-stub, linuxx64.efi.stub, linuxia32.efi.stub, linuxaa64.efi.stub - A simple UEFI kernel boot stub",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "systemd-boot",
            "section": "7",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-boot/7/json"
        },
        {
            "name": "systemd.exec",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/systemd.exec/5/json"
        },
        {
            "name": "systemd-creds",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-creds/1/json"
        },
        {
            "name": "systemd-sysext",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-sysext/8/json"
        },
        {
            "name": "ukify",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/ukify/1/json"
        },
        {
            "name": "systemd-measure",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/systemd-measure/1/json"
        }
    ]
}