]>
Commit | Line | Data |
---|---|---|
7d93e4af LP |
1 | <?xml version='1.0'?> <!--*-nxml-*--> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> | |
5 | ||
6 | <refentry id="systemd.v"> | |
7 | ||
8 | <refentryinfo> | |
9 | <title>systemd.v</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>systemd.v</refentrytitle> | |
15 | <manvolnum>7</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>systemd.v</refname> | |
20 | <refpurpose>Directory with Versioned Resources</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsect1> | |
24 | <title>Description</title> | |
25 | ||
26 | <para>In various places systemd components accept paths whose trailing components have the | |
27 | <literal>.v/</literal> suffix, pointing to a directory. These components will then automatically look for | |
28 | suitable files inside the directory, do a version comparison and open the newest file found (by | |
7fa428cf | 29 | version). Available since version v256. Specifically, two expressions are supported:</para> |
7d93e4af LP |
30 | |
31 | <itemizedlist> | |
32 | ||
33 | <listitem><para>When looking for files with a suffix <replaceable>.SUFFIX</replaceable>, and a path | |
34 | <filename>…<replaceable>PATH</replaceable>/<replaceable>NAME</replaceable><replaceable>.SUFFIX</replaceable>.v/</filename> | |
35 | is specified, then all files | |
36 | <filename>…<replaceable>PATH</replaceable>/<replaceable>NAME</replaceable><replaceable>.SUFFIX</replaceable>.v/<replaceable>NAME</replaceable>_*<replaceable>.SUFFIX</replaceable></filename> | |
37 | are enumerated, filtered, sorted and the newest file used. The primary sorting key is the | |
38 | <emphasis>variable part</emphasis>, here indicated by the wildcard | |
39 | <literal>*</literal>.</para></listitem> | |
40 | ||
41 | <listitem><para>When a path | |
42 | <filename>…<replaceable>PATH</replaceable>.v/<replaceable>NAME</replaceable>___<replaceable>.SUFFIX</replaceable></filename> | |
43 | is specified (i.e. the penultimate component of the path ends in <literal>.v</literal> and the final | |
44 | component contains a triple underscore), then all files | |
45 | <filename>…<replaceable>PATH</replaceable>.v/<replaceable>NAME</replaceable>_*<replaceable>.SUFFIX</replaceable></filename> | |
46 | are enumerated, filtered, sorted and the newest file used (again, by the <emphasis>variable | |
47 | part</emphasis>, here indicated by the wildcard <literal>*</literal>).</para></listitem> | |
48 | </itemizedlist> | |
49 | ||
50 | <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> | |
51 | ||
52 | <itemizedlist> | |
53 | <listitem><para><filename>mymachine_7.5.13.raw</filename></para></listitem> | |
54 | <listitem><para><filename>mymachine_7.5.14.raw</filename></para></listitem> | |
55 | <listitem><para><filename>mymachine_7.6.0.raw</filename></para></listitem> | |
56 | </itemizedlist> | |
57 | ||
58 | <para>Invoke a tool such as <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> with a command line like the following:</para> | |
59 | ||
60 | <programlisting># systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot</programlisting> | |
61 | ||
62 | <para>Then this would automatically be resolved to the equivalent of:</para> | |
63 | ||
64 | <programlisting># systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot</programlisting> | |
65 | ||
66 | <para>Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy | |
67 | support the <literal>.v/</literal> versioned directory mechanism, for example | |
68 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
69 | <citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry> or | |
70 | the <varname>RootDirectory=</varname>/<varname>RootImage=</varname> settings of service files (see | |
71 | <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para> | |
72 | ||
73 | <para>Use the | |
74 | <citerefentry><refentrytitle>systemd-vpick</refentrytitle><manvolnum>1</manvolnum></citerefentry> tool to | |
75 | resolve <literal>.v/</literal> paths from the command line, for example for usage in shell | |
76 | scripts.</para> | |
77 | </refsect1> | |
78 | ||
79 | <refsect1> | |
80 | <title>Filtering and Sorting</title> | |
81 | ||
82 | <para>The variable part of the filenames in the <literal>.v/</literal> directories are filtered and | |
83 | compared primarily with a version comparison, implementing <ulink | |
84 | url="https://uapi-group.org/specifications/specs/version_format_specification/">Version Format | |
85 | Specification</ulink>. However, additional rules apply:</para> | |
86 | ||
87 | <itemizedlist> | |
88 | <listitem><para>If the variable part is suffixed by one or two integer values ("tries left" and "tries | |
89 | done") in the formats <filename>+<replaceable>LEFT</replaceable></filename> or | |
90 | <filename>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable></filename>, then these | |
91 | indicate usage attempt counters. The idea is that each time before a file is attempted to be used, its | |
92 | "tries left" counter is decreased, and the "tries done" counter increased (simply by renaming the | |
93 | file). When the file is successfully used (which for example could mean for an OS image: successfully | |
94 | booted) the counters are removed from the file name, indicating that the file has been validated to | |
95 | work correctly. This mechanism mirrors the boot assessment counters defined by <ulink | |
96 | url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/">Automatic Boot Assessment</ulink>. Any filenames | |
97 | with no boot counters or with a non-zero "tries left" counter are sorted before filenames with a zero | |
98 | "tries left" counter.</para></listitem> | |
99 | ||
c270e41f | 100 | <listitem><para>Preceding the use counters (if they are specified), an optional CPU architecture |
7d93e4af LP |
101 | identifier may be specified in the filename (separated from the version with an underscore), as defined |
102 | in the architecture vocabulary of the <varname>ConditionArchitecture=</varname> unit file setting, as | |
103 | documented in | |
104 | <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Files | |
105 | whose name indicates an architecture not supported locally are filtered and not considered for the | |
106 | version comparison.</para></listitem> | |
107 | ||
108 | <listitem><para>The rest of the variable part is the version string.</para></listitem> | |
109 | </itemizedlist> | |
110 | ||
111 | <para>Or in other words, the files in the <literal>.v/</literal> directories should follow one of these | |
112 | naming structures:</para> | |
113 | ||
114 | <itemizedlist> | |
115 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
116 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
117 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>+<replaceable>LEFT</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
118 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
119 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable>+<replaceable>LEFT</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
120 | <listitem><para><filename><replaceable>NAME</replaceable>_<replaceable>VERSION</replaceable>_<replaceable>ARCHITECTURE</replaceable>+<replaceable>LEFT</replaceable>-<replaceable>DONE</replaceable><replaceable>.SUFFIX</replaceable></filename></para></listitem> | |
121 | </itemizedlist> | |
122 | </refsect1> | |
123 | ||
124 | <refsect1> | |
125 | <title>Example</title> | |
126 | ||
127 | <para>Here's a more comprehensive example, further extending the one described above. Consider a | |
128 | directory <filename>/var/lib/machines/mymachine.raw.v/</filename>, which is populated with the following | |
129 | files:</para> | |
130 | ||
131 | <itemizedlist> | |
132 | <listitem><para><filename>mymachine_7.5.13.raw</filename></para></listitem> | |
133 | <listitem><para><filename>mymachine_7.5.14_x86-64.raw</filename></para></listitem> | |
134 | <listitem><para><filename>mymachine_7.6.0_arm64.raw</filename></para></listitem> | |
135 | <listitem><para><filename>mymachine_7.7.0_x86-64+0-5.raw</filename></para></listitem> | |
136 | </itemizedlist> | |
137 | ||
138 | <para>Now invoke the following command on an x86-64 machine:</para> | |
139 | ||
140 | <programlisting>$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/</programlisting> | |
141 | ||
142 | <para>This would resolve the specified path to | |
143 | <filename>/var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw</filename>. Explanation: even | |
144 | though <filename>mymachine_7.7.0_x86-64+0-5.raw</filename> has the newest version, it is not preferred | |
145 | because its tries left counter is zero. And even though <filename>mymachine_7.6.0_arm64.raw</filename> | |
146 | has the second newest version it is also not considered, in this case because we operate on an x86_64 | |
147 | system and the image is intended for arm64 CPUs. Finally, the <filename>mymachine_7.5.13.raw</filename> | |
148 | image is not considered because it is older than <filename>mymachine_7.5.14_x86-64.raw</filename>.</para> | |
149 | </refsect1> | |
150 | ||
151 | <refsect1> | |
152 | <title>See Also</title> | |
153 | <para><simplelist type="inline"> | |
154 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
155 | <member><citerefentry><refentrytitle>systemd-vpick</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
156 | <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
157 | <member><citerefentry><refentrytitle>systemd-dissect</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
158 | <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
159 | <member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
160 | </simplelist></para> | |
161 | </refsect1> | |
162 | ||
163 | </refentry> |