1SYSTEMD.IMAGE-POLICY(7) systemd.image-policy SYSTEMD.IMAGE-POLICY(7)
2
6 systemd.image-policy - Disk Image Dissection Policy
7
9 In systemd, whenever a disk image (DDI) implementing the Discoverable
10 Partitions Specification[1] is activated, a policy may be specified
11 controlling which partitions to mount and what kind of cryptographic
12 protection to require. Such a disk image dissection policy is a string
13 that contains per-partition-type rules, separated by colons (":"). The
14 individual rules consist of a partition identifier, an equal sign
15 ("="), and one or more flags which may be set per partition. If
16 multiple flags are specified per partition they are separated by a plus
17 sign ("+").
18 The partition identifiers currently defined are: root, usr, home, srv,
20 esp, xbootldr, swap, root-verity, root-verity-sig, usr-verity,
21 usr-verity-sig, tmp, var. These identifiers match the relevant
22 partition types in the Discoverable Partitions Specification, but are
23 agnostic to CPU architectures. If the partition identifier is left
24 empty it defines the default policy for partitions defined in the
25 Discoverable Partitions Specification for which no policy flags are
26 explicitly listed in the policy string.
27 The following partition policy flags are defined that dictate the
29 existence/absence, the use, and the protection level of partitions:
30 • unprotected for partitions that shall exist and be used, but shall
32 come without cryptographic protection, lacking both Verity
33 authentication and LUKS encryption.
34 • verity for partitions that shall exist and be used, with Verity
36 authentication. (Note: if a DDI image carries a data partition,
37 along with a Verity partition and a signature partition for it, and
38 only the verity flag is set – and signed is not –, then the image
39 will be set up with Verity, but the signature data will not be
40 used. Or in other words: any DDI with a set of partitions that
41 qualify for signature also implicitly qualifies for verity, and in
42 fact unprotected).
43 • signed for partitions that shall exist and be used, with Verity
45 authentication, which are also accompanied by a PKCS#7 signature of
46 the Verity root hash.
47 • encrypted for partitions which shall exist and be used and are
49 encrypted with LUKS.
50 • unused for partitions that shall exist but shall not be used.
52 • absent for partitions that shall not exist on the image.
54 By setting a combination of the flags above, alternatives can be
56 declared. For example the combination "unused+absent" means: the
57 partition may exist (in which case it shall not be used) or may be
58 absent. The combination of
59 "unprotected+verity+signed+encrypted+unused+absent" may be specified
60 via the special shortcut "open", and indicates that the partition may
61 exist or may be absent, but if it exists is used, regardless of the
62 protection level.
63 As special rule: if none of the flags above are set for a listed
65 partition identifier, the default policy of open is implied, i.e.
66 setting none of these flags listed above means effectively all flags
67 listed above will be set.
68 The following partition policy flags are defined that dictate the state
70 of specific GPT partition flags:
71 • read-only-off, read-only-on to require that the partitions have the
73 read-only partition flag off or on.
74 • growfs-off, growfs-on to require that the partitions have the
76 growfs partition flag off or on.
77 If both read-only-off and read-only-on are set for a partition, then
79 the state of the read-only flag on the partition is not dictated by the
80 policy. Setting neither flag is equivalent to setting both, i.e.
81 setting neither of these two flags means effectively both will be set.
82 A similar logic applies to growfs-off/growfs-on.
83 If partitions are not listed within an image policy string, the default
85 policy flags are applied (configurable via an empty partition
86 identifier, see above). If no default policy flags are configured in
87 the policy string, it is implied to be "absent+unused", except for the
88 Verity partition and their signature partitions where the policy is
89 automatically derived from minimal protection level of the data
90 partition they protect, as encoded in the policy.
91
93 The special image policy string "*" is short for "use everything", i.e.
94 is equivalent to:
95 =verity+signed+encrypted+unprotected+unused+absent
97 The special image policy string "-" is short for "use nothing", i.e. is
99 equivalent to:
100 =unused+absent
102 The special image policy string "~" is short for "everything must be
104 absent", i.e. is equivalent to:
105 =absent
107
109 Most systemd components that support operating with disk images support
110 a --image-policy= command line option to specify the image policy to
111 use, and default to relatively open policies by default (typically the
112 "*" policy, as described above), under the assumption that trust in
113 disk images is established before the images are passed to the program
114 in question.
115 For the host image itself systemd-gpt-auto-generator(8) is responsible
117 for processing the GPT partition table and making use of the included
118 discoverable partitions. It accepts an image policy via the kernel
119 command line option systemd.image-policy=.
120 Note that image policies do not dictate how the components will mount
122 and use disk images — they only dictate which parts to avoid and which
123 protection level and arrangement to require while mounting/using them.
124 For example, systemd-sysext(8) only cares for the /usr/ and /opt/ trees
125 inside a disk image, and thus ignores any /home/ partitions (and
126 similar) in all cases, which might be included in the image, regardless
127 whether the configured image policy would allow access to it or not.
128 Similar, systemd-nspawn(1) is not going to make use of any discovered
129 swap device, regardless if the policy would allow that or not.
130 Use the image-policy command of the systemd-analyze(8) tool to analyze
132 image policy strings, and determine what a specific policy string means
133 for a specific partition.
134
136 The following image policy string dictates one read-only Verity-enabled
137 /usr/ partition must exist, plus encrypted root and swap partitions.
138 All other partitions are ignored:
139 usr=verity+read-only-on:root=encrypted:swap=encrypted
141 The following image policy string dictates an encrypted, writable root
143 file system, and optional /srv/ file system that must be encrypted if
144 it exists and no swap partition may exist:
145 root=encrypted+read-only-off:srv=encrypted+absent:swap=absent
147 The following image policy string dictates a single root partition that
149 may be encrypted, but doesn't have to be, and ignores swap partitions,
150 and uses all other partitions if they are available, possibly with
151 encryption.
152 root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent
154
156 systemd(1), systemd-dissect(1), systemd-gpt-auto-generator(8), systemd-
157 sysext(8), systemd-analyze(8)
158
160 1. Discoverable Partitions Specification
161 https://uapi-group.org/specifications/specs/discoverable_partitions_specification
162systemd 254 SYSTEMD.IMAGE-POLICY(7)