mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-23 10:13:34 +08:00
Code Issues Packages Projects Releases Wiki Activity
main
systemd/man/systemd.v.xml

164 lines
10 KiB
XML
Raw Permalink Normal View History

man: document the new vpick concept
2023-11-16 18:31:02 +08:00
<?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
man: create reusable snippet for 'vpick' entries
2024-02-17 05:45:01 +08:00
version). Available since version v256. Specifically, two expressions are supported:</para>
man: document the new vpick concept
2023-11-16 18:31:02 +08:00
<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>
man: fix typo Follow-up for 7d93e4af8088fae7b50eb638c6e297fb8371e307.
2024-01-05 18:06:06 +08:00
<listitem><para>Preceding the use counters (if they are specified), an optional CPU architecture
man: document the new vpick concept
2023-11-16 18:31:02 +08:00
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>
man: fix incorrect volume numbers in internal man page references Some ambiguity (e.g., same-named man pages in multiple volumes) makes it impossible to fully automate this, but the following Python snippet (run inside the man/ directory of the systemd repo) helped to generate the sed command lines (which were subsequently manually reviewed, run and the false positives reverted): from pathlib import Path import lxml from lxml import etree as ET man2vol: dict[str, str] = {} man2citerefs: dict[str, list] = {} for file in Path(".").glob("*.xml"): tree = ET.parse(file, lxml.etree.XMLParser(recover=True)) meta = tree.find("refmeta") if meta is not None: title = meta.findtext("refentrytitle") if title is not None: vol = meta.findtext("manvolnum") if vol is not None: man2vol[title] = vol citerefs = list(tree.iter("citerefentry")) if citerefs: man2citerefs[title] = citerefs for man, refs in man2citerefs.items(): for ref in refs: title = ref.findtext("refentrytitle") if title is not None: has = ref.findtext("manvolnum") try: should_have = man2vol[title] except KeyError: # Non-systemd man page reference? Ignore. continue if has != should_have: print( f"sed -i '\\|<citerefentry><refentrytitle>{title}" f"</refentrytitle><manvolnum>{has}</manvolnum>" f"</citerefentry>|s|<manvolnum>{has}</manvolnum>|" f"<manvolnum>{should_have}</manvolnum>|' {man}.xml" )
2024-11-12 03:10:00 +08:00
<member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
man: document the new vpick concept
2023-11-16 18:31:02 +08:00
</simplelist></para>
</refsect1>
</refentry>
Reference in New Issue Copy Permalink