mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-23 02:03:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

man: document the new vpick concept

Browse Source
This commit is contained in:
Lennart Poettering 2023-11-16 11:31:02 +01:00
parent a5ecdf7c6b
commit 7d93e4af80
6 changed files with 391 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
man/rules/meson.build
View File

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

5
man/systemd-dissect.xml
View File

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

26
man/systemd-nspawn.xml
View File

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

198
man/systemd-vpick.xml Normal file
View File

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

8
man/systemd.exec.xml
View File

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

163
man/systemd.v.xml Normal file
View File

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