diff --git a/man/os-release.xml b/man/os-release.xml index cda0779303..a5b2437632 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -87,315 +87,303 @@ The following OS identifications parameters may be set using os-release: - + + General information identifying the operating system - - NAME= + + + NAME= - A string identifying the operating system, - without a version component, and suitable for presentation to - the user. If not set, defaults to - NAME=Linux. Example: - NAME=Fedora or NAME="Debian - GNU/Linux". - + 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. - - VERSION= + Examples: NAME=Fedora, NAME="Debian GNU/Linux". + + - 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. Example: - VERSION=17 or VERSION="17 (Beefy - Miracle)". - + + ID= - - 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. - 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, defaults to - ID=linux. Example: - ID=fedora or - ID=debian. - + Examples: ID=fedora, ID=debian. + - - ID_LIKE= + + 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. Example: 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. - + 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. - - VERSION_CODENAME= + 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. + + - - 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 - - + + PRETTY_NAME= - - VERSION_ID= + 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 - 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. Example: VERSION_ID=17 - or VERSION_ID=11.04. - + Example: PRETTY_NAME="Fedora 17 (Beefy Miracle)". + - - PRETTY_NAME= + + CPE_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, defaults to - PRETTY_NAME="Linux". Example: - PRETTY_NAME="Fedora 17 (Beefy - Miracle)". - + 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. - - ANSI_COLOR= + Example: CPE_NAME="cpe:/o:fedoraproject:fedora:17" + - 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. Example: 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. - + + VARIANT= - - CPE_NAME= + 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. - 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" - - + Examples: VARIANT="Server Edition", VARIANT="Smart Refrigerator + Edition". - - HOME_URL= - DOCUMENTATION_URL= - SUPPORT_URL= - BUG_REPORT_URL= - PRIVACY_POLICY_URL= + Note: this field is for display purposes only. The VARIANT_ID field should + be used for making programmatic decisions. + - 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/" and - BUG_REPORT_URL="https://bugzilla.redhat.com/" - + + VARIANT_ID= - - BUILD_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. - A string uniquely identifying the system image - used as the origin for a distribution (it is not updated with - system updates). The field can be identical between different - VERSION_IDs as BUILD_ID is an only a unique identifier to a - specific version. Distributions that release each update as a - new version would only need to use VERSION_ID as each build is - already distinct based on the VERSION_ID. This field is - optional. Example: BUILD_ID="2013-03-20.3" - or BUILD_ID=201303203. + Examples: VARIANT_ID=server, VARIANT_ID=embedded. + + + + - - + + Information about the version of the operating system - - VARIANT= + + + VERSION= - - 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. - - + 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. - - VARIANT_ID= + Examples: VERSION=17, VERSION="17 (Beefy Miracle)". + + - - 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 - - + + VERSION_ID= - - LOGO= + 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. - - 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 - - + Examples: VERSION_ID=17, VERSION_ID=11.04. + + - - DEFAULT_HOSTNAME= + + VERSION_CODENAME= - 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). + 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. - See - org.freedesktop.hostname15 - for a description of how - systemd-hostnamed.service8 - determines the fallback hostname. - + Examples: VERSION_CODENAME=buster, + VERSION_CODENAME=xenial. + - - SYSEXT_LEVEL= + + BUILD_ID= - 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: - systemd-sysext8). - Example: SYSEXT_LEVEL=2 or - SYSEXT_LEVEL=15.14. - + A string uniquely identifying the system image used as the origin for a distribution + (it is not updated with system updates). The field can be identical between different + VERSION_IDs as BUILD_ID is an only a unique identifier to a + specific version. Distributions that release each update as a new version would only need to use + VERSION_ID as each build is already distinct based on the + VERSION_ID. This field is optional. - - IMAGE_ID= + Examples: BUILD_ID="2013-03-20.3", BUILD_ID=201303203. + + - 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_ID= - - IMAGE_VERSION= + 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. - 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 - + Examples: IMAGE_ID=vendorx-cashier-system, + IMAGE_ID=netbook-image. + - + + IMAGE_VERSION= - If you are reading this file from C code or a shell script - 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. + 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. + - 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. + Examples: IMAGE_VERSION=33, IMAGE_VERSION=47.1rc1. + + + + - 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/" + + Presentation information and links - 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. + + + 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/". + + + + 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. + + + + 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: + systemd-sysext8) + for more information. + + Examples: SYSEXT_LEVEL=2, SYSEXT_LEVEL=15.14. + + + + + + + Notes + + If you are reading this file from C code or a shell script 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. +