shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

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

Browse Source
This commit is contained in:
Lennart Poettering 2022-12-01 22:41:47 +01:00
parent f1f42aeaf1
commit 9ea811914f
19 changed files with 341 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
man/bootctl.xml
View File

@ -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

2
man/coredumpctl.xml
View File

@ -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>

2
man/journalctl.xml
View File

@ -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>

14
man/kernel-command-line.xml
View File

@ -396,12 +396,22 @@
<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>

1
man/rules/meson.build
View File

@ -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', [], ''],

11
man/standard-options.xml
View File

@ -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>

2
man/systemctl.xml
View File

@ -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>

41
man/systemd-analyze.xml
View File

@ -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>

1
man/systemd-dissect.xml
View File

@ -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" />

10
man/systemd-gpt-auto-generator.xml
View File

@ -249,6 +249,16 @@
</para></listitem>
</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>

2
man/systemd-machine-id-setup.xml
View File

@ -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

11
man/systemd-nspawn.xml
View File

@ -310,6 +310,17 @@
together with <option>--directory=</option>, <option>--template=</option>.</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 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>

2
man/systemd-repart.xml
View File

@ -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>

23
man/systemd-sysext.xml
View File

@ -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>

2
man/systemd-sysupdate.xml
View File

@ -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>

2
man/systemd-sysusers.xml
View File

@ -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

2
man/systemd-tmpfiles.xml
View File

@ -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

24
man/systemd.exec.xml
View File

@ -260,6 +260,30 @@
<xi:include href="system-only.xml" xpointer="singular"/></listitem>
</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>

191
man/systemd.image-policy.xml Normal file
View File

@ -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>