[systemd.git] / man / os-release.xml

<?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">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<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 should be enclosed
                in double or single quotes if they include spaces,
                semicolons or other special characters outside of A-Z,
                a-z, 0-9. All strings should be in UTF-8 format, and
                non-printable characters should not be used. If double
                or single quotes or backslashes are to be used within
                variable assignments, they should be escaped with
                backslashes, following shell style. 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>

                                <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. 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",
                                and "Report a Bug". 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 ID and VERSION_ID fields, possibly with
                ID_LIKE as fallback for ID. When looking for an OS
                identification string for presentation to the user use
                the PRETTY_NAME 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, VERSION
                and VERSION_ID 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>
Commit	Line	Data
663996b3 MS	1	<?xml version='1.0'?> <!---nxml--->
	2	<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
	3	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	4	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	5
	6	<!--
	7	This file is part of systemd.
	8
	9	Copyright 2010 Lennart Poettering
	10
	11	systemd is free software; you can redistribute it and/or modify it
	12	under the terms of the GNU Lesser General Public License as published by
	13	the Free Software Foundation; either version 2.1 of the License, or
	14	(at your option) any later version.
	15
	16	systemd is distributed in the hope that it will be useful, but
	17	WITHOUT ANY WARRANTY; without even the implied warranty of
	18	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	19	Lesser General Public License for more details.
	20
	21	You should have received a copy of the GNU Lesser General Public License
	22	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	23	-->
	24
	25	<refentry id="os-release">
	26	<refentryinfo>
	27	<title>os-release</title>
	28	<productname>systemd</productname>
	29
	30	<authorgroup>
	31	<author>
	32	<contrib>Developer</contrib>
	33	<firstname>Lennart</firstname>
	34	<surname>Poettering</surname>
	35	<email>lennart@poettering.net</email>
	36	</author>
	37	</authorgroup>
	38	</refentryinfo>
	39
	40	<refmeta>
	41	<refentrytitle>os-release</refentrytitle>
	42	<manvolnum>5</manvolnum>
	43	</refmeta>
	44
	45	<refnamediv>
	46	<refname>os-release</refname>
	47	<refpurpose>Operating system identification</refpurpose>
	48	</refnamediv>
	49
	50	<refsynopsisdiv>
	51	<para><filename>/etc/os-release</filename></para>
e842803a	52	<para><filename>/usr/lib/os-release</filename></para>
663996b3 MS	53	</refsynopsisdiv>
	54
	55	<refsect1>
	56	<title>Description</title>
	57
e842803a MB	58	<para>The <filename>/etc/os-release</filename> and
	59	<filename>/usr/lib/os-release</filename> files contain
	60	operating system identification data.</para>
663996b3 MS	61
	62	<para>The basic file format of
	63	<filename>os-release</filename> is a newline-separated
	64	list of environment-like shell-compatible variable
	65	assignments. It is possible to source the
	66	configuration from shell scripts, however, beyond mere
14228c0d	67	variable assignments, no shell features are supported
663996b3 MS	68	(this means variable expansion is explicitly not
	69	supported), allowing applications to read the file
	70	without implementing a shell compatible execution
	71	engine. Variable assignment values should be enclosed
	72	in double or single quotes if they include spaces,
	73	semicolons or other special characters outside of A-Z,
	74	a-z, 0-9. All strings should be in UTF-8 format, and
	75	non-printable characters should not be used. If double
	76	or single quotes or backslashes are to be used within
14228c0d	77	variable assignments, they should be escaped with
663996b3 MS	78	backslashes, following shell style. It is not
	79	supported to concatenate multiple individually quoted
	80	strings. Lines beginning with "#" shall be ignored as
	81	comments.</para>
	82
e842803a MB	83	<para>The file <filename>/etc/os-release</filename>
	84	takes precedence over
	85	<filename>/usr/lib/os-release</filename>. Applications
	86	should check for the former, and exclusively use its
	87	data if it exists, and only fall back to
	88	<filename>/usr/lib/os-release</filename> if it is
	89	missing. Applications should not read data from both
	90	files at the same
	91	time. <filename>/usr/lib/os-release</filename> is the
	92	recommended place to store OS release information as
5eef597e MP	93	part of vendor trees.
	94	<filename>/etc/os-release</filename> should be a
	95	relative symlink to
	96	<filename>/usr/lib/os-release</filename>,
e842803a	97	to provide compatibility with applications only
5eef597e MP	98	looking at <filename>/etc</filename>. A relative
	99	symlink instead of an absolute symlink is
	100	necessary to avoid breaking the link in a chroot or
	101	initrd environment such as dracut.</para>
e842803a MB	102
	103	<para><filename>os-release</filename> contains data
	104	that is defined by the operating system vendor and
	105	should generally not be changed by the
	106	administrator.</para>
663996b3 MS	107
	108	<para>As this file only encodes names and identifiers
	109	it should not be localized.</para>
	110
e842803a MB	111	<para>The <filename>/etc/os-release</filename> and
	112	<filename>/usr/lib/os-release</filename> files might
	113	be symlinks to other files, but it is important that
663996b3 MS	114	the file is available from earliest boot on, and hence
	115	must be located on the root file system.</para>
	116
	117	<para>For a longer rationale for
e842803a	118	<filename>os-release</filename> please refer to
663996b3 MS	119	the <ulink
	120	url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
	121	</refsect1>
	122
	123	<refsect1>
	124	<title>Options</title>
	125
	126	<para>The following OS identifications parameters may be set using
e842803a	127	<filename>os-release</filename>:</para>
663996b3 MS	128
	129	<variablelist>
	130
	131	<varlistentry>
	132	<term><varname>NAME=</varname></term>
	133
	134	<listitem><para>A string identifying
	135	the operating system, without a
	136	version component, and suitable for
14228c0d	137	presentation to the user. If not set,
663996b3 MS	138	defaults to
	139	<literal>NAME=Linux</literal>. Example:
	140	<literal>NAME=Fedora</literal> or
	141	<literal>NAME="Debian
	142	GNU/Linux"</literal>.</para></listitem>
	143	</varlistentry>
	144
	145	<varlistentry>
	146	<term><varname>VERSION=</varname></term>
	147
	148	<listitem><para>A string identifying
	149	the operating system version,
	150	excluding any OS name information,
	151	possibly including a release code
	152	name, and suitable for presentation to
	153	the user. This field is
	154	optional. Example:
	155	<literal>VERSION=17</literal> or
	156	<literal>VERSION="17 (Beefy
	157	Miracle)"</literal>.</para></listitem>
	158	</varlistentry>
	159
	160	<varlistentry>
	161	<term><varname>ID=</varname></term>
	162
	163	<listitem><para>A lower-case string
	164	(no spaces or other characters outside
	165	of 0-9, a-z, ".", "_" and "-")
	166	identifying the operating system,
	167	excluding any version information and
	168	suitable for processing by scripts or
14228c0d MB	169	usage in generated filenames. If not
14228c0d MB	170	set, defaults to
663996b3 MS	171	<literal>ID=linux</literal>. Example:
	172	<literal>ID=fedora</literal> or
	173	<literal>ID=debian</literal>.</para></listitem>
	174	</varlistentry>
	175
	176	<varlistentry>
	177	<term><varname>ID_LIKE=</varname></term>
	178
	179	<listitem><para>A space-separated list
	180	of operating system identifiers in the
	181	same syntax as the
14228c0d	182	<varname>ID=</varname> setting. It should
663996b3 MS	183	list identifiers of operating systems
	184	that are closely related to the local
	185	operating system in regards to
	186	packaging and programming interfaces,
	187	for example listing one or more
	188	OS identifiers the local
	189	OS is a derivative from. An
	190	OS should generally only list other OS
	191	identifiers it itself is a derivative
14228c0d MB	192	of, and not any OSes that
14228c0d MB	193	are derived from it, though symmetric
663996b3 MS	194	relationships are possible. Build
	195	scripts and similar should check this
	196	variable if they need to identify the
	197	local operating system and the value
	198	of <varname>ID=</varname> is not
	199	recognized. Operating systems should
	200	be listed in order of how closely the
	201	local operating system relates to the
	202	listed ones, starting with the
	203	closest. This field is
	204	optional. Example: for an operating
	205	system with
14228c0d	206	<literal>ID=centos</literal>, an
663996b3 MS	207	assignment of <literal>ID_LIKE="rhel
	208	fedora"</literal> would be
	209	appropriate. For an operating system
14228c0d	210	with <literal>ID=ubuntu</literal>, an
663996b3 MS	211	assignment of
	212	<literal>ID_LIKE=debian</literal> is
	213	appropriate.</para></listitem>
	214	</varlistentry>
	215
	216	<varlistentry>
	217	<term><varname>VERSION_ID=</varname></term>
	218
	219	<listitem><para>A lower-case string
	220	(mostly numeric, no spaces or other
	221	characters outside of 0-9, a-z, ".",
	222	"_" and "-") identifying the operating
	223	system version, excluding any OS name
	224	information or release code name, and
	225	suitable for processing by scripts or
14228c0d	226	usage in generated filenames. This
663996b3 MS	227	field is optional. Example:
	228	<literal>VERSION_ID=17</literal> or
	229	<literal>VERSION_ID=11.04</literal>.</para></listitem>
	230	</varlistentry>
	231
	232	<varlistentry>
	233	<term><varname>PRETTY_NAME=</varname></term>
	234
	235	<listitem><para>A pretty operating
	236	system name in a format suitable for
	237	presentation to the user. May or may
	238	not contain a release code name or OS
	239	version of some kind, as suitable. If
14228c0d	240	not set, defaults to
663996b3 MS	241	<literal>PRETTY_NAME="Linux"</literal>. Example:
	242	<literal>PRETTY_NAME="Fedora 17 (Beefy
	243	Miracle)"</literal>.</para></listitem>
	244	</varlistentry>
	245
	246	<varlistentry>
	247	<term><varname>ANSI_COLOR=</varname></term>
	248
	249	<listitem><para>A suggested
	250	presentation color when showing the
	251	OS name on the console. This
	252	should be specified as string suitable
	253	for inclusion in the ESC [ m
	254	ANSI/ECMA-48 escape code for setting
	255	graphical rendition. This field is
	256	optional. Example:
	257	<literal>ANSI_COLOR="0;31"</literal>
	258	for red, or
	259	<literal>ANSI_COLOR="1;34"</literal>
	260	for light blue.</para></listitem>
	261	</varlistentry>
	262
	263	<varlistentry>
	264	<term><varname>CPE_NAME=</varname></term>
	265
	266	<listitem><para>A CPE name for the
	267	operating system, following the <ulink
14228c0d	268	url="https://cpe.mitre.org/specification/">Common
663996b3 MS	269	Platform Enumeration
	270	Specification</ulink> as proposed by
	271	the MITRE Corporation. This field
	272	is optional. Example:
	273	<literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
	274	</para></listitem>
	275	</varlistentry>
	276
	277	<varlistentry>
	278	<term><varname>HOME_URL=</varname></term>
	279	<term><varname>SUPPORT_URL=</varname></term>
	280	<term><varname>BUG_REPORT_URL=</varname></term>
	281
	282	<listitem><para>Links to resources on
	283	the Internet related the operating
	284	system. <varname>HOME_URL=</varname>
	285	should refer to the homepage of the
	286	operating system, or alternatively
	287	some homepage of the specific version
	288	of the operating
	289	system. <varname>SUPPORT_URL=</varname>
	290	should refer to the main support page
	291	for the operating system, if there is
	292	any. This is primarily intended for
	293	operating systems which vendors
	294	provide support
	295	for. <varname>BUG_REPORT_URL=</varname>
	296	should refer to the main bug reporting
	297	page for the operating system, if
	298	there is any. This is primarily
	299	intended for operating systems that
	300	rely on community QA. These settings
	301	are optional, and providing only some
	302	of these settings is common. These
	303	URLs are intended to be exposed in
	304	"About this system" UIs behind links
	305	with captions such as "About this
	306	Operating System", "Obtain Support",
	307	and "Report a Bug". The values should
	308	be in <ulink
	309	url="https://tools.ietf.org/html/rfc3986">RFC3986
	310	format</ulink>, and should be
	311	<literal>http:</literal> or
	312	<literal>https:</literal> URLs, and
	313	possibly <literal>mailto:</literal> or
	314	<literal>tel:</literal>. Only one URL
	315	shall be listed in each setting. If
	316	multiple resources need to be
14228c0d	317	referenced, it is recommended to
663996b3 MS	318	provide an online landing page linking
	319	all available resources. Examples:
	320	<literal>HOME_URL="https://fedoraproject.org/"</literal>
	321	and
	322	<literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
	323	</varlistentry>
	324
	325	<varlistentry>
	326	<term><varname>BUILD_ID=</varname></term>
	327
	328	<listitem><para>A string uniquely
	329	identifying the system image used as
	330	the origin for a distribution (it is
	331	not updated with system updates). The
	332	field can be identical between
	333	different VERSION_IDs as BUILD_ID is
	334	an only a unique identifier to a
	335	specific version. Distributions that
	336	release each update as a new version
	337	would only need to use VERSION_ID as
	338	each build is already distinct based
	339	on the VERSION_ID. This field is
	340	optional. Example:
	341	<literal>BUILD_ID="2013-03-20.3"</literal>
	342	or
	343	<literal>BUILD_ID=201303203</literal>.
	344
	345	</para></listitem>
	346	</varlistentry>
	347
	348	</variablelist>
	349
	350	<para>If you are reading this file from C code or a
	351	shell script to determine the OS or a specific version
	352	of it, use the ID and VERSION_ID fields, possibly with
	353	ID_LIKE as fallback for ID. When looking for an OS
	354	identification string for presentation to the user use
	355	the PRETTY_NAME field.</para>
	356
	357	<para>Note that operating system vendors may choose
	358	not to provide version information, for example to
14228c0d	359	accommodate for rolling releases. In this case, VERSION
663996b3 MS	360	and VERSION_ID may be unset. Applications should not
	361	rely on these fields to be set.</para>
	362
	363	<para>Operating system vendors may extend the file
	364	format and introduce new fields. It is highly
	365	recommended to prefix new fields with an OS specific
	366	name in order to avoid name clashes. Applications
	367	reading this file must ignore unknown fields. Example:
	368	<literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
	369	</refsect1>
	370
	371	<refsect1>
	372	<title>Example</title>
	373
	374	<programlisting>NAME=Fedora
	375	VERSION="17 (Beefy Miracle)"
	376	ID=fedora
	377	VERSION_ID=17
	378	PRETTY_NAME="Fedora 17 (Beefy Miracle)"
	379	ANSI_COLOR="0;34"
	380	CPE_NAME="cpe:/o:fedoraproject:fedora:17"
	381	HOME_URL="https://fedoraproject.org/"
	382	BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
	383	</refsect1>
	384
	385	<refsect1>
	386	<title>See Also</title>
	387	<para>
	388	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	389	<citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	390	<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	391	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	392	<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	393	</para>
	394	</refsect1>
	395
	396	</refentry>