1<?xml version='1.0'?> 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="sysupdate.d" conditional='ENABLE_SYSUPDATE' 7 xmlns:xi="http://www.w3.org/2001/XInclude"> 8 9 <refentryinfo> 10 <title>sysupdate.d</title> 11 <productname>systemd</productname> 12 </refentryinfo> 13 14 <refmeta> 15 <refentrytitle>sysupdate.d</refentrytitle> 16 <manvolnum>5</manvolnum> 17 </refmeta> 18 19 <refnamediv> 20 <refname>sysupdate.d</refname> 21 <refpurpose>Transfer Definition Files for Automatic Updates</refpurpose> 22 </refnamediv> 23 24 <refsynopsisdiv> 25 <para><literallayout><filename>/etc/sysupdate.d/*.conf</filename> 26<filename>/run/sysupdate.d/*.conf</filename> 27<filename>/usr/lib/sysupdate.d/*.conf</filename> 28 </literallayout></para> 29 </refsynopsisdiv> 30 31 <refsect1> 32 <title>Description</title> 33 34 <para><filename>sysupdate.d/*.conf</filename> files describe how specific resources on the local system 35 shall be updated from a remote source. Each such file defines one such transfer: typically a remote 36 HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a 37 simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system 38 extension images — but in fact may be used to update any kind of file from a remote source.</para> 39 40 <para>The 41 <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry> 42 command reads these files and uses them to determine which local resources should be updated, and then 43 executes the update.</para> 44 45 <para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent 46 versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof, 47 e.g. A/B/C, A/B/C/D, …).</para> 48 49 <para>Each <filename>*.conf</filename> file defines one transfer, i.e. describes one resource to 50 update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and 51 are bound together by a common version identifier in order to update multiple resources at once on each 52 update operation, for example to update a kernel, a root file system and a Verity partition in a single, 53 combined, synchronized operation, so that only a combined update of all three together constitutes a 54 complete update.</para> 55 56 <para>Each <filename>*.conf</filename> file contains three sections: [Transfer], [Source] and [Target].</para> 57 </refsect1> 58 59 <refsect1> 60 <title>Basic Mode of Operation</title> 61 62 <para>Disk-image based OS updates typically consist of multiple different resources that need to be 63 updated together, for example a secure OS update might consist of a root file system image to drop into a 64 partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the 65 combination of the two partitions. The first two resources are files that are downloaded and placed in a 66 disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file 67 system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS" 68 to a hypothetical version 47 the following operations should take place:</para> 69 70 <orderedlist> 71 <listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be 72 downloaded, decompressed and written to a previously unused partition with GPT partition type UUID 73 4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink 74 url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions 75 Specification</ulink>.</para></listitem> 76 77 <listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal> 78 should be downloaded, decompressed and written to a previously empty partition with GPT partition type 79 UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e the partition type for Verity integrity information 80 for x86-64 root file systems).</para></listitem> 81 82 <listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi.xz</literal> (a 83 unified kernel, as per <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader 84 Specification</ulink> Type #2) should be downloaded, decompressed and written to the ESP file system, 85 i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP.</para></listitem> 86 </orderedlist> 87 88 <para>The version-independent generalization of this would be (using the special marker 89 <literal>@v</literal> as wildcard for the version identifier):</para> 90 91 <orderedlist> 92 <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.root.xz</literal> 93 → a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to 94 be set to <literal>foobarOS_@v</literal>.</para></listitem> 95 96 <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.verity.xz</literal> 97 → a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be 98 set to <literal>foobarOS_@v_verity</literal>.</para></listitem> 99 100 <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.efi.xz</literal> 101 → a local file <filename>/efi/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem> 102 </orderedlist> 103 104 <para>An update can only complete if the relevant URLs provide their resources for the same version, 105 i.e. for the same value of <literal>@v</literal>.</para> 106 107 <para>The above may be translated into three <filename>*.conf</filename> files in 108 <filename>sysupdate.d/</filename>, one for each resource to transfer. The <filename>*.conf</filename> 109 files configure the type of download, and what place to write the download to (i.e. whether to a 110 partition or a file in the file system). Most importantly these files contain the URL, partition name and 111 filename patterns shown above that describe how these resources are called on the source and how they 112 shall be called on the target.</para> 113 114 <para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is 115 necessary to list suitable files:</para> 116 117 <itemizedlist> 118 <listitem><para>For partitions: the surrounding GPT partition table contains a list of defined 119 partitions, including a partition type UUID and a partition label (in this scheme the partition label 120 plays a role for the partition similar to the filename for a regular file)</para></listitem> 121 122 <listitem><para>For regular files: the directory listing of the directory the files are contained in 123 provides a list of existing files in a straightforward way.</para></listitem> 124 125 <listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file 126 <filename>SHA256SUMS</filename>, following the format defined by <citerefentry 127 project='man-pages'><refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 128 lists file names and their SHA256 hashes.</para></listitem> 129 </itemizedlist> 130 131 <para>Transfers are done in the alphabetical order of the <filename>.conf</filename> file names they are 132 defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once 133 this is completed for all defined transfers, in a second step the files/directories/partitions are 134 renamed to their final names as defined by the target <varname>MatchPattern=</varname>, again in the 135 order the <filename>.conf</filename> transfer file names dictate. This step is not atomic, however it is 136 guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when 137 updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea 138 to order the resources via the transfer configuration file names so that the entry point is written 139 last, ensuring that any abnormal termination does not leave an entry point around whose backing is not 140 established yet. In the example above it would hence make sense to establish the EFI kernel image last 141 and thus give its transfer configuration file the alphabetically last name.</para> 142 143 <para>See below for an extended, more specific example based on the above.</para> 144 </refsect1> 145 146 <refsect1> 147 <title>Resource Types</title> 148 149 <para>Each transfer file defines one source resource to transfer to one target resource. The following 150 resource types are supported:</para> 151 152 <orderedlist> 153 154 <listitem><para>Resources of type <literal>url-file</literal> encapsulate a file on a web server, 155 referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed 156 and then written to the target file or partition. This resource type is only available for sources, not 157 for targets. The list of available versions of resources of this type is encoded in 158 <filename>SHA256SUMS</filename> manifest files, accompanied by 159 <filename>SHA256SUMS.gpg</filename> detached signatures.</para></listitem> 160 161 <listitem><para>The <literal>url-tar</literal> resource type is similar, but the file must be a 162 <filename>.tar</filename> archive. When an update takes place, the file is decompressed and unpacked 163 into a directory or btrfs subvolume. This resource type is only available for sources, not for 164 targets. Just like <literal>url-file</literal>, <literal>url-tar</literal> version enumeration makes 165 use of <filename>SHA256SUMS</filename> files, authenticated via 166 <filename>SHA256SUMS.gpg</filename>.</para></listitem> 167 168 <listitem><para>The <literal>regular-file</literal> resource type encapsulates a local regular file on 169 disk. During updates the file is uncompressed and written to the target file or partition. This 170 resource type is available both as source and as target. When updating no integrity or authentication 171 verification is done for resources of this type.</para></listitem> 172 173 <listitem><para>The <literal>partition</literal> resource type is similar to 174 <literal>regular-file</literal>, and encapsulates a GPT partition on disk. When updating, the partition 175 must exist already, and have the correct GPT partition type. A partition whose GPT partition label is 176 set to <literal>_empty</literal> is considered empty, and a candidate to place a newly downloaded 177 resource in. The GPT partition label is used to store version information, once a partition is 178 updated. This resource type is only available for target resources.</para></listitem> 179 180 <listitem><para>The <literal>tar</literal> resource type encapsulates local <filename>.tar</filename> 181 archive files. When an update takes place, the files are uncompressed and unpacked into a target 182 directory or btrfs subvolume. Behaviour of <literal>tar</literal> and <literal>url-tar</literal> is 183 generally similar, but the latter downloads from remote sources, and does integrity and authentication 184 checks while the former does not. The <literal>tar</literal> resource type is only available for source 185 resources.</para></listitem> 186 187 <listitem><para>The <literal>directory</literal> resource type encapsulates local directory trees. This 188 type is available both for source and target resources. If an update takes place on a source resource 189 of this type, a recursive copy of the directory is done.</para></listitem> 190 191 <listitem><para>The <literal>subvolume</literal> resource type is identical to 192 <literal>directory</literal>, except when used as the target, in which case the file tree is placed in 193 a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is 194 btrfs).</para></listitem> 195 </orderedlist> 196 197 <para>As already indicated, only a subset of source and target resource type combinations are 198 supported:</para> 199 200 <table> 201 <title>Resource Types</title> 202 203 <tgroup cols='3' align='left' colsep='1' rowsep='1'> 204 <colspec colname="name" /> 205 <colspec colname="explanation" /> 206 207 <thead> 208 <row> 209 <entry>Identifier</entry> 210 <entry>Description</entry> 211 <entry>Usable as Source</entry> 212 <entry>When Used as Source: Compatible Targets</entry> 213 <entry>When Used as Source: Integrity + Authentication</entry> 214 <entry>When Used as Source: Decompression</entry> 215 <entry>Usable as Target</entry> 216 <entry>When Used as Target: Compatible Sources</entry> 217 </row> 218 </thead> 219 220 <tbody> 221 <row> 222 <entry><constant>url-file</constant></entry> 223 <entry>HTTP/HTTPS files</entry> 224 <entry>yes</entry> 225 <entry><constant>regular-file</constant>, <constant>partition</constant></entry> 226 <entry>yes</entry> 227 <entry>yes</entry> 228 <entry>no</entry> 229 <entry>-</entry> 230 </row> 231 232 <row> 233 <entry><constant>url-tar</constant></entry> 234 <entry>HTTP/HTTPS <filename>.tar</filename> archives</entry> 235 <entry>yes</entry> 236 <entry><constant>directory</constant>, <constant>subvolume</constant></entry> 237 <entry>yes</entry> 238 <entry>yes</entry> 239 <entry>no</entry> 240 <entry>-</entry> 241 </row> 242 243 <row> 244 <entry><constant>regular-file</constant></entry> 245 <entry>Local files</entry> 246 <entry>yes</entry> 247 <entry><constant>regular-file</constant>, <constant>partition</constant></entry> 248 <entry>no</entry> 249 <entry>yes</entry> 250 <entry>yes</entry> 251 <entry><constant>url-file</constant>, <constant>regular-file</constant></entry> 252 </row> 253 254 <row> 255 <entry><constant>partition</constant></entry> 256 <entry>Local GPT partitions</entry> 257 <entry>no</entry> 258 <entry>-</entry> 259 <entry>-</entry> 260 <entry>-</entry> 261 <entry>yes</entry> 262 <entry><constant>url-file</constant>, <constant>regular-file</constant></entry> 263 </row> 264 265 <row> 266 <entry><constant>tar</constant></entry> 267 <entry>Local <filename>.tar</filename> archives</entry> 268 <entry>yes</entry> 269 <entry><constant>directory</constant>, <constant>subvolume</constant></entry> 270 <entry>no</entry> 271 <entry>yes</entry> 272 <entry>no</entry> 273 <entry>-</entry> 274 </row> 275 276 <row> 277 <entry><constant>directory</constant></entry> 278 <entry>Local directories</entry> 279 <entry>yes</entry> 280 <entry><constant>directory</constant>, <constant>subvolume</constant></entry> 281 <entry>no</entry> 282 <entry>no</entry> 283 <entry>yes</entry> 284 <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry> 285 </row> 286 287 <row> 288 <entry><constant>subvolume</constant></entry> 289 <entry>Local btrfs subvolumes</entry> 290 <entry>yes</entry> 291 <entry><constant>directory</constant>, <constant>subvolume</constant></entry> 292 <entry>no</entry> 293 <entry>no</entry> 294 <entry>yes</entry> 295 <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry> 296 </row> 297 298 </tbody> 299 </tgroup> 300 </table> 301 </refsect1> 302 303 <refsect1> 304 <title>Match Patterns</title> 305 306 <para>Both the source and target resources typically exist in multiple versions concurrently. An update 307 operation is done whenever the newest of the source versions is newer than the newest of the target 308 versions. To determine the newest version of the resources a directory listing, partition listing or 309 manifest listing is used, a subset of qualifying entries selected from that, and the version identifier 310 extracted from the file names or partition labels of these selected entries. Subset selection and 311 extraction of the version identifier (plus potentially other metadata) is done via match patterns, 312 configured in <varname>MatchPattern=</varname> in the [Source] and [Target] sections. These patterns are 313 strings that describe how files or partitions are named, with named wildcards for specific fields such as 314 the version identifier. The following wildcards are defined:</para> 315 316 <table> 317 <title>Match Pattern Wildcards</title> 318 319 <tgroup cols='2' align='left' colsep='1' rowsep='1'> 320 <colspec colname="name" /> 321 <colspec colname="explanation" /> 322 323 <thead> 324 <row> 325 <entry>Wildcard</entry> 326 <entry>Description</entry> 327 <entry>Format</entry> 328 <entry>Notes</entry> 329 </row> 330 </thead> 331 332 <tbody> 333 <row> 334 <entry><literal>@v</literal></entry> 335 <entry>Version identifier</entry> 336 <entry>Valid version string</entry> 337 <entry>Mandatory</entry> 338 </row> 339 340 <row> 341 <entry><literal>@u</literal></entry> 342 <entry>GPT partition UUID</entry> 343 <entry>Valid 128-Bit UUID string</entry> 344 <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry> 345 </row> 346 347 <row> 348 <entry><literal>@f</literal></entry> 349 <entry>GPT partition flags</entry> 350 <entry>Formatted hexadecimal integer</entry> 351 <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry> 352 </row> 353 354 <row> 355 <entry><literal>@a</literal></entry> 356 <entry>GPT partition flag NoAuto</entry> 357 <entry>Either <literal>0</literal> or <literal>1</literal></entry> 358 <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry> 359 </row> 360 361 <row> 362 <entry><literal>@g</literal></entry> 363 <entry>GPT partition flag GrowFileSystem</entry> 364 <entry>Either <literal>0</literal> or <literal>1</literal></entry> 365 <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry> 366 </row> 367 368 <row> 369 <entry><literal>@r</literal></entry> 370 <entry>Read-only flag</entry> 371 <entry>Either <literal>0</literal> or <literal>1</literal></entry> 372 <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below.</entry> 373 </row> 374 375 <row> 376 <entry><literal>@t</literal></entry> 377 <entry>File modification time</entry> 378 <entry>Formatted decimal integer, µs since UNIX epoch Jan 1st 1970</entry> 379 <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry> 380 </row> 381 382 <row> 383 <entry><literal>@m</literal></entry> 384 <entry>File access mode</entry> 385 <entry>Formatted octal integer, in UNIX fashion</entry> 386 <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry> 387 </row> 388 389 <row> 390 <entry><literal>@s</literal></entry> 391 <entry>File size after decompression</entry> 392 <entry>Formatted decimal integer</entry> 393 <entry>Useful for measuring progress and to improve partition allocation logic</entry> 394 </row> 395 396 <row> 397 <entry><literal>@d</literal></entry> 398 <entry>Tries done</entry> 399 <entry>Formatted decimal integer</entry> 400 <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry> 401 </row> 402 403 <row> 404 <entry><literal>@l</literal></entry> 405 <entry>Tries left</entry> 406 <entry>Formatted decimal integer</entry> 407 <entry>Useful when operating with kernel images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry> 408 </row> 409 410 <row> 411 <entry><literal>@h</literal></entry> 412 <entry>SHA256 hash of compressed file</entry> 413 <entry>64 hexadecimal characters</entry> 414 <entry>The SHA256 hash of the compressed file; not useful for <constant>url-file</constant> or <constant>url-tar</constant> where the SHA256 hash is already included in the manifest file anyway.</entry> 415 </row> 416 </tbody> 417 </tgroup> 418 </table> 419 420 <para>Of these wildcards only <literal>@v</literal> must be present in a valid pattern, all other 421 wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard 422 matching a file system source image could be <literal>MatchPattern=foobar_@v.raw.xz</literal>, i.e. any file 423 whose name begins with <literal>foobar_</literal>, followed by a version ID and suffixed by 424 <literal>.raw.xz</literal>.</para> 425 426 <para>Do not confuse the <literal>@</literal> pattern matching wildcard prefix with the 427 <literal>%</literal> specifier expansion prefix. The former encapsulate a variable part of a match 428 pattern string, the latter are simple shortcuts that are expanded while the drop-in files are 429 parsed. For details about specifiers, see below.</para> 430 </refsect1> 431 432 <refsect1> 433 <title>[Transfer] Section Options</title> 434 435 <para>This section defines general properties of this transfer.</para> 436 437 <variablelist> 438 <varlistentry> 439 <term><varname>MinVersion=</varname></term> 440 441 <listitem><para>Specifies the minimum version to require for this transfer to take place. If the 442 source or target patterns in this transfer definition match files older than this version they will 443 be considered obsolete, and never be considered for the update operation.</para></listitem> 444 </varlistentry> 445 446 <varlistentry> 447 <term><varname>ProtectVersion=</varname></term> 448 449 <listitem><para>Takes one or more version strings to mark as "protected". Protected versions are 450 never removed while making room for new, updated versions. This is useful to ensure that the 451 currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten 452 during updates, in order to avoid runtime file system corruptions.</para> 453 454 <para>Like many of the settings in these configuration files this setting supports specifier 455 expansion. It's particularly useful to set this setting to one of the <literal>%A</literal>, 456 <literal>%B</literal> or <literal>%w</literal> specifiers to automatically refer to the current OS 457 version of the running system. See below for details on supported specifiers.</para></listitem> 458 </varlistentry> 459 460 <varlistentry> 461 <term><varname>Verify=</varname></term> 462 463 <listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify 464 downloaded resources (specifically: validate the GPG signatures for downloaded 465 <filename>SHA256SUMS</filename> manifest files, via their detached signature files 466 <filename>SHA256SUMS.gpg</filename> in combination with the system keyring 467 <filename>/usr/lib/systemd/import-pubring.gpg</filename> or 468 <filename>/etc/systemd/import-pubring.gpg</filename>).</para> 469 470 <para>This option is essential to provide integrity guarantees for downloaded resources and thus 471 should be left enabled, outside of test environments.</para> 472 473 <para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes 474 listed in the manifest. This option only controls whether the signatures of these manifests are 475 verified.</para> 476 477 <para>This option only has an effect if the source resource type is selected as 478 <constant>url-file</constant> or <constant>url-tar</constant>, as integrity and authentication 479 checking is only available for transfers from remote sources.</para></listitem> 480 </varlistentry> 481 482 </variablelist> 483 </refsect1> 484 485 <refsect1> 486 <title>[Source] Section Options</title> 487 488 <para>This section defines properties of the transfer source:</para> 489 490 <variablelist> 491 <varlistentry> 492 <term><varname>Type=</varname></term> 493 494 <listitem><para>Specifies the resource type of the source for the transfer. Takes one of 495 <constant>url-file</constant>, <constant>url-tar</constant>, <constant>tar</constant>, 496 <constant>regular-file</constant>, <constant>directory</constant> or 497 <constant>subvolume</constant>. For details about the resource types, see above. This option is 498 mandatory.</para> 499 500 <para>Note that only some combinations of source and target resource types are supported, see 501 above.</para></listitem> 502 </varlistentry> 503 </variablelist> 504 505 <variablelist> 506 <varlistentry> 507 <term><varname>Path=</varname></term> 508 509 <listitem><para>Specifies where to find source versions of this resource.</para> 510 511 <para>If the source type is selected as <constant>url-file</constant> or 512 <constant>url-tar</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with 513 <filename>/SHA256SUMS</filename> to acquire the manifest file, with 514 <filename>/SHA256SUMS.gpg</filename> to acquire the detached signature file for it, and with the file 515 names listed in the manifest file in case an update is executed and a resource shall be 516 downloaded.</para> 517 518 <para>For all other source resource types this must be a local path in the file system, referring to 519 a local directory to find the versions of this resource in.</para></listitem> 520 </varlistentry> 521 522 <varlistentry> 523 <term><varname>MatchPattern=</varname></term> 524 525 <listitem><para>Specifies one or more file name match patterns that select the subset of files that 526 are update candidates as source for this transfer. See above for details on match patterns.</para> 527 528 <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal> 529 wildcard, so that a version identifier may be extracted from the filename. All other wildcards are 530 optional.</para></listitem> 531 </varlistentry> 532 </variablelist> 533 </refsect1> 534 535 <refsect1> 536 <title>[Target] Section Options</title> 537 538 <para>This section defines properties of the transfer target:</para> 539 540 <variablelist> 541 <varlistentry> 542 <term><varname>Type=</varname></term> 543 544 <listitem><para>Specifies the resource type of the target for the transfer. Takes one of 545 <constant>partition</constant>, <constant>regular-file</constant>, <constant>directory</constant> or 546 <constant>subvolume</constant>. For details about the resource types, see above. This option is 547 mandatory.</para> 548 549 <para>Note that only some combinations of source and target resource types are supported, see above.</para></listitem> 550 </varlistentry> 551 552 <varlistentry> 553 <term><varname>Path=</varname></term> 554 555 <listitem><para>Specifies a file system path where to look for already installed versions or place 556 newly downloaded versions of this configured resource. If <varname>Type=</varname> is set to 557 <constant>partition</constant>, expects a path to a (whole) block device node, or the special string 558 <literal>auto</literal> in which case the block device the root file system of the currently booted 559 system is automatically determined and used. If <varname>Type=</varname> is set to 560 <constant>regular-file</constant>, <constant>directory</constant> or <constant>subvolume</constant>, 561 must refer to a path in the local file system referencing the directory to find or place the version 562 files or directories under.</para> 563 564 <para>Note that this mechanism cannot be used to create or remove partitions, in case 565 <varname>Type=</varname> is set to <constant>partition</constant>. Partitions must exist already, and 566 a special partition label <literal>_empty</literal> is used to indicate empty partitions. To 567 automatically generate suitable partitions on first boot, use a tool such as 568 <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> 569 </varlistentry> 570 571 <varlistentry> 572 <term><varname>MatchPattern=</varname></term> 573 574 <listitem><para>Specifies one or more file name or partition label match patterns that select the 575 subset of files or partitions that are update candidates as targets for this transfer. See above for 576 details on match patterns.</para> 577 578 <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal> 579 wildcard, so that a version identifier may be extracted from the filename. All other wildcards are 580 optional.</para> 581 582 <para>This pattern is both used for matching existing installed versions and for determining the name 583 of new versions to install. If multiple patterns are specified, the first specified is used for 584 naming newly installed versions.</para></listitem> 585 </varlistentry> 586 587 <varlistentry> 588 <term><varname>MatchPartitionType=</varname></term> 589 590 <listitem><para>When the target <varname>Type=</varname> is chosen as <constant>partition</constant>, 591 specifies the GPT partition type to look for. Only partitions of this type are considered, all other 592 partitions are ignored. If not specified, the GPT partition type <constant>linux-generic</constant> 593 is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported 594 type identifiers, see the <varname>Type=</varname> setting in 595 <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem> 596 </varlistentry> 597 598 <varlistentry> 599 <term><varname>PartitionUUID=</varname></term> 600 <term><varname>PartitionFlags=</varname></term> 601 <term><varname>PartitionNoAuto=</varname></term> 602 <term><varname>PartitionGrowFileSystem=</varname></term> 603 604 <listitem><para>When the target <varname>Type=</varname> is picked as <constant>partition</constant>, 605 selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid 606 UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match 607 pattern includes wildcards for these fields (i.e. <literal>@u</literal>, <literal>@f</literal>, 608 <literal>@a</literal>, or <literal>@g</literal>), the values from the patterns are used. If neither 609 configured with wildcards or these explicit settings, the values are left untouched. If both the 610 overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings 611 <varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the 612 wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the 613 overall flags value. See <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable 614 Partitions Specification</ulink> for details about these flags.</para> 615 616 <para>Note that these settings are not used for matching, they only have effect on newly written 617 partitions in case a transfer takes place.</para></listitem> 618 </varlistentry> 619 620 <varlistentry> 621 <term><varname>ReadOnly=</varname></term> 622 623 <listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the 624 target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per 625 <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions 626 Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and 627 <varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is 628 <constant>regular-file</constant>, the writable bit is removed from the access mode. If the the 629 target type is <constant>subvolume</constant>, the subvolume will be marked read-only as a 630 whole. Finally, if the target <varname>Type=</varname> is selected as <constant>directory</constant>, 631 the "immutable" file attribute is set, see <citerefentry 632 project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> for 633 details.</para></listitem> 634 </varlistentry> 635 636 <varlistentry> 637 <term><varname>Mode=</varname></term> 638 639 <listitem><para>The UNIX file access mode to use for newly created files in case the target resource 640 type is picked as <constant>regular-file</constant>. Expects an octal integer, in typical UNIX 641 fashion. If not set, but the source match pattern includes a wildcard for this field 642 (i.e. <literal>@t</literal>), the value from the pattern is used.</para> 643 644 <para>Note that this setting is not used for matching, it only has an effect on newly written 645 files when a transfer takes place.</para></listitem> 646 </varlistentry> 647 648 <varlistentry> 649 <term><varname>TriesDone=</varname></term> 650 <term><varname>TriesLeft=</varname></term> 651 652 <listitem><para>These options take positive, decimal integers, and control the number of attempts 653 done and left for this file. These settings are useful for managing kernel images, following the 654 scheme defined in <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot 655 Assessment</ulink>, and only have an effect if the target pattern includes the <literal>@d</literal> 656 or <literal>@l</literal> wildcards.</para></listitem> 657 </varlistentry> 658 659 <varlistentry> 660 <term><varname>InstancesMax=</varname></term> 661 662 <listitem><para>Takes a decimal integer equal to or greater than 2. This configures how many concurrent 663 versions of the resource to keep. Whenever a new update is initiated it is made sure that no more 664 than the number of versions specified here minus one exist in the target. Any excess versions are 665 deleted (in case the target <varname>Type=</varname> of <constant>regular-file</constant>, 666 <constant>directory</constant>, <constant>subvolume</constant> is used) or emptied (in case the 667 target <varname>Type=</varname> of <constant>partition</constant> is used; emptying in this case 668 simply means to set the partition label to the special string <literal>_empty</literal>; note that no 669 partitions are actually removed). After an update is completed the number of concurrent versions of 670 the target resources is equal to or below the number specified here.</para> 671 672 <para>Note that this setting may be set differently for each transfer. However, it generally is 673 advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of 674 files or partitions will be left installed.</para> 675 676 <para>If the target <varname>Type=</varname> is selected as <constant>partition</constant>, the number 677 of concurrent versions to keep is additionally restricted by the number of partition slots of the 678 right type in the partition table. i.e. if there are only 2 partition slots for the selected 679 partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent 680 versions could be stored in the image anyway.</para></listitem> 681 </varlistentry> 682 683 <varlistentry> 684 <term><varname>RemoveTemporary=</varname></term> 685 686 <listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before 687 initiating an update, all left-over, incomplete updates from a previous attempt are removed from the 688 target directory. This only has an effect if the target resource <varname>Type=</varname> is selected 689 as <constant>regular-file</constant>, <constant>directory</constant> or 690 <constant>subvolume</constant>.</para></listitem> 691 </varlistentry> 692 693 <varlistentry> 694 <term><varname>CurrentSymlink=</varname></term> 695 696 <listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the 697 update a symlink under the specified name is created/updated pointing to the completed update. This 698 is useful in to provide a stable name always pointing to the newest version of the resource. This is 699 only supported if the target resource <varname>Type=</varname> is selected as 700 <constant>regular-file</constant>, <constant>directory</constant> or 701 <constant>subvolume</constant>.</para></listitem> 702 </varlistentry> 703 704 </variablelist> 705 </refsect1> 706 707 <refsect1> 708 <title>Specifiers</title> 709 710 <para>Specifiers may be used in the <varname>MinVersion=</varname>, <varname>ProtectVersion=</varname>, 711 <varname>Path=</varname>, <varname>MatchPattern=</varname> and <varname>CurrentSymlink=</varname> 712 settings. The following expansions are understood:</para> 713 <table class='specifiers'> 714 <title>Specifiers available</title> 715 <tgroup cols='3' align='left' colsep='1' rowsep='1'> 716 <colspec colname="spec" /> 717 <colspec colname="mean" /> 718 <colspec colname="detail" /> 719 <thead> 720 <row> 721 <entry>Specifier</entry> 722 <entry>Meaning</entry> 723 <entry>Details</entry> 724 </row> 725 </thead> 726 <tbody> 727 <xi:include href="standard-specifiers.xml" xpointer="a"/> 728 <xi:include href="standard-specifiers.xml" xpointer="A"/> 729 <xi:include href="standard-specifiers.xml" xpointer="b"/> 730 <xi:include href="standard-specifiers.xml" xpointer="B"/> 731 <xi:include href="standard-specifiers.xml" xpointer="H"/> 732 <xi:include href="standard-specifiers.xml" xpointer="l"/> 733 <xi:include href="standard-specifiers.xml" xpointer="m"/> 734 <xi:include href="standard-specifiers.xml" xpointer="M"/> 735 <xi:include href="standard-specifiers.xml" xpointer="o"/> 736 <xi:include href="standard-specifiers.xml" xpointer="v"/> 737 <xi:include href="standard-specifiers.xml" xpointer="w"/> 738 <xi:include href="standard-specifiers.xml" xpointer="W"/> 739 <xi:include href="standard-specifiers.xml" xpointer="T"/> 740 <xi:include href="standard-specifiers.xml" xpointer="V"/> 741 <xi:include href="standard-specifiers.xml" xpointer="percent"/> 742 </tbody> 743 </tgroup> 744 </table> 745 746 <para>Do not confuse the <literal>%</literal> specifier expansion prefix with the <literal>@</literal> 747 pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in 748 files are parsed, the latter encapsulate a variable part of a match pattern string. For details about 749 pattern matching wildcards, see above.</para> 750 </refsect1> 751 752 <refsect1> 753 <title>Examples</title> 754 755 <example> 756 <title>Updates for a Verity Enabled Secure OS</title> 757 758 <para>With the following three files we define a root file system partition, a matching Verity 759 partition, and a unified kernel image to update as one. This example is an extension of the example 760 discussed earlier in this man page.</para> 761 762 <para><programlisting># /usr/lib/sysupdate.d/50-verity.conf 763[Transfer] 764ProtectVersion=%A 765 766[Source] 767Type=url-file 768Path=https://download.example.com/ 769MatchPattern=foobarOS_@v_@u.verity.xz 770 771[Target] 772Type=partition 773Path=auto 774MatchPattern=foobarOS_@v_verity 775MatchPartitionType=root-verity 776PartitionFlags=0 777PartitionReadOnly=1</programlisting></para> 778 779 <para>The above defines the update mechanism for the Verity partition of the root file system. Verity 780 partition images are downloaded from 781 <literal>https://download.example.com/foobarOS_@v_@u.verity.xz</literal> and written to a suitable 782 local partition, which is marked read-only. Under the assumption this update is run from the image 783 itself the current image version (i.e. the <literal>%A</literal> specifier) is marked as protected, to 784 ensure it is not corrupted while booted. Note that the partition UUID for the target partition is 785 encoded in the source file name. Fixating the partition UUID can be useful to ensure that 786 <literal>roothash=</literal> on the kernel command line is sufficient to pinpoint both the Verity and 787 root file system partition, and also encode the Verity root level hash (under the assumption the UUID 788 in the file names match their top-level hash, the way 789 <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> 790 suggests).</para> 791 792 <para><programlisting># /usr/lib/sysupdate.d/60-root.conf 793[Transfer] 794ProtectVersion=%A 795 796[Source] 797Type=url-file 798Path=https://download.example.com/ 799MatchPattern=foobarOS_@v_@u.root.xz 800 801[Target] 802Type=partition 803Path=auto 804MatchPattern=foobarOS_@v 805MatchPartitionType=root 806PartitionFlags=0 807PartitionReadOnly=1</programlisting></para> 808 809 <para>The above defines a matching transfer definition for the root file system.</para> 810 811 <para><programlisting># /usr/lib/sysupdate.d/70-kernel.conf 812[Transfer] 813ProtectVersion=%A 814 815[Source] 816Type=url-file 817Path=https://download.example.com/ 818MatchPattern=foobarOS_@v.efi.xz 819 820[Target] 821Type=file 822Path=/efi/EFI/Linux 823MatchPattern=foobarOS_@v+@l-@d.efi \ 824 foobarOS_@v+@l.efi \ 825 foobarOS_@v.efi 826Mode=0444 827TriesLeft=3 828TriesDone=0 829InstancesMax=2</programlisting></para> 830 831 <para>The above installs a unified kernel image into the ESP (which is mounted to 832 <filename>/efi/</filename>), as per <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot 833 Loader Specification</ulink> Type #2. This defines three possible patterns for the names of the 834 kernel images images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot 835 Assessment</ulink>, and ensures when installing new kernels, they are set up with 3 tries left. No 836 more than two parallel kernels are kept.</para> 837 838 <para>With this setup the web server would serve the following files, for a hypothetical version 7 of 839 the OS:</para> 840 841 <itemizedlist> 842 <listitem><para><filename>SHA256SUMS</filename> – The manifest file, containing available files and their SHA256 hashes</para></listitem> 843 <listitem><para><filename>SHA256SUMS.gpg</filename> – The detached cryptographic signature for the manifest file</para></listitem> 844 <listitem><para><filename>foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz</filename> – The Verity image for version 7</para></listitem> 845 <listitem><para><filename>foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz</filename> – The root file system image for version 7</para></listitem> 846 <listitem><para><filename>foobarOS_7_efi.xz</filename> – The unified kernel image for version 7</para></listitem> 847 </itemizedlist> 848 849 <para>For each new OS release a new set of the latter three files would be added, each time with an 850 updated version. The <filename>SHA256SUMS</filename> manifest should then be updated accordingly, 851 listing all files for all versions that shall be offered for download.</para> 852 </example> 853 854 <example> 855 <title>Updates for Plain Directory Container Image</title> 856 857 <para><programlisting> 858[Source] 859Type=url-tar 860Path=https://download.example.com/ 861MatchPattern=myContainer_@v.tar.gz 862 863[Target] 864Type=subvolume 865Path=/var/lib/machines 866MatchPattern=myContainer_@v 867CurrentSymlink=myContainer</programlisting></para> 868 869 <para>On updates this downloads <literal>https://download.example.com/myContainer_@v.tar.gz</literal> 870 and decompresses/unpacks it to <filename>/var/lib/machines/myContainer_@v</filename>. After each update 871 a symlink <filename>/var/lib/machines/myContainer</filename> is created/updated always pointing to the 872 most recent update.</para> 873 </example> 874 </refsect1> 875 876 <refsect1> 877 <title>See Also</title> 878 <para> 879 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 880 <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 881 <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry> 882 </para> 883 </refsect1> 884 885</refentry> 886