]>
Commit | Line | Data |
---|---|---|
9ea81191 LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
9ea81191 LP |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
5 | ||
6 | <refentry id="systemd.image-policy"> | |
7 | ||
8 | <refentryinfo> | |
9 | <title>systemd.image-policy</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>systemd.image-policy</refentrytitle> | |
15 | <manvolnum>7</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>systemd.image-policy</refname> | |
20 | <refpurpose>Disk Image Dissection Policy</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsect1> | |
24 | <title>Description</title> | |
25 | ||
26 | <para>In systemd, whenever a disk image (DDI) implementing the <ulink | |
27 | url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable | |
28 | Partitions Specification</ulink> is activated, a policy may be specified controlling which partitions to | |
29 | mount and what kind of cryptographic protection to require. Such a disk image dissection policy is a | |
30 | string that contains per-partition-type rules, separated by colons (<literal>:</literal>). The individual | |
31 | rules consist of a partition identifier, an equal sign (<literal>=</literal>), and one or more flags | |
32 | which may be set per partition. If multiple flags are specified per partition they are separated by a | |
33 | plus sign (<literal>+</literal>).</para> | |
34 | ||
35 | <para>The partition identifiers currently defined are: <option>root</option>, <option>usr</option>, | |
36 | <option>home</option>, <option>srv</option>, <option>esp</option>, <option>xbootldr</option>, | |
37 | <option>swap</option>, <option>root-verity</option>, <option>root-verity-sig</option>, | |
38 | <option>usr-verity</option>, <option>usr-verity-sig</option>, <option>tmp</option>, | |
39 | <option>var</option>. These identifiers match the relevant partition types in the Discoverable Partitions | |
40 | Specification, but are agnostic to CPU architectures. If the partition identifier is left empty it | |
94d82b59 | 41 | defines the <emphasis>default</emphasis> policy for partitions defined in the Discoverable Partitions |
9ea81191 LP |
42 | Specification for which no policy flags are explicitly listed in the policy string.</para> |
43 | ||
44 | <para>The following partition policy flags are defined that dictate the existence/absence, the use, and | |
45 | the protection level of partitions:</para> | |
46 | ||
47 | <itemizedlist> | |
48 | <listitem><para><option>unprotected</option> for partitions that shall exist and be used, but shall | |
49 | come without cryptographic protection, lacking both Verity authentication and LUKS | |
50 | encryption.</para></listitem> | |
51 | ||
52 | <listitem><para><option>verity</option> for partitions that shall exist and be used, with Verity | |
53 | authentication. (Note: if a DDI image carries a data partition, along with a Verity partition and a | |
bf63dadb ZJS |
54 | signature partition for it, and only the <option>verity</option> flag is set (<option>signed</option> |
55 | is not), then the image will be set up with Verity, but the signature data will not be used. Or in | |
56 | other words: any DDI with a set of partitions that qualify for <option>signature</option> also | |
57 | implicitly qualifies for <option>verity</option>, and in fact also | |
9ea81191 LP |
58 | <option>unprotected</option>).</para></listitem> |
59 | ||
60 | <listitem><para><option>signed</option> for partitions that shall exist and be used, with Verity | |
61 | authentication, which are also accompanied by a PKCS#7 signature of the Verity root | |
62 | hash.</para></listitem> | |
63 | ||
64 | <listitem><para><option>encrypted</option> for partitions which shall exist and be used and are | |
65 | encrypted with LUKS.</para></listitem> | |
66 | ||
67 | <listitem><para><option>unused</option> for partitions that shall exist but shall not be | |
68 | used.</para></listitem> | |
69 | ||
70 | <listitem><para><option>absent</option> for partitions that shall not exist on the | |
71 | image.</para></listitem> | |
72 | </itemizedlist> | |
73 | ||
74 | <para>By setting a combination of the flags above, alternatives can be declared. For example the | |
75 | combination <literal>unused+absent</literal> means: the partition may exist (in which case it shall not | |
76 | be used) or may be absent. The combination of | |
77 | <literal>unprotected+verity+signed+encrypted+unused+absent</literal> may be specified via the special | |
78 | shortcut <literal>open</literal>, and indicates that the partition may exist or may be absent, but if it | |
79 | exists is used, regardless of the protection level.</para> | |
80 | ||
81 | <para>As special rule: if none of the flags above are set for a listed partition identifier, the default | |
82 | policy of <option>open</option> is implied, i.e. setting none of these flags listed above means | |
83 | effectively all flags listed above will be set.</para> | |
84 | ||
85 | <para>The following partition policy flags are defined that dictate the state of specific GPT partition | |
86 | flags:</para> | |
87 | ||
88 | <itemizedlist> | |
89 | <listitem><para><option>read-only-off</option>, <option>read-only-on</option> to require that the | |
90 | partitions have the read-only partition flag off or on.</para></listitem> | |
91 | ||
92 | <listitem><para><option>growfs-off</option>, <option>growfs-on</option> to require that the | |
93 | partitions have the growfs partition flag off or on.</para></listitem> | |
94 | </itemizedlist> | |
95 | ||
96 | <para>If both <option>read-only-off</option> and <option>read-only-on</option> are set for a partition, | |
97 | then the state of the read-only flag on the partition is not dictated by the policy. Setting neither flag | |
98 | is equivalent to setting both, i.e. setting neither of these two flags means effectively both will be | |
99 | set. A similar logic applies to <option>growfs-off</option>/<option>growfs-on</option>.</para> | |
100 | ||
101 | <para>If partitions are not listed within an image policy string, the default policy flags are applied | |
102 | (configurable via an empty partition identifier, see above). If no default policy flags are configured in | |
103 | the policy string, it is implied to be <literal>absent+unused</literal>, except for the Verity partition | |
104 | and their signature partitions where the policy is automatically derived from minimal protection level of | |
105 | the data partition they protect, as encoded in the policy.</para> | |
106 | </refsect1> | |
107 | ||
108 | <refsect1> | |
109 | <title>Special Policies</title> | |
110 | ||
111 | <para>The special image policy string <literal>*</literal> is short for "use everything", i.e. is | |
112 | equivalent to:</para> | |
113 | ||
114 | <programlisting>=verity+signed+encrypted+unprotected+unused+absent</programlisting> | |
115 | ||
116 | <para>The special image policy string <literal>-</literal> is short for "use nothing", i.e. is equivalent | |
117 | to:</para> | |
118 | ||
119 | <programlisting>=unused+absent</programlisting> | |
120 | ||
121 | <para>The special image policy string <literal>~</literal> is short for "everything must be absent", | |
122 | i.e. is equivalent to:</para> | |
123 | ||
124 | <programlisting>=absent</programlisting> | |
125 | ||
126 | </refsect1> | |
127 | ||
128 | <refsect1> | |
129 | <title>Use</title> | |
130 | ||
131 | <para>Most systemd components that support operating with disk images support a | |
132 | <option>--image-policy=</option> command line option to specify the image policy to use, and default to | |
bf63dadb ZJS |
133 | relatively open policies (typically the <literal>*</literal> policy, as described above), under the |
134 | assumption that trust in disk images is established before the images are passed to the program in | |
135 | question.</para> | |
9ea81191 LP |
136 | |
137 | <para>For the host image itself | |
138 | <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
139 | is responsible for processing the GPT partition table and making use of the included discoverable | |
140 | partitions. It accepts an image policy via the kernel command line option | |
141 | <option>systemd.image-policy=</option>.</para> | |
142 | ||
143 | <para>Note that image policies do not dictate how the components will mount and use disk images — they | |
144 | only dictate which parts to avoid and which protection level and arrangement to require while | |
145 | mounting/using them. For example, | |
146 | <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> only | |
147 | cares for the <filename>/usr/</filename> and <filename>/opt/</filename> trees inside a disk image, and | |
148 | thus ignores any <filename>/home/</filename> partitions (and similar) in all cases, which might be | |
149 | included in the image, regardless whether the configured image policy would allow access to it or | |
150 | not. Similar, | |
151 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> is not | |
152 | going to make use of any discovered swap device, regardless if the policy would allow that or not.</para> | |
153 | ||
154 | <para>Use the <command>image-policy</command> command of the | |
155 | <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry> tool | |
156 | to analyze image policy strings, and determine what a specific policy string means for a specific | |
157 | partition.</para> | |
158 | </refsect1> | |
159 | ||
160 | <refsect1> | |
161 | <title>Examples</title> | |
162 | ||
163 | <para>The following image policy string dictates one read-only Verity-enabled <filename>/usr/</filename> | |
164 | partition must exist, plus encrypted root and swap partitions. All other partitions are ignored:</para> | |
165 | ||
166 | <programlisting>usr=verity+read-only-on:root=encrypted:swap=encrypted</programlisting> | |
167 | ||
168 | <para>The following image policy string dictates an encrypted, writable root file system, and optional | |
169 | <filename>/srv/</filename> file system that must be encrypted if it exists and no swap partition may | |
170 | exist:</para> | |
171 | ||
172 | <programlisting>root=encrypted+read-only-off:srv=encrypted+absent:swap=absent</programlisting> | |
173 | ||
174 | <para>The following image policy string dictates a single root partition that may be encrypted, but | |
175 | doesn't have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption.</para> | |
176 | ||
177 | <programlisting>root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent</programlisting> | |
178 | </refsect1> | |
179 | ||
180 | <refsect1> | |
181 | <title>See Also</title> | |
13a69c12 DT |
182 | <para><simplelist type="inline"> |
183 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
184 | <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
185 | <member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
186 | <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
187 | <member><citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> | |
188 | </simplelist></para> | |
9ea81191 LP |
189 | </refsect1> |
190 | ||
191 | </refentry> |