SYSTEMD-PCRLOCK(8)

📦

version 262.1 · 13 versions

✨ NAME ✨

hey bestie, welcome to the systemd-pcrlock(8) page 💅 this is all about analyzing and predicting TPM2 PCR states and generating an access policy from the prediction ✨

so the crew is: systemd-pcrlock, systemd-pcrlock-file-system.service, systemd-pcrlock-firmware-code.service, systemd-pcrlock-firmware-config.service, systemd-pcrlock-machine-id.service, systemd-pcrlock-make-policy.service, systemd-pcrlock-secureboot-authority.service, systemd-pcrlock-secureboot-policy.service — and they're all here to analyze and predict TPM2 PCR states and generate an access policy from the prediction 🎀

🌈 SYNOPSIS 🌈

/usr/lib/systemd/systemd-pcrlock [OPTIONS...]

⚠️ EXPERIMENTAL ⚠️

💖 DESCRIPTION 💖

okay so systemd-pcrlock is a tool that you can use to analyze and predict TPM2 PCR measurements, and generate TPM2 access policies from the prediction which it stores in a TPM2 NV index (that's the TPM2 non-volatile memory, iykyk). this can then be used to restrict access to TPM2 objects (like disk encryption keys) to system boot-ups where only specific, trusted components are used ✨

systemd-pcrlock uses these inputs for its analysis and prediction:

the UEFI firmware TPM2 event log (i.e. /sys/kernel/security/tpm0/binary_bios_measurements) of the current boot 🦋
the userspace TPM2 event log (i.e. /run/log/systemd/tpm2-measure.log) of the current boot 🌸
the current PCR state of the TPM2 chip 💅
boot component definition files (*.pcrlock and *.pcrlock.d/*.pcrlock, see systemd.pcrlock(5)) that each define expected measurements for one component of the boot process, permitting alternative variants for each. (variants may be used to bless multiple kernel versions or boot loader versions at the same time 👑)

it uses these inputs to generate a combined event log, validating it against the PCR states. it then attempts to recognize event log records and matches them against the defined components. for each PCR where this can be done comprehensively (i.e. where all listed records and all defined components have been matched) this may then be used to predict future PCR measurements, taking the alternative variants defined for each component into account. this prediction may then be converted into a TPM2 access policy (consisting of TPM2 PolicyPCR and PolicyOR items), which is then stored in an NV index in the TPM2. this may be used to then lock secrets (such as disk encryption keys) to these policies (via a TPM2 PolicyAuthorizeNV policy) 🔐

use tools such as systemd-cryptenroll(1) or systemd-repart(8) to bind disk encryption to such a systemd-pcrlock TPM2 policy. specifically, see the --tpm2-pcrlock= switches of these tools 🫶

the access policy logic requires a TPM2 device that implements the "PolicyAuthorizeNV" command, i.e. implements TPM 2.0 version 1.38 or newer. no cap 💯

👑 COMMANDS 👑

the following commands are understood, bestie:

📝 log

this reads the combined TPM2 event log, validates it, matches it against the current PCR values, and outputs both in tabular form. combine with --json= to generate output in JSON format ✨

📜 cel

this reads the combined TPM2 event log and writes it to STDOUT in TCG Canonical Event Log Format (CEL-JSON)[1] 🌈

🗂️ list-components

shows a list of component definitions and their variants, i.e. the *.pcrlock files discovered in /var/lib/pcrlock.d/, /usr/lib/pcrlock.d/, and the other supported directories. see systemd.pcrlock(5) for details on these files and the full list of directories searched 🔍

🔮 predict

predicts the PCR state on future boots. this will analyze the TPM2 event log as described above, recognize components, and then generate all possible resulting PCR values for all combinations of component variants. note that no prediction is made for PCRs whose value does not match the event log records, for which unrecognized measurements are discovered or for which components are defined that cannot be found in the event log. this is a safety measure to ensure that any generated access policy can be fulfilled correctly on current and future boots 🛡️

🛠️ make-policy

this predicts the PCR state for future boots, much like the predict command above. it then uses this data to generate a TPM2 access policy which it stores in a TPM2 NV index. the prediction and information about the used TPM2 and its NV index are written to /var/lib/systemd/pcrlock.json 📁

the NV index is allocated on first invocation, and updated on subsequent invocations.

the NV index contents may be changed (and thus the policy stored in it updated) by providing an access PIN. this PIN is normally generated automatically and stored in encrypted form (with an access policy binding it to the NV index itself) in the aforementioned JSON policy file. this PIN may be chosen by the user, via the --recovery-pin= switch. if specified it may be used as alternative path of access to update the policy 🔑

if the new prediction matches the old this command terminates quickly and executes no further operation. (unless --force is specified, see below.)

starting with v256, a copy of the /var/lib/systemd/pcrlock.json policy file is encoded in a credential (see systemd-creds(1) for details) and written to the EFI System Partition or XBOOTLDR partition, in the /loader/credentials/ subdirectory. there it is picked up at boot by systemd-stub(7) and passed to the invoked initrd, where it can be used to unlock the root file system (which typically contains /var/, which is where the primary copy of the policy is located, which hence cannot be used to unlock the root file system). the credential file is named after the boot entry token of the installation (see bootctl(1)), which is configurable via the --entry-token= switch, see below 🚀

🗑️ remove-policy

removes a previously generated policy. deletes the /var/lib/systemd/pcrlock.json file, and deallocates the NV index 🧹

✅ is-supported

checks if the local TPM2 supports all functionality for systemd-pcrlock to work correctly. this does similar tests as systemd-analyze has-tpm2, but also checks for supported of the TPM2 operations requires by systemd-pcrlock. outputs one of "no", "partial" (in case some parts of TPM2 support are available in hardware, firmware, OS, but not complete), "obsolete" (if TPM2 support is available in hardware, firmware and OS, but the operations required for systemd-pcrlock are missing), "yes". returns an exit status of zero if full support is available, otherwise non-zero 🎯

if combined with --quiet, suppresses the output of the string 🤫

currently, this checks for support for the PolicAuthorizeNV TPM2 command, as well as for support of the SHA-256 hash algorithm.

🔒 lock-firmware-code, unlock-firmware-code

generates/removes .pcrlock files based on the TPM2 event log of the current boot covering all records for PCRs 0 ("platform-code") and 2 ("external-code") 🛡️

this operation allows locking the boot process to the current version of the firmware of the system and its extension cards. this operation should only be used if the system vendor does not provide suitable pcrlock data ahead of time 🙅‍♀️

note that this data only matches the current version of the firmware. if a firmware update is applied this data will be out-of-date and any access policy generated from it will no longer pass. it is thus recommended to invoke unlock-firmware-code before doing a firmware update, followed by make-policy to refresh the policy 🔄

systemd-pcrlock lock-firmware-code is invoked automatically at boot via the systemd-pcrlock-firmware-code.service unit, if enabled. this ensures that an access policy managed by systemd-pcrlock is automatically locked to the new firmware version whenever the policy has been relaxed temporarily, in order to cover for firmware updates, as described above 🤖

the files are only generated from the event log if the event log matches the current TPM2 PCR state.

this writes/removes the files /var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock and /var/lib/pcrlock.d/550-firmware-code-late.pcrlock.d/generated.pcrlock 📂

⚙️ lock-firmware-config, unlock-firmware-config

this is similar to lock-firmware-code/unlock-firmware-code but locks down the firmware configuration, i.e. PCRs 1 ("platform-config") and 3 ("external-config") 🛠️

this functionality should be used with care as in most scenarios a minor firmware configuration change should not invalidate access policies to TPM2 objects. also note that some systems measure unstable and unpredictable information (e.g. current CPU voltages, temperatures, as part of SMBIOS data) to these PCRs, which means this form of lockdown cannot be used reliably on such systems. use this functionality only if the system and hardware is well known and does not suffer by these limitations, for example in virtualized environments ⚠️

use unlock-firmware-config before making firmware configuration changes. if the systemd-pcrlock-firmware-config.service unit is enabled it will automatically generate a pcrlock file from the new measurements 🔁

this writes/removes the files /var/lib/pcrlock.d/250-firmware-config-early.pcrlock.d/generated.pcrlock and /var/lib/pcrlock.d/550-firmware-config-late.pcrlock.d/generated.pcrlock 📁

🔐 lock-secureboot-policy, unlock-secureboot-policy

generates/removes a .pcrlock file based on the SecureBoot policy currently enforced. this looks at the SecureBoot, PK, KEK, db, dbx, dbt, dbr EFI variables and predicts their measurements to PCR 7 ("secure-boot-policy") on the next boot 🦋

use unlock-secureboot-policy before applying SecureBoot policy updates. if the systemd-pcrlock-secureboot-policy.service unit is enabled it will automatically generate a pcrlock file from the policy discovered 🔄

this writes/removes the file /var/lib/pcrlock.d/230-secureboot-policy.pcrlock.d/generated.pcrlock 📄

🔒 `lock-secureboot-authority`, `unlock-secureboot-authority`

okay so this one generates/removes a .pcrlock file based on the SecureBoot authorities that were used to validate the boot path. and what even are SecureBoot authorities? bestie they're the specific SecureBoot database entries that were used to validate the UEFI PE binaries executed at boot. it peeks at the event log of the current boot and uses the relevant measurements on PCR 7 ("secure-boot-policy"). 👑

it writes/removes this file:

/var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock

✨ Added in version 255.

🗂️ `lock-gpt [DEVICE]`, `unlock-gpt`

generates/removes a .pcrlock file based on the GPT partition table of the disk you point at. no disk specified? no problem, it automatically figures out the block device backing the root file system. this locks the state of the disk partitioning of the booted medium, which firmware measures to PCR 5 ("boot-loader-config"). 🎀

it writes/removes this file:

/var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock

✨ Added in version 255.

🧬 `lock-pe [BINARY]`, `unlock-pe`

generates/removes a .pcrlock file based on the PE binary you hand it. super useful for predicting the measurements the firmware makes to PCR 4 ("boot-loader-code") when that binary is part of the UEFI boot process. use this on boot loader binaries and suchlike fr fr. and if your PE binary is a unified kernel image (UKI)? then go use lock-uki instead (it's right below, bestie).

it expects a path to the PE binary as argument. if you don't specify one, it reads the binary from STDIN instead. 🫶

the pcrlock file to write must be specified via the --pcrlock= switch.

✨ Added in version 255.

🌸 `lock-uki [UKI]`, `unlock-uki`

generates/removes a .pcrlock file based on the UKI PE binary you specify. this is the one for predicting the measurements the firmware makes to PCR 4 ("boot-loader-code"), and the ones systemd-stub(7) makes to PCR 11 ("kernel-boot"), if that UKI is booted. it's literally a superset of lock-pe. 💅

expects a path to the UKI PE binary as argument. no argument? it reads the binary from STDIN instead.

the pcrlock file to write must be specified via the --pcrlock= switch.

✨ Added in version 255.

🪪 `lock-machine-id`, `unlock-machine-id`

generates/removes a .pcrlock file based on /etc/machine-id. this is the move for predicting the measurements systemd-pcrmachine.service(8) makes to PCR 15 ("system-identity"). 🔥

it writes/removes this file:

/var/lib/pcrlock.d/820-machine-id.pcrlock

✨ Added in version 255.

💽 `lock-file-system [PATH]`, `unlock-file-system [PATH]`

generates/removes a .pcrlock file based on file system identity. useful for predicting the measurements systemd-pcrfs@.service(8) makes to PCR 15 ("system-identity") for the root and /var/ file systems. 🦋

it writes/removes these files:

/var/lib/pcrlock.d/830-root-file-system.pcrlock
/var/lib/pcrlock.d/840-file-system-path.pcrlock

✨ Added in version 255.

🧵 `lock-kernel-cmdline [FILE]`, `unlock-kernel-cmdline`

generates/removes a .pcrlock file based on /proc/cmdline (or on the file you give it, if you give one). this is how you predict the measurements the Linux kernel makes to PCR 9 ("kernel-initrd"). ⭐

it writes/removes this file:

/var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock

✨ Added in version 255.

🥚 `lock-kernel-initrd FILE`, `unlock-kernel-initrd`

generates/removes a .pcrlock file based on a kernel initrd cpio archive. great for predicting the measurements the Linux kernel makes to PCR 9 ("kernel-initrd").

it writes/removes this file:

/var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock

✨ Added in version 255.

🧊 `lock-raw [FILE]`, `unlock-raw`

generates/removes a .pcrlock file based on raw binary data. the data comes either from the file you specify or from STDIN (if you specified none). this one requires that --pcrs= is specified. the generated .pcrlock file gets written to the file specified via --pcrlock=, or to STDOUT if none is specified. 😌

✨ Added in version 255.

✨ OPTIONS ✨

these are the options it understands, bestie:

--full — shows the full hash value instead of abbreviating it down to 7 characters.

✨ Added in version 262.

--raw-description — when displaying the TPM2 event log, don't even try to decode the records into a friendly event log description string. instead, show the binary payload data in escaped form. raw and unbothered. 💀

✨ Added in version 255.

--pcr= — specifies the PCR number to use. you can specify it more than once to select multiple PCRs.

this is what lock-raw and lock-pe use to select the PCR to lock against.

if you use it with predict and make-policy, it overrides which PCRs get included in the prediction and policy. if you leave it unspecified, it defaults to PCRs 0-5, 7, 11, 13-15. and heads up: those commands will not include any PCRs in the prediction/policy (even if you specified them explicitly!) if there are measurements in the event log that don't match the current PCR value, or there are unrecognized measurements in the event log, or components define measurements not seen in the event log. so yeah, all-or-nothing energy. 😭

✨ Added in version 255.

--nv-index= — specifies the NV index to store the policy in. honoured by make-policy. if you don't specify it, the command automatically picks a free NV index for you. 🎀

✨ Added in version 255.

--components= — takes a path to read *.pcrlock and *.pcrlock.d/*.pcrlock files from. you can use it more than once to specify multiple such directories. if you don't specify it, it defaults to /etc/pcrlock.d/, /run/pcrlock.d/, /var/lib/pcrlock.d/, /usr/local/lib/pcrlock.d/, /usr/lib/pcrlock.d/. 📂

✨ Added in version 255.

--location= — takes either a string, or a colon-separated pair of strings. it configures up to which point in the sorted list of defined components to analyze/predict PCRs to.

typically, the systemd-pcrlock tool is invoked from a fully booted system, after boot-up and before shutdown. which means all the various components that are defined for shutdown haven't been measured yet, and should not be searched for. this option lets you restrict which components are considered for analysis (taking only components before some point into account, and ignoring the components after them). the expected string is ordered against the filenames of the components defined. any components with a lexicographically later name are ignored. this logic applies to the log, predict, and make-policy verbs.

if you specify a colon-separated pair of strings instead, then they select which phases of the boot to include in the prediction/policy. the first string defines where the first prediction shall be made, and the second string defines where the last prediction shall be made. all such predictions are then combined into one set. 💫

if you use it with list-components, the selected location range will be highlighted in the component list. ✨

it defaults to "760-:940-", which means the policies generated by default will basically cover the whole runtime of the OS userspace, from the initrd (since "760-" closely follows 750-enter-initrd.pcrlock) until (and including) the main runtime of the system (since "940-" is closely followed by 950-shutdown.pcrlock). see systemd.pcrlock(5) for a full list of well-known components, which illustrates where this range is placed by default.

✨ Added in version 255.

--recovery-pin= — takes one of "hide", "show" or "query". defaults to "hide". honoured by make-policy.

if "query", it'll query the user for a PIN to unlock the TPM2 NV index with. if no policy was created before, this PIN is used to protect the newly allocated NV index. if a policy has been created before, the PIN is used to unlock write access to the NV index.

if either "hide" or "show" is used, a PIN is automatically generated, and — only in the case of "show" — displayed on screen. regardless of whether it was user supplied or automatically generated, it's stored in encrypted form in the policy metadata file. the recovery PIN may be used to regain write access to an NV index in case the access policy became out of date. 🔑

✨ Added in version 255.

--pcrlock= — takes a file system path as argument. if specified, it configures where to write the generated pcrlock data to. honoured by the various lock-* commands. if not specified, a default path is generally used, as documented above. 💾

✨ Added in version 255.

--policy= — takes a file system path as argument. if specified, it configures where to write pcrlock policy metadata to. if not specified, it defaults to /var/lib/systemd/pcrlock.json. 📝

✨ Added in version 255.

--force — if specified with make-policy, the predicted policy will be written to the NV index even if it's detected to be the same as the previously stored one. no dedup for you, periodt. 💅

✨ Added in version 255.

--entry-token= — sets the boot entry token to use for the file name for the pcrlock policy credential in the EFI System Partition or XBOOTLDR partition. see the bootctl(1) option of the same regarding expected values. this switch has an effect on the make-policy command only. 🎟️

✨ Added in version 256.

--quiet — if specified, suppresses output when invoked for is-supported. 🤫

✨ Added in version 258.

--strict= — takes a boolean. defaults to false. honoured by make-policy and predict. if true, all specified PCRs must be included in the policy, otherwise the command returns failure. no half measures. 🔥

✨ Added in version 262.

--json=MODE — shows output formatted as JSON. expects one of "short" (for the shortest possible output, without any redundant whitespace or line breaks), "pretty" (for a pretty version of the same, with indentation and line breaks) or "off" (to turn off JSON output — this is the default). 🌈
--no-pager — do not pipe output into a pager. 🚫
-h, --help — print a short help text and exit. 🫶
--version — print a short version string and exit. 👑

🚦 EXIT STATUS

on success, 0 is returned, and a non-zero failure code otherwise. that's it, that's the whole vibe check. 💀

🌸 NOTES 🌸

TCG Canonical Event Log Format (CEL-JSON) https://trustedcomputinggroup.org/resource/canonical-event-log-format/

ok bestie that's the whole page, you made it 🎀 go forth and lock those PCRs responsibly, no cap. this lil masterpiece is from systemd 262.1 and yeah, it's giving SYSTEMD-PCRLOCK(8) energy. mwah 💅✨🦋

📦 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 2026-10-19: a language model's rewrite of the original, under its terms

SYSTEMD-PCRLOCK(8)

✨ NAME ✨

🌈 SYNOPSIS 🌈

⚠️ EXPERIMENTAL ⚠️

💖 DESCRIPTION 💖

👑 COMMANDS 👑

📝 log

📜 cel

🗂️ list-components

🔮 predict

🛠️ make-policy

🗑️ remove-policy

✅ is-supported

🔒 lock-firmware-code, unlock-firmware-code

⚙️ lock-firmware-config, unlock-firmware-config

🔐 lock-secureboot-policy, unlock-secureboot-policy

🔒 lock-secureboot-authority, unlock-secureboot-authority

🗂️ lock-gpt [DEVICE], unlock-gpt

🧬 lock-pe [BINARY], unlock-pe

🌸 lock-uki [UKI], unlock-uki

🪪 lock-machine-id, unlock-machine-id

💽 lock-file-system [PATH], unlock-file-system [PATH]

🧵 lock-kernel-cmdline [FILE], unlock-kernel-cmdline

🥚 lock-kernel-initrd FILE, unlock-kernel-initrd

🧊 lock-raw [FILE], unlock-raw

✨ OPTIONS ✨

🚦 EXIT STATUS

👀 SEE ALSO

🌸 NOTES 🌸

🔒 `lock-secureboot-authority`, `unlock-secureboot-authority`

🗂️ `lock-gpt [DEVICE]`, `unlock-gpt`

🧬 `lock-pe [BINARY]`, `unlock-pe`

🌸 `lock-uki [UKI]`, `unlock-uki`

🪪 `lock-machine-id`, `unlock-machine-id`

💽 `lock-file-system [PATH]`, `unlock-file-system [PATH]`

🧵 `lock-kernel-cmdline [FILE]`, `unlock-kernel-cmdline`

🥚 `lock-kernel-initrd FILE`, `unlock-kernel-initrd`

🧊 `lock-raw [FILE]`, `unlock-raw`