diff options
Diffstat (limited to 'man/os-release.xml')
| -rw-r--r-- | man/os-release.xml | 659 |
1 files changed, 293 insertions, 366 deletions
diff --git a/man/os-release.xml b/man/os-release.xml index 4fa41e7297..31dfe0ddf2 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -1,7 +1,7 @@ <?xml version='1.0'?> <!--*-nxml-*--> <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> <!-- This file is part of systemd. @@ -23,359 +23,286 @@ --> <refentry id="os-release"> - <refentryinfo> - <title>os-release</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Lennart</firstname> - <surname>Poettering</surname> - <email>lennart@poettering.net</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>os-release</refentrytitle> - <manvolnum>5</manvolnum> - </refmeta> - - <refnamediv> - <refname>os-release</refname> - <refpurpose>Operating system identification</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <para><filename>/etc/os-release</filename></para> - <para><filename>/usr/lib/os-release</filename></para> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para>The <filename>/etc/os-release</filename> and - <filename>/usr/lib/os-release</filename> files contain - operating system identification data.</para> - - <para>The basic file format of - <filename>os-release</filename> is a newline-separated - list of environment-like shell-compatible variable - assignments. It is possible to source the - configuration from 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. Shell special characters ("$", quotes, - backslash, backtick) must be escaped with backslashes, - following shell style. All strings should be in UTF-8 - format, and non-printable characters should not be used. - It is not supported to concatenate multiple individually - quoted strings. Lines beginning with "#" shall be - ignored as comments.</para> - - <para>The file <filename>/etc/os-release</filename> - takes precedence over - <filename>/usr/lib/os-release</filename>. Applications - should check for the former, and exclusively use its - data if it exists, and only fall back to - <filename>/usr/lib/os-release</filename> if it is - missing. Applications should not read data from both - files at the same - time. <filename>/usr/lib/os-release</filename> is the - recommended place to store OS release information as - part of vendor trees. - <filename>/etc/os-release</filename> should be a - relative symlink to - <filename>/usr/lib/os-release</filename>, - to provide compatibility with applications only - looking at <filename>/etc</filename>. A relative - symlink instead of an absolute symlink is - necessary to avoid breaking the link in a chroot or - initrd environment such as dracut.</para> - - <para><filename>os-release</filename> contains data - that is defined by the operating system vendor and - should generally not be changed by the - administrator.</para> - - <para>As this file only encodes names and identifiers - it should not be localized.</para> - - <para>The <filename>/etc/os-release</filename> and - <filename>/usr/lib/os-release</filename> 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.</para> - - <para>For a longer rationale for - <filename>os-release</filename> please refer to - the <ulink - url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following OS identifications parameters may be set using - <filename>os-release</filename>:</para> - - <variablelist> - - <varlistentry> - <term><varname>NAME=</varname></term> - - <listitem><para>A string identifying - the operating system, without a - version component, and suitable for - presentation to the user. If not set, - defaults to - <literal>NAME=Linux</literal>. Example: - <literal>NAME=Fedora</literal> or - <literal>NAME="Debian - GNU/Linux"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VERSION=</varname></term> - - <listitem><para>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: - <literal>VERSION=17</literal> or - <literal>VERSION="17 (Beefy - Miracle)"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ID=</varname></term> - - <listitem><para>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 - <literal>ID=linux</literal>. Example: - <literal>ID=fedora</literal> or - <literal>ID=debian</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ID_LIKE=</varname></term> - - <listitem><para>A space-separated list - of operating system identifiers in the - same syntax as the - <varname>ID=</varname> 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 <varname>ID=</varname> 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 - <literal>ID=centos</literal>, an - assignment of <literal>ID_LIKE="rhel - fedora"</literal> would be - appropriate. For an operating system - with <literal>ID=ubuntu</literal>, an - assignment of - <literal>ID_LIKE=debian</literal> is - appropriate.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>VERSION_ID=</varname></term> - - <listitem><para>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: - <literal>VERSION_ID=17</literal> or - <literal>VERSION_ID=11.04</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>PRETTY_NAME=</varname></term> - - <listitem><para>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 - <literal>PRETTY_NAME="Linux"</literal>. Example: - <literal>PRETTY_NAME="Fedora 17 (Beefy - Miracle)"</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>ANSI_COLOR=</varname></term> - - <listitem><para>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: - <literal>ANSI_COLOR="0;31"</literal> - for red, or - <literal>ANSI_COLOR="1;34"</literal> - for light blue.</para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>CPE_NAME=</varname></term> - - <listitem><para>A CPE name for the - operating system, following the <ulink - url="https://cpe.mitre.org/specification/">Common - Platform Enumeration - Specification</ulink> as proposed by - the MITRE Corporation. This field - is optional. Example: - <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> - </para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>HOME_URL=</varname></term> - <term><varname>SUPPORT_URL=</varname></term> - <term><varname>BUG_REPORT_URL=</varname></term> - <term><varname>PRIVACY_POLICY_URL=</varname></term> - - <listitem><para>Links to resources on - the Internet related the operating - system. <varname>HOME_URL=</varname> - should refer to the homepage of the - operating system, or alternatively - some homepage of the specific version - of the operating - system. <varname>SUPPORT_URL=</varname> - 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. <varname>BUG_REPORT_URL=</varname> - 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. - <varname>PRIVACY_POLICY_URL=</varname> - should refer to the main privacy policy - page for the operation 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 <ulink - url="https://tools.ietf.org/html/rfc3986">RFC3986 - format</ulink>, and should be - <literal>http:</literal> or - <literal>https:</literal> URLs, and - possibly <literal>mailto:</literal> or - <literal>tel:</literal>. 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: - <literal>HOME_URL="https://fedoraproject.org/"</literal> - and - <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem> - </varlistentry> - - <varlistentry> - <term><varname>BUILD_ID=</varname></term> - - <listitem><para>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: - <literal>BUILD_ID="2013-03-20.3"</literal> - or - <literal>BUILD_ID=201303203</literal>. - - </para></listitem> - </varlistentry> - - </variablelist> - - <para>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.</para> - - <para>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.</para> - - <para>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: - <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para> - </refsect1> - - <refsect1> - <title>Example</title> - - <programlisting>NAME=Fedora + <refentryinfo> + <title>os-release</title> + <productname>systemd</productname> + + <authorgroup> + <author> + <contrib>Developer</contrib> + <firstname>Lennart</firstname> + <surname>Poettering</surname> + <email>lennart@poettering.net</email> + </author> + </authorgroup> + </refentryinfo> + + <refmeta> + <refentrytitle>os-release</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>os-release</refname> + <refpurpose>Operating system identification</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/os-release</filename></para> + <para><filename>/usr/lib/os-release</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> files contain operating + system identification data.</para> + + <para>The basic file format of <filename>os-release</filename> is + a newline-separated list of environment-like shell-compatible + variable assignments. It is possible to source the configuration + from 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. Shell special characters ("$", quotes, + backslash, backtick) must be escaped with backslashes, following + shell style. All strings should be in UTF-8 format, and + non-printable characters should not be used. It is not supported + to concatenate multiple individually quoted strings. Lines + beginning with "#" shall be ignored as comments.</para> + + <para>The file <filename>/etc/os-release</filename> takes + precedence over <filename>/usr/lib/os-release</filename>. + Applications should check for the former, and exclusively use its + data if it exists, and only fall back to + <filename>/usr/lib/os-release</filename> if it is missing. + Applications should not read data from both files at the same + time. <filename>/usr/lib/os-release</filename> is the recommended + place to store OS release information as part of vendor trees. + <filename>/etc/os-release</filename> should be a relative symlink + to <filename>/usr/lib/os-release</filename>, to provide + compatibility with applications only looking at + <filename>/etc</filename>. A relative symlink instead of an + absolute symlink is necessary to avoid breaking the link in a + chroot or initrd environment such as dracut.</para> + + <para><filename>os-release</filename> contains data that is + defined by the operating system vendor and should generally not be + changed by the administrator.</para> + + <para>As this file only encodes names and identifiers it should + not be localized.</para> + + <para>The <filename>/etc/os-release</filename> and + <filename>/usr/lib/os-release</filename> 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.</para> + + <para>For a longer rationale for <filename>os-release</filename> + please refer to the <ulink + url="http://0pointer.de/blog/projects/os-release">Announcement of + <filename>/etc/os-release</filename></ulink>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following OS identifications parameters may be set using + <filename>os-release</filename>:</para> + + <variablelist> + + <varlistentry> + <term><varname>NAME=</varname></term> + + <listitem><para>A string identifying the operating system, + without a version component, and suitable for presentation to + the user. If not set, defaults to + <literal>NAME=Linux</literal>. Example: + <literal>NAME=Fedora</literal> or <literal>NAME="Debian + GNU/Linux"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION=</varname></term> + + <listitem><para>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: + <literal>VERSION=17</literal> or <literal>VERSION="17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID=</varname></term> + + <listitem><para>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 + <literal>ID=linux</literal>. Example: + <literal>ID=fedora</literal> or + <literal>ID=debian</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ID_LIKE=</varname></term> + + <listitem><para>A space-separated list of operating system + identifiers in the same syntax as the <varname>ID=</varname> + 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 + <varname>ID=</varname> 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 + <literal>ID=centos</literal>, an assignment of + <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. + For an operating system with <literal>ID=ubuntu</literal>, an + assignment of <literal>ID_LIKE=debian</literal> is + appropriate.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>VERSION_ID=</varname></term> + + <listitem><para>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: <literal>VERSION_ID=17</literal> + or <literal>VERSION_ID=11.04</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>PRETTY_NAME=</varname></term> + + <listitem><para>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 + <literal>PRETTY_NAME="Linux"</literal>. Example: + <literal>PRETTY_NAME="Fedora 17 (Beefy + Miracle)"</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ANSI_COLOR=</varname></term> + + <listitem><para>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: <literal>ANSI_COLOR="0;31"</literal> for red, or + <literal>ANSI_COLOR="1;34"</literal> for light + blue.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>CPE_NAME=</varname></term> + + <listitem><para>A CPE name for the operating system, following + the <ulink url="https://cpe.mitre.org/specification/">Common + Platform Enumeration Specification</ulink> as proposed by the + MITRE Corporation. This field is optional. Example: + <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal> + </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>HOME_URL=</varname></term> + <term><varname>SUPPORT_URL=</varname></term> + <term><varname>BUG_REPORT_URL=</varname></term> + <term><varname>PRIVACY_POLICY_URL=</varname></term> + + <listitem><para>Links to resources on the Internet related the + operating system. <varname>HOME_URL=</varname> should refer to + the homepage of the operating system, or alternatively some + homepage of the specific version of the operating system. + <varname>SUPPORT_URL=</varname> 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. <varname>BUG_REPORT_URL=</varname> 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. + <varname>PRIVACY_POLICY_URL=</varname> should refer to the + main privacy policy page for the operation 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 + <ulink url="https://tools.ietf.org/html/rfc3986">RFC3986 + format</ulink>, and should be <literal>http:</literal> or + <literal>https:</literal> URLs, and possibly + <literal>mailto:</literal> or <literal>tel:</literal>. 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: + <literal>HOME_URL="https://fedoraproject.org/"</literal> and + <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>BUILD_ID=</varname></term> + + <listitem><para>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: <literal>BUILD_ID="2013-03-20.3"</literal> + or <literal>BUILD_ID=201303203</literal>. + + </para></listitem> + </varlistentry> + + </variablelist> + + <para>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 + <varname>ID</varname> and <varname>VERSION_ID</varname> fields, + possibly with <varname>ID_LIKE</varname> as fallback for + <varname>ID</varname>. When looking for an OS identification + string for presentation to the user use the + <varname>PRETTY_NAME</varname> field.</para> + + <para>Note that operating system vendors may choose not to provide + version information, for example to accommodate for rolling + releases. In this case, <varname>VERSION</varname> and + <varname>VERSION_ID</varname> may be unset. Applications should + not rely on these fields to be set.</para> + + <para>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: + <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para> + </refsect1> + + <refsect1> + <title>Example</title> + + <programlisting>NAME=Fedora VERSION="17 (Beefy Miracle)" ID=fedora VERSION_ID=17 @@ -384,17 +311,17 @@ ANSI_COLOR="0;34" CPE_NAME="cpe:/o:fedoraproject:fedora:17" HOME_URL="https://fedoraproject.org/" BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> - </para> - </refsect1> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry> + </para> + </refsect1> </refentry> |