Debian Codegraph @

upstream/debian-unstable/man7/systemd.v.7

raw
1 '\" t
2 .TH "SYSTEMD\&.V" "7" "" "systemd 261~rc3" "systemd.v"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd.v \- Directory with Versioned Resources
24 .SH "DESCRIPTION"
25 .PP
26 In various places systemd components accept paths whose trailing components have the
27 "\&.v/"
28 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)\&. Available since version v256\&. Specifically, two expressions are supported:
29 .sp
30 .RS 4
31 .ie n \{\
32 \h'-04'\(bu\h'+03'\c
33 .\}
34 .el \{\
35 .sp -1
36 .IP \(bu 2.3
37 .\}
38 When looking for files with a suffix
39 \fI\&.SUFFIX\fR, and a path
40 \&...\fIPATH\fR/\fINAME\fR\fI\&.SUFFIX\fR\&.v/
41 is specified, then all files
42 \&...\fIPATH\fR/\fINAME\fR\fI\&.SUFFIX\fR\&.v/\fINAME\fR_*\fI\&.SUFFIX\fR
43 are enumerated, filtered, sorted and the newest file used\&. The primary sorting key is the
44 \fIvariable part\fR, here indicated by the wildcard
45 "*"\&.
46 .RE
47 .sp
48 .RS 4
49 .ie n \{\
50 \h'-04'\(bu\h'+03'\c
51 .\}
52 .el \{\
53 .sp -1
54 .IP \(bu 2.3
55 .\}
56 When a path
57 \&...\fIPATH\fR\&.v/\fINAME\fR___\fI\&.SUFFIX\fR
58 is specified (i\&.e\&. the penultimate component of the path ends in
59 "\&.v"
60 and the final component contains a triple underscore), then all files
61 \&...\fIPATH\fR\&.v/\fINAME\fR_*\fI\&.SUFFIX\fR
62 are enumerated, filtered, sorted and the newest file used (again, by the
63 \fIvariable part\fR, here indicated by the wildcard
64 "*")\&.
65 .RE
66 .PP
67 To illustrate this in an example, consider a directory
68 /var/lib/machines/mymachine\&.raw\&.v/, which is populated with three files:
69 .sp
70 .RS 4
71 .ie n \{\
72 \h'-04'\(bu\h'+03'\c
73 .\}
74 .el \{\
75 .sp -1
76 .IP \(bu 2.3
77 .\}
78 mymachine_7\&.5\&.13\&.raw
79 .RE
80 .sp
81 .RS 4
82 .ie n \{\
83 \h'-04'\(bu\h'+03'\c
84 .\}
85 .el \{\
86 .sp -1
87 .IP \(bu 2.3
88 .\}
89 mymachine_7\&.5\&.14\&.raw
90 .RE
91 .sp
92 .RS 4
93 .ie n \{\
94 \h'-04'\(bu\h'+03'\c
95 .\}
96 .el \{\
97 .sp -1
98 .IP \(bu 2.3
99 .\}
100 mymachine_7\&.6\&.0\&.raw
101 .RE
102 .PP
103 Invoke a tool such as
104 \fBsystemd-nspawn\fR(1)
105 with a command line like the following:
106 .sp
107 .if n \{\
108 .RS 4
109 .\}
110 .nf
111 # systemd\-nspawn \-\-image=/var/lib/machines/mymachine\&.raw\&.v \-\-boot
112 .fi
113 .if n \{\
114 .RE
115 .\}
116 .PP
117 Then this would automatically be resolved to the equivalent of:
118 .sp
119 .if n \{\
120 .RS 4
121 .\}
122 .nf
123 # systemd\-nspawn \-\-image=/var/lib/machines/mymachine\&.raw\&.v/mymachine_7\&.6\&.0\&.raw \-\-boot
124 .fi
125 .if n \{\
126 .RE
127 .\}
128 .PP
129 Much of systemd\*(Aqs functionality that expects a path to a disk image or OS directory hierarchy support the
130 "\&.v/"
131 versioned directory mechanism, for example
132 \fBsystemd-nspawn\fR(1),
133 \fBsystemd-dissect\fR(1)
134 or the
135 \fIRootDirectory=\fR/\fIRootImage=\fR
136 settings of service files (see
137 \fBsystemd.exec\fR(5))\&.
138 .PP
139 Use the
140 \fBsystemd-vpick\fR(1)
141 tool to resolve
142 "\&.v/"
143 paths from the command line, for example for usage in shell scripts\&.
144 .SH "FILTERING AND SORTING"
145 .PP
146 The variable part of the filenames in the
147 "\&.v/"
148 directories are filtered and compared primarily with a version comparison, implementing
149 \m[blue]\fBUAPI\&.10 Version Format Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. However, additional rules apply:
150 .sp
151 .RS 4
152 .ie n \{\
153 \h'-04'\(bu\h'+03'\c
154 .\}
155 .el \{\
156 .sp -1
157 .IP \(bu 2.3
158 .\}
159 If the variable part is suffixed by one or two integer values ("tries left" and "tries done") in the formats
160 +\fILEFT\fR
161 or
162 +\fILEFT\fR\-\fIDONE\fR, 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
163 \m[blue]\fBAutomatic Boot Assessment\fR\m[]\&\s-2\u[2]\d\s+2\&. Any filenames with no boot counters or with a non\-zero "tries left" counter are sorted before filenames with a zero "tries left" counter\&.
164 .RE
165 .sp
166 .RS 4
167 .ie n \{\
168 \h'-04'\(bu\h'+03'\c
169 .\}
170 .el \{\
171 .sp -1
172 .IP \(bu 2.3
173 .\}
174 Preceding 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
175 \fIConditionArchitecture=\fR
176 unit file setting, as documented in
177 \fBsystemd.unit\fR(5)\&. Files whose name indicates an architecture not supported locally are filtered and not considered for the version comparison\&.
178 .RE
179 .sp
180 .RS 4
181 .ie n \{\
182 \h'-04'\(bu\h'+03'\c
183 .\}
184 .el \{\
185 .sp -1
186 .IP \(bu 2.3
187 .\}
188 The rest of the variable part is the version string\&.
189 .RE
190 .PP
191 Or in other words, the files in the
192 "\&.v/"
193 directories should follow one of these naming structures:
194 .sp
195 .RS 4
196 .ie n \{\
197 \h'-04'\(bu\h'+03'\c
198 .\}
199 .el \{\
200 .sp -1
201 .IP \(bu 2.3
202 .\}
203 \fINAME\fR_\fIVERSION\fR\fI\&.SUFFIX\fR
204 .RE
205 .sp
206 .RS 4
207 .ie n \{\
208 \h'-04'\(bu\h'+03'\c
209 .\}
210 .el \{\
211 .sp -1
212 .IP \(bu 2.3
213 .\}
214 \fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR\fI\&.SUFFIX\fR
215 .RE
216 .sp
217 .RS 4
218 .ie n \{\
219 \h'-04'\(bu\h'+03'\c
220 .\}
221 .el \{\
222 .sp -1
223 .IP \(bu 2.3
224 .\}
225 \fINAME\fR_\fIVERSION\fR+\fILEFT\fR\fI\&.SUFFIX\fR
226 .RE
227 .sp
228 .RS 4
229 .ie n \{\
230 \h'-04'\(bu\h'+03'\c
231 .\}
232 .el \{\
233 .sp -1
234 .IP \(bu 2.3
235 .\}
236 \fINAME\fR_\fIVERSION\fR+\fILEFT\fR\-\fIDONE\fR\fI\&.SUFFIX\fR
237 .RE
238 .sp
239 .RS 4
240 .ie n \{\
241 \h'-04'\(bu\h'+03'\c
242 .\}
243 .el \{\
244 .sp -1
245 .IP \(bu 2.3
246 .\}
247 \fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR+\fILEFT\fR\fI\&.SUFFIX\fR
248 .RE
249 .sp
250 .RS 4
251 .ie n \{\
252 \h'-04'\(bu\h'+03'\c
253 .\}
254 .el \{\
255 .sp -1
256 .IP \(bu 2.3
257 .\}
258 \fINAME\fR_\fIVERSION\fR_\fIARCHITECTURE\fR+\fILEFT\fR\-\fIDONE\fR\fI\&.SUFFIX\fR
259 .RE
260 .SH "EXAMPLE"
261 .PP
262 Here\*(Aqs a more comprehensive example, further extending the one described above\&. Consider a directory
263 /var/lib/machines/mymachine\&.raw\&.v/, which is populated with the following files:
264 .sp
265 .RS 4
266 .ie n \{\
267 \h'-04'\(bu\h'+03'\c
268 .\}
269 .el \{\
270 .sp -1
271 .IP \(bu 2.3
272 .\}
273 mymachine_7\&.5\&.13\&.raw
274 .RE
275 .sp
276 .RS 4
277 .ie n \{\
278 \h'-04'\(bu\h'+03'\c
279 .\}
280 .el \{\
281 .sp -1
282 .IP \(bu 2.3
283 .\}
284 mymachine_7\&.5\&.14_x86\-64\&.raw
285 .RE
286 .sp
287 .RS 4
288 .ie n \{\
289 \h'-04'\(bu\h'+03'\c
290 .\}
291 .el \{\
292 .sp -1
293 .IP \(bu 2.3
294 .\}
295 mymachine_7\&.6\&.0_arm64\&.raw
296 .RE
297 .sp
298 .RS 4
299 .ie n \{\
300 \h'-04'\(bu\h'+03'\c
301 .\}
302 .el \{\
303 .sp -1
304 .IP \(bu 2.3
305 .\}
306 mymachine_7\&.7\&.0_x86\-64+0\-5\&.raw
307 .RE
308 .PP
309 Now invoke the following command on an x86\-64 machine:
310 .sp
311 .if n \{\
312 .RS 4
313 .\}
314 .nf
315 $ systemd\-vpick \-\-suffix=\&.raw /var/lib/machines/mymachine\&.raw\&.v/
316 .fi
317 .if n \{\
318 .RE
319 .\}
320 .PP
321 This would resolve the specified path to
322 /var/lib/machines/mymachine\&.raw\&.v/mymachine_7\&.5\&.14_x86\-64\&.raw\&. Explanation: even though
323 mymachine_7\&.7\&.0_x86\-64+0\-5\&.raw
324 has the newest version, it is not preferred because its tries left counter is zero\&. And even though
325 mymachine_7\&.6\&.0_arm64\&.raw
326 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
327 mymachine_7\&.5\&.13\&.raw
328 image is not considered because it is older than
329 mymachine_7\&.5\&.14_x86\-64\&.raw\&.
330 .SH "SEE ALSO"
331 .PP
332 \fBsystemd\fR(1), \fBsystemd-vpick\fR(1), \fBsystemd-nspawn\fR(1), \fBsystemd-dissect\fR(1), \fBsystemd.exec\fR(5), \fBsystemd-sysupdate\fR(8)
333 .SH "NOTES"
334 .IP " 1." 4
335 UAPI.10 Version Format Specification
336 .RS 4
337 \%https://uapi-group.org/specifications/specs/version_format_specification/
338 .RE
339 .IP " 2." 4
340 Automatic Boot Assessment
341 .RS 4
342 \%https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/
343 .RE