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                                 OS identifiers the local
 160                                 OS is a derivative from. An
 161                                 OS should generally only list other OS
 162                                 identifiers it itself is a derivative
 163                                 from, and not any OSes that
 164                                 are derived from it, but symmetric
 165                                 relationships are possible. Build
 166                                 scripts and similar should check this
 167                                 variable if they need to identify the
 168                                 local operating system and the value
 169                                 of <varname>ID=</varname> is not
 170                                 recognized. Operating systems should
 171                                 be listed in order of how closely the
 172                                 local operating system relates to the
 173                                 listed ones, starting with the
 174                                 closest. This field is
 175                                 optional. Example: for an operating
 176                                 system with
 177                                 <literal>ID=centos</literal> an
 178                                 assignment of <literal>ID_LIKE="rhel
 179                                 fedora"</literal> would be
 180                                 appropriate. For an operating systemd
 181                                 with <literal>ID=ubuntu</literal> an
 182                                 assignment of
 183                                 <literal>ID_LIKE=debian</literal> is
 184                                 appropriate.</para></listitem>
 185                         </varlistentry>
 186
 187                         <varlistentry>
 188                                 <term><varname>VERSION_ID=</varname></term>
 189
 190                                 <listitem><para>A lower-case string
 191                                 (mostly numeric, no spaces or other
 192                                 characters outside of 0-9, a-z, ".",
 193                                 "_" and "-") identifying the operating
 194                                 system version, excluding any OS name
 195                                 information or release code name, and
 196                                 suitable for processing by scripts or
 197                                 usage in generated file names. This
 198                                 field is optional. Example:
 199                                 <literal>VERSION_ID=17</literal> or
 200                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 201                         </varlistentry>
 202
 203                         <varlistentry>
 204                                 <term><varname>PRETTY_NAME=</varname></term>
 205
 206                                 <listitem><para>A pretty operating
 207                                 system name in a format suitable for
 208                                 presentation to the user. May or may
 209                                 not contain a release code name or OS
 210                                 version of some kind, as suitable. If
 211                                 not set defaults to
 212                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
 213                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
 214                                 Miracle)"</literal>.</para></listitem>
 215                         </varlistentry>
 216
 217                         <varlistentry>
 218                                 <term><varname>ANSI_COLOR=</varname></term>
 219
 220                                 <listitem><para>A suggested
 221                                 presentation color when showing the
 222                                 OS name on the console. This
 223                                 should be specified as string suitable
 224                                 for inclusion in the ESC [ m
 225                                 ANSI/ECMA-48 escape code for setting
 226                                 graphical rendition. This field is
 227                                 optional. Example:
 228                                 <literal>ANSI_COLOR="0;31"</literal>
 229                                 for red, or
 230                                 <literal>ANSI_COLOR="1;34"</literal>
 231                                 for light blue.</para></listitem>
 232                         </varlistentry>
 233
 234                         <varlistentry>
 235                                 <term><varname>CPE_NAME=</varname></term>
 236
 237                                 <listitem><para>A CPE name for the
 238                                 operating system, following the <ulink
 239                                 url="http://cpe.mitre.org/specification/">Common
 240                                 Platform Enumeration
 241                                 Specification</ulink> as proposed by
 242                                 the MITRE Corporation. This field
 243                                 is optional. Example:
 244                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
 245                                 </para></listitem>
 246                         </varlistentry>
 247
 248                         <varlistentry>
 249                                 <term><varname>HOME_URL=</varname></term>
 250                                 <term><varname>SUPPORT_URL=</varname></term>
 251                                 <term><varname>BUG_REPORT_URL=</varname></term>
 252
 253                                 <listitem><para>Links to resources on
 254                                 the Internet related the operating
 255                                 system. <varname>HOME_URL=</varname>
 256                                 should refer to the homepage of the of
 257                                 operating system, or alternatively
 258                                 some homepage of the specific version
 259                                 of the operating
 260                                 system. <varname>SUPPORT_URL=</varname>
 261                                 should refer to the main support page
 262                                 for the operating system, if there is
 263                                 any. This is primarily intended for
 264                                 operating systems which vendors
 265                                 provide support
 266                                 for. <varname>BUG_REPORT_URL=</varname>
 267                                 should refer to the main bug reporting
 268                                 page for the operating system, if
 269                                 there is any. This is primarily
 270                                 intended for operating systems that
 271                                 rely on community QA. These settings
 272                                 are optional, and providing only some
 273                                 of these settings is common. These
 274                                 URLs are intended to be exposed in
 275                                 "About this system" UIs behind links
 276                                 with captions such as "About this
 277                                 Operating System", "Obtain Support"
 278                                 resp. "Report a Bug". The values should
 279                                 be in <ulink
 280                                 url="https://tools.ietf.org/html/rfc3986">RFC3986
 281                                 format</ulink>, and should be
 282                                 <literal>http:</literal> or
 283                                 <literal>https:</literal> URLs, and
 284                                 possibly <literal>mailto:</literal> or
 285                                 <literal>tel:</literal>. Only one URL
 286                                 shall be listed in each setting. If
 287                                 multiple resources need to be
 288                                 referenced it is recommended to
 289                                 provide an online landing page linking
 290                                 all available resources. Examples:
 291                                 <literal>HOME_URL="https://fedoraproject.org/"</literal>
 292                                 and
 293                                 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
 294                         </varlistentry>
 295
 296
 297                 </variablelist>
 298
 299                 <para>If you are reading this file from C code or a
 300                 shell script to determine the OS or a specific version
 301                 of it, use the ID and VERSION_ID fields, possibly with
 302                 ID_LIKE as fallback for ID. When looking for an OS
 303                 identification string for presentation to the user use
 304                 the PRETTY_NAME field.</para>
 305
 306                 <para>Note that operating system vendors may choose
 307                 not to provide version information, for example to
 308                 accommodate for rolling releases. In this case VERSION
 309                 and VERSION_ID may be unset. Applications should not
 310                 rely on these fields to be set.</para>
 311         </refsect1>
 312
 313         <refsect1>
 314                 <title>Example</title>
 315
 316                 <programlisting>NAME=Fedora
 317 VERSION="17 (Beefy Miracle)"
 318 ID=fedora
 319 VERSION_ID=17
 320 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 321 ANSI_COLOR="0;34"
 322 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
 323 HOME_URL="https://fedoraproject.org/"
 324 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
 325         </refsect1>
 326
 327         <refsect1>
 328                   <title>See Also</title>
 329                   <para>
 330                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 331                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 332                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 333                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 334                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 335                   </para>
 336         </refsect1>
 337
 338 </refentry>