From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/os-release.xml | 565 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 565 insertions(+) create mode 100644 man/os-release.xml (limited to 'man/os-release.xml') diff --git a/man/os-release.xml b/man/os-release.xml new file mode 100644 index 0000000..c1819ff --- /dev/null +++ b/man/os-release.xml @@ -0,0 +1,565 @@ + + + + + + + os-release + systemd + + + + os-release + 5 + + + + os-release + initrd-release + extension-release + Operating system identification + + + + /etc/os-release + /usr/lib/os-release + /etc/initrd-release + /usr/lib/extension-release.d/extension-release.IMAGE + + + + Description + + The /etc/os-release and + /usr/lib/os-release files contain operating + system identification data. + + The format of os-release is a newline-separated list of + environment-like shell-compatible variable assignments. It is possible to source the configuration from + Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this + means variable expansion is explicitly not supported), allowing applications to read the file without + implementing a shell compatible execution engine. Variable assignment values must be enclosed in double + or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z, + 0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is + optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes, + following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not + be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#" + are treated as comments. Blank lines are permitted and ignored. + + The file /etc/os-release takes + precedence over /usr/lib/os-release. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + /usr/lib/os-release if it is missing. + Applications should not read data from both files at the same + time. /usr/lib/os-release is the recommended + place to store OS release information as part of vendor trees. + /etc/os-release should be a relative symlink + to /usr/lib/os-release, to provide + compatibility with applications only looking at + /etc/. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut. + + os-release contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator. + + As this file only encodes names and identifiers it should + not be localized. + + The /etc/os-release and + /usr/lib/os-release files might be symlinks + to other files, but it is important that the file is available + from earliest boot on, and hence must be located on the root file + system. + + os-release must not contain repeating keys. Nevertheless, readers should pick + the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A + reader may warn about repeating entries. + + For a longer rationale for os-release + please refer to the Announcement of /etc/os-release. + + + <filename>/etc/initrd-release</filename> + + In the initrd, + /etc/initrd-release plays the same role as os-release in the + 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. + + + + <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> + + /usr/lib/extension-release.d/extension-release.IMAGE + 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. + + + + + Options + + The following OS identifications parameters may be set using + os-release: + + + General information identifying the operating system + + + + NAME= + + A string identifying the operating system, without a version component, and + suitable for presentation to the user. If not set, a default of NAME=Linux may + be used. + + Examples: NAME=Fedora, NAME="Debian GNU/Linux". + + + + + ID= + + A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" + and "-") identifying the operating system, excluding any version information and suitable for + processing by scripts or usage in generated filenames. If not set, a default of + ID=linux may be used. Note that even though this string may not include + characters that require shell quoting, quoting may nevertheless be used. + + Examples: ID=fedora, ID=debian. + + + + ID_LIKE= + + A space-separated list of operating system identifiers in the same syntax as the + ID= setting. It should list identifiers of operating systems that are closely + related to the local operating system in regards to packaging and programming interfaces, for + example listing one or more OS identifiers the local OS is a derivative from. An OS should + generally only list other OS identifiers it itself is a derivative of, and not any OSes that are + derived from it, though symmetric relationships are possible. Build scripts and similar should + check this variable if they need to identify the local operating system and the value of + ID= is not recognized. Operating systems should be listed in order of how + closely the local operating system relates to the listed ones, starting with the closest. This + field is optional. + + Examples: for an operating system with ID=centos, an assignment of + ID_LIKE="rhel fedora" would be appropriate. For an operating system with + ID=ubuntu, an assignment of ID_LIKE=debian is appropriate. + + + + + PRETTY_NAME= + + A pretty operating system name in a format suitable for presentation to the + user. May or may not contain a release code name or OS version of some kind, as suitable. If not + set, a default of PRETTY_NAME="Linux" may be used + + Example: PRETTY_NAME="Fedora 17 (Beefy Miracle)". + + + + CPE_NAME= + + A CPE name for the operating system, in URI binding syntax, following the Common Platform Enumeration Specification as + proposed by the NIST. This field is optional. + + Example: CPE_NAME="cpe:/o:fedoraproject:fedora:17" + + + + VARIANT= + + A string identifying a specific variant or edition of the operating system suitable + for presentation to the user. This field may be used to inform the user that the configuration of + this system is subject to a specific divergent set of rules or default configuration settings. This + field is optional and may not be implemented on all systems. + + Examples: VARIANT="Server Edition", VARIANT="Smart Refrigerator + Edition". + + Note: this field is for display purposes only. The VARIANT_ID field should + be used for making programmatic decisions. + + + + VARIANT_ID= + + A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and + "-"), identifying a specific variant or edition of the operating system. This may be interpreted by + other packages in order to determine a divergent default configuration. This field is optional and + may not be implemented on all systems. + + Examples: VARIANT_ID=server, VARIANT_ID=embedded. + + + + + + + Information about the version of the operating system + + + + VERSION= + + A string identifying the operating system version, excluding any OS name + information, possibly including a release code name, and suitable for presentation to the + user. This field is optional. + + Examples: VERSION=17, VERSION="17 (Beefy Miracle)". + + + + + VERSION_ID= + + A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, + a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information + or release code name, and suitable for processing by scripts or usage in generated filenames. This + field is optional. + + Examples: VERSION_ID=17, VERSION_ID=11.04. + + + + + VERSION_CODENAME= + + A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" + and "-") identifying the operating system release code name, excluding any OS name information or + release version, and suitable for processing by scripts or usage in generated filenames. This field + is optional and may not be implemented on all systems. + + Examples: VERSION_CODENAME=buster, + VERSION_CODENAME=xenial. + + + + BUILD_ID= + + A string uniquely identifying the system image originally used as the installation + base. In most cases, VERSION_ID or + IMAGE_ID+IMAGE_VERSION are updated when the entire system + image is replaced during an update. BUILD_ID may be used in distributions where + the original installation image version is important: VERSION_ID would change + during incremental system updates, but BUILD_ID would not. This field is + optional. + + Examples: BUILD_ID="2013-03-20.3", BUILD_ID=201303203. + + + + + 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 particularly 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. + + + + + To summarize: if the image updates are built and shipped as comprehensive units, + IMAGE_ID+IMAGE_VERSION is the best fit. Otherwise, if updates + eventually completely replace previously installed contents, as in a typical binary distribution, + VERSION_ID should be used to identify major releases of the operating system. + BUILD_ID may be used instead or in addition to VERSION_ID when + the original system image version is important. + + + + Presentation information and links + + + + HOME_URL= + DOCUMENTATION_URL= + SUPPORT_URL= + BUG_REPORT_URL= + PRIVACY_POLICY_URL= + + Links to resources on the Internet related to the operating system. + HOME_URL= should refer to the homepage of the operating system, or alternatively + some homepage of the specific version of the operating system. + DOCUMENTATION_URL= should refer to the main documentation page for this + operating system. SUPPORT_URL= should refer to the main support page for the + operating system, if there is any. This is primarily intended for operating systems which vendors + provide support for. BUG_REPORT_URL= should refer to the main bug reporting page + for the operating system, if there is any. This is primarily intended for operating systems that + rely on community QA. PRIVACY_POLICY_URL= should refer to the main privacy + policy page for the operating system, if there is any. These settings are optional, and providing + only some of these settings is common. These URLs are intended to be exposed in "About this system" + UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a + Bug", or "Privacy Policy". The values should be in RFC3986 format, and should be + http: or https: URLs, and possibly mailto: + or tel:. Only one URL shall be listed in each setting. If multiple resources + need to be referenced, it is recommended to provide an online landing page linking all available + resources. + + Examples: HOME_URL="https://fedoraproject.org/", + BUG_REPORT_URL="https://bugzilla.redhat.com/". + + + + SUPPORT_END= + + The date at which support for this version of the OS ends. (What exactly "lack of + support" means varies between vendors, but generally users should assume that updates, including + security fixes, will not be provided.) The value is a date in the ISO 8601 format + YYYY-MM-DD, and specifies the first day on which support is + not provided. + + For example, SUPPORT_END=2001-01-01 means that the system was supported + until the end of the last day of the previous millennium. + + + + LOGO= + + A string, specifying the name of an icon as defined by freedesktop.org Icon Theme + Specification. This can be used by graphical applications to display an operating system's + or distributor's logo. This field is optional and may not necessarily be implemented on all + systems. + + Examples: LOGO=fedora-logo, LOGO=distributor-logo-opensuse + + + + + ANSI_COLOR= + + A suggested presentation color when showing the OS name on the console. This should + be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting + graphical rendition. This field is optional. + + Examples: ANSI_COLOR="0;31" for red, ANSI_COLOR="1;34" + for light blue, or ANSI_COLOR="0;38;2;60;110;180" for Fedora blue. + + + + + + + Distribution-level defaults and metadata + + + + DEFAULT_HOSTNAME= + + A string specifying the hostname if + hostname5 is not + present and no other configuration source specifies the hostname. Must be either a single DNS label + (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the + format allowed for DNS domain name labels), or a sequence of such labels separated by single dots + that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux + limitation (DNS allows longer names). + + See org.freedesktop.hostname15 + for a description of how + systemd-hostnamed.service8 + determines the fallback hostname. + + + + ARCHITECTURE= + A string that specifies which CPU architecture the userspace binaries require. + The architecture identifiers are the same as for ConditionArchitecture= + described in systemd.unit5. + The field is optional and should only be used when just single architecture is supported. + It may provide redundant information when used in a GPT partition with a GUID type that already + encodes the architecture. If this is not the case, the architecture should be specified in + e.g., an extension image, to prevent an incompatible host from loading it. + + + + + SYSEXT_LEVEL= + + 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 /usr/lib/extension-release.d/extension-release.IMAGE, + initrd and + systemd-sysext8) + for more information. + + Examples: SYSEXT_LEVEL=2, SYSEXT_LEVEL=15.14. + + + + + SYSEXT_SCOPE= + Takes a space-separated list of one or more of the strings + system, initrd and portable. This field is + only supported in extension-release.d/ files and indicates what environments + the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service + images. If unspecified, SYSEXT_SCOPE=system portable is implied, i.e. any system + extension without this field is applicable to regular systems and to portable service environments, + but not to initrd environments. + + + + PORTABLE_PREFIXES= + Takes a space-separated list of one or more valid prefix match strings for the + Portable Services logic. This field + serves two purposes: it is informational, identifying portable service images as such (and thus + allowing them to be distinguished from other OS images, such as bootable system images). It is also + used when a portable service image is attached: the specified or implied portable service prefix is + checked against the list specified here, to enforce restrictions how images may be attached to a + system. + + + + + + Notes + + If you are using this file to determine the OS or a specific version of it, use the + ID and VERSION_ID fields, possibly with + ID_LIKE as fallback for ID. When looking for an OS identification + string for presentation to the user use the PRETTY_NAME field. + + Note that operating system vendors may choose not to provide version information, for example to + accommodate for rolling releases. In this case, VERSION and + VERSION_ID may be unset. Applications should not rely on these fields to be + set. + + Operating system vendors may extend the file format and introduce new fields. It is highly + recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications + reading this file must ignore unknown fields. + + Example: DEBIAN_BTS="debbugs://bugs.debian.org/". + + Container and sandbox runtime managers may make the host's identification data available to + applications by providing the host's /etc/os-release (if available, otherwise + /usr/lib/os-release as a fallback) as + /run/host/os-release. + + + + + Examples + + + <filename>os-release</filename> file for Fedora Workstation + + NAME=Fedora +VERSION="32 (Workstation Edition)" +ID=fedora +VERSION_ID=32 +PRETTY_NAME="Fedora 32 (Workstation Edition)" +ANSI_COLOR="0;38;2;60;110;180" +LOGO=fedora-logo-icon +CPE_NAME="cpe:/o:fedoraproject:fedora:32" +HOME_URL="https://fedoraproject.org/" +DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/" +SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help" +BUG_REPORT_URL="https://bugzilla.redhat.com/" +REDHAT_BUGZILLA_PRODUCT="Fedora" +REDHAT_BUGZILLA_PRODUCT_VERSION=32 +REDHAT_SUPPORT_PRODUCT="Fedora" +REDHAT_SUPPORT_PRODUCT_VERSION=32 +PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy" +VARIANT="Workstation Edition" +VARIANT_ID=workstation + + + + <filename>extension-release</filename> file for an extension for Fedora Workstation 32 + + ID=fedora +VERSION_ID=32 + + + + Reading <filename>os-release</filename> in + <citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry> + + + + + + Reading <filename>os-release</filename> in + <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions >= 3.10) + + + + See docs for + platform.freedesktop_os_release for more details. + + + + + Reading <filename>os-release</filename> in + <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version) + + + + Note that the above version that uses the built-in implementation is preferred + in most cases, and the open-coded version here is provided for reference. + + + + + + See Also + + systemd1, + lsb_release1, + hostname5, + machine-id5, + machine-info5 + + + + -- cgit v1.2.3