chiark / gitweb /
net-util: add support for Type=ethernet
[elogind.git] / man / os-release.xml
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>
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
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>
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>
84
85                 <para>As this file only encodes names and identifiers
86                 it should not be localized.</para>
87
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
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>
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
112                                 version component, and suitable for
113                                 presentation to the user. If not set,
114                                 defaults to
115                                 <literal>NAME=Linux</literal>. Example:
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,
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:
131                                 <literal>VERSION=17</literal> or
132                                 <literal>VERSION="17 (Beefy
133                                 Miracle)"</literal>.</para></listitem>
134                         </varlistentry>
135
136                         <varlistentry>
137                                 <term><varname>ID=</varname></term>
138
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 filenames. If not
146                                 set, defaults to
147                                 <literal>ID=linux</literal>. Example:
148                                 <literal>ID=fedora</literal> or
149                                 <literal>ID=debian</literal>.</para></listitem>
150                         </varlistentry>
151
152                         <varlistentry>
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. It 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                                 of, and not any OSes that
169                                 are derived from it, though 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
181                                 system with
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
187                                 assignment of
188                                 <literal>ID_LIKE=debian</literal> is
189                                 appropriate.</para></listitem>
190                         </varlistentry>
191
192                         <varlistentry>
193                                 <term><varname>VERSION_ID=</varname></term>
194
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 filenames. This
203                                 field is optional. Example:
204                                 <literal>VERSION_ID=17</literal> or
205                                 <literal>VERSION_ID=11.04</literal>.</para></listitem>
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
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>
220                         </varlistentry>
221
222                         <varlistentry>
223                                 <term><varname>ANSI_COLOR=</varname></term>
224
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
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
244                                 url="https://cpe.mitre.org/specification/">Common
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>
251                         </varlistentry>
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>
261                                 should refer to the homepage of the
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
282                                 Operating System", "Obtain Support",
283                                 and "Report a Bug". The values should
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
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>
323
324                 </variablelist>
325
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>
332
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>
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
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>
345         </refsect1>
346
347         <refsect1>
348                 <title>Example</title>
349
350                 <programlisting>NAME=Fedora
351 VERSION="17 (Beefy Miracle)"
352 ID=fedora
353 VERSION_ID=17
354 PRETTY_NAME="Fedora 17 (Beefy Miracle)"
355 ANSI_COLOR="0;34"
356 CPE_NAME="cpe:/o:fedoraproject:fedora:17"
357 HOME_URL="https://fedoraproject.org/"
358 BUG_REPORT_URL="https://bugzilla.redhat.com/"</programlisting>
359         </refsect1>
360
361         <refsect1>
362                   <title>See Also</title>
363                   <para>
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>
369                   </para>
370         </refsect1>
371
372 </refentry>