From c8cab396a0834ca5d4d9da405b38eafa2dcc2202 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sat, 21 Aug 2021 16:02:09 +0200 Subject: [PATCH] man: adjust the description of extension-release.* --- man/os-release.xml | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/man/os-release.xml b/man/os-release.xml index 6be96cf8bc7..15608c437a3 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. /etc/os-release should be symlinked to /etc/initrd-release (or vice versa), so programs that only look for /etc/os-release (as described - above) work correctly. The rest of this document that talks about os-release - should be understood to apply to initrd-release too. + above) work correctly. + + The rest of this document that talks about os-release should be understood + to apply to initrd-release too. <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> /usr/lib/extension-release.d/extension-release.IMAGE - for extension images plays the same role as os-release in the main system, and follows the - same syntax and rules as described in the Portable Services Documentation. - 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 ID= - options match, and if they do either SYSEXT_LEVEL= has to match too (preferred), or - as a fallback if that is not present VERSION_ID= 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 extension-release.IMAGE 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 - extension-release., is located in the same directory and is tagged with a - user.extension-release.strict xattr7 - set to the string 0, will be parsed instead, if the one with the expected name cannot be found. - The rest of this document that talks about os-release should be understood to apply to - extension-release too. + plays the same role for extension images as os-release for the main system, and + follows the syntax and rules as described in the Portable Services Documentation. 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 ID= options + match, and either SYSEXT_LEVEL= exists and matches too, or if it is not present, + VERSION_ID= exists and matches. This ensures ABI/API compatibility between the + layers and prevents merging of an incompatible image in an overlay. + + In the extension-release.IMAGE filename, the + IMAGE 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 extension-release.* is present in this + directory, and the file is tagged with a user.extension-release.strict + xattr7 set to the + string 0, it will be used instead. + + The rest of this document that talks about os-release should be understood + to apply to extension-release too.