<?xml version='1.0'?> <!--*-nxml-*-->

<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="os-release">

<refentryinfo>

<title>os-release</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>os-release</refentrytitle>

<manvolnum>5</manvolnum>

</refmeta>

<refnamediv>

<refname>os-release</refname>

<refpurpose>Operating system identification</refpurpose>

</refnamediv>

<refsynopsisdiv>

<para><filename>/etc/os-release</filename></para>

<para><filename>/usr/lib/os-release</filename></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 basic file 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 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. Shell special characters ("$", quotes,

backslash, backtick) must be escaped with backslashes, following

shell style. All strings should be in UTF-8 format, and

non-printable characters should not be used. It is not supported

to concatenate multiple individually quoted strings. Lines

beginning with "#" shall be ignored as comments.</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 such as dracut.</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>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>

</refsect1>

<refsect1>

<title>Options</title>

<para>The following OS identifications parameters may be set using

<filename>os-release</filename>:</para>

<variablelist>

<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, defaults to

<literal>NAME=Linux</literal>. Example:

<literal>NAME=Fedora</literal> or <literal>NAME="Debian

GNU/Linux"</literal>.</para></listitem>

</varlistentry>

<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. Example:

<literal>VERSION=17</literal> or <literal>VERSION="17 (Beefy

Miracle)"</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, defaults to

<literal>ID=linux</literal>. Example:

<literal>ID=fedora</literal> or

<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. Example: 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>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. Example: <literal>VERSION_ID=17</literal>

or <literal>VERSION_ID=11.04</literal>.</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, defaults to

<literal>PRETTY_NAME="Linux"</literal>. Example:

<literal>PRETTY_NAME="Fedora 17 (Beefy

Miracle)"</literal>.</para></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.

Example: <literal>ANSI_COLOR="0;31"</literal> for red, or

<literal>ANSI_COLOR="1;34"</literal> for light

blue.</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>CPE_NAME=</varname></term>

<listitem><para>A CPE name for the operating system, following

the <ulink url="https://cpe.mitre.org/specification/">Common

Platform Enumeration Specification</ulink> as proposed by the

MITRE Corporation. This field is optional. Example:

<literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>

</para></listitem>

</varlistentry>

<varlistentry>

<term><varname>HOME_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 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>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 operation 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. Examples:

<literal>HOME_URL="https://fedoraproject.org/"</literal> and

<literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>

</varlistentry>

<varlistentry>

<term><varname>BUILD_ID=</varname></term>

<listitem><para>A string uniquely identifying the system image

used as the origin for a distribution (it is not updated with

system updates). The field can be identical between different

VERSION_IDs as BUILD_ID is an only a unique identifier to a

specific version. Distributions that release each update as a

new version would only need to use VERSION_ID as each build is

already distinct based on the VERSION_ID. This field is

optional. Example: <literal>BUILD_ID="2013-03-20.3"</literal>

or <literal>BUILD_ID=201303203</literal>.

</para></listitem>

</varlistentry>

</variablelist>

<para>If you are reading this file from C code or a shell script

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. Example:

<literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>

</refsect1>

<refsect1>

<title>Example</title>

<programlisting>NAME=Fedora

VERSION="17 (Beefy Miracle)"

ID=fedora

VERSION_ID=17

PRETTY_NAME="Fedora 17 (Beefy Miracle)"

ANSI_COLOR="0;34"

CPE_NAME="cpe:/o:fedoraproject:fedora:17"

HOME_URL="https://fedoraproject.org/"

BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>