HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/sysupdate.d.xml
Git blob: 4e42745f4ce741929c06f5f4354a4bd02434088c
Lines 1001–1116 of 1,116
MatchPattern=foobarOS_@v_verity
MatchPartitionType=root-verity
PartitionFlags=0
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
<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.transfer
[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
ReadOnly=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.transfer
[Transfer]
ProtectVersion=%A
[Source]
Type=url-file
Path=https://download.example.com/
MatchPattern=foobarOS_@v.efi
[Target]
Type=regular-file
Path=/EFI/Linux
PathRelativeTo=boot
MatchPattern=foobarOS_@v+@l-@d.efi \
foobarOS_@v+@l.efi \
foobarOS_@v.efi
Mode=0644
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">UAPI.1 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</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><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-sysupdate</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sysupdate.features</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>sysupdate.components</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-repart</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>