From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 20 Mar 2025 16:15:41 +0000 (+0100)
Subject: man: document image filters
X-Git-Tag: v258-rc1~923^2~5
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a05b34433002e0db38e8f5b19594dab7165ace0e;p=thirdparty%2Fsystemd.git

man: document image filters
---

diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml
index 3a4619edeef..17740fb4e45 100644
--- a/man/kernel-command-line.xml
+++ b/man/kernel-command-line.xml
@@ -481,6 +481,18 @@
         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>systemd.image_filter=</varname></term>
+
+        <listitem><para>When GPT-based partition auto-discovery is used, configures the image dissection
+        filter string to apply, as per
+        <citerefentry><refentrytitle>systemd.image-filter</refentrytitle><manvolnum>7</manvolnum></citerefentry>. For
+        details see
+        <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>systemd.default_timeout_start_sec=</varname></term>
 
diff --git a/man/rules/meson.build b/man/rules/meson.build
index c33d9fee0e4..0b930d3beb4 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1188,6 +1188,7 @@ manpages = [
  ['systemd.environment-generator', '7', [], 'ENABLE_ENVIRONMENT_D'],
  ['systemd.exec', '5', [], ''],
  ['systemd.generator', '7', [], ''],
+ ['systemd.image-filter', '7', [], ''],
  ['systemd.image-policy', '7', [], ''],
  ['systemd.journal-fields', '7', [], ''],
  ['systemd.kill', '5', [], ''],
diff --git a/man/standard-options.xml b/man/standard-options.xml
index 1e958594ad9..d07ea4a09a4 100644
--- a/man/standard-options.xml
+++ b/man/standard-options.xml
@@ -114,6 +114,14 @@
     in the image are used.</para></listitem>
   </varlistentry>
 
+  <varlistentry id='image-filter'>
+    <term><option>--image-filter=<replaceable>filter</replaceable></option></term> <listitem><para>Takes an
+    image filter string as argument, as per
+    <citerefentry><refentrytitle>systemd.image-filter</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
+    filter is taken into consideration when operating on the disk image specified via
+    <option>--image=</option>, see above. If not specified no filtering is applied.</para></listitem>
+  </varlistentry>
+
   <varlistentry id='esp-path'>
     <term><option>--esp-path=</option></term>
 
diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index 4b51fb887cd..3094a1e6d9b 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -582,6 +582,7 @@
       </varlistentry>
 
       <xi:include href="standard-options.xml" xpointer="image-policy-open" />
+      <xi:include href="standard-options.xml" xpointer="image-filter" />
       <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 af450f9fbe6..11b08f0b8de 100644
--- a/man/systemd-gpt-auto-generator.xml
+++ b/man/systemd-gpt-auto-generator.xml
@@ -320,6 +320,17 @@
         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>systemd.image_filter=</varname></term>
+
+        <listitem><para>Takes an image dissection filter string as argument (as per
+        <citerefentry><refentrytitle>systemd.image-filter</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
+        and allows enforcing a set of globbing patterns on the partition matching of the automatically
+        discovered GPT partition table entries.</para>
+
+        <xi:include href="version-info.xml" xpointer="v258"/></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><varname>root=</varname></term>
         <term><varname>rootfstype=</varname></term>
diff --git a/man/systemd.image-filter.xml b/man/systemd.image-filter.xml
new file mode 100644
index 00000000000..f5a8a811dac
--- /dev/null
+++ b/man/systemd.image-filter.xml
@@ -0,0 +1,80 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd.image-filter">
+
+  <refentryinfo>
+    <title>systemd.image-filter</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.image-filter</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.image-filter</refname>
+    <refpurpose>Disk Image Dissection Filter</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 filter may be specified controlling which partitions to
+    consider for mounting. Such a disk image dissection filter is a string that contains per-partition-type
+    patterns, separated by colons (<literal>:</literal>). The individual rules consist of a partition
+    identifier, an equal sign (<literal>=</literal>), and a shell globbing pattern applied to the GPT label
+    string of the partition. See <citerefentry
+    project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details on shell globbing.</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.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Use</title>
+
+    <para>Various systemd components that support operating with disk images support a
+    <option>--image-filter=</option> command line option to specify the image filter to use. If no filter is
+    specified all partitions in partition table are considered and no per-label filtering is applied (except
+    that partitions with the <literal>_empty</literal> label are always ignored).</para>
+
+    <para>For the host root file system 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 filter via the kernel command line option
+    <option>systemd.image_filter=</option>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>The following image filter string dictates that for the root file system partition only partitions
+    shall be considered whose label begins with <literal>ParticleOS-</literal>. For the
+    <filename>/usr/</filename> partition the precise label <literal>ParticleOS_47110815</literal> is
+    required.</para>
+
+    <programlisting>root=ParticleOS-*:usr=ParticleOS_47110815</programlisting>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+
+</refentry>
diff --git a/man/systemd.image-policy.xml b/man/systemd.image-policy.xml
index 36a8395bf0c..d351ffeea5b 100644
--- a/man/systemd.image-policy.xml
+++ b/man/systemd.image-policy.xml
@@ -185,6 +185,7 @@
       <member><citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.filter</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
     </simplelist></para>
   </refsect1>