From 9a515f0a55318d6db49be1f67fe7d3a7f8a3002c Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Mar 2021 16:10:31 +0100 Subject: [PATCH] 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. --- man/os-release.xml | 22 ++++++++++++++++++++++ man/repart.d.xml | 2 ++ man/standard-specifiers.xml | 20 +++++++++++++++----- man/systemd.dnssd.xml | 2 ++ man/systemd.unit.xml | 2 ++ man/sysusers.d.xml | 2 ++ man/tmpfiles.d.xml | 2 ++ src/shared/specifier.c | 8 ++++++++ src/shared/specifier.h | 7 +++++++ 9 files changed, 62 insertions(+), 5 deletions(-) diff --git a/man/os-release.xml b/man/os-release.xml index e6162bdacfb..e8462500f20 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -346,6 +346,28 @@ SYSEXT_LEVEL=15.14. + + IMAGE_ID= + + 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: IMAGE_ID=vendorx-cashier-system, + IMAGE_ID=netbook-image + + + + IMAGE_VERSION= + + 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 + IMAGE_ID described above, to discern different versions of the same + image. Examples: IMAGE_VERSION=33, + IMAGE_VERSION=47.1rc1 + + 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 66debd336f1..b6346b3f853 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -543,11 +543,13 @@ + + diff --git a/man/standard-specifiers.xml b/man/standard-specifiers.xml index 40bb6cc3ea0..f1666365b9c 100644 --- a/man/standard-specifiers.xml +++ b/man/standard-specifiers.xml @@ -4,16 +4,21 @@ - - %b - Boot ID - The boot ID of the running system, formatted as string. See random4 for more information. - %a Architecture A short string identifying the architecture of the local system. A string such as x86, x86-64 or arm64. See the architectures defined for ConditionArchitecture= in systemd.unit5 for a full list. + + %A + Operating system image version + The operating system image version identifier of the running system, as read from the IMAGE_VERSION= field of /etc/os-release. If not set, resolves to an empty string. See os-release5 for more information. + + + %b + Boot ID + The boot ID of the running system, formatted as string. See random4 for more information. + %B Operating system build ID @@ -34,6 +39,11 @@ Machine ID The machine ID of the running system, formatted as string. See machine-id5 for more information. + + %M + Operating system image identifier + The operating system image identifier of the running system, as read from the IMAGE_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release5 for more information. + %o Operating system ID diff --git a/man/systemd.dnssd.xml b/man/systemd.dnssd.xml index 96a14b1ba54..be2e873efb3 100644 --- a/man/systemd.dnssd.xml +++ b/man/systemd.dnssd.xml @@ -90,10 +90,12 @@ + + diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 42dcbac72ca..631658d88a4 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1872,6 +1872,7 @@ Architecture A short string identifying the architecture of the local system. A string such as x86, x86-64 or arm64. See the architectures defined for ConditionArchitecture= above for a full list. + @@ -1944,6 +1945,7 @@ Note that this setting is not influenced by the Us This is either /var/log (for the system manager) or the path $XDG_CONFIG_HOME resolves to with /log appended (for user managers). + %n Full unit name diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml index e15c1b2eee5..fd67c1f078e 100644 --- a/man/sysusers.d.xml +++ b/man/sysusers.d.xml @@ -259,11 +259,13 @@ r - 500-900 + + diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 4adbf6bb0a6..55b763e26d5 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -635,6 +635,7 @@ w- /proc/sys/vm/swappiness - - - - 10 + @@ -665,6 +666,7 @@ w- /proc/sys/vm/swappiness - - - - 10 In mode, this is the same as $XDG_CONFIG_HOME with /log appended, and /var/log otherwise. + %S diff --git a/src/shared/specifier.c b/src/shared/specifier.c index 24e8781805a..6edf4a215ca 100644 --- 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 1323b41d985..6735a7a363a 100644 --- 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 }, \