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