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>
55 <title>Description</title>
57 <para>The <filename>/etc/os-release</filename> file
58 contains operating system identification data.</para>
60 <para>The basic file format of
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
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>
85 <para>As this file only encodes names and identifiers
86 it should not be localized.</para>
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>
93 <para>For a longer rationale for
94 <filename>/etc/os-release</filename> please refer to
96 url="http://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para>
100 <title>Options</title>
102 <para>The following OS identifications parameters may be set using
103 <filename>/etc/os-release</filename>:</para>
108 <term><varname>NAME=</varname></term>
110 <listitem><para>A string identifying
111 the operating system, without a
112 version component, and suitable for
113 presentation to the user. If not set
115 <literal>NAME=Linux</literal>. Example:
116 <literal>NAME=Fedora</literal> or
117 <literal>NAME="Debian
118 GNU/Linux"</literal>.</para></listitem>
122 <term><varname>VERSION=</varname></term>
124 <listitem><para>A string identifying
125 the operating system version,
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
131 <literal>VERSION=17</literal> or
132 <literal>VERSION="17 (Beefy
133 Miracle)"</literal>.</para></listitem>
137 <term><varname>ID=</varname></term>
139 <listitem><para>A lower-case string
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
145 usage in generated file names. If not
147 <literal>ID=linux</literal>. Example:
148 <literal>ID=fedora</literal> or
149 <literal>ID=debian</literal>.</para></listitem>
153 <term><varname>ID_LIKE=</varname></term>
155 <listitem><para>A space-separated list
156 of operating system identifiers in 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
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
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
182 <literal>ID=centos</literal> an
183 assignment of <literal>ID_LIKE="rhel
184 fedora"</literal> would be
185 appropriate. For an operating system
186 with <literal>ID=ubuntu</literal> an
188 <literal>ID_LIKE=debian</literal> is
189 appropriate.</para></listitem>
193 <term><varname>VERSION_ID=</varname></term>
195 <listitem><para>A lower-case string
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
200 information or release code name, and
201 suitable for processing by scripts or
202 usage in generated file names. This
203 field is optional. Example:
204 <literal>VERSION_ID=17</literal> or
205 <literal>VERSION_ID=11.04</literal>.</para></listitem>
209 <term><varname>PRETTY_NAME=</varname></term>
211 <listitem><para>A pretty operating
212 system name in a format suitable for
213 presentation to the user. May or may
214 not contain a release code name or OS
215 version of some kind, as suitable. If
217 <literal>PRETTY_NAME="Linux"</literal>. Example:
218 <literal>PRETTY_NAME="Fedora 17 (Beefy
219 Miracle)"</literal>.</para></listitem>
223 <term><varname>ANSI_COLOR=</varname></term>
225 <listitem><para>A suggested
226 presentation color when showing the
227 OS name on the console. This
228 should be specified as string suitable
229 for inclusion in the ESC [ m
230 ANSI/ECMA-48 escape code for setting
231 graphical rendition. This field is
233 <literal>ANSI_COLOR="0;31"</literal>
235 <literal>ANSI_COLOR="1;34"</literal>
236 for light blue.</para></listitem>
240 <term><varname>CPE_NAME=</varname></term>
242 <listitem><para>A CPE name for the
243 operating system, following the <ulink
244 url="http://cpe.mitre.org/specification/">Common
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>
254 <term><varname>HOME_URL=</varname></term>
255 <term><varname>SUPPORT_URL=</varname></term>
256 <term><varname>BUG_REPORT_URL=</varname></term>
258 <listitem><para>Links to resources on
259 the Internet related the operating
260 system. <varname>HOME_URL=</varname>
261 should refer to the homepage of the
262 operating system, or alternatively
263 some homepage of the specific version
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
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
282 Operating System", "Obtain Support",
283 and "Report a Bug". The values should
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>
298 <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal></para></listitem>
302 <term><varname>BUILD_ID=</varname></term>
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
317 <literal>BUILD_ID="2013-03-20.3"</literal>
319 <literal>BUILD_ID=201303203</literal>.
326 <para>If you are reading this file from C code or a
327 shell script to determine the OS or a specific version
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>
333 <para>Note that operating system vendors may choose
334 not to provide version information, for example to
335 accommodate for rolling releases. In this case VERSION
336 and VERSION_ID may be unset. Applications should not
337 rely on these fields to be set.</para>
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
342 name in order to avoid name clashes. Applications
343 reading this file must ignore unknown fields. Example:
344 <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal></para>
348 <title>Example</title>
350 <programlisting>NAME=Fedora
351 VERSION="17 (Beefy Miracle)"
354 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
356 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
357 HOME_URL="https://fedoraproject.org/"
358 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
362 <title>See Also</title>
364 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
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>