system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-20 17:56:25 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

man: adjust the description of extension-release.*

Browse source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2021-08-21 16:02:09 +02:00
parent 98579f19e7
commit c8cab396a0
1 changed files with 24 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

42
man/os-release.xml
View file

@ -93,30 +93,36 @@
main system. Additionally, the presence of that file means that the system is in the initrd phase.
<filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
(or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
above) work correctly. The rest of this document that talks about <filename>os-release</filename>
should be understood to apply to <filename>initrd-release</filename> too.</para>
above) work correctly.</para>
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
to apply to <filename>initrd-release</filename> too.</para>
</refsect2>
<refsect2>
<title><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></title>
<para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
for extension images plays the same role as <filename>os-release</filename> in the main system, and follows the
same syntax and rules as described in the <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>.
The purpose of this file is to allow the operating system to correctly match an extension image
to a base OS image, This is typically implemented by first checking that the <varname>ID=</varname>
options match, and if they do either <varname>SYSEXT_LEVEL=</varname> has to match too (preferred), or
as a fallback if that is not present <varname>VERSION_ID=</varname> is checked. This ensures that ABI/API
between the layers matches and no incompatible images are merged in an overlay.
It is preferred that the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename is suffixed
with the exact file name of the image that contains it, so that all such files in every layer of an overlay are visible.
But for the purpose of parsing metadata, in case it is not possible to guarantee that an image file name is stable
and doesn't change between the build and the deployment phases, the first and only file which name starts with
<filename>extension-release.</filename>, is located in the same directory and is tagged with a
<varname>user.extension-release.strict</varname> <citerefentry><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry>
set to the string <literal>0</literal>, will be parsed instead, if the one with the expected name cannot be found.
The rest of this document that talks about <filename>os-release</filename> should be understood to apply to
<filename>extension-release</filename> too.</para>
plays the same role for extension images as <filename>os-release</filename> for the main system, and
follows the syntax and rules as described in the <ulink
url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>. The purpose of this
file is to identify the extension and to allow the operating system to verify that the extension image
matches the base OS. This is typically implemented by checking that the <varname>ID=</varname> options
match, and either <varname>SYSEXT_LEVEL=</varname> exists and matches too, or if it is not present,
<varname>VERSION_ID=</varname> exists and matches. This ensures ABI/API compatibility between the
layers and prevents merging of an incompatible image in an overlay.</para>
<para>In the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename, the
<replaceable>IMAGE</replaceable> part must exactly match the file name of the containing image with the
suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
change between the build and the deployment phases, it is possible to relax this check: if exactly one
file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this
directory, and the file is tagged with a <varname>user.extension-release.strict</varname>
<citerefentry><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
string <literal>0</literal>, it will be used instead.</para>
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
to apply to <filename>extension-release</filename> too.</para>
</refsect2>
</refsect1>