shared: add new IMAGE_VERSION=/IMAGE_ID= field to /etc/os-release

This specifes two new optional fields for /etc/os-release:
IMAGE_VERSION= and IMAGE_ID= that are supposed to identify the image of
the current booted system by name and version.

This is inspired by the versioning stuff in
https://github.com/systemd/mkosi/pull/683.

In environments where pre-built images are installed and updated as a
whole the existing os-release version/distro identifier are not
sufficient to describe the system's version, as they describe only the
distro an image is built from, but not the image itself, even if that
image is deployed many times on many systems, and even if that image
contains more resources than just the RPMs/DEBs.

In particular, "mkosi" is a tool for building disk images based on
distro RPMs with additional resources dropped in. The combination of all
of these together with their versions should also carry an identifier
and version, and that's what IMAGE_VERSION= and IMAGE_ID= is supposed to
be.

diff --git a/man/os-release.xml b/man/os-release.xml
index e6162bdacfb9d3add5cf6a8862e9ae88010fa43d..e8462500f20e2c2c97df952d86f9cef37c2db2f7 100644 (file)
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -346,6 +346,28 @@
         <literal>SYSEXT_LEVEL=15.14</literal>.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><varname>IMAGE_ID=</varname></term>
+
+        <listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
+        "-"), identifying a specific image of the operating system. This is supposed to be used for
+        environments where OS images are prepared, built, shipped and updated as comprehensive, consistent OS
+        images. This field is optional and may not be implemented on all systems, in particulary not on those
+        that are not managed via images but put together and updated from individual packages and on the
+        local system.  Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
+        <literal>IMAGE_ID=netbook-image</literal> </para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>IMAGE_VERSION=</varname></term>
+
+        <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+        a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
+        <varname>IMAGE_ID</varname> described above, to discern different versions of the same
+        image. Examples: <literal>IMAGE_VERSION=33</literal>,
+        <literal>IMAGE_VERSION=47.1rc1</literal> </para></listitem>
+      </varlistentry>
+
     </variablelist>
 
     <para>If you are reading this file from C code or a shell script

diff --git a/man/repart.d.xml b/man/repart.d.xml
index 66debd336f103c9df8f3289801b5d91da6b4879c..b6346b3f8537c61f5d50d6b8c0d139bb0dd824ab 100644 (file)
--- a/man/repart.d.xml
+++ b/man/repart.d.xml
@@ -543,11 +543,13 @@
           </thead>
           <tbody>
             <xi:include href="standard-specifiers.xml" xpointer="a"/>
+            <xi:include href="standard-specifiers.xml" xpointer="A"/>
             <xi:include href="standard-specifiers.xml" xpointer="b"/>
             <xi:include href="standard-specifiers.xml" xpointer="B"/>
             <xi:include href="standard-specifiers.xml" xpointer="H"/>
             <xi:include href="standard-specifiers.xml" xpointer="l"/>
             <xi:include href="standard-specifiers.xml" xpointer="m"/>
+            <xi:include href="standard-specifiers.xml" xpointer="M"/>
             <xi:include href="standard-specifiers.xml" xpointer="o"/>
             <xi:include href="standard-specifiers.xml" xpointer="v"/>
             <xi:include href="standard-specifiers.xml" xpointer="w"/>

diff --git a/man/standard-specifiers.xml b/man/standard-specifiers.xml
index 40bb6cc3ea00a57f23e59e346741cc9f0fd23390..f1666365b9c19ba7a9129067215f94e22e969600 100644 (file)
--- a/man/standard-specifiers.xml
+++ b/man/standard-specifiers.xml
@@ -4,16 +4,21 @@
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <tbody>
-  <row id='b'>
-    <entry><literal>%b</literal></entry>
-    <entry>Boot ID</entry>
-    <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
-  </row>
   <row id='a'>
     <entry><literal>%a</literal></entry>
     <entry>Architecture</entry>
     <entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for a full list.</entry>
   </row>
+  <row id='A'>
+    <entry><literal>%A</literal></entry>
+    <entry>Operating system image version</entry>
+    <entry>The operating system image version identifier of the running system, as read from the <varname>IMAGE_VERSION=</varname> field of <filename>/etc/os-release</filename>. If not set, resolves to an empty string. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
+  <row id='b'>
+    <entry><literal>%b</literal></entry>
+    <entry>Boot ID</entry>
+    <entry>The boot ID of the running system, formatted as string. See <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for more information.</entry>
+  </row>
   <row id='B'>
     <entry><literal>%B</literal></entry>
     <entry>Operating system build ID</entry>
@@ -34,6 +39,11 @@
     <entry>Machine ID</entry>
     <entry>The machine ID of the running system, formatted as string. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
   </row>
+  <row id='M'>
+    <entry><literal>%M</literal></entry>
+    <entry>Operating system image identifier</entry>
+    <entry>The operating system image identifier of the running system, as read from the <varname>IMAGE_ID=</varname> field of <filename>/etc/os-release</filename>. If not set, resolves to an empty string. See <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.</entry>
+  </row>
   <row id='o'>
     <entry><literal>%o</literal></entry>
     <entry>Operating system ID</entry>

diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml
index 96a14b1ba542063cc7e21878092e42c2f6d1bda5..be2e873efb3a10ae8bc36623eaca6a73b777920e 100644 (file)
--- a/man/systemd.dnssd.xml
+++ b/man/systemd.dnssd.xml
@@ -90,10 +90,12 @@
                 </thead>
                 <tbody>
                   <xi:include href="standard-specifiers.xml" xpointer="a"/>
+                  <xi:include href="standard-specifiers.xml" xpointer="A"/>
                   <xi:include href="standard-specifiers.xml" xpointer="b"/>
                   <xi:include href="standard-specifiers.xml" xpointer="B"/>
                   <xi:include href="standard-specifiers.xml" xpointer="H"/>
                   <xi:include href="standard-specifiers.xml" xpointer="m"/>
+                  <xi:include href="standard-specifiers.xml" xpointer="M"/>
                   <xi:include href="standard-specifiers.xml" xpointer="o"/>
                   <xi:include href="standard-specifiers.xml" xpointer="v"/>
                   <xi:include href="standard-specifiers.xml" xpointer="w"/>

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 42dcbac72ca3e19a4cb71ed9583158c18d0f6383..631658d88a481cc44ef230c916840e1882e25df4 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1872,6 +1872,7 @@
             <entry>Architecture</entry>
             <entry>A short string identifying the architecture of the local system. A string such as <constant>x86</constant>, <constant>x86-64</constant> or <constant>arm64</constant>. See the architectures defined for <varname>ConditionArchitecture=</varname> above for a full list.</entry>
           </row>
+          <xi:include href="standard-specifiers.xml" xpointer="A"/>
           <xi:include href="standard-specifiers.xml" xpointer="b"/>
           <xi:include href="standard-specifiers.xml" xpointer="B"/>
           <row>
@@ -1944,6 +1945,7 @@ Note that this setting is <emphasis>not</emphasis> influenced by the <varname>Us
             <entry>This is either <filename>/var/log</filename> (for the system manager) or the path <literal>$XDG_CONFIG_HOME</literal> resolves to with <filename index="false">/log</filename> appended (for user managers).</entry>
           </row>
           <xi:include href="standard-specifiers.xml" xpointer="m"/>
+          <xi:include href="standard-specifiers.xml" xpointer="M"/>
           <row>
             <entry><literal>%n</literal></entry>
             <entry>Full unit name</entry>

diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index e15c1b2eee5778d22170d8551e974dd14473f6bb..fd67c1f078e20b4f03fd4b30dd7d043455acadd2 100644 (file)
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -259,11 +259,13 @@ r     -        500-900
         </thead>
         <tbody>
           <xi:include href="standard-specifiers.xml" xpointer="a"/>
+          <xi:include href="standard-specifiers.xml" xpointer="A"/>
           <xi:include href="standard-specifiers.xml" xpointer="b"/>
           <xi:include href="standard-specifiers.xml" xpointer="B"/>
           <xi:include href="standard-specifiers.xml" xpointer="H"/>
           <xi:include href="standard-specifiers.xml" xpointer="l"/>
           <xi:include href="standard-specifiers.xml" xpointer="m"/>
+          <xi:include href="standard-specifiers.xml" xpointer="M"/>
           <xi:include href="standard-specifiers.xml" xpointer="o"/>
           <xi:include href="standard-specifiers.xml" xpointer="T"/>
           <xi:include href="standard-specifiers.xml" xpointer="v"/>

diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml
index 4adbf6bb0a611703c8cb5c2ac3246c7e22ab1be7..55b763e26d587f504f5047ac38592b7e94def5c6 100644 (file)
--- a/man/tmpfiles.d.xml
+++ b/man/tmpfiles.d.xml
@@ -635,6 +635,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
           </thead>
           <tbody>
             <xi:include href="standard-specifiers.xml" xpointer="a"/>
+            <xi:include href="standard-specifiers.xml" xpointer="A"/>
             <xi:include href="standard-specifiers.xml" xpointer="b"/>
             <xi:include href="standard-specifiers.xml" xpointer="B"/>
             <row>
@@ -665,6 +666,7 @@ w- /proc/sys/vm/swappiness - - - - 10</programlisting></para>
               <entry>In <option>--user</option> mode, this is the same as <varname>$XDG_CONFIG_HOME</varname> with <filename index="false">/log</filename> appended, and <filename>/var/log</filename> otherwise.</entry>
             </row>
             <xi:include href="standard-specifiers.xml" xpointer="m"/>
+            <xi:include href="standard-specifiers.xml" xpointer="M"/>
             <xi:include href="standard-specifiers.xml" xpointer="o"/>
             <row>
               <entry><literal>%S</literal></entry>

diff --git a/src/shared/specifier.c b/src/shared/specifier.c
index 24e8781805a878c8c0a62810ff57bf86c578d411..6edf4a215ca7df41a2e15ba988b0c36101fb906d 100644 (file)
--- a/src/shared/specifier.c
+++ b/src/shared/specifier.c
@@ -234,6 +234,14 @@ int specifier_os_variant_id(char specifier, const void *data, const void *userda
         return specifier_os_release_common("VARIANT_ID", ret);
 }
 
+int specifier_os_image_id(char specifier, const void *data, const void *userdata, char **ret) {
+        return specifier_os_release_common("IMAGE_ID", ret);
+}
+
+int specifier_os_image_version(char specifier, const void *data, const void *userdata, char **ret) {
+        return specifier_os_release_common("IMAGE_VERSION", ret);
+}
+
 int specifier_group_name(char specifier, const void *data, const void *userdata, char **ret) {
         char *t;
 

diff --git a/src/shared/specifier.h b/src/shared/specifier.h
index 1323b41d98567c52bb542c40355779c1c5c7d1c2..6735a7a363a656b6ea23862b8e45e3c8456a3c32 100644 (file)
--- a/src/shared/specifier.h
+++ b/src/shared/specifier.h
@@ -25,6 +25,8 @@ int specifier_os_id(char specifier, const void *data, const void *userdata, char
 int specifier_os_version_id(char specifier, const void *data, const void *userdata, char **ret);
 int specifier_os_build_id(char specifier, const void *data, const void *userdata, char **ret);
 int specifier_os_variant_id(char specifier, const void *data, const void *userdata, char **ret);
+int specifier_os_image_id(char specifier, const void *data, const void *userdata, char **ret);
+int specifier_os_image_version(char specifier, const void *data, const void *userdata, char **ret);
 
 int specifier_group_name(char specifier, const void *data, const void *userdata, char **ret);
 int specifier_group_id(char specifier, const void *data, const void *userdata, char **ret);
@@ -41,11 +43,13 @@ int specifier_var_tmp_dir(char specifier, const void *data, const void *userdata
  *
  * COMMON_SYSTEM_SPECIFIERS:
  * %a: the native userspace architecture
+ * %A: the OS image version, according to /etc/os-release
  * %b: the boot ID of the running system
  * %B: the OS build ID, according to /etc/os-release
  * %H: the hostname of the running system
  * %l: the short hostname of the running system
  * %m: the machine ID of the running system
+ * %M: the OS image ID, according to /etc/os-release
  * %o: the OS ID according to /etc/os-release
  * %v: the kernel version
  * %w: the OS version ID, according to /etc/os-release
@@ -64,16 +68,19 @@ int specifier_var_tmp_dir(char specifier, const void *data, const void *userdata
 
 #define COMMON_SYSTEM_SPECIFIERS                  \
         { 'a', specifier_architecture,    NULL }, \
+        { 'A', specifier_os_image_version,NULL }, \
         { 'b', specifier_boot_id,         NULL }, \
         { 'B', specifier_os_build_id,     NULL }, \
         { 'H', specifier_host_name,       NULL }, \
         { 'l', specifier_short_host_name, NULL }, \
         { 'm', specifier_machine_id,      NULL }, \
+        { 'M', specifier_os_image_id,     NULL }, \
         { 'o', specifier_os_id,           NULL }, \
         { 'v', specifier_kernel_release,  NULL }, \
         { 'w', specifier_os_version_id,   NULL }, \
         { 'W', specifier_os_variant_id,   NULL }
 
+
 #define COMMON_CREDS_SPECIFIERS                   \
         { 'g', specifier_group_name,      NULL }, \
         { 'G', specifier_group_id,        NULL }, \