man: document the new vpick concept

6 files changed, 391 insertions, 11 deletions

diff --git a/man/rules/meson.build b/man/rules/meson.build
index c99f79eba8..3592b862f7 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1131,6 +1131,7 @@ manpages = [
   'HAVE_LIBCRYPTSETUP'],
  ['systemd-vmspawn', '1', [], 'ENABLE_VMSPAWN'],
  ['systemd-volatile-root.service', '8', ['systemd-volatile-root'], ''],
+ ['systemd-vpick', '1', [], ''],
  ['systemd-xdg-autostart-generator', '8', [], 'ENABLE_XDG_AUTOSTART'],
  ['systemd', '1', ['init'], ''],
  ['systemd.automount', '5', [], ''],
@@ -1165,6 +1166,7 @@ manpages = [
  ['systemd.time', '7', [], ''],
  ['systemd.timer', '5', [], ''],
  ['systemd.unit', '5', [], ''],
+ ['systemd.v', '7', [], ''],
  ['sysupdate.d', '5', [], 'ENABLE_SYSUPDATE'],
  ['sysusers.d', '5', [], 'ENABLE_SYSUSERS'],
  ['telinit', '8', [], 'HAVE_SYSV_COMPAT'],
diff --git a/man/systemd-dissect.xml b/man/systemd-dissect.xml
index b238a9f7d0..85166f23d3 100644
--- a/man/systemd-dissect.xml
+++ b/man/systemd-dissect.xml
@@ -120,6 +120,10 @@
     mounted directly by <command>mount</command> and <citerefentry
     project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>. For
     details see below.</para>
+
+    <para>In place of the image path a <literal>.v/</literal> versioned directory may be specified, see
+    <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+    details.</para>
   </refsect1>
 
   <refsect1>
@@ -543,6 +547,7 @@
       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
       <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
       <member><ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink></member>
       <member><citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
       <member><citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml
index e721f0e5ab..1a9fb09aae 100644
--- a/man/systemd-nspawn.xml
+++ b/man/systemd-nspawn.xml
@@ -209,21 +209,21 @@
         <term><option>-D</option></term>
         <term><option>--directory=</option></term>
 
-        <listitem><para>Directory to use as file system root for the
-        container.</para>
+        <listitem><para>Directory to use as file system root for the container.</para>
 
-        <para>If neither <option>--directory=</option>, nor
-        <option>--image=</option> is specified the directory is
-        determined by searching for a directory named the same as the
-        machine name specified with <option>--machine=</option>. See
+        <para>If neither <option>--directory=</option>, nor <option>--image=</option> is specified the
+        directory is determined by searching for a directory named the same as the machine name specified
+        with <option>--machine=</option>. See
         <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
         section "Files and Directories" for the precise search path.</para>
 
-        <para>If neither <option>--directory=</option>,
-        <option>--image=</option>, nor <option>--machine=</option>
-        are specified, the current directory will
-        be used. May not be specified together with
-        <option>--image=</option>.</para></listitem>
+        <para>In place of the directory path a <literal>.v/</literal> versioned directory may be specified, see
+        <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details.</para>
+
+        <para>If neither <option>--directory=</option>, <option>--image=</option>, nor
+        <option>--machine=</option> are specified, the current directory will be used. May not be specified
+        together with <option>--image=</option>.</para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -317,6 +317,10 @@
         <para>Any other partitions, such as foreign partitions or swap partitions are not mounted. May not be specified
         together with <option>--directory=</option>, <option>--template=</option>.</para>
 
+        <para>In place of the image path a <literal>.v/</literal> versioned directory may be specified, see
+        <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details.</para>
+
         <xi:include href="version-info.xml" xpointer="v211"/></listitem>
       </varlistentry>
 
diff --git a/man/systemd-vpick.xml b/man/systemd-vpick.xml
new file mode 100644
index 0000000000..95f946a84c
--- /dev/null
+++ b/man/systemd-vpick.xml
@@ -0,0 +1,198 @@
+<?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-vpick"
+    xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-vpick</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-vpick</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-vpick</refname>
+    <refpurpose>Resolve paths to <literal>.v/</literal> versioned directories</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>systemd-vpick <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">PATH</arg></command>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para><command>systemd-vpick</command> resolves a file system path referencing a <literal>.v/</literal>
+    versioned directory to a path to the newest (by version) file contained therein. This tool provides a
+    command line interface for the
+    <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+    logic.</para>
+
+    <para>The tool expects a path to a <literal>.v/</literal> directory as argument (either directly, or with
+    a triple underscore pattern as final component). It then determines the newest file contained in that
+    directory, and writes its path to standard output.</para>
+
+    <para>Unless the triple underscore pattern is passed as last component of the path, it is typically
+    necessary to at least specify the <option>--suffix=</option> switch to configure the file suffix to look
+    for.</para>
+
+    <para>If the specified path does not reference a <literal>.v/</literal> path (i.e. neither the final
+    component ends in <literal>.v</literal>, nor the penultimate does or the final one does contain a triple
+    underscore) it specified path is written unmodified to standard output.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Options</title>
+
+    <para>The following options are understood:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>--basename=</option></term>
+        <term><option>-B</option></term>
+
+        <listitem><para>Overrides the "basename" of the files to look for, i.e. the part to the left of the
+        variable part of the filenames. Normally this is derived automatically from the filename of the
+        <literal>.v</literal> component of the specified path, or from the triple underscore pattern in the
+        last component of the specified path.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-V</option></term>
+
+        <listitem><para>Explicitly configures the version to select. If specified, a filename with the
+        specified version string will be looked for, instead of the newest version
+        available.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-A</option></term>
+
+        <listitem><para>Explicitly configures the architecture to select. If specified, a filename with the
+        specified architecture identifier will be looked for. If not specified only filenames with a locally
+        supported architecture are considered, or those without any architecture identifier.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--suffix=</option></term>
+        <term><option>-S</option></term>
+
+        <listitem><para>Configures the suffix of the filenames to consider. For the <literal>.v/</literal>
+        logic it is necessary to specify the suffix to look for, and the <literal>.v/</literal> component
+        must also carry the suffix immediately before <literal>.v</literal> in its name.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--type=</option></term>
+        <term><option>-t</option></term>
+
+        <listitem><para>Configures the inode type to look for in the <literal>.v/</literal> directory. Takes
+        one of <literal>reg</literal>, <literal>dir</literal>, <literal>sock</literal>,
+        <literal>fifo</literal>, <literal>blk</literal>, <literal>chr</literal>, <literal>lnk</literal> as
+        argument, each identifying an inode type. See <citerefentry
+        project='man-pages'><refentrytitle>inode</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details about inode types. If this option is used inodes not matching the specified type are filtered
+        and not taken into consideration.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--print=</option></term>
+        <term><option>-p</option></term>
+
+        <listitem><para>Configures what precisely to write to standard output. If not specified prints the
+        full, resolved path of the newest matching file in the <literal>.v/</literal> directory. This switch can be set to one of the following:</para>
+
+        <itemizedlist>
+          <listitem><para>If set to <literal>filename</literal>, will print only the filename instead of the full path of the resolved file.</para></listitem>
+          <listitem><para>If set to <literal>version</literal>, will print only the version of the resolved file.</para></listitem>
+          <listitem><para>If set to <literal>type</literal>, will print only the inode type of the resolved
+          file (i.e. a string such as <literal>reg</literal> for regular files, or <literal>dir</literal> for
+          directories).</para></listitem>
+          <listitem><para>If set to <literal>arch</literal>, will print only the architecture of the resolved
+          file.</para></listitem>
+          <listitem><para>If set to <literal>tries</literal>, will print only the tries left/tries done of the
+          resolved file.</para></listitem>
+          <listitem><para>If set to <literal>all</literal>, will print all of the above in a simple tabular
+          output.</para></listitem>
+        </itemizedlist>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--resolve=</option></term>
+
+        <listitem><para>Takes a boolean argument. If true the path to the versioned file is fully
+        canonicalized (i.e. symlinks resolved, and redundant path components removed) before it is shown. If
+        false (the default) this is not done, and the path is shown without canonicalization.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/></listitem>
+      </varlistentry>
+
+      <xi:include href="standard-options.xml" xpointer="help" />
+      <xi:include href="standard-options.xml" xpointer="version" />
+    </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>Use a command like the following to automatically pick the newest raw disk image from a
+    <literal>.v/</literal> directory:</para>
+
+    <programlisting>$ systemd-vpick --suffix=.raw --type=reg /var/lib/machines/quux.raw.v/</programlisting>
+
+    <para>This will enumerate all regular files matching
+    <filename>/var/lib/machines/quux.raw.v/quux*.raw</filename>, filter and sort them according to the rules
+    described in
+    <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>, and then
+    write the path to the newest (by version) file to standard output.</para>
+
+    <para>Use a command like the following to automatically pick the newest OS directory tree from a
+    <literal>.v/</literal> directory:</para>
+
+    <programlisting>$ systemd-vpick --type=dir /var/lib/machines/waldo.v/</programlisting>
+
+    <para>This will enumerate all directory inodes matching
+    <filename>/var/lib/machines/waldo.v/waldo*</filename>, filter and sort them according to the rules
+    described in
+    <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>, and then
+    write the path to the newest (by version) directory to standard output.</para>
+
+    <para>For further examples see
+    <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
+  </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><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+</refentry>
diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index e2b2910084..42e6ff8fd7 100644
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -155,6 +155,10 @@
           <programlisting>BindReadOnlyPaths=/dev/log /run/systemd/journal/socket /run/systemd/journal/stdout</programlisting>
         </example>
 
+        <para>In place of the directory path a <literal>.v/</literal> versioned directory may be specified,
+        see <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details.</para>
+
         <xi:include href="system-or-user-ns.xml" xpointer="singular"/></listitem>
       </varlistentry>
 
@@ -191,6 +195,10 @@
         <citerefentry><refentrytitle>systemd-soft-reboot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>),
         in case the service is configured to survive it.</para>
 
+        <para>In place of the image path a <literal>.v/</literal> versioned directory may be specified, see
+        <citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+        details.</para>
+
         <xi:include href="system-only.xml" xpointer="singular"/>
 
         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
diff --git a/man/systemd.v.xml b/man/systemd.v.xml
new file mode 100644
index 0000000000..6cc6122a34
--- /dev/null
+++ b/man/systemd.v.xml
@@ -0,0 +1,163 @@
+<?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.v">
+
+  <refentryinfo>
+    <title>systemd.v</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd.v</refentrytitle>
+    <manvolnum>7</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd.v</refname>
+    <refpurpose>Directory with Versioned Resources</refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>In various places systemd components accept paths whose trailing components have the
+    <literal>.v/</literal> suffix, pointing to a directory. These components will then automatically look for
+    suitable files inside the directory, do a version comparison and open the newest file found (by
+    version). Specifically, two expressions are supported:</para>
+
+    <itemizedlist>
+
+      <listitem><para>When looking for files with a suffix <replaceable>.SUFFIX</replaceable>, and a path
+      <filename>…<replaceable>PATH</replaceable>/<replaceable>NAME</replaceable><replaceable>.SUFFIX</replaceable>.v/</filename>
+      is specified, then all files
+      <filename>…<replaceable>PATH</replaceable>/<replaceable>NAME</replaceable><replaceable>.SUFFIX</replaceable>.v/<replaceable>NAME</replaceable>_*<replaceable>.SUFFIX</replaceable></filename>
+      are enumerated, filtered, sorted and the newest file used. The primary sorting key is the
+      <emphasis>variable part</emphasis>, here indicated by the wildcard
+      <literal>*</literal>.</para></listitem>
+
+      <listitem><para>When a path
+      <filename>…<replaceable>PATH</replaceable>.v/<replaceable>NAME</replaceable>___<replaceable>.SUFFIX</replaceable></filename>
+      is specified (i.e. the penultimate component of the path ends in <literal>.v</literal> and the final
+      component contains a triple underscore), then all files
+      <filename>…<replaceable>PATH</replaceable>.v/<replaceable>NAME</replaceable>_*<replaceable>.SUFFIX</replaceable></filename>
+      are enumerated, filtered, sorted and the newest file used (again, by the <emphasis>variable
+      part</emphasis>, here indicated by the wildcard <literal>*</literal>).</para></listitem>
+    </itemizedlist>
+
+    <para>To illustrate this in an example, consider a directory <filename>/var/lib/machines/mymachine.raw.v/</filename>, which is populated with three files:</para>
+
+    <itemizedlist>
+      <listitem><para><filename>mymachine_7.5.13.raw</filename></para></listitem>
+      <listitem><para><filename>mymachine_7.5.14.raw</filename></para></listitem>
+      <listitem><para><filename>mymachine_7.6.0.raw</filename></para></listitem>
+    </itemizedlist>
+
+    <para>Invoke a tool such as <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> with a command line like the following:</para>
+
+    <programlisting># systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot</programlisting>
+
+    <para>Then this would automatically be resolved to the equivalent of:</para>
+
+    <programlisting># systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot</programlisting>
+
+    <para>Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy
+    support the <literal>.v/</literal> versioned directory mechanism, for example
+    <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry> or
+    the <varname>RootDirectory=</varname>/<varname>RootImage=</varname> settings of service files (see
+    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
+
+    <para>Use the
+    <citerefentry><refentrytitle>systemd-vpick</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool to
+    resolve <literal>.v/</literal> paths from the command line, for example for usage in shell
+    scripts.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Filtering and Sorting</title>
+
+    <para>The variable part of the filenames in the <literal>.v/</literal> directories are filtered and
+    compared primarily with a version comparison, implementing <ulink
+    url="https://uapi-group.org/specifications/specs/version_format_specification/">Version Format
+    Specification</ulink>. However, additional rules apply:</para>
+
+    <itemizedlist>
+      <listitem><para>If the variable part is suffixed by one or two integer values ("tries left" and "tries
+      done") in the formats <filename>+<replaceable>LEFT</replaceable></filename> or
+      <filename>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable></filename>, then these
+      indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its
+      "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the
+      file). When the file is successfully used (which for example could mean for an OS image: successfully
+      booted) the counters are removed from the file name, indicating that the file has been validated to
+      work correctly. This mechanism mirrors the boot assessment counters defined by <ulink
+      url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/">Automatic Boot Assessment</ulink>. Any filenames
+      with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero
+      "tries left" counter.</para></listitem>
+
+      <listitem><para>Preceeding the use counters (if they are specified), an optional CPU architecture
+      identifier may be specified in the filename (separated from the version with an underscore), as defined
+      in the architecture vocabulary of the <varname>ConditionArchitecture=</varname> unit file setting, as
+      documented in
+      <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Files
+      whose name indicates an architecture not supported locally are filtered and not considered for the
+      version comparison.</para></listitem>
+
+      <listitem><para>The rest of the variable part is the version string.</para></listitem>
+    </itemizedlist>
+
+    <para>Or in other words, the files in the <literal>.v/</literal> directories should follow one of these
+    naming structures:</para>
+
+    <itemizedlist>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>+<replaceable>LEFT</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable>+<replaceable>LEFT</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+      <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem>
+    </itemizedlist>
+  </refsect1>
+
+  <refsect1>
+    <title>Example</title>
+
+    <para>Here's a more comprehensive example, further extending the one described above. Consider a
+    directory <filename>/var/lib/machines/mymachine.raw.v/</filename>, which is populated with the following
+    files:</para>
+
+    <itemizedlist>
+      <listitem><para><filename>mymachine_7.5.13.raw</filename></para></listitem>
+      <listitem><para><filename>mymachine_7.5.14_x86-64.raw</filename></para></listitem>
+      <listitem><para><filename>mymachine_7.6.0_arm64.raw</filename></para></listitem>
+      <listitem><para><filename>mymachine_7.7.0_x86-64+0-5.raw</filename></para></listitem>
+    </itemizedlist>
+
+    <para>Now invoke the following command on an x86-64 machine:</para>
+
+    <programlisting>$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/</programlisting>
+
+    <para>This would resolve the specified path to
+    <filename>/var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw</filename>. Explanation: even
+    though <filename>mymachine_7.7.0_x86-64+0-5.raw</filename> has the newest version, it is not preferred
+    because its tries left counter is zero. And even though <filename>mymachine_7.6.0_arm64.raw</filename>
+    has the second newest version it is also not considered, in this case because we operate on an x86_64
+    system and the image is intended for arm64 CPUs. Finally, the <filename>mymachine_7.5.13.raw</filename>
+    image is not considered because it is older than <filename>mymachine_7.5.14_x86-64.raw</filename>.</para>
+  </refsect1>
+
+  <refsect1>
+      <title>See Also</title>
+      <para><simplelist type="inline">
+        <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>systemd-vpick</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+        <member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      </simplelist></para>
+  </refsect1>
+
+</refentry>