[thirdparty/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>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para>The <filename>/etc/os-release</filename> file
                contains 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><filename>/etc/os-release</filename> contains
                data that is defined by the operating system vendor
                and should not be changed by the administrator.</para>

                <para>As this file only encodes names and identifiers
                it should not be localized.</para>

                <para>The file <filename>/etc/os-release</filename> might
                be a symlink to another file, 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>/etc/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>/etc/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. 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
                                from, and not any OSes that
                                are derived from it, but 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
e17fb729 LP	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
5430f7f2 LP	12	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	13	the Free Software Foundation; either version 2.1 of the License, or
e17fb729 LP	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
5430f7f2	19	Lesser General Public License for more details.
e17fb729	20
5430f7f2	21	You should have received a copy of the GNU Lesser General Public License
e17fb729 LP	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>
	52	</refsynopsisdiv>
	53
	54	<refsect1>
	55	<title>Description</title>
	56
	57	<para>The <filename>/etc/os-release</filename> file
	58	contains operating system identification data.</para>
	59
	60	<para>The basic file format of
88ce7229 LP	61	<filename>os-release</filename> is a newline-separated
	62	list of environment-like shell-compatible variable
	63	assignments. It is possible to source the
	64	configuration from shell scripts, however, beyond mere
	65	variable assignments no shell features are supported
	66	(this means variable expansion is explicitly not
	67	supported), allowing applications to read the file
	68	without implementing a shell compatible execution
	69	engine. Variable assignment values should be enclosed
	70	in double or single quotes if they include spaces,
	71	semicolons or other special characters outside of A-Z,
	72	a-z, 0-9. All strings should be in UTF-8 format, and
	73	non-printable characters should not be used. If double
	74	or single quotes or backslashes are to be used within
	75	variable assignments they should be escaped with
	76	backslashes, following shell style. It is not
	77	supported to concatenate multiple individually quoted
	78	strings. Lines beginning with "#" shall be ignored as
	79	comments.</para>
e17fb729 LP	80
	81	<para><filename>/etc/os-release</filename> contains
	82	data that is defined by the operating system vendor
	83	and should not be changed by the administrator.</para>
88ce7229 LP	84
	85	<para>As this file only encodes names and identifiers
	86	it should not be localized.</para>
	87
74bebb31 LP	88	<para>The file <filename>/etc/os-release</filename> might
	89	be a symlink to another file, but it is important that
	90	the file is available from earliest boot on, and hence
	91	must be located on the root file system.</para>
	92
88ce7229 LP	93	<para>For a longer rationale for
	94	<filename>/etc/os-release</filename> please refer to
	95	the <ulink
	96	url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
e17fb729 LP	97	</refsect1>
	98
	99	<refsect1>
	100	<title>Options</title>
	101
	102	<para>The following OS identifications parameters may be set using
	103	<filename>/etc/os-release</filename>:</para>
	104
	105	<variablelist>
	106
	107	<varlistentry>
	108	<term><varname>NAME=</varname></term>
	109
	110	<listitem><para>A string identifying
	111	the operating system, without a
f8045772 LP	112	version component, and suitable for
	113	presentation to the user. If not set
	114	defaults to
	115	<literal>NAME=Linux</literal>. Example:
e17fb729 LP	116	<literal>NAME=Fedora</literal> or
	117	<literal>NAME="Debian
	118	GNU/Linux"</literal>.</para></listitem>
	119	</varlistentry>
	120
	121	<varlistentry>
	122	<term><varname>VERSION=</varname></term>
	123
	124	<listitem><para>A string identifying
	125	the operating system version,
88ce7229 LP	126	excluding any OS name information,
	127	possibly including a release code
	128	name, and suitable for presentation to
	129	the user. This field is
	130	optional. Example:
f8045772	131	<literal>VERSION=17</literal> or
88ce7229 LP	132	<literal>VERSION="17 (Beefy
88ce7229 LP	133	Miracle)"</literal>.</para></listitem>
e17fb729 LP	134	</varlistentry>
	135
	136	<varlistentry>
	137	<term><varname>ID=</varname></term>
	138
	139	<listitem><para>A lower-case string
88ce7229 LP	140	(no spaces or other characters outside
	141	of 0-9, a-z, ".", "_" and "-")
	142	identifying the operating system,
	143	excluding any version information and
	144	suitable for processing by scripts or
e9dd9f95	145	usage in generated filenames. If not
88ce7229	146	set defaults to
f8045772	147	<literal>ID=linux</literal>. Example:
88ce7229 LP	148	<literal>ID=fedora</literal> or
88ce7229 LP	149	<literal>ID=debian</literal>.</para></listitem>
e17fb729 LP	150	</varlistentry>
	151
	152	<varlistentry>
e21aee14 LP	153	<term><varname>ID_LIKE=</varname></term>
	154
	155	<listitem><para>A space-separated list
	156	of operating system identifiers in the
	157	same syntax as the
	158	<varname>ID=</varname> setting. Should
	159	list identifiers of operating systems
	160	that are closely related to the local
	161	operating system in regards to
	162	packaging and programming interfaces,
	163	for example listing one or more
62ca938d LP	164	OS identifiers the local
	165	OS is a derivative from. An
	166	OS should generally only list other OS
	167	identifiers it itself is a derivative
	168	from, and not any OSes that
	169	are derived from it, but symmetric
	170	relationships are possible. Build
	171	scripts and similar should check this
	172	variable if they need to identify the
	173	local operating system and the value
	174	of <varname>ID=</varname> is not
e21aee14 LP	175	recognized. Operating systems should
	176	be listed in order of how closely the
	177	local operating system relates to the
	178	listed ones, starting with the
	179	closest. This field is
	180	optional. Example: for an operating
	181	system with
	182	<literal>ID=centos</literal> an
	183	assignment of <literal>ID_LIKE="rhel
	184	fedora"</literal> would be
d383ac0d	185	appropriate. For an operating system
e21aee14 LP	186	with <literal>ID=ubuntu</literal> an
	187	assignment of
	188	<literal>ID_LIKE=debian</literal> is
	189	appropriate.</para></listitem>
	190	</varlistentry>
	191
	192	<varlistentry>
e17fb729 LP	193	<term><varname>VERSION_ID=</varname></term>
	194
	195	<listitem><para>A lower-case string
f8045772 LP	196	(mostly numeric, no spaces or other
	197	characters outside of 0-9, a-z, ".",
	198	"_" and "-") identifying the operating
	199	system version, excluding any OS name
88ce7229	200	information or release code name, and
f8045772	201	suitable for processing by scripts or
e9dd9f95	202	usage in generated filenames. This
f8045772 LP	203	field is optional. Example:
	204	<literal>VERSION_ID=17</literal> or
	205	<literal>VERSION_ID=11.04</literal>.</para></listitem>
e17fb729 LP	206	</varlistentry>
	207
	208	<varlistentry>
	209	<term><varname>PRETTY_NAME=</varname></term>
	210
	211	<listitem><para>A pretty operating
	212	system name in a format suitable for
	213	presentation to the user. May or may
88ce7229 LP	214	not contain a release code name or OS
	215	version of some kind, as suitable. If
	216	not set defaults to
	217	<literal>PRETTY_NAME="Linux"</literal>. Example:
	218	<literal>PRETTY_NAME="Fedora 17 (Beefy
	219	Miracle)"</literal>.</para></listitem>
e17fb729 LP	220	</varlistentry>
	221
	222	<varlistentry>
	223	<term><varname>ANSI_COLOR=</varname></term>
	224
	225	<listitem><para>A suggested
	226	presentation color when showing the
62ca938d	227	OS name on the console. This
e17fb729 LP	228	should be specified as string suitable
	229	for inclusion in the ESC [ m
	230	ANSI/ECMA-48 escape code for setting
f8045772 LP	231	graphical rendition. This field is
	232	optional. Example:
	233	<literal>ANSI_COLOR="0;31"</literal>
	234	for red, or
	235	<literal>ANSI_COLOR="1;34"</literal>
	236	for light blue.</para></listitem>
	237	</varlistentry>
	238
	239	<varlistentry>
	240	<term><varname>CPE_NAME=</varname></term>
	241
	242	<listitem><para>A CPE name for the
	243	operating system, following the <ulink
6ed80a4e	244	url="https://cpe.mitre.org/specification/">Common
f8045772 LP	245	Platform Enumeration
	246	Specification</ulink> as proposed by
	247	the MITRE Corporation. This field
	248	is optional. Example:
	249	<literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
	250	</para></listitem>
e17fb729	251	</varlistentry>
62ca938d LP	252
	253	<varlistentry>
	254	<term><varname>HOME_URL=</varname></term>
	255	<term><varname>SUPPORT_URL=</varname></term>
	256	<term><varname>BUG_REPORT_URL=</varname></term>
	257
	258	<listitem><para>Links to resources on
	259	the Internet related the operating
	260	system. <varname>HOME_URL=</varname>
08307930	261	should refer to the homepage of the
62ca938d LP	262	operating system, or alternatively
	263	some homepage of the specific version
	264	of the operating
	265	system. <varname>SUPPORT_URL=</varname>
	266	should refer to the main support page
	267	for the operating system, if there is
	268	any. This is primarily intended for
	269	operating systems which vendors
	270	provide support
	271	for. <varname>BUG_REPORT_URL=</varname>
	272	should refer to the main bug reporting
	273	page for the operating system, if
	274	there is any. This is primarily
	275	intended for operating systems that
	276	rely on community QA. These settings
	277	are optional, and providing only some
	278	of these settings is common. These
	279	URLs are intended to be exposed in
	280	"About this system" UIs behind links
	281	with captions such as "About this
16dad32e AE	282	Operating System", "Obtain Support",
16dad32e AE	283	and "Report a Bug". The values should
62ca938d LP	284	be in <ulink
	285	url="https://tools.ietf.org/html/rfc3986">RFC3986
	286	format</ulink>, and should be
	287	<literal>http:</literal> or
	288	<literal>https:</literal> URLs, and
	289	possibly <literal>mailto:</literal> or
	290	<literal>tel:</literal>. Only one URL
	291	shall be listed in each setting. If
	292	multiple resources need to be
	293	referenced it is recommended to
	294	provide an online landing page linking
	295	all available resources. Examples:
	296	<literal>HOME_URL="https://fedoraproject.org/"</literal>
	297	and
	298	<literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
	299	</varlistentry>
	300
f0b64722 WD	301	<varlistentry>
	302	<term><varname>BUILD_ID=</varname></term>
	303
	304	<listitem><para>A string uniquely
	305	identifying the system image used as
	306	the origin for a distribution (it is
	307	not updated with system updates). The
	308	field can be identical between
	309	different VERSION_IDs as BUILD_ID is
	310	an only a unique identifier to a
	311	specific version. Distributions that
	312	release each update as a new version
	313	would only need to use VERSION_ID as
	314	each build is already distinct based
	315	on the VERSION_ID. This field is
	316	optional. Example:
	317	<literal>BUILD_ID="2013-03-20.3"</literal>
	318	or
	319	<literal>BUILD_ID=201303203</literal>.
	320
	321	</para></listitem>
	322	</varlistentry>
62ca938d	323
e17fb729 LP	324	</variablelist>
e17fb729 LP	325
f8045772	326	<para>If you are reading this file from C code or a
811ad2b3	327	shell script to determine the OS or a specific version
62ca938d LP	328	of it, use the ID and VERSION_ID fields, possibly with
	329	ID_LIKE as fallback for ID. When looking for an OS
	330	identification string for presentation to the user use
	331	the PRETTY_NAME field.</para>
6bd21277 LP	332
	333	<para>Note that operating system vendors may choose
	334	not to provide version information, for example to
01c3a63e	335	accommodate for rolling releases. In this case VERSION
6bd21277 LP	336	and VERSION_ID may be unset. Applications should not
6bd21277 LP	337	rely on these fields to be set.</para>
edcf3b89 LP	338
	339	<para>Operating system vendors may extend the file
	340	format and introduce new fields. It is highly
	341	recommended to prefix new fields with an OS specific
03f38e74 LP	342	name in order to avoid name clashes. Applications
03f38e74 LP	343	reading this file must ignore unknown fields. Example:
edcf3b89	344	<literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
e17fb729 LP	345	</refsect1>
	346
	347	<refsect1>
	348	<title>Example</title>
	349
	350	<programlisting>NAME=Fedora
f8045772	351	VERSION="17 (Beefy Miracle)"
e17fb729	352	ID=fedora
88ce7229	353	VERSION_ID=17
f8045772 LP	354	PRETTY_NAME="Fedora 17 (Beefy Miracle)"
f8045772 LP	355	ANSI_COLOR="0;34"
62ca938d LP	356	CPE_NAME="cpe:/o:fedoraproject:fedora:17"
	357	HOME_URL="https://fedoraproject.org/"
	358	BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
e17fb729 LP	359	</refsect1>
	360
	361	<refsect1>
	362	<title>See Also</title>
	363	<para>
	364	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
7640a5de LP	365	<citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	366	<citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	367	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
	368	<citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
e17fb729 LP	369	</para>
	370	</refsect1>
	371
	372	</refentry>