chiark / gitweb /
unit: add three new specifiers to use in unit files
[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 General Public License as published by
13   the Free Software Foundation; either version 2 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   General Public License for more details.
20
21   You should have received a copy of the GNU 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
62                 newline-separated list of environment-like
63                 shell-compatible variable assignments. It is possible
64                 to source the configuration from shell scripts,
65                 however, beyond mere variable assignments no shell
66                 features are supported, allowing applications to read
67                 the file without implementing a shell compatible
68                 execution engine.</para>
69
70                 <para><filename>/etc/os-release</filename> contains
71                 data that is defined by the operating system vendor
72                 and should not be changed by the administrator.</para>
73
74                 <para>Depending on the operating system other
75                 configuration files might be checked for OS
76                 identification as well, however only as
77                 fallback.</para>
78         </refsect1>
79
80         <refsect1>
81                 <title>Options</title>
82
83                 <para>The following OS identifications parameters may be set using
84                 <filename>/etc/os-release</filename>:</para>
85
86                 <variablelist>
87
88                         <varlistentry>
89                                 <term><varname>NAME=</varname></term>
90
91                                 <listitem><para>A string identifying
92                                 the operating system, without a
93                                 version string, and not necessarily
94                                 suitable for presentation to the
95                                 user. If not set defaults to
96                                 <literal>Linux</literal>. Example:
97                                 <literal>NAME=Fedora</literal> or
98                                 <literal>NAME="Debian
99                                 GNU/Linux"</literal>.</para></listitem>
100                         </varlistentry>
101
102                         <varlistentry>
103                                 <term><varname>VERSION=</varname></term>
104
105                                 <listitem><para>A string identifying
106                                 the operating system version,
107                                 excluding any name information and
108                                 suitable for presentation to the
109                                 user. Example:
110                                 <literal>VERSION=15</literal> or
111                                 <literal>VERSION="15
112                                 (Rawhide)"</literal>.</para></listitem>
113                         </varlistentry>
114
115                         <varlistentry>
116                                 <term><varname>ID=</varname></term>
117
118                                 <listitem><para>A lower-case string
119                                 (no spaces) identifying the operating
120                                 system, excluding any version
121                                 information and suitable for
122                                 processing by scripts or usage in
123                                 generated file names. If not set
124                                 defaults to
125                                 <literal>linux</literal>. Example:
126                                 <literal>ID=fedora</literal>.</para></listitem>
127                         </varlistentry>
128
129                         <varlistentry>
130                                 <term><varname>VERSION_ID=</varname></term>
131
132                                 <listitem><para>A lower-case string
133                                 (mostly numeric, no spaces) identifying the
134                                 operating system version, excluding
135                                 any name information and suitable for
136                                 processing by scripts or usage in generated file names. Example:
137                                 <literal>VERSION_ID=15</literal>.</para></listitem>
138                         </varlistentry>
139
140                         <varlistentry>
141                                 <term><varname>PRETTY_NAME=</varname></term>
142
143                                 <listitem><para>A pretty operating
144                                 system name in a format suitable for
145                                 presentation to the user. May or may
146                                 not contain an OS version of some
147                                 kind, as suitable. If not set defaults
148                                 to <literal>Linux</literal>. Example:
149                                 <literal>PRETTY_NAME=Fedora 15
150                                 (Rawhide)</literal>.</para></listitem>
151                         </varlistentry>
152
153                         <varlistentry>
154                                 <term><varname>ANSI_COLOR=</varname></term>
155
156                                 <listitem><para>A suggested
157                                 presentation color when showing the
158                                 distribution name on the console. This
159                                 should be specified as string suitable
160                                 for inclusion in the ESC [ m
161                                 ANSI/ECMA-48 escape code for setting
162                                 graphical rendition. Example:
163                                 <literal>ANSI_COLOR=0;31</literal> for
164                                 red, or
165                                 <literal>ANSI_COLOR=1;34</literal> for
166                                 light blue.</para></listitem>
167                         </varlistentry>
168                 </variablelist>
169
170                 <para>If you are reading this file from code or a
171                 shell script to determine the OS or a specific version
172                 of it, use the ID and VERSION_ID fields. When looking
173                 for an OS identification string for presentation to
174                 the user use the PRETTY_NAME field.</para>
175
176                 <para>Note that operating system vendors may choose
177                 not to provide version information, for example to
178                 accommodate for rolling releases. In this case VERSION
179                 and VERSION_ID may be unset. Applications should not
180                 rely on these fields to be set.</para>
181         </refsect1>
182
183         <refsect1>
184                 <title>Example</title>
185
186                 <programlisting>NAME=Fedora
187 VERSION="15 (Rawhide)"
188 ID=fedora
189 VERSION_ID=15
190 PRETTY_NAME="Fedora 15 (Rawhide)"
191 ANSI_COLOR=0;34</programlisting>
192         </refsect1>
193
194         <refsect1>
195                   <title>See Also</title>
196                   <para>
197                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
198                           <citerefentry><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
199                           <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
200                           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
201                           <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>
202                   </para>
203         </refsect1>
204
205 </refentry>