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                 <para><filename>/usr/lib/os-release</filename></para>
  53         </refsynopsisdiv>
  54
  55         <refsect1>
  56                 <title>Description</title>
  57
  58                 <para>The <filename>/etc/os-release</filename> and
  59                 <filename>/usr/lib/os-release</filename> files contain
  60                 operating system identification data.</para>
  61
  62                 <para>The basic file format of
  63                 <filename>os-release</filename> is a newline-separated
  64                 list of environment-like shell-compatible variable
  65                 assignments. It is possible to source the
  66                 configuration from shell scripts, however, beyond mere
  67                 variable assignments, no shell features are supported
  68                 (this means variable expansion is explicitly not
  69                 supported), allowing applications to read the file
  70                 without implementing a shell compatible execution
  71                 engine. Variable assignment values should be enclosed
  72                 in double or single quotes if they include spaces,
  73                 semicolons or other special characters outside of A-Z,
  74                 a-z, 0-9. All strings should be in UTF-8 format, and
  75                 non-printable characters should not be used. If double
  76                 or single quotes or backslashes are to be used within
  77                 variable assignments, they should be escaped with
  78                 backslashes, following shell style. It is not
  79                 supported to concatenate multiple individually quoted
  80                 strings. Lines beginning with "#" shall be ignored as
  81                 comments.</para>
  82
  83                 <para>The file <filename>/etc/os-release</filename>
  84                 takes precedence over
  85                 <filename>/usr/lib/os-release</filename>. Applications
  86                 should check for the former, and exclusively use its
  87                 data if it exists, and only fall back to
  88                 <filename>/usr/lib/os-release</filename> if it is
  89                 missing. Applications should not read data from both
  90                 files at the same
  91                 time. <filename>/usr/lib/os-release</filename> is the
  92                 recommended place to store OS release information as
  93                 part of vendor trees.
  94                 <filename>/etc/os-release</filename> should be a
  95                 relative symlink to
  96                 <filename>/usr/lib/os-release</filename>,
  97                 to provide compatibility with applications only
  98                 looking at <filename>/etc</filename>. A relative
  99                 symlink instead of an absolute symlink is
 100                 necessary to avoid breaking the link in a chroot or
 101                 initrd environment such as dracut.</para>
 102
 103                 <para><filename>os-release</filename> contains data
 104                 that is defined by the operating system vendor and
 105                 should generally not be changed by the
 106                 administrator.</para>
 107
 108                 <para>As this file only encodes names and identifiers
 109                 it should not be localized.</para>
 110
 111                 <para>The <filename>/etc/os-release</filename> and
 112                 <filename>/usr/lib/os-release</filename> files might
 113                 be symlinks to other files, but it is important that
 114                 the file is available from earliest boot on, and hence
 115                 must be located on the root file system.</para>
 116
 117                 <para>For a longer rationale for
 118                 <filename>os-release</filename> please refer to
 119                 the <ulink
 120                 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
 121         </refsect1>
 122
 123         <refsect1>
 124                 <title>Options</title>
 125
 126                 <para>The following OS identifications parameters may be set using
 127                 <filename>os-release</filename>:</para>
 128
 129                 <variablelist>
 130
 131                         <varlistentry>
 132                                 <term><varname>NAME=</varname></term>
 133
 134                                 <listitem><para>A string identifying
 135                                 the operating system, without a
 136                                 version component, and suitable for
 137                                 presentation to the user. If not set,
 138                                 defaults to
 139                                 <literal>NAME=Linux</literal>. Example:
 140                                 <literal>NAME=Fedora</literal> or
 141                                 <literal>NAME="Debian
 142                                 GNU/Linux"</literal>.</para></listitem>
 143                         </varlistentry>
 144
 145                         <varlistentry>
 146                                 <term><varname>VERSION=</varname></term>
 147
 148                                 <listitem><para>A string identifying
 149                                 the operating system version,
 150                                 excluding any OS name information,
 151                                 possibly including a release code
 152                                 name, and suitable for presentation to
 153                                 the user. This field is
 154                                 optional. Example:
 155                                 <literal>VERSION=17</literal> or
 156                                 <literal>VERSION="17 (Beefy
 157                                 Miracle)"</literal>.</para></listitem>
 158                         </varlistentry>
 159
 160                         <varlistentry>
 161                                 <term><varname>ID=</varname></term>
 162
 163                                 <listitem><para>A lower-case string
 164                                 (no spaces or other characters outside
 165                                 of 0-9, a-z, ".", "_" and "-")
 166                                 identifying the operating system,
 167                                 excluding any version information and
 168                                 suitable for processing by scripts or
 169                                 usage in generated filenames. If not
 170                                 set, defaults to
 171                                 <literal>ID=linux</literal>. Example:
 172                                 <literal>ID=fedora</literal> or
 173                                 <literal>ID=debian</literal>.</para></listitem>
 174                         </varlistentry>
 175
 176                         <varlistentry>
 177                                 <term><varname>ID_LIKE=</varname></term>
 178
 179                                 <listitem><para>A space-separated list
 180                                 of operating system identifiers in the
 181                                 same syntax as the
 182                                 <varname>ID=</varname> setting. It should
 183                                 list identifiers of operating systems
 184                                 that are closely related to the local
 185                                 operating system in regards to
 186                                 packaging and programming interfaces,
 187                                 for example listing one or more
 188                                 OS identifiers the local
 189                                 OS is a derivative from. An
 190                                 OS should generally only list other OS
 191                                 identifiers it itself is a derivative
 192                                 of, and not any OSes that
 193                                 are derived from it, though symmetric
 194                                 relationships are possible. Build
 195                                 scripts and similar should check this
 196                                 variable if they need to identify the
 197                                 local operating system and the value
 198                                 of <varname>ID=</varname> is not
 199                                 recognized. Operating systems should
 200                                 be listed in order of how closely the
 201                                 local operating system relates to the
 202                                 listed ones, starting with the
 203                                 closest. This field is
 204                                 optional. Example: for an operating
 205                                 system with
 206                                 <literal>ID=centos</literal>, an
 207                                 assignment of <literal>ID_LIKE="rhel
 208                                 fedora"</literal> would be
 209                                 appropriate. For an operating system
 210                                 with <literal>ID=ubuntu</literal>, an
 211                                 assignment of
 212                                 <literal>ID_LIKE=debian</literal> is
 213                                 appropriate.</para></listitem>
 214                         </varlistentry>
 215
 216                         <varlistentry>
 217                                 <term><varname>VERSION_ID=</varname></term>
 218
 219                                 <listitem><para>A lower-case string
 220                                 (mostly numeric, no spaces or other
 221                                 characters outside of 0-9, a-z, ".",
 222                                 "_" and "-") identifying the operating
 223                                 system version, excluding any OS name
 224                                 information or release code name, and
 225                                 suitable for processing by scripts or
 226                                 usage in generated filenames. This
 227                                 field is optional. Example:
 228                                 <literal>VERSION_ID=17</literal> or
 229                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
 230                         </varlistentry>
 231
 232                         <varlistentry>
 233                                 <term><varname>PRETTY_NAME=</varname></term>
 234
 235                                 <listitem><para>A pretty operating
 236                                 system name in a format suitable for
 237                                 presentation to the user. May or may
 238                                 not contain a release code name or OS
 239                                 version of some kind, as suitable. If
 240                                 not set, defaults to
 241                                 <literal>PRETTY_NAME="Linux"</literal>. Example:
 242                                 <literal>PRETTY_NAME="Fedora 17 (Beefy
 243                                 Miracle)"</literal>.</para></listitem>
 244                         </varlistentry>
 245
 246                         <varlistentry>
 247                                 <term><varname>ANSI_COLOR=</varname></term>
 248
 249                                 <listitem><para>A suggested
 250                                 presentation color when showing the
 251                                 OS name on the console. This
 252                                 should be specified as string suitable
 253                                 for inclusion in the ESC [ m
 254                                 ANSI/ECMA-48 escape code for setting
 255                                 graphical rendition. This field is
 256                                 optional. Example:
 257                                 <literal>ANSI_COLOR="0;31"</literal>
 258                                 for red, or
 259                                 <literal>ANSI_COLOR="1;34"</literal>
 260                                 for light blue.</para></listitem>
 261                         </varlistentry>
 262
 263                         <varlistentry>
 264                                 <term><varname>CPE_NAME=</varname></term>
 265
 266                                 <listitem><para>A CPE name for the
 267                                 operating system, following the <ulink
 268                                 url="https://cpe.mitre.org/specification/">Common
 269                                 Platform Enumeration
 270                                 Specification</ulink> as proposed by
 271                                 the MITRE Corporation. This field
 272                                 is optional. Example:
 273                                 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
 274                                 </para></listitem>
 275                         </varlistentry>
 276
 277                         <varlistentry>
 278                                 <term><varname>HOME_URL=</varname></term>
 279                                 <term><varname>SUPPORT_URL=</varname></term>
 280                                 <term><varname>BUG_REPORT_URL=</varname></term>
 281
 282                                 <listitem><para>Links to resources on
 283                                 the Internet related the operating
 284                                 system. <varname>HOME_URL=</varname>
 285                                 should refer to the homepage of the
 286                                 operating system, or alternatively
 287                                 some homepage of the specific version
 288                                 of the operating
 289                                 system. <varname>SUPPORT_URL=</varname>
 290                                 should refer to the main support page
 291                                 for the operating system, if there is
 292                                 any. This is primarily intended for
 293                                 operating systems which vendors
 294                                 provide support
 295                                 for. <varname>BUG_REPORT_URL=</varname>
 296                                 should refer to the main bug reporting
 297                                 page for the operating system, if
 298                                 there is any. This is primarily
 299                                 intended for operating systems that
 300                                 rely on community QA. These settings
 301                                 are optional, and providing only some
 302                                 of these settings is common. These
 303                                 URLs are intended to be exposed in
 304                                 "About this system" UIs behind links
 305                                 with captions such as "About this
 306                                 Operating System", "Obtain Support",
 307                                 and "Report a Bug". The values should
 308                                 be in <ulink
 309                                 url="https://tools.ietf.org/html/rfc3986">RFC3986
 310                                 format</ulink>, and should be
 311                                 <literal>http:</literal> or
 312                                 <literal>https:</literal> URLs, and
 313                                 possibly <literal>mailto:</literal> or
 314                                 <literal>tel:</literal>. Only one URL
 315                                 shall be listed in each setting. If
 316                                 multiple resources need to be
 317                                 referenced, it is recommended to
 318                                 provide an online landing page linking
 319                                 all available resources. Examples:
 320                                 <literal>HOME_URL="https://fedoraproject.org/"</literal>
 321                                 and
 322                                 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
 323                         </varlistentry>
 324
 325                         <varlistentry>
 326                                 <term><varname>BUILD_ID=</varname></term>
 327
 328                                 <listitem><para>A string uniquely
 329                                 identifying the system image used as
 330                                 the origin for a distribution (it is
 331                                 not updated with system updates). The
 332                                 field can be identical between
 333                                 different VERSION_IDs as BUILD_ID is
 334                                 an only a unique identifier to a
 335                                 specific version. Distributions that
 336                                 release each update as a new version
 337                                 would only need to use VERSION_ID as
 338                                 each build is already distinct based
 339                                 on the VERSION_ID. This field is
 340                                 optional. Example:
 341                                 <literal>BUILD_ID="2013-03-20.3"</literal>
 342                                 or
 343                                 <literal>BUILD_ID=201303203</literal>.
 344
 345                                 </para></listitem>
 346                         </varlistentry>
 347
 348                 </variablelist>
 349
 350                 <para>If you are reading this file from C code or a
 351                 shell script to determine the OS or a specific version
 352                 of it, use the ID and VERSION_ID fields, possibly with
 353                 ID_LIKE as fallback for ID. When looking for an OS
 354                 identification string for presentation to the user use
 355                 the PRETTY_NAME field.</para>
 356
 357                 <para>Note that operating system vendors may choose
 358                 not to provide version information, for example to
 359                 accommodate for rolling releases. In this case, VERSION
 360                 and VERSION_ID may be unset. Applications should not
 361                 rely on these fields to be set.</para>
 362
 363                 <para>Operating system vendors may extend the file
 364                 format and introduce new fields. It is highly
 365                 recommended to prefix new fields with an OS specific
 366                 name in order to avoid name clashes. Applications
 367                 reading this file must ignore unknown fields. Example:
 368                 <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
 369         </refsect1>
 370
 371         <refsect1>
 372                 <title>Example</title>
 373
 374                 <programlisting>NAME=Fedora
 375 VERSION="17 (Beefy Miracle)"
 376 ID=fedora
 377 VERSION_ID=17
 378 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 379 ANSI_COLOR="0;34"
 380 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
 381 HOME_URL="https://fedoraproject.org/"
 382 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
 383         </refsect1>
 384
 385         <refsect1>
 386                   <title>See Also</title>
 387                   <para>
 388                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 389                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 390                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 391                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 392                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 393                   </para>
 394         </refsect1>
 395
 396 </refentry>