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     <refname>extension-release</refname>
  21     <refpurpose>Operating system identification</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>/etc/os-release</filename></para>
  26     <para><filename>/usr/lib/os-release</filename></para>
  27     <para><filename>/etc/initrd-release</filename></para>
  28     <para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></para>
  29   </refsynopsisdiv>
  30
  31   <refsect1>
  32     <title>Description</title>
  33
  34     <para>The <filename>/etc/os-release</filename> and
  35     <filename>/usr/lib/os-release</filename> files contain operating
  36     system identification data.</para>
  37
  38     <para>The format of <filename>os-release</filename> is a newline-separated list of
  39     environment-like shell-compatible variable assignments. It is possible to source the configuration from
  40     Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this
  41     means variable expansion is explicitly not supported), allowing applications to read the file without
  42     implementing a shell compatible execution engine. Variable assignment values must be enclosed in double
  43     or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z,
  44     0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is
  45     optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes,
  46     following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not
  47     be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#"
  48     are treated as comments. Blank lines are permitted and ignored.</para>
  49
  50     <para>The file <filename>/etc/os-release</filename> takes
  51     precedence over <filename>/usr/lib/os-release</filename>.
  52     Applications should check for the former, and exclusively use its
  53     data if it exists, and only fall back to
  54     <filename>/usr/lib/os-release</filename> if it is missing.
  55     Applications should not read data from both files at the same
  56     time. <filename>/usr/lib/os-release</filename> is the recommended
  57     place to store OS release information as part of vendor trees.
  58     <filename>/etc/os-release</filename> should be a relative symlink
  59     to <filename>/usr/lib/os-release</filename>, to provide
  60     compatibility with applications only looking at
  61     <filename>/etc/</filename>. A relative symlink instead of an
  62     absolute symlink is necessary to avoid breaking the link in a
  63     chroot or initrd environment such as dracut.</para>
  64
  65     <para><filename>os-release</filename> contains data that is
  66     defined by the operating system vendor and should generally not be
  67     changed by the administrator.</para>
  68
  69     <para>As this file only encodes names and identifiers it should
  70     not be localized.</para>
  71
  72     <para>The <filename>/etc/os-release</filename> and
  73     <filename>/usr/lib/os-release</filename> files might be symlinks
  74     to other files, but it is important that the file is available
  75     from earliest boot on, and hence must be located on the root file
  76     system.</para>
  77
  78     <para><filename>os-release</filename> must not contain repeating keys. Nevertheless, readers should pick
  79     the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A
  80     reader may warn about repeating entries.</para>
  81
  82     <para>For a longer rationale for <filename>os-release</filename>
  83     please refer to the <ulink
  84     url="https://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
  85
  86     <refsect2>
  87       <title><filename>/etc/initrd-release</filename></title>
  88
  89       <para>In the <ulink
  90       url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>,
  91       <filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the
  92       main system. Additionally, the presence of that file means that the system is in the initrd phase.
  93       <filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
  94       (or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
  95       above) work correctly.</para>
  96
  97       <para>The rest of this document that talks about <filename>os-release</filename> should be understood
  98       to apply to <filename>initrd-release</filename> too.</para>
  99     </refsect2>
 100
 101     <refsect2>
 102       <title><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></title>
 103
 104       <para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
 105       plays the same role for extension images as <filename>os-release</filename> for the main system, and
 106       follows the syntax and rules as described in the <ulink
 107       url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink>. The purpose of this
 108       file is to identify the extension and to allow the operating system to verify that the extension image
 109       matches the base OS. This is typically implemented by checking that the <varname>ID=</varname> options
 110       match, and either <varname>SYSEXT_LEVEL=</varname> exists and matches too, or if it is not present,
 111       <varname>VERSION_ID=</varname> exists and matches. This ensures ABI/API compatibility between the
 112       layers and prevents merging of an incompatible image in an overlay.</para>
 113
 114       <para>In order to identify the extension image itself, the same fields defined below can be added to the
 115       <filename>extension-release</filename> file with a <varname>SYSEXT_</varname> prefix (to disambiguate
 116       from fields used to match on the base image). E.g.: <varname>SYSEXT_ID=myext</varname>,
 117       <varname>SYSEXT_VERSION_ID=1.2.3</varname>.</para>
 118
 119       <para>In the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename, the
 120       <replaceable>IMAGE</replaceable> part must exactly match the file name of the containing image with the
 121       suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
 122       change between the build and the deployment phases, it is possible to relax this check: if exactly one
 123       file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this
 124       directory, and the file is tagged with a <varname>user.extension-release.strict</varname>
 125       <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
 126       string <literal>0</literal>, it will be used instead.</para>
 127
 128       <para>The rest of this document that talks about <filename>os-release</filename> should be understood
 129       to apply to <filename>extension-release</filename> too.</para>
 130     </refsect2>
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Options</title>
 135
 136     <para>The following OS identifications parameters may be set using
 137     <filename>os-release</filename>:</para>
 138
 139     <refsect2>
 140       <title>General information identifying the operating system</title>
 141
 142       <variablelist class='environment-variables'>
 143         <varlistentry>
 144           <term><varname>NAME=</varname></term>
 145
 146           <listitem><para>A string identifying the operating system, without a version component, and
 147           suitable for presentation to the user. If not set, a default of <literal>NAME=Linux</literal> may
 148           be used.</para>
 149
 150           <para>Examples: <literal>NAME=Fedora</literal>, <literal>NAME="Debian GNU/Linux"</literal>.
 151           </para></listitem>
 152         </varlistentry>
 153
 154         <varlistentry>
 155           <term><varname>ID=</varname></term>
 156
 157           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 158           and "-") identifying the operating system, excluding any version information and suitable for
 159           processing by scripts or usage in generated filenames. If not set, a default of
 160           <literal>ID=linux</literal> may be used. Note that even though this string may not include
 161           characters that require shell quoting, quoting may nevertheless be used.</para>
 162
 163           <para>Examples: <literal>ID=fedora</literal>, <literal>ID=debian</literal>.</para></listitem>
 164         </varlistentry>
 165
 166         <varlistentry>
 167           <term><varname>ID_LIKE=</varname></term>
 168
 169           <listitem><para>A space-separated list of operating system identifiers in the same syntax as the
 170           <varname>ID=</varname> setting. It should list identifiers of operating systems that are closely
 171           related to the local operating system in regards to packaging and programming interfaces, for
 172           example listing one or more OS identifiers the local OS is a derivative from.  An OS should
 173           generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
 174           derived from it, though symmetric relationships are possible. Build scripts and similar should
 175           check this variable if they need to identify the local operating system and the value of
 176           <varname>ID=</varname> is not recognized. Operating systems should be listed in order of how
 177           closely the local operating system relates to the listed ones, starting with the closest. This
 178           field is optional.</para>
 179
 180           <para>Examples: for an operating system with <literal>ID=centos</literal>, an assignment of
 181           <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. For an operating system with
 182           <literal>ID=ubuntu</literal>, an assignment of <literal>ID_LIKE=debian</literal> is appropriate.
 183           </para></listitem>
 184         </varlistentry>
 185
 186         <varlistentry>
 187           <term><varname>PRETTY_NAME=</varname></term>
 188
 189           <listitem><para>A pretty operating system name in a format suitable for presentation to the
 190           user. May or may not contain a release code name or OS version of some kind, as suitable. If not
 191           set, a default of <literal>PRETTY_NAME="Linux"</literal> may be used</para>
 192
 193           <para>Example: <literal>PRETTY_NAME="Fedora 17 (Beefy Miracle)"</literal>.</para></listitem>
 194         </varlistentry>
 195
 196         <varlistentry>
 197           <term><varname>CPE_NAME=</varname></term>
 198
 199           <listitem><para>A CPE name for the operating system, in URI binding syntax, following the <ulink
 200           url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as
 201           proposed by the NIST. This field is optional.</para>
 202
 203           <para>Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal></para></listitem>
 204         </varlistentry>
 205
 206         <varlistentry>
 207           <term><varname>VARIANT=</varname></term>
 208
 209           <listitem><para>A string identifying a specific variant or edition of the operating system suitable
 210           for presentation to the user. This field may be used to inform the user that the configuration of
 211           this system is subject to a specific divergent set of rules or default configuration settings. This
 212           field is optional and may not be implemented on all systems.</para>
 213
 214           <para>Examples: <literal>VARIANT="Server Edition"</literal>, <literal>VARIANT="Smart Refrigerator
 215           Edition"</literal>.</para>
 216
 217           <para>Note: this field is for display purposes only. The <varname>VARIANT_ID</varname> field should
 218           be used for making programmatic decisions.</para>
 219
 220           <xi:include href="version-info.xml" xpointer="v220"/></listitem>
 221         </varlistentry>
 222
 223         <varlistentry>
 224           <term><varname>VARIANT_ID=</varname></term>
 225
 226           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
 227           "-"), identifying a specific variant or edition of the operating system. This may be interpreted by
 228           other packages in order to determine a divergent default configuration. This field is optional and
 229           may not be implemented on all systems.</para>
 230
 231           <para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>.
 232           </para>
 233
 234           <xi:include href="version-info.xml" xpointer="v220"/></listitem>
 235         </varlistentry>
 236       </variablelist>
 237     </refsect2>
 238
 239     <refsect2>
 240       <title>Information about the version of the operating system</title>
 241
 242       <variablelist class='environment-variables'>
 243         <varlistentry>
 244           <term><varname>VERSION=</varname></term>
 245
 246           <listitem><para>A string identifying the operating system version, excluding any OS name
 247           information, possibly including a release code name, and suitable for presentation to the
 248           user. This field is optional.</para>
 249
 250           <para>Examples: <literal>VERSION=17</literal>, <literal>VERSION="17 (Beefy Miracle)"</literal>.
 251           </para></listitem>
 252         </varlistentry>
 253
 254         <varlistentry>
 255           <term><varname>VERSION_ID=</varname></term>
 256
 257           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 258           a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
 259           or release code name, and suitable for processing by scripts or usage in generated filenames. This
 260           field is optional.</para>
 261
 262           <para>Examples: <literal>VERSION_ID=17</literal>, <literal>VERSION_ID=11.04</literal>.
 263           </para></listitem>
 264         </varlistentry>
 265
 266         <varlistentry>
 267           <term><varname>VERSION_CODENAME=</varname></term>
 268
 269           <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 270           and "-") identifying the operating system release code name, excluding any OS name information or
 271           release version, and suitable for processing by scripts or usage in generated filenames. This field
 272           is optional and may not be implemented on all systems.</para>
 273
 274           <para>Examples: <literal>VERSION_CODENAME=buster</literal>,
 275           <literal>VERSION_CODENAME=xenial</literal>.</para>
 276
 277           <xi:include href="version-info.xml" xpointer="v231"/></listitem>
 278         </varlistentry>
 279
 280         <varlistentry>
 281           <term><varname>BUILD_ID=</varname></term>
 282
 283           <listitem><para>A string uniquely identifying the system image originally used as the installation
 284           base. In most cases, <varname>VERSION_ID</varname> or
 285           <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system
 286           image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where
 287           the original installation image version is important: <varname>VERSION_ID</varname> would change
 288           during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is
 289           optional.</para>
 290
 291           <para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>.
 292           </para>
 293
 294           <xi:include href="version-info.xml" xpointer="v200"/></listitem>
 295         </varlistentry>
 296
 297         <varlistentry>
 298           <term><varname>IMAGE_ID=</varname></term>
 299
 300           <listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
 301           and "-"), identifying a specific image of the operating system. This is supposed to be used for
 302           environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
 303           OS images. This field is optional and may not be implemented on all systems, in particularly not on
 304           those that are not managed via images but put together and updated from individual packages and on
 305           the local system.</para>
 306
 307           <para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
 308           <literal>IMAGE_ID=netbook-image</literal>.</para>
 309
 310           <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 311         </varlistentry>
 312
 313         <varlistentry>
 314           <term><varname>IMAGE_VERSION=</varname></term>
 315
 316           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 317           a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
 318           <varname>IMAGE_ID</varname> described above, to discern different versions of the same image.
 319           </para>
 320
 321           <para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>.
 322           </para>
 323
 324           <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 325         </varlistentry>
 326       </variablelist>
 327
 328       <para>To summarize: if the image updates are built and shipped as comprehensive units,
 329       <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates
 330       eventually completely replace previously installed contents, as in a typical binary distribution,
 331       <varname>VERSION_ID</varname> should be used to identify major releases of the operating system.
 332       <varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when
 333       the original system image version is important.</para>
 334     </refsect2>
 335
 336     <refsect2>
 337       <title>Presentation information and links</title>
 338
 339       <variablelist class='environment-variables'>
 340         <varlistentry>
 341           <term><varname>HOME_URL=</varname></term>
 342           <term><varname>DOCUMENTATION_URL=</varname></term>
 343           <term><varname>SUPPORT_URL=</varname></term>
 344           <term><varname>BUG_REPORT_URL=</varname></term>
 345           <term><varname>PRIVACY_POLICY_URL=</varname></term>
 346
 347           <listitem><para>Links to resources on the Internet related to the operating system.
 348           <varname>HOME_URL=</varname> should refer to the homepage of the operating system, or alternatively
 349           some homepage of the specific version of the operating system.
 350           <varname>DOCUMENTATION_URL=</varname> should refer to the main documentation page for this
 351           operating system.  <varname>SUPPORT_URL=</varname> should refer to the main support page for the
 352           operating system, if there is any. This is primarily intended for operating systems which vendors
 353           provide support for. <varname>BUG_REPORT_URL=</varname> should refer to the main bug reporting page
 354           for the operating system, if there is any. This is primarily intended for operating systems that
 355           rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the main privacy
 356           policy page for the operating system, if there is any. These settings are optional, and providing
 357           only some of these settings is common. These URLs are intended to be exposed in "About this system"
 358           UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
 359           Bug", or "Privacy Policy". The values should be in <ulink
 360           url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
 361           <literal>http:</literal> or <literal>https:</literal> URLs, and possibly <literal>mailto:</literal>
 362           or <literal>tel:</literal>. Only one URL shall be listed in each setting. If multiple resources
 363           need to be referenced, it is recommended to provide an online landing page linking all available
 364           resources.</para>
 365
 366           <para>Examples: <literal>HOME_URL="https://fedoraproject.org/"</literal>,
 367           <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal>.</para></listitem>
 368         </varlistentry>
 369
 370         <varlistentry>
 371           <term><varname>SUPPORT_END=</varname></term>
 372
 373           <listitem><para>The date at which support for this version of the OS ends. (What exactly "lack of
 374           support" means varies between vendors, but generally users should assume that updates, including
 375           security fixes, will not be provided.) The value is a date in the ISO 8601 format
 376           <literal>YYYY-MM-DD</literal>, and specifies the first day on which support <emphasis>is
 377           not</emphasis> provided.</para>
 378
 379           <para>For example, <literal>SUPPORT_END=2001-01-01</literal> means that the system was supported
 380           until the end of the last day of the previous millennium.</para>
 381
 382           <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 383         </varlistentry>
 384
 385         <varlistentry>
 386           <term><varname>LOGO=</varname></term>
 387
 388           <listitem><para>A string, specifying the name of an icon as defined by <ulink
 389           url="https://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme
 390           Specification</ulink>. This can be used by graphical applications to display an operating system's
 391           or distributor's logo. This field is optional and may not necessarily be implemented on all
 392           systems.</para>
 393
 394           <para>Examples: <literal>LOGO=fedora-logo</literal>, <literal>LOGO=distributor-logo-opensuse</literal>
 395           </para>
 396
 397           <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 398         </varlistentry>
 399
 400         <varlistentry>
 401           <term><varname>ANSI_COLOR=</varname></term>
 402
 403           <listitem><para>A suggested presentation color when showing the OS name on the console. This should
 404           be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
 405           graphical rendition. This field is optional.</para>
 406
 407           <para>Examples: <literal>ANSI_COLOR="0;31"</literal> for red, <literal>ANSI_COLOR="1;34"</literal>
 408           for light blue, or <literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue.
 409           </para></listitem>
 410         </varlistentry>
 411
 412         <varlistentry>
 413           <term><varname>VENDOR_NAME=</varname></term>
 414
 415           <listitem><para>The name of the OS vendor. This is the name of the organization or company which
 416           produces the OS. This field is optional.</para>
 417
 418           <para>This name is intended to be exposed in "About this system" UIs or software update UIs when
 419           needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.</para>
 420
 421           <para>Examples: <literal>VENDOR_NAME="Fedora Project"</literal> for Fedora Linux,
 422           <literal>VENDOR_NAME="Canonical"</literal> for Ubuntu.</para>
 423
 424           <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 425         </varlistentry>
 426
 427         <varlistentry>
 428           <term><varname>VENDOR_URL=</varname></term>
 429
 430           <listitem><para>The homepage of the OS vendor. This field is optional. The
 431           <varname>VENDOR_NAME=</varname> field should be set if this one is, although clients must be
 432           robust against either field not being set.</para>
 433
 434           <para>The value should be in <ulink
 435           url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
 436           <literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the
 437           setting.</para>
 438
 439           <para>Examples: <literal>VENDOR_URL="https://fedoraproject.org/"</literal>,
 440           <literal>VENDOR_URL="https://canonical.com/"</literal>.</para>
 441
 442           <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 443         </varlistentry>
 444       </variablelist>
 445     </refsect2>
 446
 447     <refsect2>
 448       <title>Distribution-level defaults and metadata</title>
 449
 450       <variablelist class='environment-variables'>
 451         <varlistentry>
 452           <term><varname>DEFAULT_HOSTNAME=</varname></term>
 453
 454           <listitem><para>A string specifying the hostname if
 455           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not
 456           present and no other configuration source specifies the hostname. Must be either a single DNS label
 457           (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
 458           format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
 459           that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
 460           limitation (DNS allows longer names).</para>
 461
 462           <para>See <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 463           for a description of how
 464           <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 465           determines the fallback hostname.</para>
 466
 467           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 468         </varlistentry>
 469
 470         <varlistentry>
 471           <term><varname>ARCHITECTURE=</varname></term>
 472           <listitem><para>A string that specifies which CPU architecture the userspace binaries require.
 473           The architecture identifiers are the same as for <varname>ConditionArchitecture=</varname>
 474           described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 475           The field is optional and should only be used when just single architecture is supported.
 476           It may provide redundant information when used in a GPT partition with a GUID type that already
 477           encodes the architecture. If this is not the case, the architecture should be specified in
 478           e.g., an extension image, to prevent an incompatible host from loading it.
 479           </para>
 480
 481           <xi:include href="version-info.xml" xpointer="v252"/></listitem>
 482         </varlistentry>
 483
 484         <varlistentry>
 485           <term><varname>SYSEXT_LEVEL=</varname></term>
 486
 487           <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
 488           a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
 489           extension images are supported. See <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>,
 490           <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink> and
 491           <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
 492           for more information.</para>
 493
 494           <para>Examples: <literal>SYSEXT_LEVEL=2</literal>, <literal>SYSEXT_LEVEL=15.14</literal>.
 495           </para>
 496
 497           <xi:include href="version-info.xml" xpointer="v248"/></listitem>
 498         </varlistentry>
 499
 500         <varlistentry>
 501           <term><varname>CONFEXT_LEVEL=</varname></term>
 502
 503           <listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images.
 504           See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
 505           for more information.</para>
 506
 507           <para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>.
 508           </para>
 509
 510           <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 511         </varlistentry>
 512
 513         <varlistentry>
 514           <term><varname>SYSEXT_SCOPE=</varname></term>
 515           <listitem><para>Takes a space-separated list of one or more of the strings
 516           <literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is
 517           only supported in <filename>extension-release.d/</filename> files and indicates what environments
 518           the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service
 519           images. If unspecified, <literal>SYSEXT_SCOPE=system portable</literal> is implied, i.e. any system
 520           extension without this field is applicable to regular systems and to portable service environments,
 521           but not to initrd environments.</para>
 522
 523           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 524         </varlistentry>
 525
 526         <varlistentry>
 527           <term><varname>CONFEXT_SCOPE=</varname></term>
 528
 529           <listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para>
 530
 531           <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 532         </varlistentry>
 533
 534         <varlistentry>
 535           <term><varname>PORTABLE_PREFIXES=</varname></term>
 536           <listitem><para>Takes a space-separated list of one or more valid prefix match strings for the
 537           <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink> logic.
 538           This field serves two purposes: it is informational, identifying portable service images as such
 539           (and thus allowing them to be distinguished from other OS images, such as bootable system images).
 540           It is also used when a portable service image is attached: the specified or implied portable
 541           service prefix is checked against the list specified here, to enforce restrictions how images may
 542           be attached to a system.</para>
 543
 544           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 545         </varlistentry>
 546       </variablelist>
 547     </refsect2>
 548
 549     <refsect2>
 550       <title>Notes</title>
 551
 552       <para>If you are using this file to determine the OS or a specific version of it, use the
 553       <varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
 554       <varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification
 555       string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para>
 556
 557       <para>Note that operating system vendors may choose not to provide version information, for example to
 558       accommodate for rolling releases. In this case, <varname>VERSION</varname> and
 559       <varname>VERSION_ID</varname> may be unset. Applications should not rely on these fields to be
 560       set.</para>
 561
 562       <para>Operating system vendors may extend the file format and introduce new fields. It is highly
 563       recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
 564       reading this file must ignore unknown fields.</para>
 565
 566       <para>Example: <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para>
 567
 568       <para>Container and sandbox runtime managers may make the host's identification data available to
 569       applications by providing the host's <filename>/etc/os-release</filename> (if available, otherwise
 570       <filename>/usr/lib/os-release</filename> as a fallback) as
 571       <filename>/run/host/os-release</filename>.</para>
 572     </refsect2>
 573   </refsect1>
 574
 575   <refsect1>
 576     <title>Examples</title>
 577
 578     <example>
 579       <title><filename>os-release</filename> file for Fedora Workstation</title>
 580
 581       <programlisting>NAME=Fedora
 582 VERSION="32 (Workstation Edition)"
 583 ID=fedora
 584 VERSION_ID=32
 585 PRETTY_NAME="Fedora 32 (Workstation Edition)"
 586 ANSI_COLOR="0;38;2;60;110;180"
 587 LOGO=fedora-logo-icon
 588 CPE_NAME="cpe:/o:fedoraproject:fedora:32"
 589 HOME_URL="https://fedoraproject.org/"
 590 DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
 591 SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
 592 BUG_REPORT_URL="https://bugzilla.redhat.com/"
 593 REDHAT_BUGZILLA_PRODUCT="Fedora"
 594 REDHAT_BUGZILLA_PRODUCT_VERSION=32
 595 REDHAT_SUPPORT_PRODUCT="Fedora"
 596 REDHAT_SUPPORT_PRODUCT_VERSION=32
 597 PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
 598 VARIANT="Workstation Edition"
 599 VARIANT_ID=workstation</programlisting>
 600     </example>
 601
 602     <example>
 603       <title><filename>extension-release</filename> file for an extension for Fedora Workstation 32</title>
 604
 605       <programlisting>ID=fedora
 606 VERSION_ID=32</programlisting>
 607     </example>
 608
 609     <example>
 610       <title>Reading <filename>os-release</filename> in
 611       <citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
 612
 613       <programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
 614     </example>
 615
 616     <example>
 617       <title>Reading <filename>os-release</filename> in
 618       <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions &gt;= 3.10)</title>
 619
 620       <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
 621
 622       <para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release">
 623       <function>platform.freedesktop_os_release</function></ulink> for more details.
 624       </para>
 625     </example>
 626
 627     <example>
 628       <title>Reading <filename>os-release</filename> in
 629       <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
 630
 631       <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
 632
 633       <para>Note that the above version that uses the built-in implementation is preferred
 634       in most cases, and the open-coded version here is provided for reference.</para>
 635     </example>
 636
 637   </refsect1>
 638
 639   <refsect1>
 640       <title>See Also</title>
 641       <para>
 642         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 643         <citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 644         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 645         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 646         <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 647       </para>
 648   </refsect1>
 649
 650 </refentry>