{ "mode": "man", "parameter": "systemd-pcrlock", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/systemd-pcrlock/8/json", "generated": "2026-09-17T00:38:11Z", "synopsis": "", "sections": { "NAME": { "content": "systemd-pcrlock, systemd-pcrlock-file-system.service, systemd-pcrlock-firmware-code.service,\nsystemd-pcrlock-firmware-config.service, systemd-pcrlock-machine-id.service, systemd-pcrlock-\nmake-policy.service, systemd-pcrlock-secureboot-authority.service, systemd-pcrlock-\nsecureboot-policy.service - Analyze and predict TPM2 PCR states and generate an access policy\nfrom the prediction\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "/usr/lib/systemd/systemd-pcrlock [OPTIONS...]", "content": "" } ] }, "DESCRIPTION": { "content": "Note: this command is experimental for now. While it is likely to become a regular component\nof systemd, it might still change in behaviour and interface.\n\nsystemd-pcrlock is a tool that may be used to analyze and predict TPM2 PCR measurements, and\ngenerate TPM2 access policies from the prediction which it stores in a TPM2 NV index (i.e. in\nthe TPM2 non-volatile memory). This may then be used to restrict access to TPM2 objects (such\nas disk encryption keys) to system boot-ups in which only specific, trusted components are\nused.\n\nsystemd-pcrlock uses as input for its analysis and prediction:\n\n• The UEFI firmware TPM2 event log (i.e.\n/sys/kernel/security/tpm0/binarybiosmeasurements) of the current boot.\n\n• The userspace TPM2 event log (i.e. /run/log/systemd/tpm2-measure.log) of the current\nboot.\n\n• The current PCR state of the TPM2 chip.\n\n• Boot component definition files (*.pcrlock and *.pcrlock.d/*.pcrlock, see\nsystemd.pcrlock(5)) that each define expected measurements for one component of the boot\nprocess, permitting alternative variants for each. (Variants may be used used to bless\nmultiple kernel versions or boot loader versions at the same time.)\n\nIt uses these inputs to generate a combined event log, validating it against the PCR states.\nIt then attempts to recognize event log records and matches them against the defined\ncomponents. For each PCR where this can be done comprehensively (i.e. where all listed\nrecords and all defined components have been matched) this may then be used to predict future\nPCR measurements, taking the alternative variants defined for each component into account.\nThis prediction may then be converted into a TPM2 access policy (consisting of TPM2 PolicyPCR\nand PolicyOR items), which is then stored in an NV index in the TPM2. This may be used to\nthen lock secrets (such as disk encryption keys) to these policies (via a TPM2\nPolicyAuthorizeNV policy).\n\nUse tools such as systemd-cryptenroll(1) or systemd-repart(8) to bind disk encryption to such\na systemd-pcrlock TPM2 policy. Specifically, see the --tpm2-pcrlock= switches of these tools.\n\nThe access policy logic requires a TPM2 device that implements the \"PolicyAuthorizeNV\"\ncommand, i.e. implements TPM 2.0 version 1.38 or newer.\n", "subsections": [] }, "COMMANDS": { "content": "The following commands are understood:\n", "subsections": [ { "name": "log", "content": "This reads the combined TPM2 event log, validates it, matches it against the current PCR\nvalues, and outputs both in tabular form. Combine with --json= to generate output in JSON\nformat.\n\nAdded in version 255.\n" }, { "name": "cel", "content": "This reads the combined TPM2 event log and writes it to STDOUT in \u001b[34mTCG Common Event Log\n\u001b[34mFormat (CEL-JSON)[1] format.\n\nAdded in version 255.\n" }, { "name": "list-components", "content": "Shows a list of component definitions and their variants, i.e. the *.pcrlock files\ndiscovered in /var/lib/pcrlock.d/, /usr/lib/pcrlock.d/, and the other supported\ndirectories. See systemd.pcrlock(5) for details on these files and the full list of\ndirectories searched.\n\nAdded in version 255.\n" }, { "name": "predict", "content": "Predicts the PCR state on future boots. This will analyze the TPM2 event log as described\nabove, recognize components, and then generate all possible resulting PCR values for all\ncombinations of component variants. Note that no prediction is made for PCRs whose value\ndoes not match the event log records, for which unrecognized measurements are discovered\nor for which components are defined that cannot be found in the event log. This is a\nsafety measure to ensure that any generated access policy can be fulfilled correctly on\ncurrent and future boots.\n\nAdded in version 255.\n" }, { "name": "make-policy", "content": "This predicts the PCR state for future boots, much like the predict command above. It\nthen uses this data to generate a TPM2 access policy which it stores in a TPM2 NV index.\nThe prediction and information about the used TPM2 and its NV index are written to\n/var/lib/systemd/pcrlock.json.\n\nThe NV index is allocated on first invocation, and updated on subsequent invocations.\n\nThe NV index contents may be changed (and thus the policy stored in it updated) by\nproviding an access PIN. This PIN is normally generated automatically and stored in\nencrypted form (with an access policy binding it to the NV index itself) in the\naforementioned JSON policy file. This PIN may be chosen by the user, via the\n--recovery-pin= switch. If specified it may be used as alternative path of access to\nupdate the policy.\n\nIf the new prediction matches the old this command terminates quickly and executes no\nfurther operation. (Unless --force is specified, see below.)\n\nAdded in version 255.\n" }, { "name": "remove-policy", "content": "Removes a previously generated policy. Deletes the /var/lib/systemd/pcrlock.json file,\nand deallocates the NV index.\n\nAdded in version 255.\n\nlock-firmware-code, unlock-firmware-code\nGenerates/removes .pcrlock files based on the TPM2 event log of the current boot covering\nall records for PCRs 0 (\"platform-code\") and 2 (\"external-code\").\n\nThis operation allows locking the boot process to the current version of the firmware of\nthe system and its extension cards. This operation should only be used if the system\nvendor does not provide suitable pcrlock data ahead of time.\n\nNote that this data only matches the current version of the firmware. If a firmware\nupdate is applied this data will be out-of-date and any access policy generated from it\nwill no longer pass. It is thus recommended to invoke unlock-firmware-code before doing a\nfirmware update, followed by make-policy to refresh the policy.\n\nsystemd-pcrlock lock-firmware-code is invoked automatically at boot via the\nsystemd-pcrlock-firmware-code.service unit, if enabled. This ensures that an access\npolicy managed by systemd-pcrlock is automatically locked to the new firmware version\nwhenever the policy has been relaxed temporarily, in order to cover for firmware updates,\nas described above.\n\nThe files are only generated from the event log if the event log matches the current TPM2\nPCR state.\n\nThis writes/removes the files\n/var/lib/pcrlock.d/250-firmware-code-early.pcrlock.d/generated.pcrlock and\n/var/lib/pcrlock.d/550-firmware-code-late.pcrlock.d/generated.pcrlock.\n\nAdded in version 255.\n\nlock-firmware-config, unlock-firmware-config\nThis is similar to lock-firmware-code/unlock-firmware-code but locks down the firmware\nconfiguration, i.e. PCRs 1 (\"platform-config\") and 3 (\"external-config\").\n\nThis functionality should be used with care as in most scenarios a minor firmware\nconfiguration change should not invalidate access policies to TPM2 objects. Also note\nthat some systems measure unstable and unpredictable information (e.g. current CPU\nvoltages, temperatures, as part of SMBIOS data) to these PCRs, which means this form of\nlockdown cannot be used reliably on such systems. Use this functionality only if the\nsystem and hardware is well known and does not suffer by these limitations, for example\nin virtualized environments.\n\nUse unlock-firmware-config before making firmware configuration changes. If the\nsystemd-pcrlock-firmware-config.service unit is enabled it will automatically generate a\npcrlock file from the new measurements.\n\nThis writes/removes the files\n/var/lib/pcrlock.d/250-firmware-config-early.pcrlock.d/generated.pcrlock and\n/var/lib/pcrlock.d/550-firmware-config-late.pcrlock.d/generated.pcrlock.\n\nAdded in version 255.\n\nlock-secureboot-policy, unlock-secureboot-policy\nGenerates/removes a .pcrlock file based on the SecureBoot policy currently enforced. This\nlooks at the SecureBoot, PK, KEK, db, dbx, dbt, dbr EFI variables and predicts their\nmeasurements to PCR 7 (\"secure-boot-policy\") on the next boot.\n\nUse unlock-firmware-config before applying SecureBoot policy updates. If the\nsystemd-pcrlock-secureboot-policy.service unit is enabled it will automatically generate\na pcrlock file from the policy discovered.\n\nThis writes/removes the file\n/var/lib/pcrlock.d/230-secureboot-policy.pcrlock.d/generated.pcrlock.\n\nAdded in version 255.\n\nlock-secureboot-authority, unlock-secureboot-authority\nGenerates/removes a .pcrlock file based on the SecureBoot authorities used to validate\nthe boot path. SecureBoot authorities are the specific SecureBoot database entries that\nwhere used to validate the UEFI PE binaries executed at boot. This looks at the event log\nof the current boot, and uses relevant measurements on PCR 7 (\"secure-boot-policy\").\n\nThis writes/removes the file\n/var/lib/pcrlock.d/620-secureboot-authority.pcrlock.d/generated.pcrlock.\n\nAdded in version 255.\n\nlock-gpt [DEVICE], unlock-gpt\nGenerates/removes a .pcrlock file based on the GPT partition table of the specified disk.\nIf no disk is specified automatically determines the block device backing the root file\nsystem. This locks the state of the disk partitioning of the booted medium, which\nfirmware measures to PCR 5 (\"boot-loader-config\").\n\nThis writes/removes the file /var/lib/pcrlock.d/600-gpt.pcrlock.d/generated.pcrlock.\n\nAdded in version 255.\n\nlock-pe [BINARY], unlock-pe\nGenerates/removes a .pcrlock file based on the specified PE binary. This is useful for\npredicting measurements the firmware makes to PCR 4 (\"boot-loader-code\") if the specified\nbinary is part of the UEFI boot process. Use this on boot loader binaries and suchlike.\nUse lock-uki (see below) for PE binaries that are unified kernel images (UKIs).\n\nExpects a path to the PE binary as argument. If not specified, reads the binary from\nSTDIN instead.\n\nThe pcrlock file to write must be specified via the --pcrlock= switch.\n\nAdded in version 255.\n\nlock-uki [UKI], unlock-uki\nGenerates/removes a .pcrlock file based on the specified UKI PE binary. This is useful\nfor predicting measurements the firmware makes to PCR 4 (\"boot-loader-code\"), and\nsystemd-stub(7) makes to PCR 11 (\"kernel-boot\"), if the specified UKI is booted. This is\na superset of lock-pe.\n\nExpects a path to the UKI PE binary as argument. If not specified, reads the binary from\nSTDIN instead.\n\nThe pcrlock file to write must be specified via the --pcrlock= switch.\n\nAdded in version 255.\n\nlock-machine-id, unlock-machine-id\nGenerates/removes a .pcrlock file based on /etc/machine-id. This is useful for predicting\nmeasurements systemd-pcrmachine.service(8) makes to PCR 15 (\"system-identity\").\n\nThis writes/removes the file /var/lib/pcrlock.d/820-machine-id.pcrlock.\n\nAdded in version 255.\n\nlock-file-system [PATH], unlock-file-system [PATH]\nGenerates/removes a .pcrlock file based on file system identity. This is useful for\npredicting measurements systemd-pcrfs@.service(8) makes to PCR 15 (\"system-identity\") for\nthe root and /var/ file systems.\n\nThis writes/removes the files /var/lib/pcrlock.d/830-root-file-system.pcrlock and\n/var/lib/pcrlock.d/840-file-system-path.pcrlock.\n\nAdded in version 255.\n\nlock-kernel-cmdline [FILE], unlock-kernel-cmdline\nGenerates/removes a .pcrlock file based on /proc/cmdline (or the specified file if\ngiven). This is useful for predicting measurements the Linux kernel makes to PCR 9\n(\"kernel-initrd\").\n\nThis writes/removes the file\n/var/lib/pcrlock.d/710-kernel-cmdline.pcrlock/generated.pcrlock.\n\nAdded in version 255.\n\nlock-kernel-initrd FILE, unlock-kernel-initrd\nGenerates/removes a .pcrlock file based on a kernel initrd cpio archive. This is useful\nfor predicting measurements the Linux kernel makes to PCR 9 (\"kernel-initrd\"). Do not use\nfor systemd-stub UKIs, as the initrd is combined dynamically from various sources and\nhence does not take a single input, like this command.\n\nThis writes/removes the file\n/var/lib/pcrlock.d/720-kernel-initrd.pcrlock/generated.pcrlock.\n\nAdded in version 255.\n\nlock-raw [FILE], unlock-raw\nGenerates/removes a .pcrlock file based on raw binary data. The data is either read from\nthe specified file or from STDIN (if none is specified). This requires that --pcrs= is\nspecified. The generated pcrlock file is written to the file specified via --pcrlock= or\nto STDOUT (if none is specified).\n\nAdded in version 255.\n" } ] }, "OPTIONS": { "content": "The following options are understood:\n", "subsections": [ { "name": "--raw-description", "content": "When displaying the TPM2 event log do not attempt to decode the records to provide a\nfriendly event log description string. Instead, show the binary payload data in escaped\nform.\n\nAdded in version 255.\n", "long": "--raw-description" }, { "name": "--pcr=", "content": "Specifies the PCR number to use. May be specified more than once to select multiple PCRs.\n\nThis is used by lock-raw and lock-pe to select the PCR to lock against.\n\nIf used with predict and make-policy this will override which PCRs to include in the\nprediction and policy. If unspecified this defaults to PCRs 0-5, 7, 11-15. Note that\nthese commands will not include any PCRs in the prediction/policy (even if specified\nexplicitly) if there are measurements in the event log that do not match the current PCR\nvalue, or there are unrecognized measurements in the event log, or components define\nmeasurements not seen in the event log.\n\nAdded in version 255.\n" }, { "name": "--nv-index=", "content": "Specifies to NV index to store the policy in. Honoured by make-policy. If not specified\nthe command will automatically pick a free NV index.\n\nAdded in version 255.\n" }, { "name": "--components=", "content": "Takes a path to read *.pcrlock and *.pcrlock.d/*.pcrlock files from. May be used more\nthan once to specify multiple such directories. If not specified defaults to\n/etc/pcrlock.d/, /run/pcrlock.d/, /var/lib/pcrlock.d/, /usr/local/pcrlock.d/,\n/usr/lib/pcrlock.d/.\n\nAdded in version 255.\n" }, { "name": "--location=", "content": "Takes either a string or a colon-separated pair of strings. Configures up to which point\nin the sorted list of defined components to analyze/predict PCRs to. Typically, the\nsystemd-pcrlock tool is invoked from a fully booted system after boot-up and before\nshutdown. This means various components that are defined for shutdown have not been\nmeasured yet, and should not be searched for. This option allows one to restrict which\ncomponents are considered for analysis (taking only components before some point into\naccount, ignoring components after them). The expected string is ordered against the\nfilenames of the components defined. Any components with a lexicographically later name\nare ignored. This logic applies to the log, predict, and make-policy verbs. If a\ncolon-separated pair of strings are specified then they select which phases of the boot\nto include in the prediction/policy. The first string defines where the first prediction\nshall be made, and the second string defines where the last prediction shall be made. All\nsuch predictions are then combined into one set.\n\nIf used with list-components the selected location range will be highlighted in the\ncomponent list.\n\nDefaults to \"760-:940-\", which means the policies generated by default will basically\ncover the whole runtime of the OS userspace, from the initrd (as \"760-\" closely follows\n750-enter-initrd.pcrlock) until (and including) the main runtime of the system (as \"940-\"\nis closely followed by 950-shutdown.pcrlock). See systemd.pcrlock(5) for a full list of\nwell-known components, that illustrate where this range is placed by default.\n\nAdded in version 255.\n" }, { "name": "--recovery-pin=", "content": "Takes a boolean. Defaults to false. Honoured by make-policy. If true, will query the user\nfor a PIN to unlock the TPM2 NV index with. If no policy was created before this PIN is\nused to protect the newly allocated NV index. If a policy has been created before the PIN\nis used to unlock write access to the NV index. If this option is not used a PIN is\nautomatically generated. Regardless if user supplied or automatically generated, it is\nstored in encrypted form in the policy metadata file. The recovery PIN may be used to\nregain write access to an NV index in case the access policy became out of date.\n\nAdded in version 255.\n" }, { "name": "--pcrlock=", "content": "Takes a file system path as argument. If specified overrides where to write the generated\npcrlock data to. Honoured by the various lock-* commands. If not specified, a default\npath is generally used, as documented above.\n\nAdded in version 255.\n" }, { "name": "--policy=", "content": "Takes a file system path as argument. If specified overrides where to write pcrlock\npolicy metadata to. If not specified defaults to /var/lib/systemd/pcrlock.json.\n\nAdded in version 255.\n" }, { "name": "--force", "content": "If specified with make-policy, the predicted policy will be written to the NV index even\nif it is detected to be the same as the previously stored one.\n\nAdded in version 255.\n\n--json=MODE\nShows output formatted as JSON. Expects one of \"short\" (for the shortest possible output\nwithout any redundant whitespace or line breaks), \"pretty\" (for a pretty version of the\nsame, with indentation and line breaks) or \"off\" (to turn off JSON output, the default).\n", "long": "--force" }, { "name": "--no-pager", "content": "Do not pipe output into a pager.\n", "long": "--no-pager" }, { "name": "-h --help", "content": "Print a short help text and exit.\n", "flag": "-h", "long": "--help" }, { "name": "--version", "content": "Print a short version string and exit.\n", "long": "--version" } ] }, "EXIT STATUS": { "content": "On success, 0 is returned, a non-zero failure code otherwise.\n", "subsections": [] }, "SEE ALSO": { "content": "systemd(1), systemd.pcrlock(5), systemd-cryptenroll(1), systemd-cryptsetup@.service(8),\nsystemd-repart(8), systemd-pcrmachine.service(8)\n", "subsections": [] }, "NOTES": { "content": "1. TCG Common Event Log Format (CEL-JSON)\nhttps://trustedcomputinggroup.org/resource/canonical-event-log-format/\n\nsystemd 255 SYSTEMD-PCRLOCK(8)", "subsections": [] } }, "summary": "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 - Analyze and predict TPM2 PCR states and generate an access policy from the prediction", "flags": [ { "flag": "", "long": "--raw-description", "arg": null, "description": "When displaying the TPM2 event log do not attempt to decode the records to provide a friendly event log description string. Instead, show the binary payload data in escaped form. Added in version 255." }, { "flag": "", "long": null, "arg": null, "description": "Specifies the PCR number to use. May be specified more than once to select multiple PCRs. This is used by lock-raw and lock-pe to select the PCR to lock against. If used with predict and make-policy this will override which PCRs to include in the prediction and policy. If unspecified this defaults to PCRs 0-5, 7, 11-15. Note that these commands will not include any PCRs in the prediction/policy (even if specified explicitly) if there are measurements in the event log that do not match the current PCR value, or there are unrecognized measurements in the event log, or components define measurements not seen in the event log. Added in version 255." }, { "flag": "", "long": null, "arg": null, "description": "Specifies to NV index to store the policy in. Honoured by make-policy. If not specified the command will automatically pick a free NV index. Added in version 255." }, { "flag": "", "long": null, "arg": null, "description": "Takes a path to read *.pcrlock and *.pcrlock.d/*.pcrlock files from. May be used more than once to specify multiple such directories. If not specified defaults to /etc/pcrlock.d/, /run/pcrlock.d/, /var/lib/pcrlock.d/, /usr/local/pcrlock.d/, /usr/lib/pcrlock.d/. Added in version 255." }, { "flag": "", "long": null, "arg": null, "description": "Takes either a string or a colon-separated pair of strings. 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. This means various components that are defined for shutdown have not been measured yet, and should not be searched for. This option allows one to restrict which components are considered for analysis (taking only components before some point into account, ignoring 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 a colon-separated pair of strings are specified 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 used with list-components the selected location range will be highlighted in the component list. Defaults to \"760-:940-\", which means the policies generated by default will basically cover the whole runtime of the OS userspace, from the initrd (as \"760-\" closely follows 750-enter-initrd.pcrlock) until (and including) the main runtime of the system (as \"940-\" is closely followed by 950-shutdown.pcrlock). See systemd.pcrlock(5) for a full list of well-known components, that illustrate where this range is placed by default. Added in version 255." }, { "flag": "", "long": null, "arg": null, "description": "Takes a boolean. Defaults to false. Honoured by make-policy. If true, will 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 this option is not used a PIN is automatically generated. Regardless if user supplied or automatically generated, it is 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." }, { "flag": "", "long": null, "arg": null, "description": "Takes a file system path as argument. If specified overrides 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." }, { "flag": "", "long": null, "arg": null, "description": "Takes a file system path as argument. If specified overrides where to write pcrlock policy metadata to. If not specified defaults to /var/lib/systemd/pcrlock.json. Added in version 255." }, { "flag": "", "long": "--force", "arg": null, "description": "If specified with make-policy, the predicted policy will be written to the NV index even if it is detected to be the same as the previously stored one. Added in version 255. --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, the default)." }, { "flag": "", "long": "--no-pager", "arg": null, "description": "Do not pipe output into a pager." }, { "flag": "-h", "long": "--help", "arg": null, "description": "Print a short help text and exit." }, { "flag": "", "long": "--version", "arg": null, "description": "Print a short version string and exit." } ], "examples": [], "see_also": [ { "name": "systemd", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/systemd/1/json" }, { "name": "systemd.pcrlock", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/systemd.pcrlock/5/json" }, { "name": "systemd-cryptenroll", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/systemd-cryptenroll/1/json" }, { "name": ".service", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/.service/8/json" }, { "name": "systemd-repart", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/systemd-repart/8/json" }, { "name": "systemd-pcrmachine.service", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/systemd-pcrmachine.service/8/json" } ] }