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">
7 This file is part of systemd.
9 Copyright 2010 Lennart Poettering
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.
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.
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/>.
25 <refentry id="os-release">
27 <title>os-release</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>os-release</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>os-release</refname>
47 <refpurpose>Operating system identification</refpurpose>
51 <para><filename>/etc/os-release</filename></para>
52 <para><filename>/usr/lib/os-release</filename></para>
56 <title>Description</title>
58 <para>The <filename>/etc/os-release</filename> and
59 <filename>/usr/lib/os-release</filename> files contain
60 operating system identification data.</para>
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
67 variable assignments, no shell features are supported
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 must be enclosed in
72 double or single quotes if they include spaces,
73 semicolons or other special characters outside of A-Z,
74 a-z, 0-9. Shell special characters ("$", quotes,
75 backslash, backtick) must be escaped with backslashes,
76 following shell style. All strings should be in UTF-8
77 format, and non-printable characters should not be used.
78 It is not supported to concatenate multiple individually
79 quoted strings. Lines beginning with "#" shall be
80 ignored as comments.</para>
82 <para>The file <filename>/etc/os-release</filename>
84 <filename>/usr/lib/os-release</filename>. Applications
85 should check for the former, and exclusively use its
86 data if it exists, and only fall back to
87 <filename>/usr/lib/os-release</filename> if it is
88 missing. Applications should not read data from both
90 time. <filename>/usr/lib/os-release</filename> is the
91 recommended place to store OS release information as
93 <filename>/etc/os-release</filename> should be a
95 <filename>/usr/lib/os-release</filename>,
96 to provide compatibility with applications only
97 looking at <filename>/etc</filename>. A relative
98 symlink instead of an absolute symlink is
99 necessary to avoid breaking the link in a chroot or
100 initrd environment such as dracut.</para>
102 <para><filename>os-release</filename> contains data
103 that is defined by the operating system vendor and
104 should generally not be changed by the
105 administrator.</para>
107 <para>As this file only encodes names and identifiers
108 it should not be localized.</para>
110 <para>The <filename>/etc/os-release</filename> and
111 <filename>/usr/lib/os-release</filename> files might
112 be symlinks to other files, but it is important that
113 the file is available from earliest boot on, and hence
114 must be located on the root file system.</para>
116 <para>For a longer rationale for
117 <filename>os-release</filename> please refer to
119 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
123 <title>Options</title>
125 <para>The following OS identifications parameters may be set using
126 <filename>os-release</filename>:</para>
131 <term><varname>NAME=</varname></term>
133 <listitem><para>A string identifying
134 the operating system, without a
135 version component, and suitable for
136 presentation to the user. If not set,
138 <literal>NAME=Linux</literal>. Example:
139 <literal>NAME=Fedora</literal> or
140 <literal>NAME="Debian
141 GNU/Linux"</literal>.</para></listitem>
145 <term><varname>VERSION=</varname></term>
147 <listitem><para>A string identifying
148 the operating system version,
149 excluding any OS name information,
150 possibly including a release code
151 name, and suitable for presentation to
152 the user. This field is
154 <literal>VERSION=17</literal> or
155 <literal>VERSION="17 (Beefy
156 Miracle)"</literal>.</para></listitem>
160 <term><varname>ID=</varname></term>
162 <listitem><para>A lower-case string
163 (no spaces or other characters outside
164 of 0-9, a-z, ".", "_" and "-")
165 identifying the operating system,
166 excluding any version information and
167 suitable for processing by scripts or
168 usage in generated filenames. If not
170 <literal>ID=linux</literal>. Example:
171 <literal>ID=fedora</literal> or
172 <literal>ID=debian</literal>.</para></listitem>
176 <term><varname>ID_LIKE=</varname></term>
178 <listitem><para>A space-separated list
179 of operating system identifiers in the
181 <varname>ID=</varname> setting. It should
182 list identifiers of operating systems
183 that are closely related to the local
184 operating system in regards to
185 packaging and programming interfaces,
186 for example listing one or more
187 OS identifiers the local
188 OS is a derivative from. An
189 OS should generally only list other OS
190 identifiers it itself is a derivative
191 of, and not any OSes that
192 are derived from it, though symmetric
193 relationships are possible. Build
194 scripts and similar should check this
195 variable if they need to identify the
196 local operating system and the value
197 of <varname>ID=</varname> is not
198 recognized. Operating systems should
199 be listed in order of how closely the
200 local operating system relates to the
201 listed ones, starting with the
202 closest. This field is
203 optional. Example: for an operating
205 <literal>ID=centos</literal>, an
206 assignment of <literal>ID_LIKE="rhel
207 fedora"</literal> would be
208 appropriate. For an operating system
209 with <literal>ID=ubuntu</literal>, an
211 <literal>ID_LIKE=debian</literal> is
212 appropriate.</para></listitem>
216 <term><varname>VERSION_ID=</varname></term>
218 <listitem><para>A lower-case string
219 (mostly numeric, no spaces or other
220 characters outside of 0-9, a-z, ".",
221 "_" and "-") identifying the operating
222 system version, excluding any OS name
223 information or release code name, and
224 suitable for processing by scripts or
225 usage in generated filenames. This
226 field is optional. Example:
227 <literal>VERSION_ID=17</literal> or
228 <literal>VERSION_ID=11.04</literal>.</para></listitem>
232 <term><varname>PRETTY_NAME=</varname></term>
234 <listitem><para>A pretty operating
235 system name in a format suitable for
236 presentation to the user. May or may
237 not contain a release code name or OS
238 version of some kind, as suitable. If
240 <literal>PRETTY_NAME="Linux"</literal>. Example:
241 <literal>PRETTY_NAME="Fedora 17 (Beefy
242 Miracle)"</literal>.</para></listitem>
246 <term><varname>ANSI_COLOR=</varname></term>
248 <listitem><para>A suggested
249 presentation color when showing the
250 OS name on the console. This
251 should be specified as string suitable
252 for inclusion in the ESC [ m
253 ANSI/ECMA-48 escape code for setting
254 graphical rendition. This field is
256 <literal>ANSI_COLOR="0;31"</literal>
258 <literal>ANSI_COLOR="1;34"</literal>
259 for light blue.</para></listitem>
263 <term><varname>CPE_NAME=</varname></term>
265 <listitem><para>A CPE name for the
266 operating system, following the <ulink
267 url="https://cpe.mitre.org/specification/">Common
269 Specification</ulink> as proposed by
270 the MITRE Corporation. This field
271 is optional. Example:
272 <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal>
277 <term><varname>HOME_URL=</varname></term>
278 <term><varname>SUPPORT_URL=</varname></term>
279 <term><varname>BUG_REPORT_URL=</varname></term>
281 <listitem><para>Links to resources on
282 the Internet related the operating
283 system. <varname>HOME_URL=</varname>
284 should refer to the homepage of the
285 operating system, or alternatively
286 some homepage of the specific version
288 system. <varname>SUPPORT_URL=</varname>
289 should refer to the main support page
290 for the operating system, if there is
291 any. This is primarily intended for
292 operating systems which vendors
294 for. <varname>BUG_REPORT_URL=</varname>
295 should refer to the main bug reporting
296 page for the operating system, if
297 there is any. This is primarily
298 intended for operating systems that
299 rely on community QA. These settings
300 are optional, and providing only some
301 of these settings is common. These
302 URLs are intended to be exposed in
303 "About this system" UIs behind links
304 with captions such as "About this
305 Operating System", "Obtain Support",
306 and "Report a Bug". The values should
308 url="https://tools.ietf.org/html/rfc3986">RFC3986
309 format</ulink>, and should be
310 <literal>http:</literal> or
311 <literal>https:</literal> URLs, and
312 possibly <literal>mailto:</literal> or
313 <literal>tel:</literal>. Only one URL
314 shall be listed in each setting. If
315 multiple resources need to be
316 referenced, it is recommended to
317 provide an online landing page linking
318 all available resources. Examples:
319 <literal>HOME_URL="https://fedoraproject.org/"</literal>
321 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
325 <term><varname>BUILD_ID=</varname></term>
327 <listitem><para>A string uniquely
328 identifying the system image used as
329 the origin for a distribution (it is
330 not updated with system updates). The
331 field can be identical between
332 different VERSION_IDs as BUILD_ID is
333 an only a unique identifier to a
334 specific version. Distributions that
335 release each update as a new version
336 would only need to use VERSION_ID as
337 each build is already distinct based
338 on the VERSION_ID. This field is
340 <literal>BUILD_ID="2013-03-20.3"</literal>
342 <literal>BUILD_ID=201303203</literal>.
349 <para>If you are reading this file from C code or a
350 shell script to determine the OS or a specific version
351 of it, use the ID and VERSION_ID fields, possibly with
352 ID_LIKE as fallback for ID. When looking for an OS
353 identification string for presentation to the user use
354 the PRETTY_NAME field.</para>
356 <para>Note that operating system vendors may choose
357 not to provide version information, for example to
358 accommodate for rolling releases. In this case, VERSION
359 and VERSION_ID may be unset. Applications should not
360 rely on these fields to be set.</para>
362 <para>Operating system vendors may extend the file
363 format and introduce new fields. It is highly
364 recommended to prefix new fields with an OS specific
365 name in order to avoid name clashes. Applications
366 reading this file must ignore unknown fields. Example:
367 <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
371 <title>Example</title>
373 <programlisting>NAME=Fedora
374 VERSION="17 (Beefy Miracle)"
377 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
379 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
380 HOME_URL="https://fedoraproject.org/"
381 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
385 <title>See Also</title>
387 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
388 <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
389 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
390 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
391 <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>