diff options
Diffstat (limited to 'man/os-release.xml')
| -rw-r--r-- | man/os-release.xml | 42 |
1 files changed, 24 insertions, 18 deletions
diff --git a/man/os-release.xml b/man/os-release.xml index 6be96cf8bc..15608c437a 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -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> |