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 Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 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   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser 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>The file <filename>/etc/os-release</filename> might
  89                 be a symlink to another file, but it is important that
  90                 the file is available from earliest boot on, and hence
  91                 must be located on the root file system.</para>
  92
  93                 <para>For a longer rationale for
  94                 <filename>/etc/os-release</filename> please refer to
  95                 the <ulink
  96                 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
  97         </refsect1>
  98
  99         <refsect1>
 100                 <title>Options</title>
 101
 102                 <para>The following OS identifications parameters may be set using
 103                 <filename>/etc/os-release</filename>:</para>
 104
 105                 <variablelist>
 106
 107                         <varlistentry>
 108                                 <term><varname>NAME=</varname></term>
 109
 110                                 <listitem><para>A string identifying
 111                                 the operating system, without a
 112                                 version component, and suitable for
 113                                 presentation to the user. If not set
 114                                 defaults to
 115                                 <literal>NAME=Linux</literal>. Example:
 116                                 <literal>NAME=Fedora</literal> or
 117                                 <literal>NAME="Debian
 118                                 GNU/Linux"</literal>.</para></listitem>
 119                         </varlistentry>
 120
 121                         <varlistentry>
 122                                 <term><varname>VERSION=</varname></term>
 123
 124                                 <listitem><para>A string identifying
 125                                 the operating system version,
 126                                 excluding any OS name information,
 127                                 possibly including a release code
 128                                 name, and suitable for presentation to
 129                                 the user. This field is
 130                                 optional. Example:
 131                                 <literal>VERSION=17</literal> or
 132                                 <literal>VERSION="17 (Beefy
 133                                 Miracle)"</literal>.</para></listitem>
 134                         </varlistentry>
 135
 136                         <varlistentry>
 137                                 <term><varname>ID=</varname></term>
 138
 139                                 <listitem><para>A lower-case string
 140                                 (no spaces or other characters outside
 141                                 of 0-9, a-z, ".", "_" and "-")
 142                                 identifying the operating system,
 143                                 excluding any version information and
 144                                 suitable for processing by scripts or
 145                                 usage in generated file names. If not
 146                                 set defaults to
 147                                 <literal>ID=linux</literal>. Example:
 148                                 <literal>ID=fedora</literal> or
 149                                 <literal>ID=debian</literal>.</para></listitem>
 150                         </varlistentry>
 151
 152                         <varlistentry>
 153                                 <term><varname>ID_LIKE=</varname></term>
 154
 155                                 <listitem><para>A space-separated list
 156                                 of operating system identifiers in the
 157                                 same syntax as the
 158                                 <varname>ID=</varname> setting. Should
 159                                 list identifiers of operating systems
 160                                 that are closely related to the local
 161                                 operating system in regards to
 162                                 packaging and programming interfaces,
 163                                 for example listing one or more
 164                                 OS identifiers the local
 165                                 OS is a derivative from. An
 166                                 OS should generally only list other OS
 167                                 identifiers it itself is a derivative
 168                                 from, and not any OSes that
 169                                 are derived from it, but symmetric
 170                                 relationships are possible. Build
 171                                 scripts and similar should check this
 172                                 variable if they need to identify the
 173                                 local operating system and the value
 174                                 of <varname>ID=</varname> is not
 175                                 recognized. Operating systems should
 176                                 be listed in order of how closely the
 177                                 local operating system relates to the
 178                                 listed ones, starting with the
 179                                 closest. This field is
 180                                 optional. Example: for an operating
 181                                 system with
 182                                 <literal>ID=centos</literal> an
 183                                 assignment of <literal>ID_LIKE="rhel
 184                                 fedora"</literal> would be
 185                                 appropriate. For an operating system
 186                                 with <literal>ID=ubuntu</literal> an
 187                                 assignment of
 188                                 <literal>ID_LIKE=debian</literal> is
 189                                 appropriate.</para></listitem>
 190                         </varlistentry>
 191
 192                         <varlistentry>
 193                                 <term><varname>VERSION_ID=</varname></term>
 194
 195                                 <listitem><para>A lower-case string
 196                                 (mostly numeric, no spaces or other
 197                                 characters outside of 0-9, a-z, ".",
 198                                 "_" and "-") identifying the operating
 199                                 system version, excluding any OS name
 200                                 information or release code name, and
 201                                 suitable for processing by scripts or
 202                                 usage in generated file names. This
 203                                 field is optional. Example:
 204                                 <literal>VERSION_ID=17</literal> or
 205                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 206                         </varlistentry>
 207
 208                         <varlistentry>
 209                                 <term><varname>PRETTY_NAME=</varname></term>
 210
 211                                 <listitem><para>A pretty operating
 212                                 system name in a format suitable for
 213                                 presentation to the user. May or may
 214                                 not contain a release code name or OS
 215                                 version of some kind, as suitable. If
 216                                 not set defaults to
 217                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
 218                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
 219                                 Miracle)"</literal>.</para></listitem>
 220                         </varlistentry>
 221
 222                         <varlistentry>
 223                                 <term><varname>ANSI_COLOR=</varname></term>
 224
 225                                 <listitem><para>A suggested
 226                                 presentation color when showing the
 227                                 OS name on the console. This
 228                                 should be specified as string suitable
 229                                 for inclusion in the ESC [ m
 230                                 ANSI/ECMA-48 escape code for setting
 231                                 graphical rendition. This field is
 232                                 optional. Example:
 233                                 <literal>ANSI_COLOR="0;31"</literal>
 234                                 for red, or
 235                                 <literal>ANSI_COLOR="1;34"</literal>
 236                                 for light blue.</para></listitem>
 237                         </varlistentry>
 238
 239                         <varlistentry>
 240                                 <term><varname>CPE_NAME=</varname></term>
 241
 242                                 <listitem><para>A CPE name for the
 243                                 operating system, following the <ulink
 244                                 url="http://cpe.mitre.org/specification/">Common
 245                                 Platform Enumeration
 246                                 Specification</ulink> as proposed by
 247                                 the MITRE Corporation. This field
 248                                 is optional. Example:
 249                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
 250                                 </para></listitem>
 251                         </varlistentry>
 252
 253                         <varlistentry>
 254                                 <term><varname>HOME_URL=</varname></term>
 255                                 <term><varname>SUPPORT_URL=</varname></term>
 256                                 <term><varname>BUG_REPORT_URL=</varname></term>
 257
 258                                 <listitem><para>Links to resources on
 259                                 the Internet related the operating
 260                                 system. <varname>HOME_URL=</varname>
 261                                 should refer to the homepage of the
 262                                 operating system, or alternatively
 263                                 some homepage of the specific version
 264                                 of the operating
 265                                 system. <varname>SUPPORT_URL=</varname>
 266                                 should refer to the main support page
 267                                 for the operating system, if there is
 268                                 any. This is primarily intended for
 269                                 operating systems which vendors
 270                                 provide support
 271                                 for. <varname>BUG_REPORT_URL=</varname>
 272                                 should refer to the main bug reporting
 273                                 page for the operating system, if
 274                                 there is any. This is primarily
 275                                 intended for operating systems that
 276                                 rely on community QA. These settings
 277                                 are optional, and providing only some
 278                                 of these settings is common. These
 279                                 URLs are intended to be exposed in
 280                                 "About this system" UIs behind links
 281                                 with captions such as "About this
 282                                 Operating System", "Obtain Support",
 283                                 and "Report a Bug". The values should
 284                                 be in <ulink
 285                                 url="https://tools.ietf.org/html/rfc3986">RFC3986
 286                                 format</ulink>, and should be
 287                                 <literal>http:</literal> or
 288                                 <literal>https:</literal> URLs, and
 289                                 possibly <literal>mailto:</literal> or
 290                                 <literal>tel:</literal>. Only one URL
 291                                 shall be listed in each setting. If
 292                                 multiple resources need to be
 293                                 referenced it is recommended to
 294                                 provide an online landing page linking
 295                                 all available resources. Examples:
 296                                 <literal>HOME_URL="https://fedoraproject.org/"</literal>
 297                                 and
 298                                 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
 299                         </varlistentry>
 300
 301                         <varlistentry>
 302                                 <term><varname>BUILD_ID=</varname></term>
 303
 304                                 <listitem><para>A string uniquely
 305                                 identifying the system image used as
 306                                 the origin for a distribution (it is
 307                                 not updated with system updates). The
 308                                 field can be identical between
 309                                 different VERSION_IDs as BUILD_ID is
 310                                 an only a unique identifier to a
 311                                 specific version. Distributions that
 312                                 release each update as a new version
 313                                 would only need to use VERSION_ID as
 314                                 each build is already distinct based
 315                                 on the VERSION_ID. This field is
 316                                 optional. Example:
 317                                 <literal>BUILD_ID="2013-03-20.3"</literal>
 318                                 or
 319                                 <literal>BUILD_ID=201303203</literal>.
 320
 321                                 </para></listitem>
 322                         </varlistentry>
 323
 324                 </variablelist>
 325
 326                 <para>If you are reading this file from C code or a
 327                 shell script to determine the OS or a specific version
 328                 of it, use the ID and VERSION_ID fields, possibly with
 329                 ID_LIKE as fallback for ID. When looking for an OS
 330                 identification string for presentation to the user use
 331                 the PRETTY_NAME field.</para>
 332
 333                 <para>Note that operating system vendors may choose
 334                 not to provide version information, for example to
 335                 accommodate for rolling releases. In this case VERSION
 336                 and VERSION_ID may be unset. Applications should not
 337                 rely on these fields to be set.</para>
 338
 339                 <para>Operating system vendors may extend the file
 340                 format and introduce new fields. It is highly
 341                 recommended to prefix new fields with an OS specific
 342                 name in order to avoid name clashes. Applications
 343                 reading this file must ignore unknown fields. Example:
 344                 <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
 345         </refsect1>
 346
 347         <refsect1>
 348                 <title>Example</title>
 349
 350                 <programlisting>NAME=Fedora
 351 VERSION="17 (Beefy Miracle)"
 352 ID=fedora
 353 VERSION_ID=17
 354 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 355 ANSI_COLOR="0;34"
 356 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
 357 HOME_URL="https://fedoraproject.org/"
 358 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
 359         </refsect1>
 360
 361         <refsect1>
 362                   <title>See Also</title>
 363                   <para>
 364                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 365                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 366                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 367                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 368                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 369                   </para>
 370         </refsect1>
 371
 372 </refentry>