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 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
77 variable assignments, they should be escaped with
78 backslashes, following shell style. It is not
79 supported to concatenate multiple individually quoted
80 strings. Lines beginning with "#" shall be ignored as
83 <para>The file <filename>/etc/os-release</filename>
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
91 time. <filename>/usr/lib/os-release</filename> is the
92 recommended place to store OS release information as
94 <filename>/etc/os-release</filename> should be a
96 <filename>/usr/lib/os-release</filename>,
97 to provide compatibility with applications only
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>
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>
108 <para>As this file only encodes names and identifiers
109 it should not be localized.</para>
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
114 the file is available from earliest boot on, and hence
115 must be located on the root file system.</para>
117 <para>For a longer rationale for
118 <filename>os-release</filename> please refer to
120 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
124 <title>Options</title>
126 <para>The following OS identifications parameters may be set using
127 <filename>os-release</filename>:</para>
132 <term><varname>NAME=</varname></term>
134 <listitem><para>A string identifying
135 the operating system, without a
136 version component, and suitable for
137 presentation to the user. If not set,
139 <literal>NAME=Linux</literal>. Example:
140 <literal>NAME=Fedora</literal> or
141 <literal>NAME="Debian
142 GNU/Linux"</literal>.</para></listitem>
146 <term><varname>VERSION=</varname></term>
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
155 <literal>VERSION=17</literal> or
156 <literal>VERSION="17 (Beefy
157 Miracle)"</literal>.</para></listitem>
161 <term><varname>ID=</varname></term>
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
169 usage in generated filenames. If not
171 <literal>ID=linux</literal>. Example:
172 <literal>ID=fedora</literal> or
173 <literal>ID=debian</literal>.</para></listitem>
177 <term><varname>ID_LIKE=</varname></term>
179 <listitem><para>A space-separated list
180 of operating system identifiers in the
182 <varname>ID=</varname> setting. It should
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
192 of, and not any OSes that
193 are derived from it, though symmetric
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
206 <literal>ID=centos</literal>, an
207 assignment of <literal>ID_LIKE="rhel
208 fedora"</literal> would be
209 appropriate. For an operating system
210 with <literal>ID=ubuntu</literal>, an
212 <literal>ID_LIKE=debian</literal> is
213 appropriate.</para></listitem>
217 <term><varname>VERSION_ID=</varname></term>
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
226 usage in generated filenames. This
227 field is optional. Example:
228 <literal>VERSION_ID=17</literal> or
229 <literal>VERSION_ID=11.04</literal>.</para></listitem>
233 <term><varname>PRETTY_NAME=</varname></term>
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
241 <literal>PRETTY_NAME="Linux"</literal>. Example:
242 <literal>PRETTY_NAME="Fedora 17 (Beefy
243 Miracle)"</literal>.</para></listitem>
247 <term><varname>ANSI_COLOR=</varname></term>
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
257 <literal>ANSI_COLOR="0;31"</literal>
259 <literal>ANSI_COLOR="1;34"</literal>
260 for light blue.</para></listitem>
264 <term><varname>CPE_NAME=</varname></term>
266 <listitem><para>A CPE name for the
267 operating system, following the <ulink
268 url="https://cpe.mitre.org/specification/">Common
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>
278 <term><varname>HOME_URL=</varname></term>
279 <term><varname>SUPPORT_URL=</varname></term>
280 <term><varname>BUG_REPORT_URL=</varname></term>
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
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
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
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
317 referenced, it is recommended to
318 provide an online landing page linking
319 all available resources. Examples:
320 <literal>HOME_URL="https://fedoraproject.org/"</literal>
322 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
326 <term><varname>BUILD_ID=</varname></term>
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
341 <literal>BUILD_ID="2013-03-20.3"</literal>
343 <literal>BUILD_ID=201303203</literal>.
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>
357 <para>Note that operating system vendors may choose
358 not to provide version information, for example to
359 accommodate for rolling releases. In this case, VERSION
360 and VERSION_ID may be unset. Applications should not
361 rely on these fields to be set.</para>
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>
372 <title>Example</title>
374 <programlisting>NAME=Fedora
375 VERSION="17 (Beefy Miracle)"
378 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
380 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
381 HOME_URL="https://fedoraproject.org/"
382 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
386 <title>See Also</title>
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>