Debian Codegraph @

upstream/fedora-44/man8/systemd-pcrphase.service.8

raw
1 '\" t
2 .TH "SYSTEMD\-PCRPHASE\&.SERVICE" "8" "" "systemd 259.5" "systemd-pcrphase.service"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-pcrphase.service, systemd-pcrphase-sysinit.service, systemd-pcrphase-initrd.service, systemd-pcrmachine.service, systemd-pcrproduct.service, systemd-pcrfs-root.service, [email protected], systemd-pcrnvdone.service, systemd-pcrextend \- Measure boot phases, machine ID, product UUID and file system identity into TPM PCRs and NvPCRs
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-pcrphase\&.service
27 .PP
28 systemd\-pcrphase\-sysinit\&.service
29 .PP
30 systemd\-pcrphase\-initrd\&.service
31 .PP
32 systemd\-pcrmachine\&.service
33 .PP
34 systemd\-pcrproduct\&.service
35 .PP
36 systemd\-pcrfs\-root\&.service
37 .PP
38 systemd\-pcrfs@\&.service
39 .PP
40 systemd\-pcrnvdone\&.service
41 .PP
42 /usr/lib/systemd/systemd\-pcrextend
43 [\fISTRING\fR]
44 .SH "DESCRIPTION"
45 .PP
46 systemd\-pcrphase\&.service,
47 systemd\-pcrphase\-sysinit\&.service, and
48 systemd\-pcrphase\-initrd\&.service
49 are system services that measure specific strings into TPM2 PCR 11 during boot at various milestones of the boot process\&.
50 .PP
51 systemd\-pcrmachine\&.service
52 is a system service that measures the machine ID (see
53 \fBmachine-id\fR(5)) into PCR 15\&.
54 .PP
55 systemd\-pcrproduct\&.service
56 is a system service that measures the firmware product UUID (as provided by one of SMBIOS, Devicetree, \&...) into a NvPCR named
57 "hardware"\&.
58 .PP
59 systemd\-pcrnvdone\&.service
60 is a system service that measures a separator event into PCR 9 once all NvPCRs have completed initialization\&.
61 .PP
62 systemd\-pcrfs\-root\&.service
63 and
64 systemd\-pcrfs@\&.service
65 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\&.
66 systemd\-pcrfs\-root\&.service
67 does so for the root file system,
68 systemd\-pcrfs@\&.service
69 is a template unit that measures the file system indicated by its instance identifier instead\&.
70 .PP
71 These services require
72 \fBsystemd-stub\fR(7)
73 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:
74 .sp
75 .RS 4
76 .ie n \{\
77 \h'-04' 1.\h'+01'\c
78 .\}
79 .el \{\
80 .sp -1
81 .IP " 1." 4.2
82 .\}
83 "enter\-initrd"
84 \(em 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
85 \fBsystemd-pcrphase-initrd.service\fR(8)
86 service is started\&.)
87 .RE
88 .sp
89 .RS 4
90 .ie n \{\
91 \h'-04' 2.\h'+01'\c
92 .\}
93 .el \{\
94 .sp -1
95 .IP " 2." 4.2
96 .\}
97 "leave\-initrd"
98 \(em 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
99 \fBsystemd-pcrphase-sysinit.service\fR(8)
100 service is stopped\&.)
101 .RE
102 .sp
103 .RS 4
104 .ie n \{\
105 \h'-04' 3.\h'+01'\c
106 .\}
107 .el \{\
108 .sp -1
109 .IP " 3." 4.2
110 .\}
111 "sysinit"
112 \(em 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
113 \fBsystemd-pcrphase-sysinit.service\fR(8)
114 service is started\&.)
115 .RE
116 .sp
117 .RS 4
118 .ie n \{\
119 \h'-04' 4.\h'+01'\c
120 .\}
121 .el \{\
122 .sp -1
123 .IP " 4." 4.2
124 .\}
125 "ready"
126 \(em during later boot\-up, after remote file systems have been activated (i\&.e\&. after
127 remote\-fs\&.target), but before users are permitted to log in (i\&.e\&. before
128 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
129 \fBsystemd-pcrphase-sysinit.service\fR(8)
130 service is started\&.)
131 .RE
132 .sp
133 .RS 4
134 .ie n \{\
135 \h'-04' 5.\h'+01'\c
136 .\}
137 .el \{\
138 .sp -1
139 .IP " 5." 4.2
140 .\}
141 "shutdown"
142 \(em 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
143 systemd\-pcrphase\&.service
144 service is stopped\&.)
145 .RE
146 .sp
147 .RS 4
148 .ie n \{\
149 \h'-04' 6.\h'+01'\c
150 .\}
151 .el \{\
152 .sp -1
153 .IP " 6." 4.2
154 .\}
155 "final"
156 \(em 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
157 \fBsystemd-pcrphase-sysinit.service\fR(8)
158 service is stopped\&.)
159 .RE
160 .PP
161 During a regular system lifecycle, PCR 11 is extended with the strings
162 "enter\-initrd",
163 "leave\-initrd",
164 "sysinit",
165 "ready",
166 "shutdown", and
167 "final"\&.
168 .PP
169 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
170 "enter\-initrd:leave\-initrd:sysinit:ready", while the one for the initrd is just
171 "enter\-initrd"\&. The phase path for the boot phase before the initrd is an empty string; because that\*(Aqs 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\&.
172 .PP
173 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\*(Aqs encryption key after the system transitioned from the initrd into the host root file system\&.
174 .PP
175 Use
176 \fBsystemd-measure\fR(1)
177 to pre\-calculate expected PCR 11 values for specific boot phases (via the
178 \fB\-\-phase=\fR
179 switch)\&.
180 .PP
181 systemd\-pcrfs\-root\&.service
182 and
183 systemd\-pcrfs@\&.service
184 are automatically pulled into the initial transaction by
185 \fBsystemd-gpt-auto-generator\fR(8)
186 for the root and
187 /var/
188 file systems\&.
189 \fBsystemd-fstab-generator\fR(8)
190 will do this for all mounts with the
191 \fBx\-systemd\&.pcrfs\fR
192 mount option in
193 /etc/fstab\&.
194 .SH "OPTIONS"
195 .PP
196 The
197 /usr/lib/systemd/system\-pcrextend
198 executable may also be invoked from the command line, where it expects the word to extend into a PCR or NvPCR, as well as the following switches:
199 .PP
200 \fB\-\-bank=\fR
201 .RS 4
202 Takes the PCR banks to extend the specified word into\&. If not specified, the tool automatically determines all enabled PCR banks and measures the word into all of them\&.
203 .sp
204 Added in version 252\&.
205 .RE
206 .PP
207 \fB\-\-pcr=\fR
208 .RS 4
209 Takes the index of the PCR to extend\&. If
210 \fB\-\-machine\-id\fR
211 or
212 \fB\-\-file\-system=\fR
213 are specified defaults to 15, otherwise (and unless
214 \fB\-\-product\-id\fR
215 is specified) defaults to 11\&. May not be combined with
216 \fB\-\-nvpcr=\fR\&.
217 .sp
218 Added in version 255\&.
219 .RE
220 .PP
221 \fB\-\-nvpcr=\fR
222 .RS 4
223 Takes a name of an NvPCR to extend\&. NvPCRs are additional PCRs implemented via TPM NV indexes\&. The name should be a short string such as
224 "hardware"
225 or
226 "disk\-encryption"\&. If
227 \fB\-\-product\-id\fR
228 is specified defaults
229 "hardware"\&. May not be combined with
230 \fB\-\-pcr=\fR\&.
231 .sp
232 Added in version 259\&.
233 .RE
234 .PP
235 \fB\-\-tpm2\-device=\fR\fB\fIPATH\fR\fR
236 .RS 4
237 Controls which TPM2 device to use\&. Expects a device node path referring to the TPM2 chip (e\&.g\&.
238 /dev/tpmrm0)\&. Alternatively the special value
239 "auto"
240 may be specified, in order to automatically determine the device node of a suitable TPM2 device (of which there must be exactly one)\&. The special value
241 "list"
242 may be used to enumerate all suitable TPM2 devices currently discovered\&.
243 .sp
244 Added in version 252\&.
245 .RE
246 .PP
247 \fB\-\-graceful\fR
248 .RS 4
249 If no TPM2 firmware, kernel subsystem, kernel driver or device support is found, exit with exit status 0 (i\&.e\&. indicate success)\&. If this is not specified, any attempt to measure without a TPM2 device will cause the invocation to fail\&.
250 .sp
251 Added in version 253\&.
252 .RE
253 .PP
254 \fB\-\-early\fR
255 .RS 4
256 Selects early\-boot mode\&. Specifically this means that the NvPCR anchor secret is not attempted to be written into
257 /var/lib/
258 and the boot loader partition in addition to
259 /run/\&. (Unlike the latter the former are generally not mounted and writable during early boot or in the initrd\&.)
260 .sp
261 Added in version 259\&.
262 .RE
263 .PP
264 \fB\-\-machine\-id\fR
265 .RS 4
266 Instead of measuring a word specified on the command line into PCR 11, measure the host\*(Aqs machine ID into PCR 15\&.
267 .sp
268 Added in version 253\&.
269 .RE
270 .PP
271 \fB\-\-product\-id\fR
272 .RS 4
273 Instead of measuring a word specified on the command line into PCR 11, measure the firmware\*(Aqs product UUID into an NvPCR named
274 "hardware"\&.
275 .sp
276 Added in version 259\&.
277 .RE
278 .PP
279 \fB\-\-file\-system=\fR
280 .RS 4
281 Instead of measuring a word specified on the command line into PCR 11, measure identity information of the specified file system into PCR 15\&. The parameter must be the path to the established mount point of the file system to measure\&.
282 .sp
283 Added in version 253\&.
284 .RE
285 .PP
286 \fB\-\-event\-type=\fR
287 .RS 4
288 Set the event log event type for this measurement\&. Pass
289 "help"
290 for a list of currently defined identifiers\&. Defaults to an appropriate value for
291 \fB\-\-machine\-id\fR,
292 \fB\-\-product\-id\fR,
293 \fB\-\-file\-system=\fR, and otherwise to
294 "phase"\&.
295 .sp
296 Added in version 259\&.
297 .RE
298 .PP
299 \fB\-h\fR, \fB\-\-help\fR
300 .RS 4
301 Print a short help text and exit\&.
302 .RE
303 .PP
304 \fB\-\-version\fR
305 .RS 4
306 Print a short version string and exit\&.
307 .RE
308 .SH "FILES"
309 .PP
310 /run/log/systemd/tpm2\-measure\&.log
311 .RS 4
312 Measurements are logged into an event log file maintained in
313 /run/log/systemd/tpm2\-measure\&.log, which contains a
314 \m[blue]\fBJSON\-SEQ\fR\m[]\&\s-2\u[1]\d\s+2
315 series of objects that follow the general structure of the
316 \m[blue]\fBTCG Canonical Event Log Format (CEL\-JSON)\fR\m[]\&\s-2\u[2]\d\s+2
317 event objects (but lack the
318 "recnum"
319 field)\&.
320 .sp
321 A
322 \fBLOCK_EX\fR
323 BSD file lock (\fBflock\fR(2)) on the log file is acquired while the measurement is made and the file is updated\&. Thus, applications that intend to acquire a consistent quote from the TPM with the associated snapshot of the event log should acquire a
324 \fBLOCK_SH\fR
325 lock while doing so\&.
326 .sp
327 Added in version 252\&.
328 .RE
329 .PP
330 /usr/lib/nvpcr/*\&.nvpcr
331 .RS 4
332 Definition files for NvPCRs\&.
333 .sp
334 Added in version 259\&.
335 .RE
336 .SH "SEE ALSO"
337 .PP
338 \fBsystemd\fR(1), \fBsystemd-stub\fR(7), \fBsystemd-measure\fR(1), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-fstab-generator\fR(8), \m[blue]\fBTPM2 PCR Measurements Made by systemd\fR\m[]\&\s-2\u[3]\d\s+2
339 .SH "NOTES"
340 .IP " 1." 4
341 JSON-SEQ
342 .RS 4
343 \%https://www.rfc-editor.org/rfc/rfc7464.html
344 .RE
345 .IP " 2." 4
346 TCG Canonical Event Log Format (CEL-JSON)
347 .RS 4
348 \%https://trustedcomputinggroup.org/resource/canonical-event-log-format/
349 .RE
350 .IP " 3." 4
351 TPM2 PCR Measurements Made by systemd
352 .RS 4
353 \%https://systemd.io/TPM2_PCR_MEASUREMENTS
354 .RE