Systemd/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 General Public License as published by
  the Free Software Foundation; either version 2 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
  General Public License for more details.

  You should have received a copy of the GNU 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>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
                                distribution identifiers the local
                                distribution is a derivative
                                from. 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 systemd
                                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
                                distribution 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>
                </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. 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>
        </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"</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>