man: we don't support systems without /etc/os-release anymore

[thirdparty/systemd.git] / 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, allowing applications to read
                the file without implementing a shell compatible
                execution engine.</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>
        </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 string, and not necessarily
                                suitable for presentation to the
                                user. If not set defaults to
                                <literal>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 name information and
                                suitable for presentation to the
                                user. Example:
                                <literal>VERSION=15</literal> or
                                <literal>VERSION="15
                                (Rawhide)"</literal>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>ID=</varname></term>

                                <listitem><para>A lower-case string
                                (no spaces) 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>linux</literal>. Example:
                                <literal>ID=fedora</literal>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><varname>VERSION_ID=</varname></term>

                                <listitem><para>A lower-case string
                                (mostly numeric, no spaces) identifying the
                                operating system version, excluding
                                any name information and suitable for
                                processing by scripts or usage in generated file names. Example:
                                <literal>VERSION_ID=15</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 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>
                        </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. Example:
                                <literal>ANSI_COLOR="0;31"</literal> for
                                red, or
                                <literal>ANSI_COLOR="1;34"</literal> for
                                light blue.</para></listitem>
                        </varlistentry>
                </variablelist>

                <para>If you are reading this file from 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="15 (Rawhide)"
ID=fedora
VERSION_ID=15
PRETTY_NAME="Fedora 15 (Rawhide)"
ANSI_COLOR="0;34"</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>