man: add sysupdate documentation

3 files changed, 1180 insertions, 0 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 2e334ff331..aa969344ab 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -987,6 +987,13 @@ manpages = [
   '5',
   ['system.conf.d', 'systemd-user.conf', 'user.conf.d'],
   ''],
+ ['systemd-sysupdate',
+  '8',
+  ['systemd-sysupdate-reboot.service',
+   'systemd-sysupdate-reboot.timer',
+   'systemd-sysupdate.service',
+   'systemd-sysupdate.timer'],
+  'ENABLE_SYSUPDATE'],
  ['systemd-sysusers', '8', ['systemd-sysusers.service'], ''],
  ['systemd-sysv-generator', '8', [], 'HAVE_SYSV_COMPAT'],
  ['systemd-time-wait-sync.service',
@@ -1058,6 +1065,7 @@ manpages = [
  ['systemd.time', '7', [], ''],
  ['systemd.timer', '5', [], ''],
  ['systemd.unit', '5', [], ''],
+ ['sysupdate.d', '5', [], 'ENABLE_SYSUPDATE'],
  ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'],
  ['telinit', '8', [], 'HAVE_SYSV_COMPAT'],
  ['timedatectl', '1', [], 'ENABLE_TIMEDATECTL'],
diff --git a/man/systemd-sysupdate.xml b/man/systemd-sysupdate.xml
new file mode 100644
index 0000000000..81f57e8b52
--- /dev/null
+++ b/man/systemd-sysupdate.xml
@@ -0,0 +1,287 @@
+<?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-sysupdate" conditional='ENABLE_SYSUPDATE'
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-sysupdate</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-sysupdate</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-sysupdate</refname>
+    <refname>systemd-sysupdate.service</refname>
+    <refname>systemd-sysupdate.timer</refname>
+    <refname>systemd-sysupdate-reboot.service</refname>
+    <refname>systemd-sysupdate-reboot.timer</refname>
+    <refpurpose>Automatically Update OS or Other Resources</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>systemd-sysupdate</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+    </cmdsynopsis>
+
+    <para><filename>systemd-sysupdate.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><command>systemd-sysupdate</command> atomically updates the host OS, container images, portable
+    service images or other sources, based on the transfer configuration files described in
+    <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+    <para>This tool implements file, directory, or partition based update schemes, supporting multiple
+    parallel installed versions of specific resources in an A/B (or even: A/B/C, A/B/C/D/, …) style. A/B
+    updating means that when one version of a resource is currently being used, the next version can be
+    downloaded, unpacked, and prepared in an entirely separate location, indepdently of the first, and — once
+    complete — be activated, swapping the roles so that it becomes the used one and the previously used one
+    becomes the the one that is replaced by the next update, and so on. The resources to update are defined
+    in transfer files, one for each resource to be updated. For example, resources that may be updated with
+    this tool could be: a root file system partition, a matching Verity partition plus one kernel image. The
+    combination of the three would be considered a complete OS update.</para>
+
+    <para>The tool updates partitions, files or directory trees always in whole, and operates with at least
+    two versions of each of these resources: the <emphasis>current</emphasis> version, plus the
+    <emphasis>next</emphasis> version: the one that is being updated to, and which is initially incomplete as
+    the downloaded data is written to it; plus optionally more versions. Once the download of a newer version
+    is complete it becomes the current version, releasing the version previously considered current for
+    deletion/replacement/updating.</para>
+
+    <para>When installing new versions the tool will directly download, decompress, unpack and write the new
+    version into the destination. This is done in a robust fashion so that an incomplete download can be
+    recognized on next invocation, and flushed out before a new attempt is initiated.</para>
+
+    <para>Note that when writing updates to a partition, the partition has to exist already, as
+    <command>systemd-sysupdate</command> will not automatically create new partitions. Use a tool such as
+    <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> to
+    automatically create additional partitions to be used with <command>systemd-sysupdate</command> on
+    boot.</para>
+
+    <para>The tool can both be used on the running OS, to update the OS in "online" state from within itself,
+    and on "offline" disk images, to update them from the outside based on transfer files
+    embedded in the disk images. For the latter, see <option>--image=</option> below. The latter is
+    particularly interesting to update container images or portable service images.</para>
+
+    <para>The <filename>systemd-sysupdate.service</filename> system service will automatically update the
+    host OS based on the installed transfer files. It is triggered in regular intervals via
+    <filename>systemd-sysupdate.timer</filename>. The <filename>systemd-sysupdate-reboot.service</filename>
+    will automatically reboot the system after a new version is installed. It is triggered via
+    <filename>systemd-sysupdate-reboot.timer</filename>. The two services are separate from each other as it
+    is typically advisable to download updates regularly while the system is up, but delay reboots until the
+    appropriate time (i.e. typically at night). The two sets of service/timer units may be enabled
+    separately.</para>
+
+    <para>For details about transfer files and examples see
+    <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Command</title>
+
+    <para>The following commands are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>list</option> <optional><replaceable>VERSION</replaceable></optional></term>
+
+        <listitem><para>If invoked without an argument, enumerates downloadable and installed versions, and
+        shows a summarizing table with the discovered versions and their properties, including whether
+        there's a newer candidate version to update to. If a version argument is specified, shows details
+        about the specific version, including the individual files that need to be transferred to acquire the
+        version.</para>
+
+        <para>If no command is explicitly specified this command is implied.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>check-new</option></term>
+
+        <listitem><para>Checks if there's a new version available. This internally enumerates downloadable and
+        installed versions and returns exit status 0 if there's a new version to update to, non-zero
+        otherwise. If there is a new version to update to, its version identifier is written to standard
+        output.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>update</option> <optional><replaceable>VERSION</replaceable></optional></term>
+
+        <listitem><para>Installs (updates to) the specified version, or if none is specified to the newest
+        version available. If the version is already installed or no newer version available, no operation is
+        executed.</para>
+
+        <para>If a new version to install/update to is found, old installed versions are deleted until at
+        least one new version can be installed, as configured via <varname>InstanceMax=</varname> in
+        <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>, or
+        via the available partition slots of the right type. This implicit operation can also be invoked
+        explicitly via the <command>vacuum</command> command described below.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>vacuum</option></term>
+
+        <listitem><para>Deletes old installed versions until the limits configured via
+        <varname>InstanceMax=</varname> in
+        <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> are
+        met again. Normally, it should not be necessary to invoke this command explicitly, since it is
+        implicitly invoked whenever a new update is initiated.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>pending</option></term>
+
+        <listitem><para>Checks whether a newer version of the OS is installed than the one currently
+        running. Returns zero if so, non-zero otherwise. This compares the newest installed version's
+        identifier with the OS image version as reported by the <varname>IMAGE_VERSION=</varname> field in
+        <filename>/etc/os-release</filename>. If the former is newer than the latter, an update was
+        apparently completed but not activated (i.e. rebooted into) yet.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>reboot</option></term>
+
+        <listitem><para>Similar to the <option>pending</option> command but immediately reboots in case a
+        newer version of the OS has been installed than the one currently running. This operation can be done
+        implicitly together with the <command>update</command> command, after a completed update via the
+        <option>--reboot</option> switch, see below. This command will execute no operation (and return
+        success) if no update has been installed, and thus the system was not rebooted.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>components</option></term>
+
+        <listitem><para>Lists components that can be updated. This enumerates the
+        <filename>/etc/sysupdate.*.d/</filename>, <filename>/run/sysupdate.*.d/</filename> and
+        <filename>/usr/lib/sysupdate.*.d/</filename> directories that contain transfer files. This command is
+        useful to list possible parameters for <option>--component=</option> (see below).</para></listitem>
+      </varlistentry>
+
+      <xi:include href="standard-options.xml" xpointer="help" />
+      <xi:include href="standard-options.xml" xpointer="version" />
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist>
+
+      <varlistentry>
+        <term><option>--component=</option></term>
+        <term><option>-C</option></term>
+
+        <listitem><para>Selects the component to update. Takes a component name as argument. This has the
+        effect of slightly altering the search logic for transfer files. If this switch is not used, the
+        transfer files are loaded from <filename>/etc/sysupdate.d/*.conf</filename>,
+        <filename>/run/sysupdate.d/*.conf</filename> and <filename>/usr/lib/sysupdate.d/*.conf</filename>. If
+        this switch is used, the specified component name is used to alter the directories to look in to be
+        <filename>/etc/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>,
+        <filename>/run/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename> and
+        <filename>/usr/lib/sysupdate.<replaceable>component</replaceable>.d/*.conf</filename>, each time with
+        the <filename><replaceable>component</replaceable></filename> string replaced with the specified
+        component name.</para>
+
+        <para>Use the <command>components</command> command to list available components to update. This enumerates
+        the directories matching this naming rule.</para>
+
+        <para>Components may be used to define a separate set of transfer files for different components of
+        the OS that shall be updated separately. Do not use this concept for resources that shall always be
+        updated together in a synchronous fashion. Simply define multiple transfer files within the same
+        <filename>sysupdate.d/</filename> directory for these cases.</para>
+
+        <para>This option may not be combined with <option>--definitions=</option>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--definitions=</option></term>
+
+        <listitem><para>A path to a directory. If specified, the transfer <filename>*.conf</filename> files
+        are read from this directory instead of <filename>/usr/lib/sysupdate.d/*.conf</filename>,
+        <filename>/etc/sysupdate.d/*.conf</filename>, and <filename>/run/sysupdate.d/*.conf</filename>.</para>
+
+        <para>This option may not be combined with <option>--component=</option>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--root=</option></term>
+
+        <listitem><para>Takes a path to a directory to use as root file system when searching for
+        <filename>sysupdate.d/*.conf</filename> files.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--image=</option></term>
+
+        <listitem><para>Takes a path to a disk image file or device to mount and use in a similar fashion to
+        <option>--root=</option>, see above. If this is used and partition resources are updated this is done
+        inside the specified disk image.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--instances-max=</option></term>
+        <term><option>-m</option></term>
+
+        <listitem><para>Takes a decimal integer greater than or equal to 2. Controls how many versions to
+        keep at any time. This option may also be configured inside the transfer files, via the
+        <varname>InstancesMax=</varname> setting, see
+        <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
+        details.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--sync=</option></term>
+
+        <listitem><para>Takes a boolean argument, defaults to yes. This may be used to specify whether the
+        newly updated resource versions shall be synchronized to disk when appropriate (i.e. after the
+        download is complete, before it is finalized, and again after finalization). This should not be
+        turned off, except to improve runtime performance in testing environments.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--verify=</option></term>
+
+        <listitem><para>Takes a boolean argument, defaults to yes. Controls whether to cryptographically
+        verify downloads. Do not turn this off, except in testing environments.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--reboot</option></term>
+
+        <listitem><para>When used in combination with the <command>update</command> command and a new version is
+        installed, automatically reboots the system immediately afterwards.</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" />
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Exit status</title>
+
+    <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>sysupdate.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>
diff --git a/man/sysupdate.d.xml b/man/sysupdate.d.xml
new file mode 100644
index 0000000000..03d27b9fbc
--- /dev/null
+++ b/man/sysupdate.d.xml
@@ -0,0 +1,885 @@
+<?xml version='1.0'?>
+<!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="sysupdate.d" conditional='ENABLE_SYSUPDATE'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>sysupdate.d</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sysupdate.d</refentrytitle>
+    <manvolnum>5</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sysupdate.d</refname>
+    <refpurpose>Transfer Definition Files for Automatic Updates</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><literallayout><filename>/etc/sysupdate.d/*.conf</filename>
+<filename>/run/sysupdate.d/*.conf</filename>
+<filename>/usr/lib/sysupdate.d/*.conf</filename>
+    </literallayout></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><filename>sysupdate.d/*.conf</filename> files describe how specific resources on the local system
+    shall be updated from a remote source. Each such file defines one such transfer: typically a remote
+    HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a
+    simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system
+    extension images — but in fact may be used to update any kind of file from a remote source.</para>
+
+    <para>The
+    <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    command reads these files and uses them to determine which local resources should be updated, and then
+    executes the update.</para>
+
+    <para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent
+    versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof,
+    e.g. A/B/C, A/B/C/D, …).</para>
+
+    <para>Each <filename>*.conf</filename> file defines one transfer, i.e. describes one resource to
+    update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and
+    are bound together by a common version identifier in order to update multiple resources at once on each
+    update operation, for example to update a kernel, a root file system and a Verity partition in a single,
+    combined, synchronized operation, so that only a combined update of all three together constitutes a
+    complete update.</para>
+
+    <para>Each <filename>*.conf</filename> file contains three sections: [Transfer], [Source] and [Target].</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Basic Mode of Operation</title>
+
+    <para>Disk-image based OS updates typically consist of multiple different resources that need to be
+    updated together, for example a secure OS update might consist of a root file system image to drop into a
+    partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the
+    combination of the two partitions. The first two resources are files that are downloaded and placed in a
+    disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file
+    system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS"
+    to a hypothetical version 47 the following operations should take place:</para>
+
+    <orderedlist>
+      <listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be
+      downloaded, decompressed and written to a previously unused partition with GPT partition type UUID
+      4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink
+      url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
+      Specification</ulink>.</para></listitem>
+
+      <listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal>
+      should be downloaded, decompressed and written to a previously empty partition with GPT partition type
+      UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e the partition type for Verity integrity information
+      for x86-64 root file systems).</para></listitem>
+
+      <listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi.xz</literal> (a
+      unified kernel, as per <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader
+      Specification</ulink> Type #2) should be downloaded, decompressed and written to the ESP file system,
+      i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP.</para></listitem>
+    </orderedlist>
+
+    <para>The version-independent generalization of this would be (using the special marker
+    <literal>@v</literal> as wildcard for the version identifier):</para>
+
+    <orderedlist>
+      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.root.xz</literal>
+      → a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to
+      be set to <literal>foobarOS_@v</literal>.</para></listitem>
+
+      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.verity.xz</literal>
+      → a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be
+      set to <literal>foobarOS_@v_verity</literal>.</para></listitem>
+
+      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.efi.xz</literal>
+      → a local file <filename>/efi/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem>
+    </orderedlist>
+
+    <para>An update can only complete if the relevant URLs provide their resources for the same version,
+    i.e. for the same value of <literal>@v</literal>.</para>
+
+    <para>The above may be translated into three <filename>*.conf</filename> files in
+    <filename>sysupdate.d/</filename>, one for each resource to transfer. The <filename>*.conf</filename>
+    files configure the type of download, and what place to write the download to (i.e. whether to a
+    partition or a file in the file system). Most importantly these files contain the URL, partition name and
+    filename patterns shown above that describe how these resources are called on the source and how they
+    shall be called on the target.</para>
+
+    <para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is
+    necessary to list suitable files:</para>
+
+    <itemizedlist>
+      <listitem><para>For partitions: the surrounding GPT partition table contains a list of defined
+      partitions, including a partition type UUID and a partition label (in this scheme the partition label
+      plays a role for the partition similar to the filename for a regular file)</para></listitem>
+
+      <listitem><para>For regular files: the directory listing of the directory the files are contained in
+      provides a list of existing files in a straightforward way.</para></listitem>
+
+      <listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file
+      <filename>SHA256SUMS</filename>, following the format defined by <citerefentry
+      project='man-pages'><refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      lists file names and their SHA256 hashes.</para></listitem>
+    </itemizedlist>
+
+    <para>Transfers are done in the alphabetical order of the <filename>.conf</filename> file names they are
+    defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once
+    this is completed for all defined transfers, in a second step the files/directories/partitions are
+    renamed to their final names as defined by the target <varname>MatchPattern=</varname>, again in the
+    order the <filename>.conf</filename> transfer file names dictate. This step is not atomic, however it is
+    guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when
+    updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea
+    to order the resources via the transfer configuration file names so that the entry point is written
+    last, ensuring that any abnormal termination does not leave an entry point around whose backing is not
+    established yet. In the example above it would hence make sense to establish the EFI kernel image last
+    and thus give its transfer configuration file the alphabetically last name.</para>
+
+    <para>See below for an extended, more specific example based on the above.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Resource Types</title>
+
+    <para>Each transfer file defines one source resource to transfer to one target resource. The following
+    resource types are supported:</para>
+
+    <orderedlist>
+
+      <listitem><para>Resources of type <literal>url-file</literal> encapsulate a file on a web server,
+      referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed
+      and then written to the target file or partition. This resource type is only available for sources, not
+      for targets. The list of available versions of resources of this type is encoded in
+      <filename>SHA256SUMS</filename> manifest files, accompanied by
+      <filename>SHA256SUMS.gpg</filename> detached signatures.</para></listitem>
+
+      <listitem><para>The <literal>url-tar</literal> resource type is similar, but the file must be a
+      <filename>.tar</filename> archive. When an update takes place, the file is decompressed and unpacked
+      into a directory or btrfs subvolume. This resource type is only available for sources, not for
+      targets. Just like <literal>url-file</literal>, <literal>url-tar</literal> version enumeration makes
+      use of <filename>SHA256SUMS</filename> files, authenticated via
+      <filename>SHA256SUMS.gpg</filename>.</para></listitem>
+
+      <listitem><para>The <literal>regular-file</literal> resource type encapsulates a local regular file on
+      disk. During updates the file is uncompressed and written to the target file or partition. This
+      resource type is available both as source and as target. When updating no integrity or authentication
+      verification is done for resources of this type.</para></listitem>
+
+      <listitem><para>The <literal>partition</literal> resource type is similar to
+      <literal>regular-file</literal>, and encapsulates a GPT partition on disk. When updating, the partition
+      must exist already, and have the correct GPT partition type. A partition whose GPT partition label is
+      set to <literal>_empty</literal> is considered empty, and a candidate to place a newly downloaded
+      resource in. The GPT partition label is used to store version information, once a partition is
+      updated. This resource type is only available for target resources.</para></listitem>
+
+      <listitem><para>The <literal>tar</literal> resource type encapsulates local <filename>.tar</filename>
+      archive files. When an update takes place, the files are uncompressed and unpacked into a target
+      directory or btrfs subvolume. Behaviour of <literal>tar</literal> and <literal>url-tar</literal> is
+      generally similar, but the latter downloads from remote sources, and does integrity and authentication
+      checks while the former does not. The <literal>tar</literal> resource type is only available for source
+      resources.</para></listitem>
+
+      <listitem><para>The <literal>directory</literal> resource type encapsulates local directory trees. This
+      type is available both for source and target resources. If an update takes place on a source resource
+      of this type, a recursive copy of the directory is done.</para></listitem>
+
+      <listitem><para>The <literal>subvolume</literal> resource type is identical to
+      <literal>directory</literal>, except when used as the target, in which case the file tree is placed in
+      a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is
+      btrfs).</para></listitem>
+    </orderedlist>
+
+    <para>As already indicated, only a subset of source and target resource type combinations are
+    supported:</para>
+
+    <table>
+      <title>Resource Types</title>
+
+      <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+        <colspec colname="name" />
+        <colspec colname="explanation" />
+
+        <thead>
+          <row>
+            <entry>Identifier</entry>
+            <entry>Description</entry>
+            <entry>Usable as Source</entry>
+            <entry>When Used as Source: Compatible Targets</entry>
+            <entry>When Used as Source: Integrity + Authentication</entry>
+            <entry>When Used as Source: Decompression</entry>
+            <entry>Usable as Target</entry>
+            <entry>When Used as Target: Compatible Sources</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><constant>url-file</constant></entry>
+            <entry>HTTP/HTTPS files</entry>
+            <entry>yes</entry>
+            <entry><constant>regular-file</constant>, <constant>partition</constant></entry>
+            <entry>yes</entry>
+            <entry>yes</entry>
+            <entry>no</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry><constant>url-tar</constant></entry>
+            <entry>HTTP/HTTPS <filename>.tar</filename> archives</entry>
+            <entry>yes</entry>
+            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
+            <entry>yes</entry>
+            <entry>yes</entry>
+            <entry>no</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry><constant>regular-file</constant></entry>
+            <entry>Local files</entry>
+            <entry>yes</entry>
+            <entry><constant>regular-file</constant>, <constant>partition</constant></entry>
+            <entry>no</entry>
+            <entry>yes</entry>
+            <entry>yes</entry>
+            <entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
+          </row>
+
+          <row>
+            <entry><constant>partition</constant></entry>
+            <entry>Local GPT partitions</entry>
+            <entry>no</entry>
+            <entry>-</entry>
+            <entry>-</entry>
+            <entry>-</entry>
+            <entry>yes</entry>
+            <entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
+          </row>
+
+          <row>
+            <entry><constant>tar</constant></entry>
+            <entry>Local <filename>.tar</filename> archives</entry>
+            <entry>yes</entry>
+            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
+            <entry>no</entry>
+            <entry>yes</entry>
+            <entry>no</entry>
+            <entry>-</entry>
+          </row>
+
+          <row>
+            <entry><constant>directory</constant></entry>
+            <entry>Local directories</entry>
+            <entry>yes</entry>
+            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
+            <entry>no</entry>
+            <entry>no</entry>
+            <entry>yes</entry>
+            <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
+          </row>
+
+          <row>
+            <entry><constant>subvolume</constant></entry>
+            <entry>Local btrfs subvolumes</entry>
+            <entry>yes</entry>
+            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
+            <entry>no</entry>
+            <entry>no</entry>
+            <entry>yes</entry>
+            <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
+          </row>
+
+        </tbody>
+      </tgroup>
+    </table>
+  </refsect1>
+
+  <refsect1>
+    <title>Match Patterns</title>
+
+    <para>Both the source and target resources typically exist in multiple versions concurrently. An update
+    operation is done whenever the newest of the source versions is newer than the newest of the target
+    versions. To determine the newest version of the resources a directory listing, partition listing or
+    manifest listing is used, a subset of qualifying entries selected from that, and the version identifier
+    extracted from the file names or partition labels of these selected entries. Subset selection and
+    extraction of the version identifier (plus potentially other metadata) is done via match patterns,
+    configured in <varname>MatchPattern=</varname> in the [Source] and [Target] sections. These patterns are
+    strings that describe how files or partitions are named, with named wildcards for specific fields such as
+    the version identifier. The following wildcards are defined:</para>
+
+    <table>
+      <title>Match Pattern Wildcards</title>
+
+      <tgroup cols='2' align='left' colsep='1' rowsep='1'>
+        <colspec colname="name" />
+        <colspec colname="explanation" />
+
+        <thead>
+          <row>
+            <entry>Wildcard</entry>
+            <entry>Description</entry>
+            <entry>Format</entry>
+            <entry>Notes</entry>
+          </row>
+        </thead>
+
+        <tbody>
+          <row>
+            <entry><literal>@v</literal></entry>
+            <entry>Version identifier</entry>
+            <entry>Valid version string</entry>
+            <entry>Mandatory</entry>
+          </row>
+
+          <row>
+            <entry><literal>@u</literal></entry>
+            <entry>GPT partition UUID</entry>
+            <entry>Valid 128-Bit UUID string</entry>
+            <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@f</literal></entry>
+            <entry>GPT partition flags</entry>
+            <entry>Formatted hexadecimal integer</entry>
+            <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@a</literal></entry>
+            <entry>GPT partition flag NoAuto</entry>
+            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
+            <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@g</literal></entry>
+            <entry>GPT partition flag GrowFileSystem</entry>
+            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
+            <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@r</literal></entry>
+            <entry>Read-only flag</entry>
+            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
+            <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below.</entry>
+          </row>
+
+          <row>
+            <entry><literal>@t</literal></entry>
+            <entry>File modification time</entry>
+            <entry>Formatted decimal integer, µs since UNIX epoch Jan 1st 1970</entry>
+            <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@m</literal></entry>
+            <entry>File access mode</entry>
+            <entry>Formatted octal integer, in UNIX fashion</entry>
+            <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
+          </row>
+
+          <row>
+            <entry><literal>@s</literal></entry>
+            <entry>File size after decompression</entry>
+            <entry>Formatted decimal integer</entry>
+            <entry>Useful for measuring progress and to improve partition allocation logic</entry>
+          </row>
+
+          <row>
+            <entry><literal>@d</literal></entry>
+            <entry>Tries done</entry>
+            <entry>Formatted decimal integer</entry>
+            <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
+          </row>
+
+          <row>
+            <entry><literal>@l</literal></entry>
+            <entry>Tries left</entry>
+            <entry>Formatted decimal integer</entry>
+            <entry>Useful when operating with kernel images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
+          </row>
+
+          <row>
+            <entry><literal>@h</literal></entry>
+            <entry>SHA256 hash of compressed file</entry>
+            <entry>64 hexadecimal characters</entry>
+            <entry>The SHA256 hash of the compressed file; not useful for <constant>url-file</constant> or <constant>url-tar</constant> where the SHA256 hash is already included in the manifest file anyway.</entry>
+          </row>
+        </tbody>
+      </tgroup>
+    </table>
+
+    <para>Of these wildcards only <literal>@v</literal> must be present in a valid pattern, all other
+    wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard
+    matching a file system source image could be <literal>MatchPattern=foobar_@v.raw.xz</literal>, i.e. any file
+    whose name begins with <literal>foobar_</literal>, followed by a version ID and suffixed by
+    <literal>.raw.xz</literal>.</para>
+
+    <para>Do not confuse the <literal>@</literal> pattern matching wildcard prefix with the
+    <literal>%</literal> specifier expansion prefix. The former encapsulate a variable part of a match
+    pattern string, the latter are simple shortcuts that are expanded while the drop-in files are
+    parsed. For details about specifiers, see below.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>[Transfer] Section Options</title>
+
+    <para>This section defines general properties of this transfer.</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>MinVersion=</varname></term>
+
+        <listitem><para>Specifies the minimum version to require for this transfer to take place. If the
+        source or target patterns in this transfer definition match files older than this version they will
+        be considered obsolete, and never be considered for the update operation.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ProtectVersion=</varname></term>
+
+        <listitem><para>Takes one or more version strings to mark as "protected". Protected versions are
+        never removed while making room for new, updated versions. This is useful to ensure that the
+        currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten
+        during updates, in order to avoid runtime file system corruptions.</para>
+
+        <para>Like many of the settings in these configuration files this setting supports specifier
+        expansion. It's particularly useful to set this setting to one of the <literal>%A</literal>,
+        <literal>%B</literal> or <literal>%w</literal> specifiers to automatically refer to the current OS
+        version of the running system. See below for details on supported specifiers.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Verify=</varname></term>
+
+        <listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify
+        downloaded resources (specifically: validate the GPG signatures for downloaded
+        <filename>SHA256SUMS</filename> manifest files, via their detached signature files
+        <filename>SHA256SUMS.gpg</filename> in combination with the system keyring
+        <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
+        <filename>/etc/systemd/import-pubring.gpg</filename>).</para>
+
+        <para>This option is essential to provide integrity guarantees for downloaded resources and thus
+        should be left enabled, outside of test environments.</para>
+
+        <para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes
+        listed in the manifest. This option only controls whether the signatures of these manifests are
+        verified.</para>
+
+        <para>This option only has an effect if the source resource type is selected as
+        <constant>url-file</constant> or <constant>url-tar</constant>, as integrity and authentication
+        checking is only available for transfers from remote sources.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>[Source] Section Options</title>
+
+    <para>This section defines properties of the transfer source:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>Type=</varname></term>
+
+        <listitem><para>Specifies the resource type of the source for the transfer. Takes one of
+        <constant>url-file</constant>, <constant>url-tar</constant>, <constant>tar</constant>,
+        <constant>regular-file</constant>, <constant>directory</constant> or
+        <constant>subvolume</constant>. For details about the resource types, see above. This option is
+        mandatory.</para>
+
+        <para>Note that only some combinations of source and target resource types are supported, see
+        above.</para></listitem>
+      </varlistentry>
+    </variablelist>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>Path=</varname></term>
+
+        <listitem><para>Specifies where to find source versions of this resource.</para>
+
+        <para>If the source type is selected as <constant>url-file</constant> or
+        <constant>url-tar</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with
+        <filename>/SHA256SUMS</filename> to acquire the manifest file, with
+        <filename>/SHA256SUMS.gpg</filename> to acquire the detached signature file for it, and with the file
+        names listed in the manifest file in case an update is executed and a resource shall be
+        downloaded.</para>
+
+        <para>For all other source resource types this must be a local path in the file system, referring to
+        a local directory to find the versions of this resource in.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MatchPattern=</varname></term>
+
+        <listitem><para>Specifies one or more file name match patterns that select the subset of files that
+        are update candidates as source for this transfer. See above for details on match patterns.</para>
+
+        <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
+        wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
+        optional.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>[Target] Section Options</title>
+
+    <para>This section defines properties of the transfer target:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>Type=</varname></term>
+
+        <listitem><para>Specifies the resource type of the target for the transfer. Takes one of
+        <constant>partition</constant>, <constant>regular-file</constant>, <constant>directory</constant> or
+        <constant>subvolume</constant>. For details about the resource types, see above. This option is
+        mandatory.</para>
+
+        <para>Note that only some combinations of source and target resource types are supported, see above.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Path=</varname></term>
+
+        <listitem><para>Specifies a file system path where to look for already installed versions or place
+        newly downloaded versions of this configured resource. If <varname>Type=</varname> is set to
+        <constant>partition</constant>, expects a path to a (whole) block device node, or the special string
+        <literal>auto</literal> in which case the block device the root file system of the currently booted
+        system is automatically determined and used. If <varname>Type=</varname> is set to
+        <constant>regular-file</constant>, <constant>directory</constant> or <constant>subvolume</constant>,
+        must refer to a path in the local file system referencing the directory to find or place the version
+        files or directories under.</para>
+
+        <para>Note that this mechanism cannot be used to create or remove partitions, in case
+        <varname>Type=</varname> is set to <constant>partition</constant>. Partitions must exist already, and
+        a special partition label <literal>_empty</literal> is used to indicate empty partitions. To
+        automatically generate suitable partitions on first boot, use a tool such as
+        <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MatchPattern=</varname></term>
+
+        <listitem><para>Specifies one or more file name or partition label match patterns that select the
+        subset of files or partitions that are update candidates as targets for this transfer. See above for
+        details on match patterns.</para>
+
+        <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
+        wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
+        optional.</para>
+
+        <para>This pattern is both used for matching existing installed versions and for determining the name
+        of new versions to install. If multiple patterns are specified, the first specified is used for
+        naming newly installed versions.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>MatchPartitionType=</varname></term>
+
+        <listitem><para>When the target <varname>Type=</varname> is chosen as <constant>partition</constant>,
+        specifies the GPT partition type to look for. Only partitions of this type are considered, all other
+        partitions are ignored. If not specified, the GPT partition type <constant>linux-generic</constant>
+        is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported
+        type identifiers, see the <varname>Type=</varname> setting in
+        <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>PartitionUUID=</varname></term>
+        <term><varname>PartitionFlags=</varname></term>
+        <term><varname>PartitionNoAuto=</varname></term>
+        <term><varname>PartitionGrowFileSystem=</varname></term>
+
+        <listitem><para>When the target <varname>Type=</varname> is picked as <constant>partition</constant>,
+        selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid
+        UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match
+        pattern includes wildcards for these fields (i.e. <literal>@u</literal>, <literal>@f</literal>,
+        <literal>@a</literal>, or <literal>@g</literal>), the values from the patterns are used. If neither
+        configured with wildcards or these explicit settings, the values are left untouched. If both the
+        overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings
+        <varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the
+        wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the
+        overall flags value. See <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable
+        Partitions Specification</ulink> for details about these flags.</para>
+
+        <para>Note that these settings are not used for matching, they only have effect on newly written
+        partitions in case a transfer takes place.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ReadOnly=</varname></term>
+
+        <listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the
+        target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per
+        <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
+        Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and
+        <varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is
+        <constant>regular-file</constant>, the writable bit is removed from the access mode. If the the
+        target type is <constant>subvolume</constant>, the subvolume will be marked read-only as a
+        whole. Finally, if the target <varname>Type=</varname> is selected as <constant>directory</constant>,
+        the "immutable" file attribute is set, see <citerefentry
+        project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+        details.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>Mode=</varname></term>
+
+        <listitem><para>The UNIX file access mode to use for newly created files in case the target resource
+        type is picked as <constant>regular-file</constant>. Expects an octal integer, in typical UNIX
+        fashion. If not set, but the source match pattern includes a wildcard for this field
+        (i.e. <literal>@t</literal>), the value from the pattern is used.</para>
+
+        <para>Note that this setting is not used for matching, it only has an effect on newly written
+        files when a transfer takes place.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>TriesDone=</varname></term>
+        <term><varname>TriesLeft=</varname></term>
+
+        <listitem><para>These options take positive, decimal integers, and control the number of attempts
+        done and left for this file. These settings are useful for managing kernel images, following the
+        scheme defined in <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
+        Assessment</ulink>, and only have an effect if the target pattern includes the <literal>@d</literal>
+        or <literal>@l</literal> wildcards.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>InstancesMax=</varname></term>
+
+        <listitem><para>Takes a decimal integer equal to or greater than 2. This configures how many concurrent
+        versions of the resource to keep. Whenever a new update is initiated it is made sure that no more
+        than the number of versions specified here minus one exist in the target. Any excess versions are
+        deleted (in case the target <varname>Type=</varname> of <constant>regular-file</constant>,
+        <constant>directory</constant>, <constant>subvolume</constant> is used) or emptied (in case the
+        target <varname>Type=</varname> of <constant>partition</constant> is used; emptying in this case
+        simply means to set the partition label to the special string <literal>_empty</literal>; note that no
+        partitions are actually removed). After an update is completed the number of concurrent versions of
+        the target resources is equal to or below the number specified here.</para>
+
+        <para>Note that this setting may be set differently for each transfer. However, it generally is
+        advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of
+        files or partitions will be left installed.</para>
+
+        <para>If the target <varname>Type=</varname> is selected as <constant>partition</constant>, the number
+        of concurrent versions to keep is additionally restricted by the number of partition slots of the
+        right type in the partition table. i.e. if there are only 2 partition slots for the selected
+        partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent
+        versions could be stored in the image anyway.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>RemoveTemporary=</varname></term>
+
+        <listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before
+        initiating an update, all left-over, incomplete updates from a previous attempt are removed from the
+        target directory. This only has an effect if the target resource <varname>Type=</varname> is selected
+        as <constant>regular-file</constant>, <constant>directory</constant> or
+        <constant>subvolume</constant>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>CurrentSymlink=</varname></term>
+
+        <listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the
+        update a symlink under the specified name is created/updated pointing to the completed update. This
+        is useful in to provide a stable name always pointing to the newest version of the resource. This is
+        only supported if the target resource <varname>Type=</varname> is selected as
+        <constant>regular-file</constant>, <constant>directory</constant> or
+        <constant>subvolume</constant>.</para></listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Specifiers</title>
+
+    <para>Specifiers may be used in the <varname>MinVersion=</varname>, <varname>ProtectVersion=</varname>,
+    <varname>Path=</varname>, <varname>MatchPattern=</varname> and <varname>CurrentSymlink=</varname>
+    settings. The following expansions are understood:</para>
+      <table class='specifiers'>
+        <title>Specifiers available</title>
+        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+          <colspec colname="spec" />
+          <colspec colname="mean" />
+          <colspec colname="detail" />
+          <thead>
+            <row>
+              <entry>Specifier</entry>
+              <entry>Meaning</entry>
+              <entry>Details</entry>
+            </row>
+          </thead>
+          <tbody>
+            <xi:include href="standard-specifiers.xml" xpointer="a"/>
+            <xi:include href="standard-specifiers.xml" xpointer="A"/>
+            <xi:include href="standard-specifiers.xml" xpointer="b"/>
+            <xi:include href="standard-specifiers.xml" xpointer="B"/>
+            <xi:include href="standard-specifiers.xml" xpointer="H"/>
+            <xi:include href="standard-specifiers.xml" xpointer="l"/>
+            <xi:include href="standard-specifiers.xml" xpointer="m"/>
+            <xi:include href="standard-specifiers.xml" xpointer="M"/>
+            <xi:include href="standard-specifiers.xml" xpointer="o"/>
+            <xi:include href="standard-specifiers.xml" xpointer="v"/>
+            <xi:include href="standard-specifiers.xml" xpointer="w"/>
+            <xi:include href="standard-specifiers.xml" xpointer="W"/>
+            <xi:include href="standard-specifiers.xml" xpointer="T"/>
+            <xi:include href="standard-specifiers.xml" xpointer="V"/>
+            <xi:include href="standard-specifiers.xml" xpointer="percent"/>
+          </tbody>
+        </tgroup>
+      </table>
+
+    <para>Do not confuse the <literal>%</literal> specifier expansion prefix with the <literal>@</literal>
+    pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in
+    files are parsed, the latter encapsulate a variable part of a match pattern string. For details about
+    pattern matching wildcards, see above.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Updates for a Verity Enabled Secure OS</title>
+
+      <para>With the following three files we define a root file system partition, a matching Verity
+      partition, and a unified kernel image to update as one. This example is an extension of the example
+      discussed earlier in this man page.</para>
+
+      <para><programlisting># /usr/lib/sysupdate.d/50-verity.conf
+[Transfer]
+ProtectVersion=%A
+
+[Source]
+Type=url-file
+Path=https://download.example.com/
+MatchPattern=foobarOS_@v_@u.verity.xz
+
+[Target]
+Type=partition
+Path=auto
+MatchPattern=foobarOS_@v_verity
+MatchPartitionType=root-verity
+PartitionFlags=0
+PartitionReadOnly=1</programlisting></para>
+
+      <para>The above defines the update mechanism for the Verity partition of the root file system. Verity
+      partition images are downloaded from
+      <literal>https://download.example.com/foobarOS_@v_@u.verity.xz</literal> and written to a suitable
+      local partition, which is marked read-only. Under the assumption this update is run from the image
+      itself the current image version (i.e. the <literal>%A</literal> specifier) is marked as protected, to
+      ensure it is not corrupted while booted. Note that the partition UUID for the target partition is
+      encoded in the source file name. Fixating the partition UUID can be useful to ensure that
+      <literal>roothash=</literal> on the kernel command line is sufficient to pinpoint both the Verity and
+      root file system partition, and also encode the Verity root level hash (under the assumption the UUID
+      in the file names match their top-level hash, the way
+      <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+      suggests).</para>
+
+      <para><programlisting># /usr/lib/sysupdate.d/60-root.conf
+[Transfer]
+ProtectVersion=%A
+
+[Source]
+Type=url-file
+Path=https://download.example.com/
+MatchPattern=foobarOS_@v_@u.root.xz
+
+[Target]
+Type=partition
+Path=auto
+MatchPattern=foobarOS_@v
+MatchPartitionType=root
+PartitionFlags=0
+PartitionReadOnly=1</programlisting></para>
+
+      <para>The above defines a matching transfer definition for the root file system.</para>
+
+      <para><programlisting># /usr/lib/sysupdate.d/70-kernel.conf
+[Transfer]
+ProtectVersion=%A
+
+[Source]
+Type=url-file
+Path=https://download.example.com/
+MatchPattern=foobarOS_@v.efi.xz
+
+[Target]
+Type=file
+Path=/efi/EFI/Linux
+MatchPattern=foobarOS_@v+@l-@d.efi \
+             foobarOS_@v+@l.efi \
+             foobarOS_@v.efi
+Mode=0444
+TriesLeft=3
+TriesDone=0
+InstancesMax=2</programlisting></para>
+
+        <para>The above installs a unified kernel image into the ESP (which is mounted to
+        <filename>/efi/</filename>), as per <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot
+        Loader Specification</ulink> Type #2. This defines three possible patterns for the names of the
+        kernel images images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
+        Assessment</ulink>, and ensures when installing new kernels, they are set up with 3 tries left. No
+        more than two parallel kernels are kept.</para>
+
+        <para>With this setup the web server would serve the following files, for a hypothetical version 7 of
+        the OS:</para>
+
+        <itemizedlist>
+          <listitem><para><filename>SHA256SUMS</filename> – The manifest file, containing available files and their SHA256 hashes</para></listitem>
+          <listitem><para><filename>SHA256SUMS.gpg</filename> – The detached cryptographic signature for the manifest file</para></listitem>
+          <listitem><para><filename>foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz</filename> – The Verity image for version 7</para></listitem>
+          <listitem><para><filename>foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz</filename> – The root file system image for version 7</para></listitem>
+          <listitem><para><filename>foobarOS_7_efi.xz</filename> – The unified kernel image for version 7</para></listitem>
+        </itemizedlist>
+
+        <para>For each new OS release a new set of the latter three files would be added, each time with an
+        updated version. The <filename>SHA256SUMS</filename> manifest should then be updated accordingly,
+        listing all files for all versions that shall be offered for download.</para>
+    </example>
+
+    <example>
+      <title>Updates for Plain Directory Container Image</title>
+
+      <para><programlisting>
+[Source]
+Type=url-tar
+Path=https://download.example.com/
+MatchPattern=myContainer_@v.tar.gz
+
+[Target]
+Type=subvolume
+Path=/var/lib/machines
+MatchPattern=myContainer_@v
+CurrentSymlink=myContainer</programlisting></para>
+
+      <para>On updates this downloads <literal>https://download.example.com/myContainer_@v.tar.gz</literal>
+      and decompresses/unpacks it to <filename>/var/lib/machines/myContainer_@v</filename>. After each update
+      a symlink <filename>/var/lib/machines/myContainer</filename> is created/updated always pointing to the
+      most recent update.</para>
+    </example>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>