man/os-release.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="os-release">
  26         <refentryinfo>
  27                 <title>os-release</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>os-release</refentrytitle>
  42                 <manvolnum>5</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>os-release</refname>
  47                 <refpurpose>Operating system identification</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <para><filename>/etc/os-release</filename></para>
  52         </refsynopsisdiv>
  53
  54         <refsect1>
  55                 <title>Description</title>
  56
  57                 <para>The <filename>/etc/os-release</filename> file
  58                 contains operating system identification data.</para>
  59
  60                 <para>The basic file format of
  61                 <filename>os-release</filename> is a newline-separated
  62                 list of environment-like shell-compatible variable
  63                 assignments. It is possible to source the
  64                 configuration from shell scripts, however, beyond mere
  65                 variable assignments no shell features are supported
  66                 (this means variable expansion is explicitly not
  67                 supported), allowing applications to read the file
  68                 without implementing a shell compatible execution
  69                 engine. Variable assignment values should be enclosed
  70                 in double or single quotes if they include spaces,
  71                 semicolons or other special characters outside of A-Z,
  72                 a-z, 0-9. All strings should be in UTF-8 format, and
  73                 non-printable characters should not be used. If double
  74                 or single quotes or backslashes are to be used within
  75                 variable assignments they should be escaped with
  76                 backslashes, following shell style. It is not
  77                 supported to concatenate multiple individually quoted
  78                 strings. Lines beginning with "#" shall be ignored as
  79                 comments.</para>
  80
  81                 <para><filename>/etc/os-release</filename> contains
  82                 data that is defined by the operating system vendor
  83                 and should not be changed by the administrator.</para>
  84
  85                 <para>As this file only encodes names and identifiers
  86                 it should not be localized.</para>
  87
  88                 <para>For a longer rationale for
  89                 <filename>/etc/os-release</filename> please refer to
  90                 the <ulink
  91                 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
  92         </refsect1>
  93
  94         <refsect1>
  95                 <title>Options</title>
  96
  97                 <para>The following OS identifications parameters may be set using
  98                 <filename>/etc/os-release</filename>:</para>
  99
 100                 <variablelist>
 101
 102                         <varlistentry>
 103                                 <term><varname>NAME=</varname></term>
 104
 105                                 <listitem><para>A string identifying
 106                                 the operating system, without a
 107                                 version component, and suitable for
 108                                 presentation to the user. If not set
 109                                 defaults to
 110                                 <literal>NAME=Linux</literal>. Example:
 111                                 <literal>NAME=Fedora</literal> or
 112                                 <literal>NAME="Debian
 113                                 GNU/Linux"</literal>.</para></listitem>
 114                         </varlistentry>
 115
 116                         <varlistentry>
 117                                 <term><varname>VERSION=</varname></term>
 118
 119                                 <listitem><para>A string identifying
 120                                 the operating system version,
 121                                 excluding any OS name information,
 122                                 possibly including a release code
 123                                 name, and suitable for presentation to
 124                                 the user. This field is
 125                                 optional. Example:
 126                                 <literal>VERSION=17</literal> or
 127                                 <literal>VERSION="17 (Beefy
 128                                 Miracle)"</literal>.</para></listitem>
 129                         </varlistentry>
 130
 131                         <varlistentry>
 132                                 <term><varname>ID=</varname></term>
 133
 134                                 <listitem><para>A lower-case string
 135                                 (no spaces or other characters outside
 136                                 of 0-9, a-z, ".", "_" and "-")
 137                                 identifying the operating system,
 138                                 excluding any version information and
 139                                 suitable for processing by scripts or
 140                                 usage in generated file names. If not
 141                                 set defaults to
 142                                 <literal>ID=linux</literal>. Example:
 143                                 <literal>ID=fedora</literal> or
 144                                 <literal>ID=debian</literal>.</para></listitem>
 145                         </varlistentry>
 146
 147                         <varlistentry>
 148                                 <term><varname>VERSION_ID=</varname></term>
 149
 150                                 <listitem><para>A lower-case string
 151                                 (mostly numeric, no spaces or other
 152                                 characters outside of 0-9, a-z, ".",
 153                                 "_" and "-") identifying the operating
 154                                 system version, excluding any OS name
 155                                 information or release code name, and
 156                                 suitable for processing by scripts or
 157                                 usage in generated file names. This
 158                                 field is optional. Example:
 159                                 <literal>VERSION_ID=17</literal> or
 160                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 161                         </varlistentry>
 162
 163                         <varlistentry>
 164                                 <term><varname>PRETTY_NAME=</varname></term>
 165
 166                                 <listitem><para>A pretty operating
 167                                 system name in a format suitable for
 168                                 presentation to the user. May or may
 169                                 not contain a release code name or OS
 170                                 version of some kind, as suitable. If
 171                                 not set defaults to
 172                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
 173                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
 174                                 Miracle)"</literal>.</para></listitem>
 175                         </varlistentry>
 176
 177                         <varlistentry>
 178                                 <term><varname>ANSI_COLOR=</varname></term>
 179
 180                                 <listitem><para>A suggested
 181                                 presentation color when showing the
 182                                 distribution name on the console. This
 183                                 should be specified as string suitable
 184                                 for inclusion in the ESC [ m
 185                                 ANSI/ECMA-48 escape code for setting
 186                                 graphical rendition. This field is
 187                                 optional. Example:
 188                                 <literal>ANSI_COLOR="0;31"</literal>
 189                                 for red, or
 190                                 <literal>ANSI_COLOR="1;34"</literal>
 191                                 for light blue.</para></listitem>
 192                         </varlistentry>
 193
 194                         <varlistentry>
 195                                 <term><varname>CPE_NAME=</varname></term>
 196
 197                                 <listitem><para>A CPE name for the
 198                                 operating system, following the <ulink
 199                                 url="http://cpe.mitre.org/specification/">Common
 200                                 Platform Enumeration
 201                                 Specification</ulink> as proposed by
 202                                 the MITRE Corporation. This field
 203                                 is optional. Example:
 204                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
 205                                 </para></listitem>
 206                         </varlistentry>
 207                 </variablelist>
 208
 209                 <para>If you are reading this file from C code or a
 210                 shell script to determine the OS or a specific version
 211                 of it, use the ID and VERSION_ID fields. When looking
 212                 for an OS identification string for presentation to
 213                 the user use the PRETTY_NAME field.</para>
 214
 215                 <para>Note that operating system vendors may choose
 216                 not to provide version information, for example to
 217                 accommodate for rolling releases. In this case VERSION
 218                 and VERSION_ID may be unset. Applications should not
 219                 rely on these fields to be set.</para>
 220         </refsect1>
 221
 222         <refsect1>
 223                 <title>Example</title>
 224
 225                 <programlisting>NAME=Fedora
 226 VERSION="17 (Beefy Miracle)"
 227 ID=fedora
 228 VERSION_ID=17
 229 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 230 ANSI_COLOR="0;34"
 231 CPE_NAME="cpe:/o:fedoraproject:fedora:17"</programlisting>
 232         </refsect1>
 233
 234         <refsect1>
 235                   <title>See Also</title>
 236                   <para>
 237                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 238                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 239                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 240                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 241                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 242                   </para>
 243         </refsect1>
 244
 245 </refentry>