man/os-release.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="os-release" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>os-release</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>os-release</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>os-release</refname>
  19     <refname>initrd-release</refname>
  20     <refpurpose>Operating system identification</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <para><filename>/etc/os-release</filename></para>
  25     <para><filename>/usr/lib/os-release</filename></para>
  26     <para><filename>/etc/initrd-release</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para>The <filename>/etc/os-release</filename> and
  33     <filename>/usr/lib/os-release</filename> files contain operating
  34     system identification data.</para>
  35
  36     <para>The basic file format of <filename>os-release</filename> is
  37     a newline-separated list of environment-like shell-compatible
  38     variable assignments. It is possible to source the configuration
  39     from shell scripts, however, beyond mere variable assignments, no
  40     shell features are supported (this means variable expansion is
  41     explicitly not supported), allowing applications to read the file
  42     without implementing a shell compatible execution engine. Variable
  43     assignment values must be enclosed in double or single quotes if
  44     they include spaces, semicolons or other special characters
  45     outside of A–Z, a–z, 0–9. Shell special characters ("$", quotes,
  46     backslash, backtick) must be escaped with backslashes, following
  47     shell style. All strings should be in UTF-8 format, and
  48     non-printable characters should not be used. It is not supported
  49     to concatenate multiple individually quoted strings. Lines
  50     beginning with "#" shall be ignored as comments. Blank lines are
  51     permitted and ignored.</para>
  52
  53     <para>The file <filename>/etc/os-release</filename> takes
  54     precedence over <filename>/usr/lib/os-release</filename>.
  55     Applications should check for the former, and exclusively use its
  56     data if it exists, and only fall back to
  57     <filename>/usr/lib/os-release</filename> if it is missing.
  58     Applications should not read data from both files at the same
  59     time. <filename>/usr/lib/os-release</filename> is the recommended
  60     place to store OS release information as part of vendor trees.
  61     <filename>/etc/os-release</filename> should be a relative symlink
  62     to <filename>/usr/lib/os-release</filename>, to provide
  63     compatibility with applications only looking at
  64     <filename>/etc/</filename>. A relative symlink instead of an
  65     absolute symlink is necessary to avoid breaking the link in a
  66     chroot or initrd environment such as dracut.</para>
  67
  68     <para><filename>os-release</filename> contains data that is
  69     defined by the operating system vendor and should generally not be
  70     changed by the administrator.</para>
  71
  72     <para>As this file only encodes names and identifiers it should
  73     not be localized.</para>
  74
  75     <para>The <filename>/etc/os-release</filename> and
  76     <filename>/usr/lib/os-release</filename> files might be symlinks
  77     to other files, but it is important that the file is available
  78     from earliest boot on, and hence must be located on the root file
  79     system.</para>
  80
  81     <para>For a longer rationale for <filename>os-release</filename>
  82     please refer to the <ulink
  83     url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
  84
  85     <refsect2>
  86       <title><filename>/etc/initrd-release</filename></title>
  87
  88       <para>In the <ulink
  89       url="https://www.kernel.org/doc/html/latest/admin-guide/initrd.html">initrd</ulink>,
  90       <filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the
  91       main system. Additionally, the presence of that file means that the system is in the initrd phase.
  92       <filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
  93       (or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
  94       above) work correctly. The rest of this document that talks about <filename>os-release</filename>
  95       should be understood to apply to <filename>initrd-release</filename> too.</para>
  96     </refsect2>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Options</title>
 101
 102     <para>The following OS identifications parameters may be set using
 103     <filename>os-release</filename>:</para>
 104
 105     <refsect2>
 106       <title>General information identifying the operating system</title>
 107
 108       <variablelist class='environment-variables'>
 109         <varlistentry>
 110           <term><varname>NAME=</varname></term>
 111
 112           <listitem><para>A string identifying the operating system, without a version component, and
 113           suitable for presentation to the user. If not set, a default of <literal>NAME=Linux</literal> may
 114           be used.</para>
 115
 116           <para>Examples: <literal>NAME=Fedora</literal>, <literal>NAME="Debian GNU/Linux"</literal>.
 117           </para></listitem>
 118         </varlistentry>
 119
 120         <varlistentry>
 121           <term><varname>ID=</varname></term>
 122
 123           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 124           and "-") identifying the operating system, excluding any version information and suitable for
 125           processing by scripts or usage in generated filenames. If not set, a default of
 126           <literal>ID=linux</literal> may be used.</para>
 127
 128           <para>Examples: <literal>ID=fedora</literal>, <literal>ID=debian</literal>.</para></listitem>
 129         </varlistentry>
 130
 131         <varlistentry>
 132           <term><varname>ID_LIKE=</varname></term>
 133
 134           <listitem><para>A space-separated list of operating system identifiers in the same syntax as the
 135           <varname>ID=</varname> setting. It should list identifiers of operating systems that are closely
 136           related to the local operating system in regards to packaging and programming interfaces, for
 137           example listing one or more OS identifiers the local OS is a derivative from.  An OS should
 138           generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
 139           derived from it, though symmetric relationships are possible. Build scripts and similar should
 140           check this variable if they need to identify the local operating system and the value of
 141           <varname>ID=</varname> is not recognized. Operating systems should be listed in order of how
 142           closely the local operating system relates to the listed ones, starting with the closest. This
 143           field is optional.</para>
 144
 145           <para>Examples: for an operating system with <literal>ID=centos</literal>, an assignment of
 146           <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. For an operating system with
 147           <literal>ID=ubuntu</literal>, an assignment of <literal>ID_LIKE=debian</literal> is appropriate.
 148           </para></listitem>
 149         </varlistentry>
 150
 151         <varlistentry>
 152           <term><varname>PRETTY_NAME=</varname></term>
 153
 154           <listitem><para>A pretty operating system name in a format suitable for presentation to the
 155           user. May or may not contain a release code name or OS version of some kind, as suitable. If not
 156           set, a default of <literal>PRETTY_NAME="Linux"</literal> may be used</para>
 157
 158           <para>Example: <literal>PRETTY_NAME="Fedora 17 (Beefy Miracle)"</literal>.</para></listitem>
 159         </varlistentry>
 160
 161         <varlistentry>
 162           <term><varname>CPE_NAME=</varname></term>
 163
 164           <listitem><para>A CPE name for the operating system, in URI binding syntax, following the <ulink
 165           url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as
 166           proposed by the NIST. This field is optional.</para>
 167
 168           <para>Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal></para></listitem>
 169         </varlistentry>
 170
 171         <varlistentry>
 172           <term><varname>VARIANT=</varname></term>
 173
 174           <listitem><para>A string identifying a specific variant or edition of the operating system suitable
 175           for presentation to the user. This field may be used to inform the user that the configuration of
 176           this system is subject to a specific divergent set of rules or default configuration settings. This
 177           field is optional and may not be implemented on all systems.</para>
 178
 179           <para>Examples: <literal>VARIANT="Server Edition"</literal>, <literal>VARIANT="Smart Refrigerator
 180           Edition"</literal>.</para>
 181
 182           <para>Note: this field is for display purposes only. The <varname>VARIANT_ID</varname> field should
 183           be used for making programmatic decisions.</para></listitem>
 184         </varlistentry>
 185
 186         <varlistentry>
 187           <term><varname>VARIANT_ID=</varname></term>
 188
 189           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
 190           "-"), identifying a specific variant or edition of the operating system. This may be interpreted by
 191           other packages in order to determine a divergent default configuration. This field is optional and
 192           may not be implemented on all systems.</para>
 193
 194           <para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>.
 195           </para></listitem>
 196         </varlistentry>
 197       </variablelist>
 198     </refsect2>
 199
 200     <refsect2>
 201       <title>Information about the version of the operating system</title>
 202
 203       <variablelist class='environment-variables'>
 204         <varlistentry>
 205           <term><varname>VERSION=</varname></term>
 206
 207           <listitem><para>A string identifying the operating system version, excluding any OS name
 208           information, possibly including a release code name, and suitable for presentation to the
 209           user. This field is optional.</para>
 210
 211           <para>Examples: <literal>VERSION=17</literal>, <literal>VERSION="17 (Beefy Miracle)"</literal>.
 212           </para></listitem>
 213         </varlistentry>
 214
 215         <varlistentry>
 216           <term><varname>VERSION_ID=</varname></term>
 217
 218           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 219           a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
 220           or release code name, and suitable for processing by scripts or usage in generated filenames. This
 221           field is optional.</para>
 222
 223           <para>Examples: <literal>VERSION_ID=17</literal>, <literal>VERSION_ID=11.04</literal>.
 224           </para></listitem>
 225         </varlistentry>
 226
 227         <varlistentry>
 228           <term><varname>VERSION_CODENAME=</varname></term>
 229
 230           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 231           and "-") identifying the operating system release code name, excluding any OS name information or
 232           release version, and suitable for processing by scripts or usage in generated filenames. This field
 233           is optional and may not be implemented on all systems.</para>
 234
 235           <para>Examples: <literal>VERSION_CODENAME=buster</literal>,
 236           <literal>VERSION_CODENAME=xenial</literal>.</para></listitem>
 237         </varlistentry>
 238
 239         <varlistentry>
 240           <term><varname>BUILD_ID=</varname></term>
 241
 242           <listitem><para>A string uniquely identifying the system image originally used as the installation
 243           base. In most cases, <varname>VERSION_ID</varname> or
 244           <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system
 245           image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where
 246           the original installation image version is important: <varname>VERSION_ID</varname> would change
 247           during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is
 248           optional.</para>
 249
 250           <para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>.
 251           </para></listitem>
 252         </varlistentry>
 253
 254         <varlistentry>
 255           <term><varname>IMAGE_ID=</varname></term>
 256
 257           <listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 258           and "-"), identifying a specific image of the operating system. This is supposed to be used for
 259           environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
 260           OS images. This field is optional and may not be implemented on all systems, in particularly not on
 261           those that are not managed via images but put together and updated from individual packages and on
 262           the local system.</para>
 263
 264           <para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
 265           <literal>IMAGE_ID=netbook-image</literal>.</para></listitem>
 266         </varlistentry>
 267
 268         <varlistentry>
 269           <term><varname>IMAGE_VERSION=</varname></term>
 270
 271           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 272           a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
 273           <varname>IMAGE_ID</varname> described above, to discern different versions of the same image.
 274           </para>
 275
 276           <para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>.
 277           </para></listitem>
 278         </varlistentry>
 279       </variablelist>
 280
 281       <para>To summarize: if the image updates are built and shipped as comprehensive units,
 282       <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates
 283       eventually completely replace previously installed contents, as in a typical binary distribution,
 284       <varname>VERSION_ID</varname> should be used to identify major releases of the operating system.
 285       <varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when
 286       the original system image version is important.</para>
 287     </refsect2>
 288
 289     <refsect2>
 290       <title>Presentation information and links</title>
 291
 292       <variablelist class='environment-variables'>
 293         <varlistentry>
 294           <term><varname>HOME_URL=</varname></term>
 295           <term><varname>DOCUMENTATION_URL=</varname></term>
 296           <term><varname>SUPPORT_URL=</varname></term>
 297           <term><varname>BUG_REPORT_URL=</varname></term>
 298           <term><varname>PRIVACY_POLICY_URL=</varname></term>
 299
 300           <listitem><para>Links to resources on the Internet related to the operating system.
 301           <varname>HOME_URL=</varname> should refer to the homepage of the operating system, or alternatively
 302           some homepage of the specific version of the operating system.
 303           <varname>DOCUMENTATION_URL=</varname> should refer to the main documentation page for this
 304           operating system.  <varname>SUPPORT_URL=</varname> should refer to the main support page for the
 305           operating system, if there is any. This is primarily intended for operating systems which vendors
 306           provide support for. <varname>BUG_REPORT_URL=</varname> should refer to the main bug reporting page
 307           for the operating system, if there is any. This is primarily intended for operating systems that
 308           rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the main privacy
 309           policy page for the operating system, if there is any. These settings are optional, and providing
 310           only some of these settings is common. These URLs are intended to be exposed in "About this system"
 311           UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
 312           Bug", or "Privacy Policy". The values should be in <ulink
 313           url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
 314           <literal>http:</literal> or <literal>https:</literal> URLs, and possibly <literal>mailto:</literal>
 315           or <literal>tel:</literal>. Only one URL shall be listed in each setting. If multiple resources
 316           need to be referenced, it is recommended to provide an online landing page linking all available
 317           resources.</para>
 318
 319           <para>Examples: <literal>HOME_URL="https://fedoraproject.org/"</literal>,
 320           <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal>.</para></listitem>
 321         </varlistentry>
 322
 323         <varlistentry>
 324           <term><varname>LOGO=</varname></term>
 325
 326           <listitem><para>A string, specifying the name of an icon as defined by <ulink
 327           url="http://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme
 328           Specification</ulink>. This can be used by graphical applications to display an operating system's
 329           or distributor's logo. This field is optional and may not necessarily be implemented on all
 330           systems.</para>
 331
 332           <para>Examples: <literal>LOGO=fedora-logo</literal>, <literal>LOGO=distributor-logo-opensuse</literal>
 333           </para></listitem>
 334         </varlistentry>
 335
 336         <varlistentry>
 337           <term><varname>ANSI_COLOR=</varname></term>
 338
 339           <listitem><para>A suggested presentation color when showing the OS name on the console. This should
 340           be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
 341           graphical rendition. This field is optional.</para>
 342
 343           <para>Examples: <literal>ANSI_COLOR="0;31"</literal> for red, <literal>ANSI_COLOR="1;34"</literal>
 344           for light blue, or <literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue.
 345           </para></listitem>
 346         </varlistentry>
 347       </variablelist>
 348     </refsect2>
 349
 350     <refsect2>
 351       <title>Distribution-level defaults and metadata</title>
 352
 353       <variablelist class='environment-variables'>
 354         <varlistentry>
 355           <term><varname>DEFAULT_HOSTNAME=</varname></term>
 356
 357           <listitem><para>A string specifying the hostname if
 358           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not
 359           present and no other configuration source specifies the hostname. Must be either a single DNS label
 360           (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
 361           format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
 362           that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
 363           limitation (DNS allows longer names).</para>
 364
 365           <para>See <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 366           for a description of how
 367           <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 368           determines the fallback hostname.</para></listitem>
 369         </varlistentry>
 370
 371         <varlistentry>
 372           <term><varname>SYSEXT_LEVEL=</varname></term>
 373
 374           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 375           a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
 376           extension images are supported. See:
 377           <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
 378           for more information.</para>
 379
 380           <para>Examples: <literal>SYSEXT_LEVEL=2</literal>, <literal>SYSEXT_LEVEL=15.14</literal>.
 381           </para></listitem>
 382         </varlistentry>
 383       </variablelist>
 384     </refsect2>
 385
 386     <refsect2>
 387       <title>Notes</title>
 388
 389       <para>If you are using this file to determine the OS or a specific version of it, use the
 390       <varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
 391       <varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification
 392       string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para>
 393
 394       <para>Note that operating system vendors may choose not to provide version information, for example to
 395       accommodate for rolling releases. In this case, <varname>VERSION</varname> and
 396       <varname>VERSION_ID</varname> may be unset. Applications should not rely on these fields to be
 397       set.</para>
 398
 399       <para>Operating system vendors may extend the file format and introduce new fields. It is highly
 400       recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
 401       reading this file must ignore unknown fields.</para>
 402
 403       <para>Example: <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para>
 404
 405       <para>Container and sandbox runtime managers may make the host's identification data available to
 406       applications by providing the host's <filename>/etc/os-release</filename> (if available, otherwise
 407       <filename>/usr/lib/os-release</filename> as a fallback) as
 408       <filename>/run/host/os-release</filename>.</para>
 409     </refsect2>
 410   </refsect1>
 411
 412   <refsect1>
 413     <title>Examples</title>
 414
 415     <example>
 416       <title><filename>os-release</filename> file for Fedora Workstation</title>
 417
 418       <programlisting>NAME=Fedora
 419 VERSION="32 (Workstation Edition)"
 420 ID=fedora
 421 VERSION_ID=32
 422 PRETTY_NAME="Fedora 32 (Workstation Edition)"
 423 ANSI_COLOR="0;38;2;60;110;180"
 424 LOGO=fedora-logo-icon
 425 CPE_NAME="cpe:/o:fedoraproject:fedora:32"
 426 HOME_URL="https://fedoraproject.org/"
 427 DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
 428 SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
 429 BUG_REPORT_URL="https://bugzilla.redhat.com/"
 430 REDHAT_BUGZILLA_PRODUCT="Fedora"
 431 REDHAT_BUGZILLA_PRODUCT_VERSION=32
 432 REDHAT_SUPPORT_PRODUCT="Fedora"
 433 REDHAT_SUPPORT_PRODUCT_VERSION=32
 434 PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
 435 VARIANT="Workstation Edition"
 436 VARIANT_ID=workstation</programlisting>
 437     </example>
 438
 439     <example>
 440       <title>Reading <filename>os-release</filename> in
 441       <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
 442
 443       <programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
 444     </example>
 445
 446     <example>
 447       <title>Reading <filename>os-release</filename> in
 448       <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
 449
 450       <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
 451     </example>
 452
 453   </refsect1>
 454
 455   <refsect1>
 456       <title>See Also</title>
 457       <para>
 458         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 459         <citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 460         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 461         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 462         <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 463       </para>
 464   </refsect1>
 465
 466 </refentry>