mirror of
https://github.com/systemd/systemd
synced 2024-09-06 16:56:43 +00:00
![Daan De Meyer](/assets/img/avatar_default.png)
Let's remove some explicit references to dracut as we prefer initrds built with mkosi these days.
653 lines
34 KiB
XML
653 lines
34 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||
|
||
<refentry id="os-release" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||
<refentryinfo>
|
||
<title>os-release</title>
|
||
<productname>systemd</productname>
|
||
</refentryinfo>
|
||
|
||
<refmeta>
|
||
<refentrytitle>os-release</refentrytitle>
|
||
<manvolnum>5</manvolnum>
|
||
</refmeta>
|
||
|
||
<refnamediv>
|
||
<refname>os-release</refname>
|
||
<refname>initrd-release</refname>
|
||
<refname>extension-release</refname>
|
||
<refpurpose>Operating system identification</refpurpose>
|
||
</refnamediv>
|
||
|
||
<refsynopsisdiv>
|
||
<para><simplelist>
|
||
<member><filename>/etc/os-release</filename></member>
|
||
<member><filename>/usr/lib/os-release</filename></member>
|
||
<member><filename>/etc/initrd-release</filename></member>
|
||
<member><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></member>
|
||
</simplelist></para>
|
||
</refsynopsisdiv>
|
||
|
||
<refsect1>
|
||
<title>Description</title>
|
||
|
||
<para>The <filename>/etc/os-release</filename> and
|
||
<filename>/usr/lib/os-release</filename> files contain operating
|
||
system identification data.</para>
|
||
|
||
<para>The format of <filename>os-release</filename> is a newline-separated list of
|
||
environment-like shell-compatible variable assignments. It is possible to source the configuration from
|
||
Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this
|
||
means variable expansion is explicitly not supported), allowing applications to read the file without
|
||
implementing a shell compatible execution engine. Variable assignment values must be enclosed in double
|
||
or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z,
|
||
0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is
|
||
optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes,
|
||
following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not
|
||
be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#"
|
||
are treated as comments. Blank lines are permitted and ignored.</para>
|
||
|
||
<para>The file <filename>/etc/os-release</filename> takes
|
||
precedence over <filename>/usr/lib/os-release</filename>.
|
||
Applications should check for the former, and exclusively use its
|
||
data if it exists, and only fall back to
|
||
<filename>/usr/lib/os-release</filename> if it is missing.
|
||
Applications should not read data from both files at the same
|
||
time. <filename>/usr/lib/os-release</filename> is the recommended
|
||
place to store OS release information as part of vendor trees.
|
||
<filename>/etc/os-release</filename> should be a relative symlink
|
||
to <filename>/usr/lib/os-release</filename>, to provide
|
||
compatibility with applications only looking at
|
||
<filename>/etc/</filename>. A relative symlink instead of an
|
||
absolute symlink is necessary to avoid breaking the link in a
|
||
chroot or initrd environment.</para>
|
||
|
||
<para><filename>os-release</filename> contains data that is
|
||
defined by the operating system vendor and should generally not be
|
||
changed by the administrator.</para>
|
||
|
||
<para>As this file only encodes names and identifiers it should
|
||
not be localized.</para>
|
||
|
||
<para>The <filename>/etc/os-release</filename> and
|
||
<filename>/usr/lib/os-release</filename> files might be symlinks
|
||
to other files, but it is important that the file is available
|
||
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="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://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>
|
||
(or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described
|
||
above) work correctly.</para>
|
||
|
||
<para>The rest of this document that talks about <filename>os-release</filename> should be understood
|
||
to apply to <filename>initrd-release</filename> too.</para>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></title>
|
||
|
||
<para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>
|
||
plays the same role for extension images as <filename>os-release</filename> for the main system, and
|
||
follows the syntax and rules as described in the <ulink
|
||
url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page. The purpose of this
|
||
file is to identify the extension and to allow the operating system to verify that the extension image
|
||
matches the base OS. This is typically implemented by checking that the <varname>ID=</varname> options
|
||
match, and either <varname>SYSEXT_LEVEL=</varname> exists and matches too, or if it is not present,
|
||
<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 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
|
||
to apply to <filename>extension-release</filename> too.</para>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Options</title>
|
||
|
||
<para>The following OS identifications parameters may be set using
|
||
<filename>os-release</filename>:</para>
|
||
|
||
<refsect2>
|
||
<title>General information identifying the operating system</title>
|
||
|
||
<variablelist class='environment-variables'>
|
||
<varlistentry>
|
||
<term><varname>NAME=</varname></term>
|
||
|
||
<listitem><para>A string identifying the operating system, without a version component, and
|
||
suitable for presentation to the user. If not set, a default of <literal>NAME=Linux</literal> may
|
||
be used.</para>
|
||
|
||
<para>Examples: <literal>NAME=Fedora</literal>, <literal>NAME="Debian GNU/Linux"</literal>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ID=</varname></term>
|
||
|
||
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
|
||
and "-") identifying the operating system, excluding any version information and suitable for
|
||
processing by scripts or usage in generated filenames. If not set, a default of
|
||
<literal>ID=linux</literal> may be used. Note that even though this string may not include
|
||
characters that require shell quoting, quoting may nevertheless be used.</para>
|
||
|
||
<para>Examples: <literal>ID=fedora</literal>, <literal>ID=debian</literal>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ID_LIKE=</varname></term>
|
||
|
||
<listitem><para>A space-separated list of operating system identifiers in the same syntax as the
|
||
<varname>ID=</varname> setting. It should list identifiers of operating systems that are closely
|
||
related to the local operating system in regards to packaging and programming interfaces, for
|
||
example listing one or more OS identifiers the local OS is a derivative from. An OS should
|
||
generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
|
||
derived from it, though symmetric relationships are possible. Build scripts and similar should
|
||
check this variable if they need to identify the local operating system and the value of
|
||
<varname>ID=</varname> is not recognized. Operating systems should be listed in order of how
|
||
closely the local operating system relates to the listed ones, starting with the closest. This
|
||
field is optional.</para>
|
||
|
||
<para>Examples: for an operating system with <literal>ID=centos</literal>, an assignment of
|
||
<literal>ID_LIKE="rhel fedora"</literal> would be appropriate. For an operating system with
|
||
<literal>ID=ubuntu</literal>, an assignment of <literal>ID_LIKE=debian</literal> is appropriate.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>PRETTY_NAME=</varname></term>
|
||
|
||
<listitem><para>A pretty operating system name in a format suitable for presentation to the
|
||
user. May or may not contain a release code name or OS version of some kind, as suitable. If not
|
||
set, a default of <literal>PRETTY_NAME="Linux"</literal> may be used</para>
|
||
|
||
<para>Example: <literal>PRETTY_NAME="Fedora 17 (Beefy Miracle)"</literal>.</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>CPE_NAME=</varname></term>
|
||
|
||
<listitem><para>A CPE name for the operating system, in URI binding syntax, following the <ulink
|
||
url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as
|
||
proposed by the NIST. This field is optional.</para>
|
||
|
||
<para>Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal></para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>VARIANT=</varname></term>
|
||
|
||
<listitem><para>A string identifying a specific variant or edition of the operating system suitable
|
||
for presentation to the user. This field may be used to inform the user that the configuration of
|
||
this system is subject to a specific divergent set of rules or default configuration settings. This
|
||
field is optional and may not be implemented on all systems.</para>
|
||
|
||
<para>Examples: <literal>VARIANT="Server Edition"</literal>, <literal>VARIANT="Smart Refrigerator
|
||
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>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v220"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>VARIANT_ID=</varname></term>
|
||
|
||
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
|
||
"-"), identifying a specific variant or edition of the operating system. This may be interpreted by
|
||
other packages in order to determine a divergent default configuration. This field is optional and
|
||
may not be implemented on all systems.</para>
|
||
|
||
<para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v220"/></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Information about the version of the operating system</title>
|
||
|
||
<variablelist class='environment-variables'>
|
||
<varlistentry>
|
||
<term><varname>VERSION=</varname></term>
|
||
|
||
<listitem><para>A string identifying the operating system version, excluding any OS name
|
||
information, possibly including a release code name, and suitable for presentation to the
|
||
user. This field is optional.</para>
|
||
|
||
<para>Examples: <literal>VERSION=17</literal>, <literal>VERSION="17 (Beefy Miracle)"</literal>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>VERSION_ID=</varname></term>
|
||
|
||
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
|
||
a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
|
||
or release code name, and suitable for processing by scripts or usage in generated filenames. This
|
||
field is optional.</para>
|
||
|
||
<para>Examples: <literal>VERSION_ID=17</literal>, <literal>VERSION_ID=11.04</literal>.
|
||
</para></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>VERSION_CODENAME=</varname></term>
|
||
|
||
<listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
|
||
and "-") identifying the operating system release code name, excluding any OS name information or
|
||
release version, and suitable for processing by scripts or usage in generated filenames. This field
|
||
is optional and may not be implemented on all systems.</para>
|
||
|
||
<para>Examples: <literal>VERSION_CODENAME=buster</literal>,
|
||
<literal>VERSION_CODENAME=xenial</literal>.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v231"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>BUILD_ID=</varname></term>
|
||
|
||
<listitem><para>A string uniquely identifying the system image originally used as the installation
|
||
base. In most cases, <varname>VERSION_ID</varname> or
|
||
<varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system
|
||
image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where
|
||
the original installation image version is important: <varname>VERSION_ID</varname> would change
|
||
during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is
|
||
optional.</para>
|
||
|
||
<para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v200"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>IMAGE_ID=</varname></term>
|
||
|
||
<listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
|
||
and "-"), identifying a specific image of the operating system. This is supposed to be used for
|
||
environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
|
||
OS images. This field is optional and may not be implemented on all systems, in particularly not on
|
||
those that are not managed via images but put together and updated from individual packages and on
|
||
the local system.</para>
|
||
|
||
<para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>,
|
||
<literal>IMAGE_ID=netbook-image</literal>.</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>IMAGE_VERSION=</varname></term>
|
||
|
||
<listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
|
||
a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
|
||
<varname>IMAGE_ID</varname> described above, to discern different versions of the same image.
|
||
</para>
|
||
|
||
<para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>.
|
||
</para>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v249"/></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
<para>To summarize: if the image updates are built and shipped as comprehensive units,
|
||
<varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates
|
||
eventually completely replace previously installed contents, as in a typical binary distribution,
|
||
<varname>VERSION_ID</varname> should be used to identify major releases of the operating system.
|
||
<varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when
|
||
the original system image version is important.</para>
|
||
</refsect2>
|
||
|
||
<refsect2>
|
||
<title>Presentation information and links</title>
|
||
|
||
<variablelist class='environment-variables'>
|
||
<varlistentry>
|
||
<term><varname>HOME_URL=</varname></term>
|
||
<term><varname>DOCUMENTATION_URL=</varname></term>
|
||
<term><varname>SUPPORT_URL=</varname></term>
|
||
<term><varname>BUG_REPORT_URL=</varname></term>
|
||
<term><varname>PRIVACY_POLICY_URL=</varname></term>
|
||
|
||
<listitem><para>Links to resources on the Internet related to the operating system.
|
||
<varname>HOME_URL=</varname> should refer to the homepage of the operating system, or alternatively
|
||
some homepage of the specific version of the operating system.
|
||
<varname>DOCUMENTATION_URL=</varname> should refer to the main documentation page for this
|
||
operating system. <varname>SUPPORT_URL=</varname> should refer to the main support page for the
|
||
operating system, if there is any. This is primarily intended for operating systems which vendors
|
||
provide support for. <varname>BUG_REPORT_URL=</varname> should refer to the main bug reporting page
|
||
for the operating system, if there is any. This is primarily intended for operating systems that
|
||
rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the main privacy
|
||
policy page for the operating system, if there is any. These settings are optional, and providing
|
||
only some of these settings is common. These URLs are intended to be exposed in "About this system"
|
||
UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
|
||
Bug", or "Privacy Policy". The values 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, and possibly <literal>mailto:</literal>
|
||
or <literal>tel:</literal>. Only one URL shall be listed in each setting. If multiple resources
|
||
need to be referenced, it is recommended to provide an online landing page linking all available
|
||
resources.</para>
|
||
|
||
<para>Examples: <literal>HOME_URL="https://fedoraproject.org/"</literal>,
|
||
<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="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>
|
||
|
||
<xi:include href="version-info.xml" xpointer="v240"/></listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><varname>ANSI_COLOR=</varname></term>
|
||
|
||
<listitem><para>A suggested presentation color when showing the OS name on the console. This should
|
||
be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
|
||
graphical rendition. This field is optional.</para>
|
||
|
||
<para>Examples: <literal>ANSI_COLOR="0;31"</literal> for red, <literal>ANSI_COLOR="1;34"</literal>
|
||
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>
|
||
|
||
<refsect2>
|
||
<title>Distribution-level defaults and metadata</title>
|
||
|
||
<variablelist class='environment-variables'>
|
||
<varlistentry>
|
||
<term><varname>DEFAULT_HOSTNAME=</varname></term>
|
||
|
||
<listitem><para>A string specifying the hostname if
|
||
<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not
|
||
present and no other configuration source specifies the hostname. Must be either a single DNS label
|
||
(a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
|
||
format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
|
||
that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
|
||
limitation (DNS allows longer names).</para>
|
||
|
||
<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>
|
||
|
||
<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>
|
||
<term><varname>SYSEXT_LEVEL=</varname></term>
|
||
|
||
<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://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>
|
||
|
||
<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>
|
||
<term><varname>SYSEXT_SCOPE=</varname></term>
|
||
<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 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).
|
||
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>
|
||
|
||
<refsect2>
|
||
<title>Notes</title>
|
||
|
||
<para>If you are using this file to determine the OS or a specific version of it, use the
|
||
<varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with
|
||
<varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification
|
||
string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para>
|
||
|
||
<para>Note that operating system vendors may choose not to provide version information, for example to
|
||
accommodate for rolling releases. In this case, <varname>VERSION</varname> and
|
||
<varname>VERSION_ID</varname> may be unset. Applications should not rely on these fields to be
|
||
set.</para>
|
||
|
||
<para>Operating system vendors may extend the file format and introduce new fields. It is highly
|
||
recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
|
||
reading this file must ignore unknown fields.</para>
|
||
|
||
<para>Example: <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para>
|
||
|
||
<para>Container and sandbox runtime managers may make the host's identification data available to
|
||
applications by providing the host's <filename>/etc/os-release</filename> (if available, otherwise
|
||
<filename>/usr/lib/os-release</filename> as a fallback) as
|
||
<filename>/run/host/os-release</filename>.</para>
|
||
</refsect2>
|
||
</refsect1>
|
||
|
||
<refsect1>
|
||
<title>Examples</title>
|
||
|
||
<example>
|
||
<title><filename>os-release</filename> file for Fedora Workstation</title>
|
||
|
||
<programlisting>NAME=Fedora
|
||
VERSION="32 (Workstation Edition)"
|
||
ID=fedora
|
||
VERSION_ID=32
|
||
PRETTY_NAME="Fedora 32 (Workstation Edition)"
|
||
ANSI_COLOR="0;38;2;60;110;180"
|
||
LOGO=fedora-logo-icon
|
||
CPE_NAME="cpe:/o:fedoraproject:fedora:32"
|
||
HOME_URL="https://fedoraproject.org/"
|
||
DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
|
||
SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
|
||
BUG_REPORT_URL="https://bugzilla.redhat.com/"
|
||
REDHAT_BUGZILLA_PRODUCT="Fedora"
|
||
REDHAT_BUGZILLA_PRODUCT_VERSION=32
|
||
REDHAT_SUPPORT_PRODUCT="Fedora"
|
||
REDHAT_SUPPORT_PRODUCT_VERSION=32
|
||
PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
|
||
VARIANT="Workstation Edition"
|
||
VARIANT_ID=workstation</programlisting>
|
||
</example>
|
||
|
||
<example>
|
||
<title><filename>extension-release</filename> file for an extension for Fedora Workstation 32</title>
|
||
|
||
<programlisting>ID=fedora
|
||
VERSION_ID=32</programlisting>
|
||
</example>
|
||
|
||
<example>
|
||
<title>Reading <filename>os-release</filename> in
|
||
<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 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>
|
||
|
||
<refsect1>
|
||
<title>See Also</title>
|
||
<para><simplelist type="inline">
|
||
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||
<member><citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
||
<member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
||
</simplelist></para>
|
||
</refsect1>
|
||
|
||
</refentry>
|