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>ID_LIKE=</varname></term>
 149
 150                                 <listitem><para>A space-separated list
 151                                 of operating system identifiers in the
 152                                 same syntax as the
 153                                 <varname>ID=</varname> setting. Should
 154                                 list identifiers of operating systems
 155                                 that are closely related to the local
 156                                 operating system in regards to
 157                                 packaging and programming interfaces,
 158                                 for example listing one or more
 159                                 distribution identifiers the local
 160                                 distribution is a derivative
 161                                 from. Build scripts and similar should
 162                                 check this variable if they need to
 163                                 identify the local operating system
 164                                 and the value of
 165                                 <varname>ID=</varname> is not
 166                                 recognized. Operating systems should
 167                                 be listed in order of how closely the
 168                                 local operating system relates to the
 169                                 listed ones, starting with the
 170                                 closest. This field is
 171                                 optional. Example: for an operating
 172                                 system with
 173                                 <literal>ID=centos</literal> an
 174                                 assignment of <literal>ID_LIKE="rhel
 175                                 fedora"</literal> would be
 176                                 appropriate. For an operating systemd
 177                                 with <literal>ID=ubuntu</literal> an
 178                                 assignment of
 179                                 <literal>ID_LIKE=debian</literal> is
 180                                 appropriate.</para></listitem>
 181                         </varlistentry>
 182
 183                         <varlistentry>
 184                                 <term><varname>VERSION_ID=</varname></term>
 185
 186                                 <listitem><para>A lower-case string
 187                                 (mostly numeric, no spaces or other
 188                                 characters outside of 0-9, a-z, ".",
 189                                 "_" and "-") identifying the operating
 190                                 system version, excluding any OS name
 191                                 information or release code name, and
 192                                 suitable for processing by scripts or
 193                                 usage in generated file names. This
 194                                 field is optional. Example:
 195                                 <literal>VERSION_ID=17</literal> or
 196                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 197                         </varlistentry>
 198
 199                         <varlistentry>
 200                                 <term><varname>PRETTY_NAME=</varname></term>
 201
 202                                 <listitem><para>A pretty operating
 203                                 system name in a format suitable for
 204                                 presentation to the user. May or may
 205                                 not contain a release code name or OS
 206                                 version of some kind, as suitable. If
 207                                 not set defaults to
 208                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
 209                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
 210                                 Miracle)"</literal>.</para></listitem>
 211                         </varlistentry>
 212
 213                         <varlistentry>
 214                                 <term><varname>ANSI_COLOR=</varname></term>
 215
 216                                 <listitem><para>A suggested
 217                                 presentation color when showing the
 218                                 distribution name on the console. This
 219                                 should be specified as string suitable
 220                                 for inclusion in the ESC [ m
 221                                 ANSI/ECMA-48 escape code for setting
 222                                 graphical rendition. This field is
 223                                 optional. Example:
 224                                 <literal>ANSI_COLOR="0;31"</literal>
 225                                 for red, or
 226                                 <literal>ANSI_COLOR="1;34"</literal>
 227                                 for light blue.</para></listitem>
 228                         </varlistentry>
 229
 230                         <varlistentry>
 231                                 <term><varname>CPE_NAME=</varname></term>
 232
 233                                 <listitem><para>A CPE name for the
 234                                 operating system, following the <ulink
 235                                 url="http://cpe.mitre.org/specification/">Common
 236                                 Platform Enumeration
 237                                 Specification</ulink> as proposed by
 238                                 the MITRE Corporation. This field
 239                                 is optional. Example:
 240                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
 241                                 </para></listitem>
 242                         </varlistentry>
 243                 </variablelist>
 244
 245                 <para>If you are reading this file from C code or a
 246                 shell script to determine the OS or a specific version
 247                 of it, use the ID and VERSION_ID fields. When looking
 248                 for an OS identification string for presentation to
 249                 the user use the PRETTY_NAME field.</para>
 250
 251                 <para>Note that operating system vendors may choose
 252                 not to provide version information, for example to
 253                 accommodate for rolling releases. In this case VERSION
 254                 and VERSION_ID may be unset. Applications should not
 255                 rely on these fields to be set.</para>
 256         </refsect1>
 257
 258         <refsect1>
 259                 <title>Example</title>
 260
 261                 <programlisting>NAME=Fedora
 262 VERSION="17 (Beefy Miracle)"
 263 ID=fedora
 264 VERSION_ID=17
 265 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 266 ANSI_COLOR="0;34"
 267 CPE_NAME="cpe:/o:fedoraproject:fedora:17"</programlisting>
 268         </refsect1>
 269
 270         <refsect1>
 271                   <title>See Also</title>
 272                   <para>
 273                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 274                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 275                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 276                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 277                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 278                   </para>
 279         </refsect1>
 280
 281 </refentry>