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                                 <term><varname>PRIVACY_POLICY_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.
 301                                 <varname>PRIVACY_POLICY_URL=</varname>
 302                                 should refer to the main privacy policy
 303                                 page for the operation system, if there
 304                                 is any. These settings
 305                                 are optional, and providing only some
 306                                 of these settings is common. These
 307                                 URLs are intended to be exposed in
 308                                 "About this system" UIs behind links
 309                                 with captions such as "About this
 310                                 Operating System", "Obtain Support",
 311                                 "Report a Bug", or "Privacy Policy". The
 312                                 values should be in <ulink
 313                                 url="https://tools.ietf.org/html/rfc3986">RFC3986
 314                                 format</ulink>, and should be
 315                                 <literal>http:</literal> or
 316                                 <literal>https:</literal> URLs, and
 317                                 possibly <literal>mailto:</literal> or
 318                                 <literal>tel:</literal>. Only one URL
 319                                 shall be listed in each setting. If
 320                                 multiple resources need to be
 321                                 referenced, it is recommended to
 322                                 provide an online landing page linking
 323                                 all available resources. Examples:
 324                                 <literal>HOME_URL="https://fedoraproject.org/"</literal>
 325                                 and
 326                                 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
 327                         </varlistentry>
 328
 329                         <varlistentry>
 330                                 <term><varname>BUILD_ID=</varname></term>
 331
 332                                 <listitem><para>A string uniquely
 333                                 identifying the system image used as
 334                                 the origin for a distribution (it is
 335                                 not updated with system updates). The
 336                                 field can be identical between
 337                                 different VERSION_IDs as BUILD_ID is
 338                                 an only a unique identifier to a
 339                                 specific version. Distributions that
 340                                 release each update as a new version
 341                                 would only need to use VERSION_ID as
 342                                 each build is already distinct based
 343                                 on the VERSION_ID. This field is
 344                                 optional. Example:
 345                                 <literal>BUILD_ID="2013-03-20.3"</literal>
 346                                 or
 347                                 <literal>BUILD_ID=201303203</literal>.
 348
 349                                 </para></listitem>
 350                         </varlistentry>
 351
 352                 </variablelist>
 353
 354                 <para>If you are reading this file from C code or a
 355                 shell script to determine the OS or a specific version
 356                 of it, use the ID and VERSION_ID fields, possibly with
 357                 ID_LIKE as fallback for ID. When looking for an OS
 358                 identification string for presentation to the user use
 359                 the PRETTY_NAME field.</para>
 360
 361                 <para>Note that operating system vendors may choose
 362                 not to provide version information, for example to
 363                 accommodate for rolling releases. In this case, VERSION
 364                 and VERSION_ID may be unset. Applications should not
 365                 rely on these fields to be set.</para>
 366
 367                 <para>Operating system vendors may extend the file
 368                 format and introduce new fields. It is highly
 369                 recommended to prefix new fields with an OS specific
 370                 name in order to avoid name clashes. Applications
 371                 reading this file must ignore unknown fields. Example:
 372                 <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
 373         </refsect1>
 374
 375         <refsect1>
 376                 <title>Example</title>
 377
 378                 <programlisting>NAME=Fedora
 379 VERSION="17 (Beefy Miracle)"
 380 ID=fedora
 381 VERSION_ID=17
 382 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
 383 ANSI_COLOR="0;34"
 384 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
 385 HOME_URL="https://fedoraproject.org/"
 386 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
 387         </refsect1>
 388
 389         <refsect1>
 390                   <title>See Also</title>
 391                   <para>
 392                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 393                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 394                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 395                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 396                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 397                   </para>
 398         </refsect1>
 399
 400 </refentry>