summaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorLuca Boccassi <luca.boccassi@microsoft.com>2021-07-23 15:45:38 +0200
committerLuca Boccassi <luca.boccassi@microsoft.com>2021-08-17 14:15:13 +0200
commit9c8b6eaa468ec3706e789894d1ddec1e568cbcf0 (patch)
tree4d1f6b438a9783bdd7e68dfbe8fe6e1906ce7b64 /man
parentextension-release: search for other files if expected name not found (diff)
downloadsystemd-9c8b6eaa468ec3706e789894d1ddec1e568cbcf0.tar.xz
systemd-9c8b6eaa468ec3706e789894d1ddec1e568cbcf0.zip
man: further document extension-release
Diffstat (limited to '')
-rw-r--r--man/os-release.xml34
-rw-r--r--man/portablectl.xml6
-rw-r--r--man/systemd.exec.xml5
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,