'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', [], ''],
['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'],
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>
<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>
<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>
<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>
--- /dev/null
+<?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>
<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>
<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>
--- /dev/null
+<?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>
projects / thirdparty / systemd.git / commitdiff
