SYSTEMD-PCREXTEND(8)

📦
version 262.1 · 14 versions
, in arch rolling

🌸 NAME 🌸

okay bestie, so this whole page lives under the manual systemd-pcrphase.service(8), and it's basically the group chat for a whole squad of units plus one lil binary 💖. meet the fam:

  • systemd-pcrphase.service
  • systemd-pcrphase-sysinit.service
  • systemd-pcrphase-initrd.service
  • systemd-pcrmachine.service
  • systemd-pcrosseparator.service
  • systemd-pcrproduct.service
  • systemd-pcrlogin@.service
  • systemd-pcrfs-root.service
  • systemd-pcrfs@.service
  • systemd-pcrnvdone.service
  • systemd-pcrphase-factory-reset.service
  • systemd-pcrphase-storage-target-mode.service
  • systemd-pcrextend

and what do they collectively do?? they measure boot phases, machine ID, product UUID, user records and file system identity into TPM PCRs and NvPCRs ✨🫶 like, that's the entire vibe, no cap.

✨ SYNOPSIS ✨

systemd-pcrphase.service

systemd-pcrphase-sysinit.service

systemd-pcrphase-initrd.service

systemd-pcrmachine.service

systemd-pcrosseparator.service

systemd-pcrproduct.service

systemd-pcrlogin@.service

systemd-pcrfs-root.service

systemd-pcrfs@.service

systemd-pcrnvdone.service

systemd-pcrphase-factory-reset.service

systemd-pcrphase-storage-target-mode.service

/usr/lib/systemd/systemd-pcrextend WORD

/usr/lib/systemd/systemd-pcrextend --file-system=PATH

/usr/lib/systemd/systemd-pcrextend --machine-id

/usr/lib/systemd/systemd-pcrextend --product-id

/usr/lib/systemd/systemd-pcrextend --login=UID|USER

💅 DESCRIPTION 💅

okay so systemd-pcrphase.service, systemd-pcrphase-sysinit.service, and systemd-pcrphase-initrd.service are system services, and their whole entire job is measuring specific strings into TPM2 PCR 11 during boot, at various milestones of the boot process. like little timestamped vibes but cryptographically real ⏱️💖

systemd-pcrmachine.service is a system service that measures the machine ID (peep machine-id(5)) into PCR 15.

systemd-pcrosseparator.service is a system service that measures the word "os-separator" into PCRs 0-7, 9, 12-14. it's giving extra separator measurement, and what it separates is the pre-boot measurements (i.e. firmware + bootloader) from the OS measurements — and in particular it "seals" off the firmware PCRs 🔒✨

systemd-pcrproduct.service is a system service that measures the firmware product UUID (as provided by one of SMBIOS, Devicetree, ...) into a NvPCR named "hardware".

systemd-pcrlogin@.service is a template service that measures the (reduced, canonical JSON) user record of the user indicated by its instance identifier (a UID) into a NvPCR named "login". it gets started by systemd-logind.service(8) on the user's first login of the current boot, much like user-runtime-dir@.service(5). but unlike that one, it is intentionally never stopped again 🙈 — it's a Type=oneshot service with RemainAfterExit=yes in system.slice, so each user is measured exactly once per boot no matter how many times they log in and out (NvPCR extensions form a hash chain, so measuring the same record twice would otherwise make the NvPCR value unpredictable — messy, we don't do that). the resulting "login" NvPCR (together with the /run/log/systemd/tpm2-measure.log event log) thus provides a TPM-backed, append-only record of which user identities were activated during the current boot. bestie that's receipts, but for identities 👑

systemd-pcrnvdone.service is a system service that measures a separator event into PCR 9 once all NvPCRs have completed initialization.

systemd-pcrfs-root.service and systemd-pcrfs@.service are services that measure file system identity information (i.e. mount point, file system type, label and UUID, partition label and UUID) into PCR 15. systemd-pcrfs-root.service does so for the root file system, and systemd-pcrfs@.service is a template unit that measures the file system indicated by its instance identifier instead.

These services require systemd-stub(7) to be used in a unified kernel image (UKI). They execute no operation when the stub has not been used to invoke the kernel. The stub will measure the invoked kernel and associated vendor resources into PCR 11 before handing control to it; once userspace is invoked these services then will extend TPM2 PCR 11 with certain literal strings indicating phases of the boot process. During a regular boot process PCR 11 is extended with the following strings:

  1. "enter-initrd" — early when the initrd initializes, before activating system extension images for the initrd. It acts as a barrier between the time where the kernel initializes and where the initrd starts operating and enables system extension images, i.e. code shipped outside of the UKI. (This extension happens when the systemd-pcrphase-initrd.service(8) service is started.)
  2. "leave-initrd" — when the initrd is about to transition into the host file system. It acts as barrier between initrd code and host OS code. (This extension happens when the systemd-pcrphase-sysinit.service(8) service is stopped.)
  3. "sysinit" — when basic system initialization is complete (which includes local file systems having been mounted), and the system begins starting regular system services. (This extension happens when the systemd-pcrphase-sysinit.service(8) service is started.)
  4. "ready" — during later boot-up, after remote file systems have been activated (i.e. after remote-fs.target), but before users are permitted to log in (i.e. before systemd-user-sessions.service). It acts as barrier between the time where unprivileged regular users are still prohibited to log in and where they are allowed to log in. (This extension happens when the systemd-pcrphase-sysinit.service(8) service is started.)
  5. "shutdown" — when the system shutdown begins. It acts as barrier between the time the system is fully up and running and where it is about to shut down. (This extension happens when the systemd-pcrphase.service service is stopped.)
  6. "final" — at the end of system shutdown. It acts as barrier between the time the service manager still runs and when it transitions into the final shutdown phase where service management is not available anymore. (This extension happens when the systemd-pcrphase-sysinit.service(8) service is stopped.)

During a regular system lifecycle, PCR 11 is extended with the strings "enter-initrd", "leave-initrd", "sysinit", "ready", "shutdown", and "final". that's the canon order, periodt 💅

Specific phases of the boot process may be referenced via the series of strings measured, separated by colons (the "phase path"). For example, the phase path for the regular system runtime is "enter-initrd:leave-initrd:sysinit:ready", while the one for the initrd is just "enter-initrd". The phase path for the boot phase before the initrd is an empty string; because that's hard to pass around a single colon (":") may be used instead. Note that the aforementioned six strings are just the default strings and individual systems might measure other strings at other times, and thus implement different and more fine-grained boot phases to bind policy to. so like, don't assume everyone's running the same setlist 🌈

By binding policy of TPM2 objects to a specific phase path it is possible to restrict access to them to specific phases of the boot process, for example making it impossible to access the root file system's encryption key after the system transitioned from the initrd into the host root file system. obsessed honestly 🔥

Use systemd-measure(1) to pre-calculate expected PCR 11 values for specific boot phases (via the --phase= switch).

systemd-pcrfs-root.service and systemd-pcrfs@.service are automatically pulled into the initial transaction by systemd-gpt-auto-generator(8) for the root and /var/ file systems. systemd-fstab-generator(8) will do this for all mounts with the x-systemd.pcrfs mount option in /etc/fstab.

✨ OPTIONS ✨

okay so bestie, the /usr/lib/systemd/systemd-pcrextend executable can also be run straight from the command line, and when you do that it wants a word to extend into a PCR or an NvPCR, plus these little switches 💅

  • --bank= — tells it which PCR banks to extend your word into. If you don't say anything, the tool figures out all the enabled PCR banks by itself and measures the word into every single one of them. overachiever behaviour, honestly 💖

Added in version 252.

  • --pcr= — the index of the PCR to extend. If --machine-id or --file-system= are specified, this defaults to 15; otherwise (and unless --product-id is specified) it defaults to 11. You can pass it multiple times to measure into multiple PCRs at once, no cap 🔥 But you may not combine it with --nvpcr=.

Added in version 255.

  • --nvpcr= — the name of an NvPCR to extend. NvPCRs are extra PCRs that live in TPM NV indexes. The name should be a short lil string, like "hardware" or "disk-encryption". If --product-id is specified, it defaults to "hardware". You may not combine it with --pcr=.

Added in version 259.

  • --tpm2-device=PATH — controls which TPM2 device gets used. It wants a device node path pointing at the TPM2 chip, e.g. /dev/tpmrm0. OR you can pass the special value "auto" and it'll sniff out the device node of a suitable TPM2 device all by itself (and there must be exactly one of those, so no chaos pls 😭). There's also the special value "list", which enumerates every suitable TPM2 device it's currently discovered. very demure, very mindful 🦋

Added in version 252.

  • --graceful — if there's no TPM2 firmware, kernel subsystem, kernel driver or device support to be found, it exits with exit status 0 (aka: "yeah bestie, success ✨"). If you don't pass this, any attempt to measure with no TPM2 device around will make the whole invocation fail. So like, choose your vibe knowingly 💀

Added in version 253.

  • --machine-id — instead of measuring a word you typed on the command line into PCR 11, it measures the host's machine ID into PCR 15. she's got her own plans now 💜

Added in version 253.

  • --product-id — instead of measuring a word you typed on the command line into PCR 11, it measures the firmware's product UUID into an NvPCR named "hardware".

Added in version 259.

  • --login= — instead of measuring a word you typed on the command line into PCR 11, it measures the user record of the specified user into an NvPCR named "login". The parameter has to be a user name or a numeric UID. The record gets reduced down to its "regular", "perMachine" and "binding" sections (meaning the privileged, secret, status and signature sections get stripped — so that, for example, password hash changes don't perturb the NvPCR, iconic, truly 🎀), then normalized and serialized into canonical JSON before it gets measured. This is mainly used by systemd-pcrlogin@.service.

Added in version 261.

  • --file-system= — instead of measuring a word you typed on the command line into PCR 11, it measures identity info of the specified file system into PCR 15. The parameter must be the path to the established mount point of the file system you want measured. 📁

Added in version 253.

  • --event-type= — sets the event log event type for this measurement. Pass "help" and it'll list all the currently defined identifiers for you. It defaults to an appropriate value for --machine-id, --product-id, --file-system=, --login=, and otherwise it defaults to "phase".

Added in version 259.

  • -h, --help — prints a short help text and exits. our fave low-effort queen 🙈
  • --version — prints a short version string and exits.

🌸 FILES 🌸

  • /run/log/systemd/tpm2-measure.log — measurements get logged into this event log file, and it holds a JSON-SEQ[1] series of objects that follow the general structure of the TCG Canonical Event Log Format (CEL-JSON)[2] event objects (but ngl, they're missing the "recnum" field).

A LOCK_EX BSD file lock (flock(2)) on the log file is acquired while the measurement is made and the file gets updated. So any application that wants to grab a consistent quote from the TPM along with the matching snapshot of the event log should acquire a LOCK_SH lock while it's doing that. synchronization is self-care, fr fr ⭐

Added in version 252.

  • /usr/lib/nvpcr/*.nvpcr — definition files for NvPCRs.

Added in version 259.

👀 SEE ALSO 👀

systemd(1), systemd-stub(7), systemd-measure(1), systemd-gpt-auto-generator(8), systemd-fstab-generator(8), TPM2 PCR Measurements Made by systemd[3]

📝 NOTES 📝

  1. JSON-SEQ — https://www.rfc-editor.org/rfc/rfc7464.html
  2. TCG Canonical Event Log Format (CEL-JSON) — https://trustedcomputinggroup.org/resource/canonical-event-log-format/
  3. TPM2 PCR Measurements Made by systemd — https://systemd.io/TPM2_PCR_MEASUREMENTS

okay that's the whole page bestie, you ate that 🫶 this is from systemd 262.1 and the man page is SYSTEMD-PCRPHASE.SERVICE(8) — go forth and extend some PCRs, no cap 💖✨

📦 where this page comes from
  • arch rolling: systemd 262.1-1 · LGPL-2.1-or-later AND CC0-1.0 AND GPL-2.0-or-later AND MIT-0
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on : a language model's rewrite of the original, under its terms