udevadm-settle: add missing brace

[elogind.git] / man / os-release.xml

diff --git a/man/os-release.xml b/man/os-release.xml
index c6eb28f395f3d2112192ad845e87182248426f14..c1dd62f7156d2c1c978eab7229d522d0681cf565 100644 (file)
--- a/man/os-release.xml
+++ b/man/os-release.xml
@@ -9,16 +9,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or

   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -58,23 +58,42 @@
                 contains operating system identification data.</para>
 
                 <para>The basic file format of
                 contains 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, allowing applications to read
-                the file without implementing a shell compatible
-                execution engine.</para>
+                <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 should be enclosed
+                in double or single quotes if they include spaces,
+                semicolons or other special characters outside of A-Z,
+                a-z, 0-9. All strings should be in UTF-8 format, and
+                non-printable characters should not be used. If double
+                or single quotes or backslashes are to be used within
+                variable assignments, they should be escaped with
+                backslashes, following shell style. It is not
+                supported to concatenate multiple individually quoted
+                strings. Lines beginning with "#" shall be ignored as
+                comments.</para>

 
                 <para><filename>/etc/os-release</filename> contains
                 data that is defined by the operating system vendor
                 and should not be changed by the administrator.</para>
 
 
                 <para><filename>/etc/os-release</filename> contains
                 data that is defined by the operating system vendor
                 and should not be changed by the administrator.</para>
 

-                <para>Depending on the operating system other
-                configuration files might be checked for OS
-                identification as well, however only as
-                fallback.</para>
+                <para>As this file only encodes names and identifiers
+                it should not be localized.</para>
+
+                <para>The file <filename>/etc/os-release</filename> might
+                be a symlink to another file, 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>/etc/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>
         </refsect1>
 
         <refsect1>


@@ -90,10 +109,10 @@
 
                                 <listitem><para>A string identifying
                                 the operating system, without a
 
                                 <listitem><para>A string identifying
                                 the operating system, without a

-                                version string, and not necessarily
-                                suitable for presentation to the
-                                user. If not set defaults to
-                                <literal>Linux</literal>. Example:
+                                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>
                                 <literal>NAME=Fedora</literal> or
                                 <literal>NAME="Debian
                                 GNU/Linux"</literal>.</para></listitem>


@@ -104,35 +123,86 @@
 
                                 <listitem><para>A string identifying
                                 the operating system version,
 
                                 <listitem><para>A string identifying
                                 the operating system version,

-                                excluding any name information and
-                                suitable for presentation to the
-                                user. Example:
-                                <literal>VERSION=15</literal> or
-                                <literal>VERSION="15
-                                (Rawhide)"</literal>.</para></listitem>
+                                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
                         </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
                                 identifying the operating system,
                                 excluding any version information and

-                                suitable for processing by scripts. If
-                                not set defaults to
-                                <literal>linux</literal>. Example:
-                                <literal>ID=fedora</literal>.</para></listitem>
+                                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
                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>VERSION_ID=</varname></term>
 
                                 <listitem><para>A lower-case string

-                                (mostly numeric) identifying the
-                                operating system version, excluding
-                                any name information and suitable for
-                                processing by scripts. Example:
-                                <literal>VERSION_ID=15</literal>.</para></listitem>
+                                (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>
                         </varlistentry>
 
                         <varlistentry>


@@ -141,11 +211,12 @@
                                 <listitem><para>A pretty operating
                                 system name in a format suitable for
                                 presentation to the user. May or may
                                 <listitem><para>A pretty operating
                                 system name in a format suitable for
                                 presentation to the user. May or may

-                                not contain an OS version of some
-                                kind, as suitable. If not set defaults
-                                to <literal>Linux</literal>. Example:
-                                <literal>PRETTY_NAME=Fedora 15
-                                (Rawhide)</literal>.</para></listitem>
+                                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>
                         </varlistentry>
 
                         <varlistentry>


@@ -153,41 +224,148 @@
 
                                 <listitem><para>A suggested
                                 presentation color when showing the
 
                                 <listitem><para>A suggested
                                 presentation color when showing the

-                                distribution name on the console. This
+                                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
                                 should be specified as string suitable
                                 for inclusion in the ESC [ m
                                 ANSI/ECMA-48 escape code for setting

-                                graphical rendition. Example:
-                                <literal>ANSI_COLOR=0;31</literal> for
-                                red, or
-                                <literal>ANSI_COLOR=1;34</literal> for
-                                light blue.</para></listitem>
+                                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>

+
+                        <varlistentry>
+                                <term><varname>HOME_URL=</varname></term>
+                                <term><varname>SUPPORT_URL=</varname></term>
+                                <term><varname>BUG_REPORT_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. 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",
+                                and "Report a Bug". 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>
 
                 </variablelist>
 

-                <para>If you interpreting this file from code or a
-                shell script, use the ID and VERSION_ID fields. When
-                looking for an OS indetification string for
-                presentation to the user use the PRETTY_STRING
-                field.</para>
+                <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
         </refsect1>
 
         <refsect1>
                 <title>Example</title>
 
                 <programlisting>NAME=Fedora

-VERSION=15 (Rawhide)
+VERSION="17 (Beefy Miracle)"

 ID=fedora
 ID=fedora

-VERSION_ID=15
-PRETTY_NAME=Fedora 15 (Rawhide)
-ANSI_COLOR=0;34</programlisting>
+VERSION_ID=17
+PRETTY_NAME="Fedora 17 (Beefy Miracle)"
+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>,
         </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>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>
 
                   </para>
         </refsect1>