Debian Codegraph @

upstream/debian-unstable/man5/sysupdate.features.5

raw
1 '\" t
2 .TH "SYSUPDATE\&.FEATURES" "5" "" "systemd 261~rc3" "sysupdate.features"
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 sysupdate.features \- Definition Files for Optional Features
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/sysupdate\&.d/*\&.feature
28 .RE
29 .RS 4
30 /run/sysupdate\&.d/*\&.feature
31 .RE
32 .RS 4
33 /usr/local/lib/sysupdate\&.d/*\&.feature
34 .RE
35 .RS 4
36 /usr/lib/sysupdate\&.d/*\&.feature
37 .RE
38 .SH "DESCRIPTION"
39 .PP
40 "Optional Features" are functionality provided by
41 \fBsystemd-sysupdate\fR(8), that allow a distribution to define sets of
42 \fBsysupdate.d\fR(5)
43 transfer definitions that are intended to be enabled or disabled by the system administrator\&.
44 .PP
45 When a feature is enabled, transfers belonging to it will be considered when checking for and downloading updates, when vacuuming, and in all other situations\&. In effect, transfers belonging to a feature will always be updated in lock\-step with the rest of their target\&. This is the primary difference an Optional Feature and a
46 \fBsystemd-sysupdate\fR(8)
47 component\&. When a feature is disabled, its transfers will not be considered when checking for and downloading updates, but
48 \fBsystemd\-sysupdate\fR
49 will still consider them while vacuuming and in other situations where it needs to determine ownership over previously downloaded system resources\&.
50 \fBsystemd\-sysupdate\fR
51 will clean up all instances of the feature\*(Aqs transfers whenever it is disabled, effectively uninstalling it\&.
52 .PP
53 Optional Features are described by
54 sysupdate\&.d/*\&.feature
55 files, which are defined below\&. Transfers can declare that they belong to a feature via the
56 \fIFeatures=\fR
57 setting\&. Feature definitions support drop\-in files, which are most commonly used to override the
58 \fIEnabled=\fR
59 setting\&. They can also be masked to hide the availability of the feature entirely\&.
60 .PP
61 Each
62 *\&.feature
63 file contains one section: [Feature]\&.
64 .SH "[FEATURE] SECTION OPTIONS"
65 .PP
66 This section defines general properties of this feature\&.
67 .PP
68 \fIDescription=\fR
69 .RS 4
70 A short human\-readable description of this feature\&. This may be used as a label for this feature, so the string should meaningfully identify the feature among the features available in
71 sysupdate\&.d/\&.
72 .sp
73 Added in version 257\&.
74 .RE
75 .PP
76 \fIDocumentation=\fR
77 .RS 4
78 A user\-presentable URL to documentation about this feature\&. This setting supports specifier expansion; see below for details on supported specifiers\&.
79 .sp
80 Added in version 257\&.
81 .RE
82 .PP
83 \fIAppStream=\fR
84 .RS 4
85 A URL to an
86 \m[blue]\fBAppStream catalog\fR\m[]\&\s-2\u[1]\d\s+2
87 XML file\&. This may be used by software centers (such as GNOME Software or KDE Discover) to present rich metadata about this feature\&. This includes display names, changelogs, icons, and more\&. This setting supports specifier expansion; see below for details on supported specifiers\&.
88 .sp
89 Added in version 257\&.
90 .RE
91 .PP
92 \fIEnabled=\fR
93 .RS 4
94 Whether or not this feature is enabled\&. If unspecified, the feature is disabled by default\&.
95 .sp
96 Added in version 257\&.
97 .RE
98 .SH "SPECIFIERS"
99 .PP
100 Specifiers may be used in the
101 \fIDocumentation=\fR
102 and
103 \fIAppStream=\fR
104 settings\&. The following expansions are understood:
105 .sp
106 .it 1 an-trap
107 .nr an-no-space-flag 1
108 .nr an-break-flag 1
109 .br
110 .B Table\ \&1.\ \&Specifiers available
111 .TS
112 allbox tab(:);
113 lB lB lB.
114 T{
115 Specifier
116 T}:T{
117 Meaning
118 T}:T{
119 Details
120 T}
121 .T&
122 l l l
123 l l l
124 l l l
125 l l l
126 l l l
127 l l l
128 l l l
129 l l l
130 l l l
131 l l l
132 l l l
133 l l l
134 l l l
135 l l l
136 l l l.
137 T{
138 "%a"
139 T}:T{
140 Architecture
141 T}:T{
142 A short string identifying the architecture of the local system\&. A string such as \fBx86\fR, \fBx86\-64\fR or \fBarm64\fR\&. See the architectures defined for \fIConditionArchitecture=\fR in \fBsystemd.unit\fR(5) for a full list\&.
143 T}
144 T{
145 "%A"
146 T}:T{
147 Operating system image version
148 T}:T{
149 The operating system image version identifier of the running system, as read from the \fIIMAGE_VERSION=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
150 T}
151 T{
152 "%b"
153 T}:T{
154 Boot ID
155 T}:T{
156 The boot ID of the running system, formatted as string\&. See \fBrandom\fR(4) for more information\&.
157 T}
158 T{
159 "%B"
160 T}:T{
161 Operating system build ID
162 T}:T{
163 The operating system build identifier of the running system, as read from the \fIBUILD_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
164 T}
165 T{
166 "%H"
167 T}:T{
168 Host name
169 T}:T{
170 The hostname of the running system\&.
171 T}
172 T{
173 "%l"
174 T}:T{
175 Short host name
176 T}:T{
177 The hostname of the running system, truncated at the first dot to remove any domain component\&.
178 T}
179 T{
180 "%m"
181 T}:T{
182 Machine ID
183 T}:T{
184 The machine ID of the running system, formatted as string\&. See \fBmachine-id\fR(5) for more information\&.
185 T}
186 T{
187 "%M"
188 T}:T{
189 Operating system image identifier
190 T}:T{
191 The operating system image identifier of the running system, as read from the \fIIMAGE_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
192 T}
193 T{
194 "%o"
195 T}:T{
196 Operating system ID
197 T}:T{
198 The operating system identifier of the running system, as read from the \fIID=\fR field of /etc/os\-release\&. See \fBos-release\fR(5) for more information\&.
199 T}
200 T{
201 "%v"
202 T}:T{
203 Kernel release
204 T}:T{
205 Identical to \fBuname \-r\fR output\&.
206 T}
207 T{
208 "%w"
209 T}:T{
210 Operating system version ID
211 T}:T{
212 The operating system version identifier of the running system, as read from the \fIVERSION_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
213 T}
214 T{
215 "%W"
216 T}:T{
217 Operating system variant ID
218 T}:T{
219 The operating system variant identifier of the running system, as read from the \fIVARIANT_ID=\fR field of /etc/os\-release\&. If not set, resolves to an empty string\&. See \fBos-release\fR(5) for more information\&.
220 T}
221 T{
222 "%T"
223 T}:T{
224 Directory for temporary files
225 T}:T{
226 This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
227 T}
228 T{
229 "%V"
230 T}:T{
231 Directory for larger and persistent temporary files
232 T}:T{
233 This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to\&. (Note that the directory may be specified without a trailing slash\&.)
234 T}
235 T{
236 "%%"
237 T}:T{
238 Single percent sign
239 T}:T{
240 Use "%%" in place of "%" to specify a single percent sign\&.
241 T}
242 .TE
243 .sp 1
244 .SH "EXAMPLES"
245 .PP
246 \fBExample\ \&1.\ \&Development Tools for Image\-Based OS\fR
247 .PP
248 We\*(Aqll use the hypothetical "foobarOS" described in
249 \fBsysupdate.d\fR(5)
250 as our example base OS\&. The vast majority of foobarOS\*(Aqs users have no need for a compiler, build system, debugger, and other such development tools to be part of their OS\&. However, the developers of foobarOS itself need this build tooling to be available\&. So, foobarOS needs to provide a system extension image (see
251 \fBsystemd-sysext\fR(8)) containing these development tools, and this image must be updated in lock\-step with the underlying base OS\&. This is a great use case for an optional OS feature, so let\*(Aqs define one:
252 .PP
253 .if n \{\
254 .RS 4
255 .\}
256 .nf
257 # /usr/lib/sysupdate\&.d/devel\&.feature
258 [Feature]
259 Description=Development Tools
260 Documentation=https://developer\&.example\&.com/foobarOS/getting\-started
261 Enabled=false
262 .fi
263 .if n \{\
264 .RE
265 .\}
266 .PP
267 The above defines the
268 "devel"
269 feature, and disables it by default\&. Now let\*(Aqs define a transfer that\*(Aqs associated with this feature:
270 .PP
271 .if n \{\
272 .RS 4
273 .\}
274 .nf
275 # /usr/lib/sysupdate\&.d/50\-devel\&.transfer
276 [Transfer]
277 Features=devel
278 ProtectVersion=%A
279
280 [Source]
281 Type=url\-file
282 Path=https://download\&.example\&.com/
283 MatchPattern=foobarOS_@v_devel\&.raw\&.xz
284
285 [Target]
286 Type=regular\-file
287 Path=/var/lib/extensions
288 MatchPattern=foobarOS_@v_devel\&.raw
289 Mode=0444
290 InstancesMax=2
291 .fi
292 .if n \{\
293 .RE
294 .\}
295 .PP
296 With these two files, we have created a feature called
297 "devel"
298 that, when enabled, will download and decompress the appropriate version of
299 "https://download\&.example\&.com/foobarOS_@v_devel\&.raw\&.xz"
300 into
301 "/var/lib/extensions/foobarOS_@v_devel\&.raw"
302 during each OS update\&.
303 .PP
304 The developers of foobarOS can enable the
305 "devel"
306 feature on their workstations by creating the following drop\-in:
307 .PP
308 .if n \{\
309 .RS 4
310 .\}
311 .nf
312 # /etc/sysupdate\&.d/devel\&.feature\&.d/enable\&.conf
313 [Feature]
314 Enabled=true
315 .fi
316 .if n \{\
317 .RE
318 .\}
319
320 .PP
321 \fBExample\ \&2.\ \&Proprietary Drivers\fR
322 .PP
323 Suppose that many of foobarOS\*(Aqs users have a GPU manufactured by the MVISUAL corporation\&. Due to lack of documentation and difficulty in reverse\-engineering the hardware, the open\-source drivers for MVISUAL GPUs are unable to make proper use of available graphics and compute performance\&. MVISUAL provides a redistributable proprietary driver for their cards, and foobarOS\*(Aqs developers distribute them to address their users\*(Aq needs\&.
324 .PP
325 MVISUAL\*(Aqs driver has a couple different parts that must be installed for it to function: a UKI addon to configure the kernel command\-line, an initrd system extension image to add the MVISUAL kernel module into the initrd, and a regular system extension image to add the proprietary OpenGL and Vulkan userspace drivers\&. All of these should be version\-locked to the core OS\&.
326 .PP
327 Let\*(Aqs start by defining an optional feature named
328 "mvisual\-driver":
329 .PP
330 .if n \{\
331 .RS 4
332 .\}
333 .nf
334 # /usr/lib/sysupdate\&.d/mvisual\-driver\&.feature
335 [Feature]
336 Description=MVISUAL Proprietary GPU Driver
337 Documentation=https://support\&.example\&.com/foobarOS/mvisual
338 AppStream=https://metadata\&.example\&.com/mvisual\-driver\-%A\&.xml\&.gz
339 .fi
340 .if n \{\
341 .RE
342 .\}
343 .PP
344 Note that we define AppStream metadata for this feature, because we want software centers to present it to end\-users\&. Next, let\*(Aqs define the corresponding transfers:
345 .PP
346 .if n \{\
347 .RS 4
348 .\}
349 .nf
350 # /usr/lib/sysupdate\&.d/50\-mvisual\-userspace\&.transfer
351 [Transfer]
352 Features=mvisual\-driver
353 ProtectVersion=%A
354
355 [Source]
356 Type=url\-file
357 Path=https://download\&.example\&.com/
358 MatchPattern=foobarOS_@v_mvisual_userspace\&.raw\&.xz
359
360 [Target]
361 Type=regular\-file
362 Path=/var/lib/extensions
363 MatchPattern=foobarOS_@v_mvisual\&.raw
364 Mode=0444
365 InstancesMax=2
366 .fi
367 .if n \{\
368 .RE
369 .\}
370 .PP
371 .if n \{\
372 .RS 4
373 .\}
374 .nf
375 # /usr/lib/sysupdate\&.d/70\-mvisual\-initrd\&.transfer
376 [Transfer]
377 Features=mvisual\-driver
378 ProtectVersion=%A
379
380 [Source]
381 Type=url\-file
382 Path=https://download\&.example\&.com/
383 MatchPattern=foobarOS_@v_mvisual_initrd\&.raw\&.xz
384
385 [Target]
386 Type=regular\-file
387 Path=/EFI/Linux
388 PathRelativeTo=boot
389 MatchPattern=foobarOS_@v\&.efi\&.extra\&.d/foobarOS_mvisual\&.raw
390 Mode=0444
391 InstancesMax=2
392 .fi
393 .if n \{\
394 .RE
395 .\}
396 .PP
397 .if n \{\
398 .RS 4
399 .\}
400 .nf
401 # /usr/lib/sysupdate\&.d/90\-mvisual\-addon\&.transfer
402 [Transfer]
403 Features=mvisual\-driver
404 ProtectVersion=%A
405
406 [Source]
407 Type=url\-file
408 Path=https://download\&.example\&.com/
409 MatchPattern=foobarOS_@v_mvisual_addon\&.efi\&.xz
410
411 [Target]
412 Type=regular\-file
413 Path=/EFI/Linux
414 PathRelativeTo=boot
415 MatchPattern=foobarOS_@v\&.efi\&.extra\&.d/foobarOS_mvisual\&.addon\&.efi
416 Mode=0444
417 InstancesMax=2
418 .fi
419 .if n \{\
420 .RE
421 .\}
422
423 .PP
424 \fBExample\ \&3.\ \&Intersecting Features\fR
425 .PP
426 Suppose that MVISUAL releases special tooling to help a distribution developer troubleshoot crashes in their proprietary driver\&. Let\*(Aqs define a transfer:
427 .PP
428 .if n \{\
429 .RS 4
430 .\}
431 .nf
432 # /usr/lib/sysupdate\&.d/50\-mvisual\-debugger\&.transfer
433 [Transfer]
434 RequisiteFeatures=devel mvisual\-driver
435 ProtectVersion=%A
436
437 [Source]
438 Type=url\-file
439 Path=https://download\&.example\&.com/
440 MatchPattern=foobarOS_@v_devel\&.raw\&.xz
441
442 [Target]
443 Type=regular\-file
444 Path=/var/lib/extensions
445 MatchPattern=foobarOS_@v_devel\&.raw
446 Mode=0444
447 InstancesMax=2
448 .fi
449 .if n \{\
450 .RE
451 .\}
452 .PP
453 This transfer will be used only if both the
454 "devel"
455 and
456 "mvisual\-driver"
457 features are enabled\&.
458 .SH "SEE ALSO"
459 .PP
460 \fBsystemd\fR(1), \fBsystemd-sysupdate\fR(8), \fBsysupdate.d\fR(5)
461 .SH "NOTES"
462 .IP " 1." 4
463 AppStream catalog
464 .RS 4
465 \%https://www.freedesktop.org/software/appstream/docs/chap-CatalogData.html
466 .RE