summaryrefslogtreecommitdiffstats
path: root/man/sysupdate.d.xml
blob: 1987e649ae6f6d18a465bdaa22e551dcc6315420 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
<?xml version='1.0'?>
<!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="sysupdate.d" conditional='ENABLE_SYSUPDATE'
          xmlns:xi="http://www.w3.org/2001/XInclude">

  <refentryinfo>
    <title>sysupdate.d</title>
    <productname>systemd</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>sysupdate.d</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>sysupdate.d</refname>
    <refpurpose>Transfer Definition Files for Automatic Updates</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><literallayout><filename>/etc/sysupdate.d/*.conf</filename>
<filename>/run/sysupdate.d/*.conf</filename>
<filename>/usr/lib/sysupdate.d/*.conf</filename>
    </literallayout></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><filename>sysupdate.d/*.conf</filename> files describe how specific resources on the local system
    shall be updated from a remote source. Each such file defines one such transfer: typically a remote
    HTTP/HTTPS resource as source; and a local file, directory or partition as target. This may be used as a
    simple, automatic, atomic update mechanism for the OS itself, for containers, portable services or system
    extension images  but in fact may be used to update any kind of file from a remote source.</para>

    <para>The
    <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    command reads these files and uses them to determine which local resources should be updated, and then
    executes the update.</para>

    <para>Both the remote HTTP/HTTPS source and the local target typically exist in multiple, concurrent
    versions, in order to implement flexible update schemes, e.g. A/B updating (or a superset thereof,
    e.g. A/B/C, A/B/C/D, …).</para>

    <para>Each <filename>*.conf</filename> file defines one transfer, i.e. describes one resource to
    update. Typically, multiple of these files (i.e. multiple of such transfers) are defined together, and
    are bound together by a common version identifier in order to update multiple resources at once on each
    update operation, for example to update a kernel, a root file system and a Verity partition in a single,
    combined, synchronized operation, so that only a combined update of all three together constitutes a
    complete update.</para>

    <para>Each <filename>*.conf</filename> file contains three sections: [Transfer], [Source] and [Target].</para>
  </refsect1>

  <refsect1>
    <title>Basic Mode of Operation</title>

    <para>Disk-image based OS updates typically consist of multiple different resources that need to be
    updated together, for example a secure OS update might consist of a root file system image to drop into a
    partition, a matching Verity integrity data partition image, and a kernel image prepared to boot into the
    combination of the two partitions. The first two resources are files that are downloaded and placed in a
    disk partition, the latter is a file that is downloaded and placed in a regular file in the boot file
    system (e.g. EFI system partition). Hence, during an update of a hypothetical operating system "foobarOS"
    to a hypothetical version 47 the following operations should take place:</para>

    <orderedlist>
      <listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be
      downloaded, decompressed and written to a previously unused partition with GPT partition type UUID
      4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink
      url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
      Specification</ulink>.</para></listitem>

      <listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal>
      should be downloaded, decompressed and written to a previously empty partition with GPT partition type
      UUID of 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5 (i.e. the partition type for Verity integrity information
      for x86-64 root file systems).</para></listitem>

      <listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi.xz</literal> (a
      unified kernel, as per <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
      Specification</ulink> Type #2) should be downloaded, decompressed and written to the $BOOT file system,
      i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP or XBOOTLDR partition.</para></listitem>
    </orderedlist>

    <para>The version-independent generalization of this would be (using the special marker
    <literal>@v</literal> as wildcard for the version identifier):</para>

    <orderedlist>
      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.root.xz</literal>
       a local, previously empty GPT partition of type 4f68bce3-e8cd-4db1-96e7-fbcaf984b709, with the label to
      be set to <literal>foobarOS_@v</literal>.</para></listitem>

      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.verity.xz</literal>
       a local, previously empty GPT partition of type 2c7357ed-ebd2-46d9-aec1-23d437ec2bf5, with the label to be
      set to <literal>foobarOS_@v_verity</literal>.</para></listitem>

      <listitem><para>A transfer of a file <literal>https://download.example.com/foobarOS_@v.efi.xz</literal>
       a local file <filename>$BOOT/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem>
    </orderedlist>

    <para>An update can only complete if the relevant URLs provide their resources for the same version,
    i.e. for the same value of <literal>@v</literal>.</para>

    <para>The above may be translated into three <filename>*.conf</filename> files in
    <filename>sysupdate.d/</filename>, one for each resource to transfer. The <filename>*.conf</filename>
    files configure the type of download, and what place to write the download to (i.e. whether to a
    partition or a file in the file system). Most importantly these files contain the URL, partition name and
    filename patterns shown above that describe how these resources are called on the source and how they
    shall be called on the target.</para>

    <para>In order to enumerate available versions and figuring out candidates to update to, a mechanism is
    necessary to list suitable files:</para>

    <itemizedlist>
      <listitem><para>For partitions: the surrounding GPT partition table contains a list of defined
      partitions, including a partition type UUID and a partition label (in this scheme the partition label
      plays a role for the partition similar to the filename for a regular file).</para></listitem>

      <listitem><para>For regular files: the directory listing of the directory the files are contained in
      provides a list of existing files in a straightforward way.</para></listitem>

      <listitem><para>For HTTP/HTTPS sources a simple scheme is used: a manifest file
      <filename>SHA256SUMS</filename>, following the format defined by <citerefentry
      project='man-pages'><refentrytitle>sha256sum</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      lists file names and their SHA256 hashes.</para></listitem>
    </itemizedlist>

    <para>Transfers are done in the alphabetical order of the <filename>.conf</filename> file names they are
    defined in. First, the resource data is downloaded directly into a target file/directory/partition. Once
    this is completed for all defined transfers, in a second step the files/directories/partitions are
    renamed to their final names as defined by the target <varname>MatchPattern=</varname>, again in the
    order the <filename>.conf</filename> transfer file names dictate. This step is not atomic, however it is
    guaranteed to be executed strictly in order with suitable disk synchronization in place. Typically, when
    updating an OS one of the transfers defines the entry point when booting. Thus it is generally a good idea
    to order the resources via the transfer configuration file names so that the entry point is written
    last, ensuring that any abnormal termination does not leave an entry point around whose backing is not
    established yet. In the example above it would hence make sense to establish the EFI kernel image last
    and thus give its transfer configuration file the alphabetically last name.</para>

    <para>See below for an extended, more specific example based on the above.</para>
  </refsect1>

  <refsect1>
    <title>Resource Types</title>

    <para>Each transfer file defines one source resource to transfer to one target resource. The following
    resource types are supported:</para>

    <orderedlist>

      <listitem><para>Resources of type <literal>url-file</literal> encapsulate a file on a web server,
      referenced via a HTTP or HTTPS URL. When an update takes place, the file is downloaded and decompressed
      and then written to the target file or partition. This resource type is only available for sources, not
      for targets. The list of available versions of resources of this type is encoded in
      <filename>SHA256SUMS</filename> manifest files, accompanied by
      <filename>SHA256SUMS.gpg</filename> detached signatures.</para></listitem>

      <listitem><para>The <literal>url-tar</literal> resource type is similar, but the file must be a
      <filename>.tar</filename> archive. When an update takes place, the file is decompressed and unpacked
      into a directory or btrfs subvolume. This resource type is only available for sources, not for
      targets. Just like <literal>url-file</literal>, <literal>url-tar</literal> version enumeration makes
      use of <filename>SHA256SUMS</filename> files, authenticated via
      <filename>SHA256SUMS.gpg</filename>.</para></listitem>

      <listitem><para>The <literal>regular-file</literal> resource type encapsulates a local regular file on
      disk. During updates the file is uncompressed and written to the target file or partition. This
      resource type is available both as source and as target. When updating no integrity or authentication
      verification is done for resources of this type.</para></listitem>

      <listitem><para>The <literal>partition</literal> resource type is similar to
      <literal>regular-file</literal>, and encapsulates a GPT partition on disk. When updating, the partition
      must exist already, and have the correct GPT partition type. A partition whose GPT partition label is
      set to <literal>_empty</literal> is considered empty, and a candidate to place a newly downloaded
      resource in. The GPT partition label is used to store version information, once a partition is
      updated. This resource type is only available for target resources.</para></listitem>

      <listitem><para>The <literal>tar</literal> resource type encapsulates local <filename>.tar</filename>
      archive files. When an update takes place, the files are uncompressed and unpacked into a target
      directory or btrfs subvolume. Behaviour of <literal>tar</literal> and <literal>url-tar</literal> is
      generally similar, but the latter downloads from remote sources, and does integrity and authentication
      checks while the former does not. The <literal>tar</literal> resource type is only available for source
      resources.</para></listitem>

      <listitem><para>The <literal>directory</literal> resource type encapsulates local directory trees. This
      type is available both for source and target resources. If an update takes place on a source resource
      of this type, a recursive copy of the directory is done.</para></listitem>

      <listitem><para>The <literal>subvolume</literal> resource type is identical to
      <literal>directory</literal>, except when used as the target, in which case the file tree is placed in
      a btrfs subvolume instead of a plain directory, if the backing file system supports it (i.e. is
      btrfs).</para></listitem>
    </orderedlist>

    <para>As already indicated, only a subset of source and target resource type combinations are
    supported:</para>

    <table>
      <title>Resource Types</title>

      <tgroup cols='3' align='left' colsep='1' rowsep='1'>
        <colspec colname="name" />
        <colspec colname="explanation" />

        <thead>
          <row>
            <entry>Identifier</entry>
            <entry>Description</entry>
            <entry>Usable as Source</entry>
            <entry>When Used as Source: Compatible Targets</entry>
            <entry>When Used as Source: Integrity + Authentication</entry>
            <entry>When Used as Source: Decompression</entry>
            <entry>Usable as Target</entry>
            <entry>When Used as Target: Compatible Sources</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><constant>url-file</constant></entry>
            <entry>HTTP/HTTPS files</entry>
            <entry>yes</entry>
            <entry><constant>regular-file</constant>, <constant>partition</constant></entry>
            <entry>yes</entry>
            <entry>yes</entry>
            <entry>no</entry>
            <entry>-</entry>
          </row>

          <row>
            <entry><constant>url-tar</constant></entry>
            <entry>HTTP/HTTPS <filename>.tar</filename> archives</entry>
            <entry>yes</entry>
            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
            <entry>yes</entry>
            <entry>yes</entry>
            <entry>no</entry>
            <entry>-</entry>
          </row>

          <row>
            <entry><constant>regular-file</constant></entry>
            <entry>Local files</entry>
            <entry>yes</entry>
            <entry><constant>regular-file</constant>, <constant>partition</constant></entry>
            <entry>no</entry>
            <entry>yes</entry>
            <entry>yes</entry>
            <entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
          </row>

          <row>
            <entry><constant>partition</constant></entry>
            <entry>Local GPT partitions</entry>
            <entry>no</entry>
            <entry>-</entry>
            <entry>-</entry>
            <entry>-</entry>
            <entry>yes</entry>
            <entry><constant>url-file</constant>, <constant>regular-file</constant></entry>
          </row>

          <row>
            <entry><constant>tar</constant></entry>
            <entry>Local <filename>.tar</filename> archives</entry>
            <entry>yes</entry>
            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
            <entry>no</entry>
            <entry>yes</entry>
            <entry>no</entry>
            <entry>-</entry>
          </row>

          <row>
            <entry><constant>directory</constant></entry>
            <entry>Local directories</entry>
            <entry>yes</entry>
            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
            <entry>no</entry>
            <entry>no</entry>
            <entry>yes</entry>
            <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
          </row>

          <row>
            <entry><constant>subvolume</constant></entry>
            <entry>Local btrfs subvolumes</entry>
            <entry>yes</entry>
            <entry><constant>directory</constant>, <constant>subvolume</constant></entry>
            <entry>no</entry>
            <entry>no</entry>
            <entry>yes</entry>
            <entry><constant>url-tar</constant>, <constant>tar</constant>, <constant>directory</constant>, <constant>subvolume</constant></entry>
          </row>

        </tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    <title>Match Patterns</title>

    <para>Both the source and target resources typically exist in multiple versions concurrently. An update
    operation is done whenever the newest of the source versions is newer than the newest of the target
    versions. To determine the newest version of the resources a directory listing, partition listing or
    manifest listing is used, a subset of qualifying entries selected from that, and the version identifier
    extracted from the file names or partition labels of these selected entries. Subset selection and
    extraction of the version identifier (plus potentially other metadata) is done via match patterns,
    configured in <varname>MatchPattern=</varname> in the [Source] and [Target] sections. These patterns are
    strings that describe how files or partitions are named, with named wildcards for specific fields such as
    the version identifier. The following wildcards are defined:</para>

    <table>
      <title>Match Pattern Wildcards</title>

      <tgroup cols='2' align='left' colsep='1' rowsep='1'>
        <colspec colname="name" />
        <colspec colname="explanation" />

        <thead>
          <row>
            <entry>Wildcard</entry>
            <entry>Description</entry>
            <entry>Format</entry>
            <entry>Notes</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry><literal>@v</literal></entry>
            <entry>Version identifier</entry>
            <entry>Valid version string</entry>
            <entry>Mandatory</entry>
          </row>

          <row>
            <entry><literal>@u</literal></entry>
            <entry>GPT partition UUID</entry>
            <entry>Valid 128-Bit UUID string</entry>
            <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
          </row>

          <row>
            <entry><literal>@f</literal></entry>
            <entry>GPT partition flags</entry>
            <entry>Formatted hexadecimal integer</entry>
            <entry>Only relevant if target resource type chosen as <constant>partition</constant></entry>
          </row>

          <row>
            <entry><literal>@a</literal></entry>
            <entry>GPT partition flag NoAuto</entry>
            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
            <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
          </row>

          <row>
            <entry><literal>@g</literal></entry>
            <entry>GPT partition flag GrowFileSystem</entry>
            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
            <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
          </row>

          <row>
            <entry><literal>@r</literal></entry>
            <entry>Read-only flag</entry>
            <entry>Either <literal>0</literal> or <literal>1</literal></entry>
            <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below</entry>
          </row>

          <row>
            <entry><literal>@t</literal></entry>
            <entry>File modification time</entry>
            <entry>Formatted decimal integer, μs since UNIX epoch Jan 1st 1970</entry>
            <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
          </row>

          <row>
            <entry><literal>@m</literal></entry>
            <entry>File access mode</entry>
            <entry>Formatted octal integer, in UNIX fashion</entry>
            <entry>Only relevant if target resource type chosen as <constant>regular-file</constant></entry>
          </row>

          <row>
            <entry><literal>@s</literal></entry>
            <entry>File size after decompression</entry>
            <entry>Formatted decimal integer</entry>
            <entry>Useful for measuring progress and to improve partition allocation logic</entry>
          </row>

          <row>
            <entry><literal>@d</literal></entry>
            <entry>Tries done</entry>
            <entry>Formatted decimal integer</entry>
            <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
          </row>

          <row>
            <entry><literal>@l</literal></entry>
            <entry>Tries left</entry>
            <entry>Formatted decimal integer</entry>
            <entry>Useful when operating with kernel image files, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink></entry>
          </row>

          <row>
            <entry><literal>@h</literal></entry>
            <entry>SHA256 hash of compressed file</entry>
            <entry>64 hexadecimal characters</entry>
            <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>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>Of these wildcards only <literal>@v</literal> must be present in a valid pattern, all other
    wildcards are optional. Each wildcard may be used at most once in each pattern. A typical wildcard
    matching a file system source image could be <literal>MatchPattern=foobar_@v.raw.xz</literal>, i.e. any file
    whose name begins with <literal>foobar_</literal>, followed by a version ID and suffixed by
    <literal>.raw.xz</literal>.</para>

    <para>Do not confuse the <literal>@</literal> pattern matching wildcard prefix with the
    <literal>%</literal> specifier expansion prefix. The former encapsulate a variable part of a match
    pattern string, the latter are simple shortcuts that are expanded while the drop-in files are
    parsed. For details about specifiers, see below.</para>
  </refsect1>

  <refsect1>
    <title>[Transfer] Section Options</title>

    <para>This section defines general properties of this transfer.</para>

    <variablelist>
      <varlistentry>
        <term><varname>MinVersion=</varname></term>

        <listitem><para>Specifies the minimum version to require for this transfer to take place. If the
        source or target patterns in this transfer definition match files older than this version they will
        be considered obsolete, and never be considered for the update operation.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ProtectVersion=</varname></term>

        <listitem><para>Takes one or more version strings to mark as "protected". Protected versions are
        never removed while making room for new, updated versions. This is useful to ensure that the
        currently booted OS version (or auxiliary resources associated with it) is not replaced/overwritten
        during updates, in order to avoid runtime file system corruptions.</para>

        <para>Like many of the settings in these configuration files this setting supports specifier
        expansion. It's particularly useful to set this setting to one of the <literal>%A</literal>,
        <literal>%B</literal> or <literal>%w</literal> specifiers to automatically refer to the current OS
        version of the running system. See below for details on supported specifiers.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Verify=</varname></term>

        <listitem><para>Takes a boolean, defaults to yes. Controls whether to cryptographically verify
        downloaded resources (specifically: validate the GPG signatures for downloaded
        <filename>SHA256SUMS</filename> manifest files, via their detached signature files
        <filename>SHA256SUMS.gpg</filename> in combination with the system keyring
        <filename>/usr/lib/systemd/import-pubring.gpg</filename> or
        <filename>/etc/systemd/import-pubring.gpg</filename>).</para>

        <para>This option is essential to provide integrity guarantees for downloaded resources and thus
        should be left enabled, outside of test environments.</para>

        <para>Note that the downloaded payload files are unconditionally checked against the SHA256 hashes
        listed in the manifest. This option only controls whether the signatures of these manifests are
        verified.</para>

        <para>This option only has an effect if the source resource type is selected as
        <constant>url-file</constant> or <constant>url-tar</constant>, as integrity and authentication
        checking is only available for transfers from remote sources.</para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>[Source] Section Options</title>

    <para>This section defines properties of the transfer source.</para>

    <variablelist>
      <varlistentry>
        <term><varname>Type=</varname></term>

        <listitem><para>Specifies the resource type of the source for the transfer. Takes one of
        <constant>url-file</constant>, <constant>url-tar</constant>, <constant>tar</constant>,
        <constant>regular-file</constant>, <constant>directory</constant> or
        <constant>subvolume</constant>. For details about the resource types, see above. This option is
        mandatory.</para>

        <para>Note that only certain combinations of source and target resource types are supported, see
        above.</para></listitem>
      </varlistentry>
    </variablelist>

    <variablelist>
      <varlistentry>
        <term><varname>Path=</varname></term>

        <listitem><para>Specifies where to find source versions of this resource.</para>

        <para>If the source type is selected as <constant>url-file</constant> or
        <constant>url-tar</constant> this must be a HTTP/HTTPS URL. The URL is suffixed with
        <filename>/SHA256SUMS</filename> to acquire the manifest file, with
        <filename>/SHA256SUMS.gpg</filename> to acquire the detached signature file for it, and with the file
        names listed in the manifest file in case an update is executed and a resource shall be
        downloaded.</para>

        <para>For all other source resource types this must be a local path in the file system, referring to
        a local directory to find the versions of this resource in.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>MatchPattern=</varname></term>

        <listitem><para>Specifies one or more file name match patterns that select the subset of files that
        are update candidates as source for this transfer. See above for details on match patterns.</para>

        <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
        wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
        optional.</para></listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>[Target] Section Options</title>

    <para>This section defines properties of the transfer target.</para>

    <variablelist>
      <varlistentry>
        <term><varname>Type=</varname></term>

        <listitem><para>Specifies the resource type of the target for the transfer. Takes one of
        <constant>partition</constant>, <constant>regular-file</constant>, <constant>directory</constant> or
        <constant>subvolume</constant>. For details about the resource types, see above. This option is
        mandatory.</para>

        <para>Note that only certain combinations of source and target resource types are supported, see
        above.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Path=</varname></term>

        <listitem><para>Specifies a file system path where to look for already installed versions or place
        newly downloaded versions of this configured resource. If <varname>Type=</varname> is set to
        <constant>partition</constant>, expects a path to a (whole) block device node, or the special string
        <literal>auto</literal> in which case the block device which contains the root file system of the
        currently booted system is automatically determined and used. If <varname>Type=</varname> is set to
        <constant>regular-file</constant>, <constant>directory</constant> or <constant>subvolume</constant>,
        must refer to a path in the local file system referencing the directory to find or place the version
        files or directories under.</para>

        <para>Note that this mechanism cannot be used to create or remove partitions, in case
        <varname>Type=</varname> is set to <constant>partition</constant>. Partitions must exist already, and
        a special partition label <literal>_empty</literal> is used to indicate empty partitions. To
        automatically generate suitable partitions on first boot, use a tool such as
        <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PathRelativeTo=</varname></term>

        <listitem><para>Specifies what partition <varname>Path=</varname> should be relative to. Takes one of
        <constant>root</constant>, <constant>esp</constant>, <constant>xbootldr</constant>, or <constant>boot</constant>.
        If unspecified, defaults to <constant>root</constant>.</para>

        <para>If set to <constant>boot</constant>, the specified <varname>Path=</varname> will be resolved
        relative to the mount point of the $BOOT partition (i.e. the ESP or XBOOTLDR), as defined by the
        <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
        Specification</ulink>.</para>

        <para>The values <constant>esp</constant>, <constant>xbootldr</constant>, and
        <constant>boot</constant> are only supported when <varname>Type=</varname> is set to
        <constant>regular-file</constant> or <constant>directory</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>MatchPattern=</varname></term>

        <listitem><para>Specifies one or more file name or partition label match patterns that select the
        subset of files or partitions that are update candidates as targets for this transfer. See above for
        details on match patterns.</para>

        <para>This option is mandatory. Any pattern listed must contain at least the <literal>@v</literal>
        wildcard, so that a version identifier may be extracted from the filename. All other wildcards are
        optional.</para>

        <para>This pattern is both used for matching existing installed versions and for determining the name
        of new versions to install. If multiple patterns are specified, the first specified is used for
        naming newly installed versions.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>MatchPartitionType=</varname></term>

        <listitem><para>When the target <varname>Type=</varname> is chosen as <constant>partition</constant>,
        specifies the GPT partition type to look for. Only partitions of this type are considered, all other
        partitions are ignored. If not specified, the GPT partition type <constant>linux-generic</constant>
        is used. Accepts either a literal type UUID or a symbolic type identifier. For a list of supported
        type identifiers, see the <varname>Type=</varname> setting in
        <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PartitionUUID=</varname></term>
        <term><varname>PartitionFlags=</varname></term>
        <term><varname>PartitionNoAuto=</varname></term>
        <term><varname>PartitionGrowFileSystem=</varname></term>

        <listitem><para>When the target <varname>Type=</varname> is picked as <constant>partition</constant>,
        selects the GPT partition UUID and partition flags to use for the updated partition. Expects a valid
        UUID string, a hexadecimal integer, or booleans, respectively. If not set, but the source match
        pattern includes wildcards for these fields (i.e. <literal>@u</literal>, <literal>@f</literal>,
        <literal>@a</literal>, or <literal>@g</literal>), the values from the patterns are used. If neither
        configured with wildcards or these explicit settings, the values are left untouched. If both the
        overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings
        <varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the
        wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the
        overall flags value. See <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
        Partitions Specification</ulink> for details about these flags.</para>

        <para>Note that these settings are not used for matching, they only have effect on newly written
        partitions in case a transfer takes place.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ReadOnly=</varname></term>

        <listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the
        target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per
        <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
        Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and
        <varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is
        <constant>regular-file</constant>, the writable bit is removed from the access mode. If the
        target type is <constant>subvolume</constant>, the subvolume will be marked read-only as a
        whole. Finally, if the target <varname>Type=</varname> is selected as <constant>directory</constant>,
        the "immutable" file attribute is set, see <citerefentry
        project='man-pages'><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
        details.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Mode=</varname></term>

        <listitem><para>The UNIX file access mode to use for newly created files in case the target resource
        type is picked as <constant>regular-file</constant>. Expects an octal integer, in typical UNIX
        fashion. If not set, but the source match pattern includes a wildcard for this field
        (i.e. <literal>@t</literal>), the value from the pattern is used.</para>

        <para>Note that this setting is not used for matching, it only has an effect on newly written
        files when a transfer takes place.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>TriesDone=</varname></term>
        <term><varname>TriesLeft=</varname></term>

        <listitem><para>These options take positive, decimal integers, and control the number of attempts
        done and left for this file. These settings are useful for managing kernel images, following the
        scheme defined in <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot
        Assessment</ulink>, and only have an effect if the target pattern includes the <literal>@d</literal>
        or <literal>@l</literal> wildcards.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>InstancesMax=</varname></term>

        <listitem><para>Takes a decimal integer equal to or greater than 2. This configures how many concurrent
        versions of the resource to keep. Whenever a new update is initiated it is made sure that no more
        than the number of versions specified here minus one exist in the target. Any excess versions are
        deleted (in case the target <varname>Type=</varname> of <constant>regular-file</constant>,
        <constant>directory</constant>, <constant>subvolume</constant> is used) or emptied (in case the
        target <varname>Type=</varname> of <constant>partition</constant> is used; emptying in this case
        simply means to set the partition label to the special string <literal>_empty</literal>; note that no
        partitions are actually removed). After an update is completed the number of concurrent versions of
        the target resources is equal to or below the number specified here.</para>

        <para>Note that this setting may be set differently for each transfer. However, it generally is
        advisable to keep this setting the same for all transfers, since otherwise incomplete combinations of
        files or partitions will be left installed.</para>

        <para>If the target <varname>Type=</varname> is selected as <constant>partition</constant>, the number
        of concurrent versions to keep is additionally restricted by the number of partition slots of the
        right type in the partition table. I.e. if there are only 2 partition slots for the selected
        partition type, setting this value larger than 2 is without effect, since no more than 2 concurrent
        versions could be stored in the image anyway.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>RemoveTemporary=</varname></term>

        <listitem><para>Takes a boolean argument. If this option is enabled (which is the default) before
        initiating an update, all left-over, incomplete updates from a previous attempt are removed from the
        target directory. This only has an effect if the target resource <varname>Type=</varname> is selected
        as <constant>regular-file</constant>, <constant>directory</constant> or
        <constant>subvolume</constant>.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>CurrentSymlink=</varname></term>

        <listitem><para>Takes a symlink name as argument. If this option is used, as the last step of the
        update a symlink under the specified name is created/updated pointing to the completed update. This
        is useful in to provide a stable name always pointing to the newest version of the resource. This is
        only supported if the target resource <varname>Type=</varname> is selected as
        <constant>regular-file</constant>, <constant>directory</constant> or
        <constant>subvolume</constant>.</para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>Specifiers</title>

    <para>Specifiers may be used in the <varname>MinVersion=</varname>, <varname>ProtectVersion=</varname>,
    <varname>Path=</varname>, <varname>MatchPattern=</varname> and <varname>CurrentSymlink=</varname>
    settings. The following expansions are understood:</para>
      <table class='specifiers'>
        <title>Specifiers available</title>
        <tgroup cols='3' align='left' colsep='1' rowsep='1'>
          <colspec colname="spec" />
          <colspec colname="mean" />
          <colspec colname="detail" />
          <thead>
            <row>
              <entry>Specifier</entry>
              <entry>Meaning</entry>
              <entry>Details</entry>
            </row>
          </thead>
          <tbody>
            <xi:include href="standard-specifiers.xml" xpointer="a"/>
            <xi:include href="standard-specifiers.xml" xpointer="A"/>
            <xi:include href="standard-specifiers.xml" xpointer="b"/>
            <xi:include href="standard-specifiers.xml" xpointer="B"/>
            <xi:include href="standard-specifiers.xml" xpointer="H"/>
            <xi:include href="standard-specifiers.xml" xpointer="l"/>
            <xi:include href="standard-specifiers.xml" xpointer="m"/>
            <xi:include href="standard-specifiers.xml" xpointer="M"/>
            <xi:include href="standard-specifiers.xml" xpointer="o"/>
            <xi:include href="standard-specifiers.xml" xpointer="v"/>
            <xi:include href="standard-specifiers.xml" xpointer="w"/>
            <xi:include href="standard-specifiers.xml" xpointer="W"/>
            <xi:include href="standard-specifiers.xml" xpointer="T"/>
            <xi:include href="standard-specifiers.xml" xpointer="V"/>
            <xi:include href="standard-specifiers.xml" xpointer="percent"/>
          </tbody>
        </tgroup>
      </table>

    <para>Do not confuse the <literal>%</literal> specifier expansion prefix with the <literal>@</literal>
    pattern matching wildcard prefix. The former are simple shortcuts that are expanded while the drop-in
    files are parsed, the latter encapsulate a variable part of a match pattern string. For details about
    pattern matching wildcards, see above.</para>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <example>
      <title>Updates for a Verity Enabled Secure OS</title>

      <para>With the following three files we define a root file system partition, a matching Verity
      partition, and a unified kernel image to update as one. This example is an extension of the example
      discussed earlier in this man page.</para>

      <para><programlisting># /usr/lib/sysupdate.d/50-verity.conf
[Transfer]
ProtectVersion=%A

[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.verity.xz

[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
PartitionReadOnly=1</programlisting></para>

      <para>The above defines the update mechanism for the Verity partition of the root file system. Verity
      partition images are downloaded from
      <literal>https://download.example.com/foobarOS_@v_@u.verity.xz</literal> and written to a suitable
      local partition, which is marked read-only. Under the assumption this update is run from the image
      itself the current image version (i.e. the <literal>%A</literal> specifier) is marked as protected, to
      ensure it is not corrupted while booted. Note that the partition UUID for the target partition is
      encoded in the source file name. Fixating the partition UUID can be useful to ensure that
      <literal>roothash=</literal> on the kernel command line is sufficient to pinpoint both the Verity and
      root file system partition, and also encode the Verity root level hash (under the assumption the UUID
      in the file names match their top-level hash, the way
      <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      suggests).</para>

      <para><programlisting># /usr/lib/sysupdate.d/60-root.conf
[Transfer]
ProtectVersion=%A

[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v_@u.root.xz

[Target]
Type=partition
Path=auto
MatchPattern=foobarOS_@v
MatchPartitionType=root
PartitionFlags=0
PartitionReadOnly=1</programlisting></para>

      <para>The above defines a matching transfer definition for the root file system.</para>

      <para><programlisting># /usr/lib/sysupdate.d/70-kernel.conf
[Transfer]
ProtectVersion=%A

[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v.efi.xz

[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v+@l-@d.efi \
             foobarOS_@v+@l.efi \
             foobarOS_@v.efi
Mode=0444
TriesLeft=3
TriesDone=0
InstancesMax=2</programlisting></para>

        <para>The above installs a unified kernel image into the $BOOT partition, as per
        <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
        Specification</ulink> Type #2. This defines three possible patterns for the names of the kernel
        images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink>,
        and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel
        kernels are kept.</para>

        <para>With this setup the web server would serve the following files, for a hypothetical version 7 of
        the OS:</para>

        <itemizedlist>
          <listitem><para><filename>SHA256SUMS</filename>  The manifest file, containing available files and their SHA256 hashes</para></listitem>
          <listitem><para><filename>SHA256SUMS.gpg</filename>  The detached cryptographic signature for the manifest file</para></listitem>
          <listitem><para><filename>foobarOS_7_8b8186b1-2b4e-4eb6-ad39-8d4d18d2a8fb.verity.xz</filename>  The Verity image for version 7</para></listitem>
          <listitem><para><filename>foobarOS_7_f4d1234f-3ebf-47c4-b31d-4052982f9a2f.root.xz</filename>  The root file system image for version 7</para></listitem>
          <listitem><para><filename>foobarOS_7_efi.xz</filename>  The unified kernel image for version 7</para></listitem>
        </itemizedlist>

        <para>For each new OS release a new set of the latter three files would be added, each time with an
        updated version. The <filename>SHA256SUMS</filename> manifest should then be updated accordingly,
        listing all files for all versions that shall be offered for download.</para>
    </example>

    <example>
      <title>Updates for Plain Directory Container Image</title>

      <para><programlisting>
[Source]
Type=url-tar
Path=https://download.example.com/
MatchPattern=myContainer_@v.tar.gz

[Target]
Type=subvolume
Path=/var/lib/machines
MatchPattern=myContainer_@v
CurrentSymlink=myContainer</programlisting></para>

      <para>On updates this downloads <literal>https://download.example.com/myContainer_@v.tar.gz</literal>
      and decompresses/unpacks it to <filename>/var/lib/machines/myContainer_@v</filename>. After each update
      a symlink <filename>/var/lib/machines/myContainer</filename> is created/updated always pointing to the
      most recent update.</para>
    </example>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <para>
      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    </para>
  </refsect1>

</refentry>