Debian Codegraph @

upstream/debian-trixie/man7/systemd.image-policy.7

raw
1 '\" t
2 .TH "SYSTEMD\&.IMAGE\-POLICY" "7" "" "systemd 257.13" "systemd.image-policy"
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.image-policy \- Disk Image Dissection Policy
24 .SH "DESCRIPTION"
25 .PP
26 In systemd, whenever a disk image (DDI) implementing the
27 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2
28 is activated, a policy may be specified controlling which partitions to mount and what kind of cryptographic protection to require\&. Such a disk image dissection policy is a string that contains per\-partition\-type rules, separated by colons (":")\&. The individual rules consist of a partition identifier, an equal sign ("="), and one or more flags which may be set per partition\&. If multiple flags are specified per partition they are separated by a plus sign ("+")\&.
29 .PP
30 The partition identifiers currently defined are:
31 \fBroot\fR,
32 \fBusr\fR,
33 \fBhome\fR,
34 \fBsrv\fR,
35 \fBesp\fR,
36 \fBxbootldr\fR,
37 \fBswap\fR,
38 \fBroot\-verity\fR,
39 \fBroot\-verity\-sig\fR,
40 \fBusr\-verity\fR,
41 \fBusr\-verity\-sig\fR,
42 \fBtmp\fR,
43 \fBvar\fR\&. These identifiers match the relevant partition types in the Discoverable Partitions Specification, but are agnostic to CPU architectures\&. If the partition identifier is left empty it defines the
44 \fIdefault\fR
45 policy for partitions defined in the Discoverable Partitions Specification for which no policy flags are explicitly listed in the policy string\&.
46 .PP
47 The following partition policy flags are defined that dictate the existence/absence, the use, and the protection level of partitions:
48 .sp
49 .RS 4
50 .ie n \{\
51 \h'-04'\(bu\h'+03'\c
52 .\}
53 .el \{\
54 .sp -1
55 .IP \(bu 2.3
56 .\}
57 \fBunprotected\fR
58 for partitions that shall exist and be used, but shall come without cryptographic protection, lacking both Verity authentication and LUKS encryption\&.
59 .RE
60 .sp
61 .RS 4
62 .ie n \{\
63 \h'-04'\(bu\h'+03'\c
64 .\}
65 .el \{\
66 .sp -1
67 .IP \(bu 2.3
68 .\}
69 \fBverity\fR
70 for partitions that shall exist and be used, with Verity authentication\&. (Note: if a DDI image carries a data partition, along with a Verity partition and a signature partition for it, and only the
71 \fBverity\fR
72 flag is set (\fBsigned\fR
73 is not), then the image will be set up with Verity, but the signature data will not be used\&. Or in other words: any DDI with a set of partitions that qualify for
74 \fBsignature\fR
75 also implicitly qualifies for
76 \fBverity\fR, and in fact also
77 \fBunprotected\fR)\&.
78 .RE
79 .sp
80 .RS 4
81 .ie n \{\
82 \h'-04'\(bu\h'+03'\c
83 .\}
84 .el \{\
85 .sp -1
86 .IP \(bu 2.3
87 .\}
88 \fBsigned\fR
89 for partitions that shall exist and be used, with Verity authentication, which are also accompanied by a PKCS#7 signature of the Verity root hash\&.
90 .RE
91 .sp
92 .RS 4
93 .ie n \{\
94 \h'-04'\(bu\h'+03'\c
95 .\}
96 .el \{\
97 .sp -1
98 .IP \(bu 2.3
99 .\}
100 \fBencrypted\fR
101 for partitions which shall exist and be used and are encrypted with LUKS\&.
102 .RE
103 .sp
104 .RS 4
105 .ie n \{\
106 \h'-04'\(bu\h'+03'\c
107 .\}
108 .el \{\
109 .sp -1
110 .IP \(bu 2.3
111 .\}
112 \fBunused\fR
113 for partitions that shall exist but shall not be used\&.
114 .RE
115 .sp
116 .RS 4
117 .ie n \{\
118 \h'-04'\(bu\h'+03'\c
119 .\}
120 .el \{\
121 .sp -1
122 .IP \(bu 2.3
123 .\}
124 \fBabsent\fR
125 for partitions that shall not exist on the image\&.
126 .RE
127 .PP
128 By setting a combination of the flags above, alternatives can be declared\&. For example the combination
129 "unused+absent"
130 means: the partition may exist (in which case it shall not be used) or may be absent\&. The combination of
131 "unprotected+verity+signed+encrypted+unused+absent"
132 may be specified via the special shortcut
133 "open", and indicates that the partition may exist or may be absent, but if it exists is used, regardless of the protection level\&.
134 .PP
135 As special rule: if none of the flags above are set for a listed partition identifier, the default policy of
136 \fBopen\fR
137 is implied, i\&.e\&. setting none of these flags listed above means effectively all flags listed above will be set\&.
138 .PP
139 The following partition policy flags are defined that dictate the state of specific GPT partition flags:
140 .sp
141 .RS 4
142 .ie n \{\
143 \h'-04'\(bu\h'+03'\c
144 .\}
145 .el \{\
146 .sp -1
147 .IP \(bu 2.3
148 .\}
149 \fBread\-only\-off\fR,
150 \fBread\-only\-on\fR
151 to require that the partitions have the read\-only partition flag off or on\&.
152 .RE
153 .sp
154 .RS 4
155 .ie n \{\
156 \h'-04'\(bu\h'+03'\c
157 .\}
158 .el \{\
159 .sp -1
160 .IP \(bu 2.3
161 .\}
162 \fBgrowfs\-off\fR,
163 \fBgrowfs\-on\fR
164 to require that the partitions have the growfs partition flag off or on\&.
165 .RE
166 .PP
167 If both
168 \fBread\-only\-off\fR
169 and
170 \fBread\-only\-on\fR
171 are set for a partition, then the state of the read\-only flag on the partition is not dictated by the policy\&. Setting neither flag is equivalent to setting both, i\&.e\&. setting neither of these two flags means effectively both will be set\&. A similar logic applies to
172 \fBgrowfs\-off\fR/\fBgrowfs\-on\fR\&.
173 .PP
174 If partitions are not listed within an image policy string, the default policy flags are applied (configurable via an empty partition identifier, see above)\&. If no default policy flags are configured in the policy string, it is implied to be
175 "absent+unused", except for the Verity partition and their signature partitions where the policy is automatically derived from minimal protection level of the data partition they protect, as encoded in the policy\&.
176 .SH "SPECIAL POLICIES"
177 .PP
178 The special image policy string
179 "*"
180 is short for "use everything", i\&.e\&. is equivalent to:
181 .sp
182 .if n \{\
183 .RS 4
184 .\}
185 .nf
186 =verity+signed+encrypted+unprotected+unused+absent
187 .fi
188 .if n \{\
189 .RE
190 .\}
191 .PP
192 The special image policy string
193 "\-"
194 is short for "use nothing", i\&.e\&. is equivalent to:
195 .sp
196 .if n \{\
197 .RS 4
198 .\}
199 .nf
200 =unused+absent
201 .fi
202 .if n \{\
203 .RE
204 .\}
205 .PP
206 The special image policy string
207 "~"
208 is short for "everything must be absent", i\&.e\&. is equivalent to:
209 .sp
210 .if n \{\
211 .RS 4
212 .\}
213 .nf
214 =absent
215 .fi
216 .if n \{\
217 .RE
218 .\}
219 .SH "USE"
220 .PP
221 Most systemd components that support operating with disk images support a
222 \fB\-\-image\-policy=\fR
223 command line option to specify the image policy to use, and default to relatively open policies (typically the
224 "*"
225 policy, as described above), under the assumption that trust in disk images is established before the images are passed to the program in question\&.
226 .PP
227 For the host image itself
228 \fBsystemd-gpt-auto-generator\fR(8)
229 is responsible for processing the GPT partition table and making use of the included discoverable partitions\&. It accepts an image policy via the kernel command line option
230 \fBsystemd\&.image_policy=\fR\&.
231 .PP
232 Note that image policies do not dictate how the components will mount and use disk images \(em they only dictate which parts to avoid and which protection level and arrangement to require while mounting/using them\&. For example,
233 \fBsystemd-sysext\fR(8)
234 only cares for the
235 /usr/
236 and
237 /opt/
238 trees inside a disk image, and thus ignores any
239 /home/
240 partitions (and similar) in all cases, which might be included in the image, regardless whether the configured image policy would allow access to it or not\&. Similar,
241 \fBsystemd-nspawn\fR(1)
242 is not going to make use of any discovered swap device, regardless if the policy would allow that or not\&.
243 .PP
244 Use the
245 \fBimage\-policy\fR
246 command of the
247 \fBsystemd-analyze\fR(1)
248 tool to analyze image policy strings, and determine what a specific policy string means for a specific partition\&.
249 .SH "EXAMPLES"
250 .PP
251 The following image policy string dictates one read\-only Verity\-enabled
252 /usr/
253 partition must exist, plus encrypted root and swap partitions\&. All other partitions are ignored:
254 .sp
255 .if n \{\
256 .RS 4
257 .\}
258 .nf
259 usr=verity+read\-only\-on:root=encrypted:swap=encrypted
260 .fi
261 .if n \{\
262 .RE
263 .\}
264 .PP
265 The following image policy string dictates an encrypted, writable root file system, and optional
266 /srv/
267 file system that must be encrypted if it exists and no swap partition may exist:
268 .sp
269 .if n \{\
270 .RS 4
271 .\}
272 .nf
273 root=encrypted+read\-only\-off:srv=encrypted+absent:swap=absent
274 .fi
275 .if n \{\
276 .RE
277 .\}
278 .PP
279 The following image policy string dictates a single root partition that may be encrypted, but does not have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption\&.
280 .sp
281 .if n \{\
282 .RS 4
283 .\}
284 .nf
285 root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent
286 .fi
287 .if n \{\
288 .RE
289 .\}
290 .SH "SEE ALSO"
291 .PP
292 \fBsystemd\fR(1), \fBsystemd-dissect\fR(1), \fBsystemd-gpt-auto-generator\fR(8), \fBsystemd-sysext\fR(8), \fBsystemd-analyze\fR(1)
293 .SH "NOTES"
294 .IP " 1." 4
295 Discoverable Partitions Specification
296 .RS 4
297 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
298 .RE