from earliest boot on, and hence must be located on the root file
system.</para>
+ <para><filename>os-release</filename> must not contain repeating keys. Nevertheless, readers should pick
+ the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A
+ reader may warn about repeating entries.</para>
+
<para>For a longer rationale for <filename>os-release</filename>
please refer to the <ulink
- url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
+ url="https://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
<refsect2>
<title><filename>/etc/initrd-release</filename></title>
<para>In the <ulink
- url="https://www.kernel.org/doc/html/latest/admin-guide/initrd.html">initrd</ulink>,
+ url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>,
<filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the
main system. Additionally, the presence of that file means that the system is in the initrd phase.
<filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename>
<varname>VERSION_ID=</varname> exists and matches. This ensures ABI/API compatibility between the
layers and prevents merging of an incompatible image in an overlay.</para>
+ <para>In order to identify the extension image itself, the same fields defined below can be added to the
+ <filename>extension-release</filename> file with a <varname>SYSEXT_</varname> prefix (to disambiguate
+ from fields used to match on the base image). E.g.: <varname>SYSEXT_ID=myext</varname>,
+ <varname>SYSEXT_VERSION_ID=1.2.3</varname>.</para>
+
<para>In the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename, the
<replaceable>IMAGE</replaceable> part must exactly match the file name of the containing image with the
suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
change between the build and the deployment phases, it is possible to relax this check: if exactly one
file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this
directory, and the file is tagged with a <varname>user.extension-release.strict</varname>
- <citerefentry><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
+ <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the
string <literal>0</literal>, it will be used instead.</para>
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
Edition"</literal>.</para>
<para>Note: this field is for display purposes only. The <varname>VARIANT_ID</varname> field should
- be used for making programmatic decisions.</para></listitem>
+ be used for making programmatic decisions.</para>
+
+ <xi:include href="version-info.xml" xpointer="v220"/></listitem>
</varlistentry>
<varlistentry>
may not be implemented on all systems.</para>
<para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v220"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
is optional and may not be implemented on all systems.</para>
<para>Examples: <literal>VERSION_CODENAME=buster</literal>,
- <literal>VERSION_CODENAME=xenial</literal>.</para></listitem>
+ <literal>VERSION_CODENAME=xenial</literal>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v231"/></listitem>
</varlistentry>
<varlistentry>
optional.</para>
<para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v200"/></listitem>
</varlistentry>
<varlistentry>
the local system.</para>
<para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
- <literal>IMAGE_ID=netbook-image</literal>.</para></listitem>
+ <literal>IMAGE_ID=netbook-image</literal>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v249"/></listitem>
</varlistentry>
<varlistentry>
</para>
<para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v249"/></listitem>
</varlistentry>
</variablelist>
<literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal>.</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><varname>SUPPORT_END=</varname></term>
+
+ <listitem><para>The date at which support for this version of the OS ends. (What exactly "lack of
+ support" means varies between vendors, but generally users should assume that updates, including
+ security fixes, will not be provided.) The value is a date in the ISO 8601 format
+ <literal>YYYY-MM-DD</literal>, and specifies the first day on which support <emphasis>is
+ not</emphasis> provided.</para>
+
+ <para>For example, <literal>SUPPORT_END=2001-01-01</literal> means that the system was supported
+ until the end of the last day of the previous millennium.</para>
+
+ <xi:include href="version-info.xml" xpointer="v252"/></listitem>
+ </varlistentry>
+
<varlistentry>
<term><varname>LOGO=</varname></term>
<listitem><para>A string, specifying the name of an icon as defined by <ulink
- url="http://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme
+ url="https://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme
Specification</ulink>. This can be used by graphical applications to display an operating system's
or distributor's logo. This field is optional and may not necessarily be implemented on all
systems.</para>
<para>Examples: <literal>LOGO=fedora-logo</literal>, <literal>LOGO=distributor-logo-opensuse</literal>
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v240"/></listitem>
</varlistentry>
<varlistentry>
for light blue, or <literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue.
</para></listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><varname>VENDOR_NAME=</varname></term>
+
+ <listitem><para>The name of the OS vendor. This is the name of the organization or company which
+ produces the OS. This field is optional.</para>
+
+ <para>This name is intended to be exposed in "About this system" UIs or software update UIs when
+ needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.</para>
+
+ <para>Examples: <literal>VENDOR_NAME="Fedora Project"</literal> for Fedora Linux,
+ <literal>VENDOR_NAME="Canonical"</literal> for Ubuntu.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>VENDOR_URL=</varname></term>
+
+ <listitem><para>The homepage of the OS vendor. This field is optional. The
+ <varname>VENDOR_NAME=</varname> field should be set if this one is, although clients must be
+ robust against either field not being set.</para>
+
+ <para>The value should be in <ulink
+ url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be
+ <literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the
+ setting.</para>
+
+ <para>Examples: <literal>VENDOR_URL="https://fedoraproject.org/"</literal>,
+ <literal>VENDOR_URL="https://canonical.com/"</literal>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
+ </varlistentry>
</variablelist>
</refsect2>
<para>See <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for a description of how
<citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- determines the fallback hostname.</para></listitem>
+ determines the fallback hostname.</para>
+
+ <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ARCHITECTURE=</varname></term>
+ <listitem><para>A string that specifies which CPU architecture the userspace binaries require.
+ The architecture identifiers are the same as for <varname>ConditionArchitecture=</varname>
+ described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ The field is optional and should only be used when just single architecture is supported.
+ It may provide redundant information when used in a GPT partition with a GUID type that already
+ encodes the architecture. If this is not the case, the architecture should be specified in
+ e.g., an extension image, to prevent an incompatible host from loading it.
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v252"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
extension images are supported. See <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>,
- <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/initrd.html">initrd</ulink> and
+ <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink> and
<citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
for more information.</para>
<para>Examples: <literal>SYSEXT_LEVEL=2</literal>, <literal>SYSEXT_LEVEL=15.14</literal>.
- </para></listitem>
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v248"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>CONFEXT_LEVEL=</varname></term>
+
+ <listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images.
+ See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
+ for more information.</para>
+
+ <para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>.
+ </para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<listitem><para>Takes a space-separated list of one or more of the strings
<literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is
only supported in <filename>extension-release.d/</filename> files and indicates what environments
- the system extension is applicable to: i.e. to regular systems, to initial RAM filesystems
- ("initrd") or to portable service images. If unspecified, <literal>SYSEXT_SCOPE=system
- portable</literal> is implied, i.e. any system extension without this field is applicable to
- regular systems and to portable service environments, but not to initrd
- environments.</para></listitem>
+ the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service
+ images. If unspecified, <literal>SYSEXT_SCOPE=system portable</literal> is implied, i.e. any system
+ extension without this field is applicable to regular systems and to portable service environments,
+ but not to initrd environments.</para>
+
+ <xi:include href="version-info.xml" xpointer="v250"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>CONFEXT_SCOPE=</varname></term>
+
+ <listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para>
+
+ <xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>PORTABLE_PREFIXES=</varname></term>
<listitem><para>Takes a space-separated list of one or more valid prefix match strings for the
- <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> logic. This field
- serves two purposes: it is informational, identifying portable service images as such (and thus
- allowing them to be distinguished from other OS images, such as bootable system images). In is also
- used when a portable service image is attached: the specified or implied portable service prefix is
- checked against the list specified here, to enforce restrictions how images may be attached to a
- system.</para></listitem>
+ <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services Documentation</ulink> logic.
+ This field serves two purposes: it is informational, identifying portable service images as such
+ (and thus allowing them to be distinguished from other OS images, such as bootable system images).
+ It is also used when a portable service image is attached: the specified or implied portable
+ service prefix is checked against the list specified here, to enforce restrictions how images may
+ be attached to a system.</para>
+
+ <xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
</variablelist>
</refsect2>
<example>
<title>Reading <filename>os-release</filename> in
- <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+ <citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
<programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting>
</example>
<example>
<title>Reading <filename>os-release</filename> in
- <citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry></title>
+ <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions >= 3.10)</title>
+
+ <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting>
+
+ <para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release">
+ <function>platform.freedesktop_os_release</function></ulink> for more details.
+ </para>
+ </example>
+
+ <example>
+ <title>Reading <filename>os-release</filename> in
+ <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title>
<programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting>
+
+ <para>Note that the above version that uses the built-in implementation is preferred
+ in most cases, and the open-coded version here is provided for reference.</para>
</example>
</refsect1>
projects / thirdparty / systemd.git / blobdiff