</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>
+ <para><simplelist>
+ <member><filename>/etc/sysupdate.d/*.conf</filename></member>
+ <member><filename>/run/sysupdate.d/*.conf</filename></member>
+ <member><filename>/usr/lib/sysupdate.d/*.conf</filename></member>
+ </simplelist></para>
</refsynopsisdiv>
<refsect1>
<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 ESP file system,
- i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP.</para></listitem>
+ 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
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>/efi/EFI/Linux/foobarOS_@v.efi</filename>.</para></listitem>
+ → 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,
<row>
<entry><literal>@t</literal></entry>
<entry>File modification time</entry>
- <entry>Formatted decimal integer, µs since UNIX epoch Jan 1st 1970</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>
<refsect1>
<title>[Transfer] Section Options</title>
- <para>This section defines general properties of this transfer:</para>
+ <para>This section defines general properties of this transfer.</para>
<variablelist>
<varlistentry>
<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>
+ be considered obsolete, and never be considered for the update operation.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ version of the running system. See below for details on supported specifiers.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ checking is only available for transfers from remote sources.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
<refsect1>
<title>[Source] Section Options</title>
- <para>This section defines properties of the transfer source:</para>
+ <para>This section defines properties of the transfer source.</para>
<variablelist>
<varlistentry>
<constant>subvolume</constant>. For details about the resource types, see above. This option is
mandatory.</para>
- <para>Note that only some combinations of source and target resource types are supported, see
- above.</para></listitem>
+ <para>Note that only certain combinations of source and target resource types are supported, see
+ above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
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>
+ a local directory to find the versions of this resource in.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ optional.</para>
+
+ <para>If the source type is <constant>regular-file</constant> or <constant>directory</constant>, the
+ pattern may contain slash characters. In this case it will match the file or directory in
+ corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
+ <literal>bar.efi</literal> in directory <literal>foo_1</literal>. </para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>[Target] Section Options</title>
- <para>This section defines properties of the transfer target:</para>
+ <para>This section defines properties of the transfer target.</para>
<variablelist>
<varlistentry>
<constant>subvolume</constant>. For details about the resource types, see above. This option is
mandatory.</para>
- <para>Note that only some combinations of source and target resource types are supported, see above.</para></listitem>
+ <para>Note that only certain combinations of source and target resource types are supported, see
+ above.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ <citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></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>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<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>
+ naming newly installed versions.</para>
+
+ <para>If the target type is <constant>regular-file</constant> or <constant>directory</constant>, the
+ pattern may contain slash characters. In this case it will match the file or directory in
+ corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
+ <literal>bar.efi</literal> in directory <literal>foo_1</literal>. Directories in the path will be
+ created when file is installed. Empty directories will be removed when file is removed.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
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>
+ <citerefentry><refentrytitle>repart.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
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>
+ partitions in case a transfer takes place.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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 the
+ <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>
+ details.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
(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>
+ files when a transfer takes place.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
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>
+ or <literal>@l</literal> wildcards.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<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
+ 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>
+ versions could be stored in the image anyway.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
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>
+ <constant>subvolume</constant>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
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>
+ <constant>subvolume</constant>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
</variablelist>
MatchPattern=foobarOS_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
-PartitionReadOnly=1</programlisting></para>
+ReadOnly=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
MatchPattern=foobarOS_@v
MatchPartitionType=root
PartitionFlags=0
-PartitionReadOnly=1</programlisting></para>
+ReadOnly=1</programlisting></para>
<para>The above defines a matching transfer definition for the root file system.</para>
[Target]
Type=regular-file
-Path=/efi/EFI/Linux
+Path=/EFI/Linux
+PathRelativeTo=boot
MatchPattern=foobarOS_@v+@l-@d.efi \
foobarOS_@v+@l.efi \
foobarOS_@v.efi
TriesDone=0
InstancesMax=2</programlisting></para>
- <para>The above installs a unified kernel image into the ESP (which is mounted to
- <filename>/efi/</filename>), 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>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>
projects / thirdparty / systemd.git / blobdiff