eudev/man/os-release.xml

<?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">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  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
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<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>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para>The <filename>/etc/os-release</filename> file
                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
                (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>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>
                <title>Options</title>

                <para>The following OS identifications parameters may be set using
                <filename>/etc/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 file names. 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. 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
                                from, and not any OSes that
                                are derived from it, but 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 file names. 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="http://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>

                                <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"
                                resp. "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>


                </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
VERSION="17 (Beefy Miracle)"
ID=fedora
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>,
                          <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>