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