diff options
| -rw-r--r-- | man/os-release.xml | 34 | ||||
| -rw-r--r-- | man/portablectl.xml | 6 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 5 |
3 files changed, 43 insertions, 2 deletions
diff --git a/man/os-release.xml b/man/os-release.xml index a7c60183ae..6be96cf8bc 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -17,6 +17,7 @@ <refnamediv> <refname>os-release</refname> <refname>initrd-release</refname> + <refname>extension-release</refname> <refpurpose>Operating system identification</refpurpose> </refnamediv> @@ -24,6 +25,7 @@ <para><filename>/etc/os-release</filename></para> <para><filename>/usr/lib/os-release</filename></para> <para><filename>/etc/initrd-release</filename></para> + <para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></para> </refsynopsisdiv> <refsect1> @@ -94,6 +96,28 @@ 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> </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> + </refsect2> </refsect1> <refsect1> @@ -373,7 +397,8 @@ <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which - extension images are supported. See + extension images are supported. See <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>, + <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/initrd.html">initrd</ulink> and <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>) for more information.</para> @@ -437,6 +462,13 @@ VARIANT_ID=workstation</programlisting> </example> <example> + <title><filename>extension-release</filename> file for an extension for Fedora Workstation 32</title> + + <programlisting>ID=fedora +VERSION_ID=32</programlisting> + </example> + + <example> <title>Reading <filename>os-release</filename> in <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title> diff --git a/man/portablectl.xml b/man/portablectl.xml index d798219d45..c5404db0ba 100644 --- a/man/portablectl.xml +++ b/man/portablectl.xml @@ -359,7 +359,11 @@ top of <replaceable>IMAGE</replaceable> when attaching/detaching. This argument can be specified multiple times, in which case the order in which images are laid down follows the rules specified in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for the <varname>ExtensionImages=</varname> directive.</para> + for the <varname>ExtensionImages=</varname> directive. The image(s) must contain an + <filename>extension-release</filename> file with metadata that matches what is defined in the + <filename>os-release</filename> of <replaceable>IMAGE</replaceable>. See: + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> <para>Note that the same extensions have to be specified, in the same order, when attaching and detaching.</para></listitem> diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 008cbe9af1..eadfc02421 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -428,6 +428,11 @@ paths. If the empty string is assigned, the entire list of mount paths defined prior to this is reset.</para> + <para>Each image must carry a <filename>/usr/lib/extension-release.d/extension-release.IMAGE</filename> + file, with the appropriate metadata which matches <varname>RootImage=</varname>/<varname>RootDirectory=</varname> + or the host. See: + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + <para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or <literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is set, then this setting adds <filename>/dev/loop-control</filename> with <constant>rw</constant> mode, |