man: document image policy syntax and semantics, and the hooks in the various components

19 files changed, 341 insertions, 4 deletions

diff --git a/man/bootctl.xml b/man/bootctl.xml
index a6f1fc1c4c..5f98486343 100644
--- a/man/bootctl.xml
+++ b/man/bootctl.xml
@@ -305,6 +305,8 @@
         switch of the same name.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--install-source=</option></term>
         <listitem><para>When installing binaries with <option>--root=</option> or
diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml
index 79632eb2d4..0f4a2e83e6 100644
--- a/man/coredumpctl.xml
+++ b/man/coredumpctl.xml
@@ -268,6 +268,8 @@
         switch of the same name.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>-q</option></term>
         <term><option>--quiet</option></term>
diff --git a/man/journalctl.xml b/man/journalctl.xml
index ae86c50d62..aa124dd98f 100644
--- a/man/journalctl.xml
+++ b/man/journalctl.xml
@@ -182,6 +182,8 @@
         switch of the same name.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term>
 
diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml
index 6f026318d8..27ef72da36 100644
--- a/man/kernel-command-line.xml
+++ b/man/kernel-command-line.xml
@@ -396,13 +396,23 @@
         <term><varname>rd.systemd.gpt_auto=</varname></term>
 
         <listitem>
-          <para>Configures whether GPT based partition auto-discovery
-          shall be attempted. For details, see
+          <para>Configures whether GPT-based partition auto-discovery shall be attempted. For details, see
           <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
         </listitem>
       </varlistentry>
 
       <varlistentry>
+        <term><varname>systemd.image_policy=</varname></term>
+        <term><varname>rd.systemd.image_policy=</varname></term>
+
+        <listitem><para>When GPT-based partition auto-discovery is used, configures the image dissection
+        policy string to apply, as per
+        <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+        details see
+        <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>systemd.default_timeout_start_sec=</varname></term>
 
         <listitem>
diff --git a/man/rules/meson.build b/man/rules/meson.build
index 63a68c3211..42c546f18d 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1104,6 +1104,7 @@ manpages = [
  ['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'],
  ['systemd.exec', '5', [], ''],
  ['systemd.generator', '7', [], ''],
+ ['systemd.image-policy', '7', [], ''],
  ['systemd.journal-fields', '7', [], ''],
  ['systemd.kill', '5', [], ''],
  ['systemd.link', '5', [], ''],
diff --git a/man/standard-options.xml b/man/standard-options.xml
index d42f3296ca..71c84958ab 100644
--- a/man/standard-options.xml
+++ b/man/standard-options.xml
@@ -86,4 +86,15 @@
       numerical signal numbers and the program will exit immediately.</para>
     </listitem>
   </varlistentry>
+
+  <varlistentry id='image-policy-open'>
+    <term><option>--image-policy=<replaceable>policy</replaceable></option></term>
+
+    <listitem><para>Takes an image policy string as argument, as per
+    <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+    policy is enforced when operating on the disk image specified via <option>--image=</option>, see
+    above. If not specified defaults to the <literal>*</literal> policy, i.e. all recognized file systems
+    in the image are used.</para></listitem>
+  </varlistentry>
+
 </variablelist>
diff --git a/man/systemctl.xml b/man/systemctl.xml
index f930034cb1..1a881d1049 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -2276,6 +2276,8 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err
         switch of the same name.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--runtime</option></term>
 
diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml
index 9fd28e6f45..7176e3c046 100644
--- a/man/systemd-analyze.xml
+++ b/man/systemd-analyze.xml
@@ -162,6 +162,12 @@
       <arg choice="plain">fdstore</arg>
       <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
     </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-analyze</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain">image-policy</arg>
+      <arg choice="plain" rep="repeat"><replaceable>POLICY</replaceable></arg>
+    </cmdsynopsis>
   </refsynopsisdiv>
 
   <refsect1>
@@ -840,6 +846,39 @@ stored sock 0:8   4213190 -      socket:[4213190] ro
       "DEVNO".</para>
     </refsect2>
 
+    <refsect2>
+      <title><command>systemd-analyze image-policy <optional><replaceable>POLICY</replaceable>…</optional></command></title>
+
+      <para>This command analyzes the specified image policy string, as per
+      <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+      policy is normalized and simplified. For each currently defined partition identifier (as per the <ulink
+      url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+      Partitions Specification</ulink> the effect of the image policy string is shown in tabular form.</para>
+
+      <example>
+        <title>Example Output</title>
+
+        <programlisting>$ systemd-analyze image-policy swap=encrypted:usr=read-only-on+verity:root=encrypted
+Analyzing policy: root=encrypted:usr=verity+read-only-on:swap=encrypted
+       Long form: root=encrypted:usr=verity+read-only-on:swap=encrypted:=unused+absent
+
+PARTITION       MODE        READ-ONLY GROWFS
+root            encrypted   -         -
+usr             verity      yes       -
+home            ignore      -         -
+srv             ignore      -         -
+esp             ignore      -         -
+xbootldr        ignore      -         -
+swap            encrypted   -         -
+root-verity     ignore      -         -
+usr-verity      unprotected yes       -
+root-verity-sig ignore      -         -
+usr-verity-sig  ignore      -         -
+tmp             ignore      -         -
+var             ignore      -         -
+default         ignore      -         -</programlisting>
+      </example>
+    </refsect2>
   </refsect1>
 
   <refsect1>
@@ -967,6 +1006,8 @@ stored sock 0:8   4213190 -      socket:[4213190] ro
         operate on files inside the specified image path <replaceable>PATH</replaceable>.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--offline=<replaceable>BOOL</replaceable></option></term>
 
diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index f388cde3c6..2a83477357 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -419,6 +419,7 @@
         <command>cfdisk /dev/loop/by-ref/quux</command>.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
       <xi:include href="standard-options.xml" xpointer="no-pager" />
       <xi:include href="standard-options.xml" xpointer="no-legend" />
       <xi:include href="standard-options.xml" xpointer="json" />
diff --git a/man/systemd-gpt-auto-generator.xml b/man/systemd-gpt-auto-generator.xml
index bd542cb7f7..1730039b62 100644
--- a/man/systemd-gpt-auto-generator.xml
+++ b/man/systemd-gpt-auto-generator.xml
@@ -250,6 +250,16 @@
       </varlistentry>
 
       <varlistentry>
+        <term><varname>systemd.image_policy=</varname></term>
+        <term><varname>rd.systemd.image_policy=</varname></term>
+
+        <listitem><para>Takes an image dissection policy string as argument (as per
+        <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+        and allows enforcing a policy on dissection and use of the automatically discovered GPT partition
+        table entries.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>root=</varname></term>
         <term><varname>rootfstype=</varname></term>
         <term><varname>rootflags=</varname></term>
diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml
index f1695b6ddb..c07a853418 100644
--- a/man/systemd-machine-id-setup.xml
+++ b/man/systemd-machine-id-setup.xml
@@ -95,6 +95,8 @@
         tree.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--commit</option></term>
         <listitem><para>Commit a transient machine ID to disk. This
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index e2c751692f..39a6febb3c 100644
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -311,6 +311,17 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>--image-policy=<replaceable>policy</replaceable></option></term>
+
+        <listitem><para>Takes an image policy string as argument, as per
+        <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+        policy is enforced when operating on the disk image specified via <option>--image=</option>, see
+        above. If not specified defaults to
+        <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent:home=encrypted+unprotected+absent:srv=encrypted+unprotected+absent:esp=unprotected+absent:xbootldr=unprotected+absent:tmp=encrypted+unprotected+absent:var=encrypted+unprotected+absent</literal>,
+        i.e. all recognized file systems in the image are used, but not the swap partition.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>--oci-bundle=</option></term>
 
         <listitem><para>Takes the path to an OCI runtime bundle to invoke, as specified in the <ulink
diff --git a/man/systemd-repart.xml b/man/systemd-repart.xml
index 9033ef76d6..98ca1c431a 100644
--- a/man/systemd-repart.xml
+++ b/man/systemd-repart.xml
@@ -269,6 +269,8 @@
         <option>--root=</option>, see above.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--seed=</option></term>
 
diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml
index 96e40ddf95..2b7a87f510 100644
--- a/man/systemd-sysext.xml
+++ b/man/systemd-sysext.xml
@@ -89,7 +89,12 @@
     carrying large binary images, however are still useful for carrying symlinks to them. The primary place
     for installing system extensions is <filename>/var/lib/extensions/</filename>. Any directories found in
     these search directories are considered directory based extension images; any files with the
-    <filename>.raw</filename> suffix are considered disk image based extension images.</para>
+    <filename>.raw</filename> suffix are considered disk image based extension images. When invoked in the
+    initrd, the additional directory <filename>/.extra/sysext/</filename> is included in the directories that
+    are searched for extension images. Note however, that by default a tighter image policy applies to images
+    found there, though, see below. This directory is populated by
+    <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> with
+    extension images found in the system's EFI System Partition.</para>
 
     <para>During boot OS extension images are activated automatically, if the
     <filename>systemd-sysext.service</filename> is enabled. Note that this service runs only after the
@@ -230,6 +235,19 @@
         not.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><option>--image-policy=<replaceable>policy</replaceable></option></term>
+
+        <listitem><para>Takes an image policy string as argument, as per
+        <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+        policy is enforced when operating on system extension disk images. If not specified defaults to
+        <literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent</literal>,
+        i.e. only the root and <filename>/usr/</filename> file systems in the image are used. When run in the
+        initrd and operating on a system extension image stored in the <filename>/.extra/sysext/</filename>
+        directory a slightly stricter policy is used by default:
+        <literal>root=signed+absent:usr=signed+absent</literal>, see above for details.</para></listitem>
+      </varlistentry>
+
       <xi:include href="standard-options.xml" xpointer="no-pager" />
       <xi:include href="standard-options.xml" xpointer="no-legend" />
       <xi:include href="standard-options.xml" xpointer="json" />
@@ -246,7 +264,8 @@
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry>
     </para>
   </refsect1>
 
diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml
index 77c1635b9d..409281c19f 100644
--- a/man/systemd-sysupdate.xml
+++ b/man/systemd-sysupdate.xml
@@ -229,6 +229,8 @@
         inside the specified disk image.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--instances-max=</option></term>
         <term><option>-m</option></term>
diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml
index aba275024f..f7ee5e79d9 100644
--- a/man/systemd-sysusers.xml
+++ b/man/systemd-sysusers.xml
@@ -80,6 +80,8 @@
         switch of the same name.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--replace=<replaceable>PATH</replaceable></option></term>
         <listitem><para>When this option is given, one or more positional arguments
diff --git a/man/systemd-tmpfiles.xml b/man/systemd-tmpfiles.xml
index 49eda985b4..5612b4803d 100644
--- a/man/systemd-tmpfiles.xml
+++ b/man/systemd-tmpfiles.xml
@@ -202,6 +202,8 @@
         <para>Implies <option>-E</option>.</para></listitem>
       </varlistentry>
 
+      <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+
       <varlistentry>
         <term><option>--replace=<replaceable>PATH</replaceable></option></term>
         <listitem><para>When this option is given, one or more positional arguments
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 17be33c56a..1d99c58601 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -261,6 +261,30 @@
       </varlistentry>
 
       <varlistentry>
+        <term><varname>RootImagePolicy=</varname></term>
+        <term><varname>MountImagePolicy=</varname></term>
+        <term><varname>ExtensionImagePolicy=</varname></term>
+
+        <listitem><para>Takes an image policy string as per
+        <citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+        to use when mounting the disk images (DDI) specified in <varname>RootImage=</varname>,
+        <varname>MountImage=</varname>, <varname>ExtensionImage=</varname>, respectively. If not specified
+        the following policy string is the default for <varname>RootImagePolicy=</varname> and <varname>MountImagePolicy</varname>:</para>
+
+        <programlisting>root=verity+signed+encrypted+unprotected+absent: \
+        usr=verity+signed+encrypted+unprotected+absent: \
+        home=encrypted+unprotected+absent: \
+        srv=encrypted+unprotected+absent: \
+        tmp=encrypted+unprotected+absent: \
+        var=encrypted+unprotected+absent</programlisting>
+
+        <para>The default policy for <varname>ExtensionImagePolicy=</varname> is:</para>
+
+        <programlisting>root=verity+signed+encrypted+unprotected+absent: \
+        usr=verity+signed+encrypted+unprotected+absent</programlisting></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><varname>MountAPIVFS=</varname></term>
 
         <listitem><para>Takes a boolean argument. If on, a private mount namespace for the unit's processes is created
diff --git a/man/systemd.image-policy.xml b/man/systemd.image-policy.xml
new file mode 100644
index 0000000000..4f7b0986b6
--- /dev/null
+++ b/man/systemd.image-policy.xml
@@ -0,0 +1,191 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd.image-policy">
+
+  <refentryinfo>
+    <title>systemd.image-policy</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.image-policy</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.image-policy</refname>
+    <refpurpose>Disk Image Dissection Policy</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>In systemd, whenever a disk image (DDI) implementing the <ulink
+    url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+    Partitions Specification</ulink> 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 (<literal>:</literal>). The individual
+    rules consist of a partition identifier, an equal sign (<literal>=</literal>), 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 (<literal>+</literal>).</para>
+
+    <para>The partition identifiers currently defined are: <option>root</option>, <option>usr</option>,
+    <option>home</option>, <option>srv</option>, <option>esp</option>, <option>xbootldr</option>,
+    <option>swap</option>, <option>root-verity</option>, <option>root-verity-sig</option>,
+    <option>usr-verity</option>, <option>usr-verity-sig</option>, <option>tmp</option>,
+    <option>var</option>. 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 <emphasis>default</emphasis> policy for partitions defined in the Discoverable Parition
+    Specification for which no policy flags are explicitly listed in the policy string.</para>
+
+    <para>The following partition policy flags are defined that dictate the existence/absence, the use, and
+    the protection level of partitions:</para>
+
+    <itemizedlist>
+      <listitem><para><option>unprotected</option> for partitions that shall exist and be used, but shall
+      come without cryptographic protection, lacking both Verity authentication and LUKS
+      encryption.</para></listitem>
+
+      <listitem><para><option>verity</option> 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 <option>verity</option> flag is set – and
+      <option>signed</option> 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
+      <option>signature</option> also implicitly qualifies for <option>verity</option>, and in fact
+      <option>unprotected</option>).</para></listitem>
+
+      <listitem><para><option>signed</option> 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.</para></listitem>
+
+      <listitem><para><option>encrypted</option> for partitions which shall exist and be used and are
+      encrypted with LUKS.</para></listitem>
+
+      <listitem><para><option>unused</option> for partitions that shall exist but shall not be
+      used.</para></listitem>
+
+      <listitem><para><option>absent</option> for partitions that shall not exist on the
+      image.</para></listitem>
+    </itemizedlist>
+
+    <para>By setting a combination of the flags above, alternatives can be declared. For example the
+    combination <literal>unused+absent</literal> means: the partition may exist (in which case it shall not
+    be used) or may be absent. The combination of
+    <literal>unprotected+verity+signed+encrypted+unused+absent</literal> may be specified via the special
+    shortcut <literal>open</literal>, and indicates that the partition may exist or may be absent, but if it
+    exists is used, regardless of the protection level.</para>
+
+    <para>As special rule: if none of the flags above are set for a listed partition identifier, the default
+    policy of <option>open</option> is implied, i.e. setting none of these flags listed above means
+    effectively all flags listed above will be set.</para>
+
+    <para>The following partition policy flags are defined that dictate the state of specific GPT partition
+    flags:</para>
+
+    <itemizedlist>
+      <listitem><para><option>read-only-off</option>, <option>read-only-on</option> to require that the
+      partitions have the read-only partition flag off or on.</para></listitem>
+
+      <listitem><para><option>growfs-off</option>, <option>growfs-on</option> to require that the
+      partitions have the growfs partition flag off or on.</para></listitem>
+    </itemizedlist>
+
+    <para>If both <option>read-only-off</option> and <option>read-only-on</option> 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 <option>growfs-off</option>/<option>growfs-on</option>.</para>
+
+    <para>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 <literal>absent+unused</literal>, 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.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Special Policies</title>
+
+    <para>The special image policy string <literal>*</literal> is short for "use everything", i.e. is
+    equivalent to:</para>
+
+    <programlisting>=verity+signed+encrypted+unprotected+unused+absent</programlisting>
+
+    <para>The special image policy string <literal>-</literal> is short for "use nothing", i.e. is equivalent
+    to:</para>
+
+    <programlisting>=unused+absent</programlisting>
+
+    <para>The special image policy string <literal>~</literal> is short for "everything must be absent",
+    i.e. is equivalent to:</para>
+
+    <programlisting>=absent</programlisting>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Use</title>
+
+    <para>Most systemd components that support operating with disk images support a
+    <option>--image-policy=</option> command line option to specify the image policy to use, and default to
+    relatively open policies by default (typically the <literal>*</literal> policy, as described above),
+    under the assumption that trust in disk images is established before the images are passed to the program
+    in question.</para>
+
+    <para>For the host image itself
+    <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    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
+    <option>systemd.image-policy=</option>.</para>
+
+    <para>Note that image policies do not dictate how the components will mount and use disk images — they
+    only dictate which parts to avoid and which protection level and arrangement to require while
+    mounting/using them. For example,
+    <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry> only
+    cares for the <filename>/usr/</filename> and <filename>/opt/</filename> trees inside a disk image, and
+    thus ignores any <filename>/home/</filename> 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,
+    <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> is not
+    going to make use of any discovered swap device, regardless if the policy would allow that or not.</para>
+
+    <para>Use the <command>image-policy</command> command of the
+    <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry> tool
+    to analyze image policy strings, and determine what a specific policy string means for a specific
+    partition.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>The following image policy string dictates one read-only Verity-enabled <filename>/usr/</filename>
+    partition must exist, plus encrypted root and swap partitions. All other partitions are ignored:</para>
+
+    <programlisting>usr=verity+read-only-on:root=encrypted:swap=encrypted</programlisting>
+
+    <para>The following image policy string dictates an encrypted, writable root file system, and optional
+    <filename>/srv/</filename> file system that must be encrypted if it exists and no swap partition may
+    exist:</para>
+
+    <programlisting>root=encrypted+read-only-off:srv=encrypted+absent:swap=absent</programlisting>
+
+    <para>The following image policy string dictates a single root partition that may be encrypted, but
+    doesn't have to be, and ignores swap partitions, and uses all other partitions if they are available, possibly with encryption.</para>
+
+    <programlisting>root=unprotected+encrypted:swap=absent+unused:=unprotected+encrypted+absent</programlisting>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>