]>
Commit | Line | Data |
---|---|---|
e17fb729 | 1 | <?xml version='1.0'?> <!--*-nxml-*--> |
3a54a157 | 2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
e17fb729 | 5 | |
e839ebe5 | 6 | <refentry id="os-release" xmlns:xi="http://www.w3.org/2001/XInclude"> |
798d3a52 ZJS |
7 | <refentryinfo> |
8 | <title>os-release</title> | |
9 | <productname>systemd</productname> | |
798d3a52 ZJS |
10 | </refentryinfo> |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>os-release</refentrytitle> | |
14 | <manvolnum>5</manvolnum> | |
15 | </refmeta> | |
16 | ||
17 | <refnamediv> | |
18 | <refname>os-release</refname> | |
c0527e1f | 19 | <refname>initrd-release</refname> |
9c8b6eaa | 20 | <refname>extension-release</refname> |
798d3a52 ZJS |
21 | <refpurpose>Operating system identification</refpurpose> |
22 | </refnamediv> | |
23 | ||
24 | <refsynopsisdiv> | |
73e97bb0 ZJS |
25 | <para><simplelist> |
26 | <member><filename>/etc/os-release</filename></member> | |
27 | <member><filename>/usr/lib/os-release</filename></member> | |
28 | <member><filename>/etc/initrd-release</filename></member> | |
29 | <member><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></member> | |
30 | </simplelist></para> | |
798d3a52 ZJS |
31 | </refsynopsisdiv> |
32 | ||
33 | <refsect1> | |
34 | <title>Description</title> | |
35 | ||
36 | <para>The <filename>/etc/os-release</filename> and | |
37 | <filename>/usr/lib/os-release</filename> files contain operating | |
38 | system identification data.</para> | |
39 | ||
49fddcd3 | 40 | <para>The format of <filename>os-release</filename> is a newline-separated list of |
5c12ee36 LP |
41 | environment-like shell-compatible variable assignments. It is possible to source the configuration from |
42 | Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this | |
43 | means variable expansion is explicitly not supported), allowing applications to read the file without | |
44 | implementing a shell compatible execution engine. Variable assignment values must be enclosed in double | |
45 | or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z, | |
46 | 0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is | |
47 | optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes, | |
48 | following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not | |
49fddcd3 ZJS |
49 | be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#" |
50 | are treated as comments. Blank lines are permitted and ignored.</para> | |
798d3a52 ZJS |
51 | |
52 | <para>The file <filename>/etc/os-release</filename> takes | |
53 | precedence over <filename>/usr/lib/os-release</filename>. | |
54 | Applications should check for the former, and exclusively use its | |
55 | data if it exists, and only fall back to | |
56 | <filename>/usr/lib/os-release</filename> if it is missing. | |
57 | Applications should not read data from both files at the same | |
58 | time. <filename>/usr/lib/os-release</filename> is the recommended | |
59 | place to store OS release information as part of vendor trees. | |
60 | <filename>/etc/os-release</filename> should be a relative symlink | |
61 | to <filename>/usr/lib/os-release</filename>, to provide | |
62 | compatibility with applications only looking at | |
3b121157 | 63 | <filename>/etc/</filename>. A relative symlink instead of an |
798d3a52 | 64 | absolute symlink is necessary to avoid breaking the link in a |
98118c44 | 65 | chroot or initrd environment.</para> |
798d3a52 ZJS |
66 | |
67 | <para><filename>os-release</filename> contains data that is | |
68 | defined by the operating system vendor and should generally not be | |
69 | changed by the administrator.</para> | |
70 | ||
71 | <para>As this file only encodes names and identifiers it should | |
72 | not be localized.</para> | |
73 | ||
74 | <para>The <filename>/etc/os-release</filename> and | |
75 | <filename>/usr/lib/os-release</filename> files might be symlinks | |
76 | to other files, but it is important that the file is available | |
77 | from earliest boot on, and hence must be located on the root file | |
78 | system.</para> | |
79 | ||
3a84a3c9 ZJS |
80 | <para><filename>os-release</filename> must not contain repeating keys. Nevertheless, readers should pick |
81 | the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A | |
82 | reader may warn about repeating entries.</para> | |
83 | ||
798d3a52 ZJS |
84 | <para>For a longer rationale for <filename>os-release</filename> |
85 | please refer to the <ulink | |
dc7e580e | 86 | url="https://0pointer.de/blog/projects/os-release">Announcement of <filename>/etc/os-release</filename></ulink>.</para> |
c0527e1f ZJS |
87 | |
88 | <refsect2> | |
89 | <title><filename>/etc/initrd-release</filename></title> | |
90 | ||
91 | <para>In the <ulink | |
0e685823 | 92 | url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink>, |
c0527e1f ZJS |
93 | <filename>/etc/initrd-release</filename> plays the same role as <filename>os-release</filename> in the |
94 | main system. Additionally, the presence of that file means that the system is in the initrd phase. | |
95 | <filename>/etc/os-release</filename> should be symlinked to <filename>/etc/initrd-release</filename> | |
96 | (or vice versa), so programs that only look for <filename>/etc/os-release</filename> (as described | |
c8cab396 ZJS |
97 | above) work correctly.</para> |
98 | ||
99 | <para>The rest of this document that talks about <filename>os-release</filename> should be understood | |
100 | to apply to <filename>initrd-release</filename> too.</para> | |
c0527e1f | 101 | </refsect2> |
9c8b6eaa LB |
102 | |
103 | <refsect2> | |
104 | <title><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename></title> | |
105 | ||
106 | <para><filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> | |
c8cab396 ZJS |
107 | plays the same role for extension images as <filename>os-release</filename> for the main system, and |
108 | follows the syntax and rules as described in the <ulink | |
de6d05d7 | 109 | url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> page. The purpose of this |
c8cab396 ZJS |
110 | file is to identify the extension and to allow the operating system to verify that the extension image |
111 | matches the base OS. This is typically implemented by checking that the <varname>ID=</varname> options | |
112 | match, and either <varname>SYSEXT_LEVEL=</varname> exists and matches too, or if it is not present, | |
113 | <varname>VERSION_ID=</varname> exists and matches. This ensures ABI/API compatibility between the | |
114 | layers and prevents merging of an incompatible image in an overlay.</para> | |
115 | ||
38d1d104 LB |
116 | <para>In order to identify the extension image itself, the same fields defined below can be added to the |
117 | <filename>extension-release</filename> file with a <varname>SYSEXT_</varname> prefix (to disambiguate | |
118 | from fields used to match on the base image). E.g.: <varname>SYSEXT_ID=myext</varname>, | |
119 | <varname>SYSEXT_VERSION_ID=1.2.3</varname>.</para> | |
120 | ||
c8cab396 ZJS |
121 | <para>In the <filename>extension-release.<replaceable>IMAGE</replaceable></filename> filename, the |
122 | <replaceable>IMAGE</replaceable> part must exactly match the file name of the containing image with the | |
123 | suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't | |
124 | change between the build and the deployment phases, it is possible to relax this check: if exactly one | |
125 | file whose name matches <literal><filename>extension-release.*</filename></literal> is present in this | |
126 | directory, and the file is tagged with a <varname>user.extension-release.strict</varname> | |
ff9412c1 | 127 | <citerefentry project='man-pages'><refentrytitle>xattr</refentrytitle><manvolnum>7</manvolnum></citerefentry> set to the |
c8cab396 ZJS |
128 | string <literal>0</literal>, it will be used instead.</para> |
129 | ||
130 | <para>The rest of this document that talks about <filename>os-release</filename> should be understood | |
131 | to apply to <filename>extension-release</filename> too.</para> | |
9c8b6eaa | 132 | </refsect2> |
798d3a52 ZJS |
133 | </refsect1> |
134 | ||
135 | <refsect1> | |
136 | <title>Options</title> | |
137 | ||
138 | <para>The following OS identifications parameters may be set using | |
139 | <filename>os-release</filename>:</para> | |
140 | ||
00e3abe0 ZJS |
141 | <refsect2> |
142 | <title>General information identifying the operating system</title> | |
143 | ||
144 | <variablelist class='environment-variables'> | |
145 | <varlistentry> | |
146 | <term><varname>NAME=</varname></term> | |
147 | ||
148 | <listitem><para>A string identifying the operating system, without a version component, and | |
149 | suitable for presentation to the user. If not set, a default of <literal>NAME=Linux</literal> may | |
150 | be used.</para> | |
151 | ||
152 | <para>Examples: <literal>NAME=Fedora</literal>, <literal>NAME="Debian GNU/Linux"</literal>. | |
153 | </para></listitem> | |
154 | </varlistentry> | |
155 | ||
156 | <varlistentry> | |
157 | <term><varname>ID=</varname></term> | |
158 | ||
159 | <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" | |
160 | and "-") identifying the operating system, excluding any version information and suitable for | |
161 | processing by scripts or usage in generated filenames. If not set, a default of | |
5c12ee36 LP |
162 | <literal>ID=linux</literal> may be used. Note that even though this string may not include |
163 | characters that require shell quoting, quoting may nevertheless be used.</para> | |
00e3abe0 ZJS |
164 | |
165 | <para>Examples: <literal>ID=fedora</literal>, <literal>ID=debian</literal>.</para></listitem> | |
166 | </varlistentry> | |
167 | ||
168 | <varlistentry> | |
169 | <term><varname>ID_LIKE=</varname></term> | |
170 | ||
171 | <listitem><para>A space-separated list of operating system identifiers in the same syntax as the | |
172 | <varname>ID=</varname> setting. It should list identifiers of operating systems that are closely | |
173 | related to the local operating system in regards to packaging and programming interfaces, for | |
174 | example listing one or more OS identifiers the local OS is a derivative from. An OS should | |
175 | generally only list other OS identifiers it itself is a derivative of, and not any OSes that are | |
176 | derived from it, though symmetric relationships are possible. Build scripts and similar should | |
177 | check this variable if they need to identify the local operating system and the value of | |
178 | <varname>ID=</varname> is not recognized. Operating systems should be listed in order of how | |
179 | closely the local operating system relates to the listed ones, starting with the closest. This | |
180 | field is optional.</para> | |
181 | ||
182 | <para>Examples: for an operating system with <literal>ID=centos</literal>, an assignment of | |
183 | <literal>ID_LIKE="rhel fedora"</literal> would be appropriate. For an operating system with | |
184 | <literal>ID=ubuntu</literal>, an assignment of <literal>ID_LIKE=debian</literal> is appropriate. | |
185 | </para></listitem> | |
186 | </varlistentry> | |
187 | ||
188 | <varlistentry> | |
189 | <term><varname>PRETTY_NAME=</varname></term> | |
190 | ||
191 | <listitem><para>A pretty operating system name in a format suitable for presentation to the | |
192 | user. May or may not contain a release code name or OS version of some kind, as suitable. If not | |
193 | set, a default of <literal>PRETTY_NAME="Linux"</literal> may be used</para> | |
194 | ||
195 | <para>Example: <literal>PRETTY_NAME="Fedora 17 (Beefy Miracle)"</literal>.</para></listitem> | |
196 | </varlistentry> | |
197 | ||
198 | <varlistentry> | |
199 | <term><varname>CPE_NAME=</varname></term> | |
200 | ||
201 | <listitem><para>A CPE name for the operating system, in URI binding syntax, following the <ulink | |
202 | url="http://scap.nist.gov/specifications/cpe/">Common Platform Enumeration Specification</ulink> as | |
203 | proposed by the NIST. This field is optional.</para> | |
204 | ||
205 | <para>Example: <literal>CPE_NAME="cpe:/o:fedoraproject:fedora:17"</literal></para></listitem> | |
206 | </varlistentry> | |
207 | ||
208 | <varlistentry> | |
209 | <term><varname>VARIANT=</varname></term> | |
210 | ||
211 | <listitem><para>A string identifying a specific variant or edition of the operating system suitable | |
212 | for presentation to the user. This field may be used to inform the user that the configuration of | |
213 | this system is subject to a specific divergent set of rules or default configuration settings. This | |
214 | field is optional and may not be implemented on all systems.</para> | |
215 | ||
216 | <para>Examples: <literal>VARIANT="Server Edition"</literal>, <literal>VARIANT="Smart Refrigerator | |
217 | Edition"</literal>.</para> | |
218 | ||
219 | <para>Note: this field is for display purposes only. The <varname>VARIANT_ID</varname> field should | |
aefdc112 AK |
220 | be used for making programmatic decisions.</para> |
221 | ||
222 | <xi:include href="version-info.xml" xpointer="v220"/></listitem> | |
00e3abe0 ZJS |
223 | </varlistentry> |
224 | ||
225 | <varlistentry> | |
226 | <term><varname>VARIANT_ID=</varname></term> | |
227 | ||
228 | <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and | |
229 | "-"), identifying a specific variant or edition of the operating system. This may be interpreted by | |
230 | other packages in order to determine a divergent default configuration. This field is optional and | |
231 | may not be implemented on all systems.</para> | |
232 | ||
233 | <para>Examples: <literal>VARIANT_ID=server</literal>, <literal>VARIANT_ID=embedded</literal>. | |
aefdc112 AK |
234 | </para> |
235 | ||
236 | <xi:include href="version-info.xml" xpointer="v220"/></listitem> | |
00e3abe0 ZJS |
237 | </varlistentry> |
238 | </variablelist> | |
239 | </refsect2> | |
240 | ||
241 | <refsect2> | |
242 | <title>Information about the version of the operating system</title> | |
243 | ||
244 | <variablelist class='environment-variables'> | |
245 | <varlistentry> | |
246 | <term><varname>VERSION=</varname></term> | |
247 | ||
248 | <listitem><para>A string identifying the operating system version, excluding any OS name | |
249 | information, possibly including a release code name, and suitable for presentation to the | |
250 | user. This field is optional.</para> | |
251 | ||
252 | <para>Examples: <literal>VERSION=17</literal>, <literal>VERSION="17 (Beefy Miracle)"</literal>. | |
253 | </para></listitem> | |
254 | </varlistentry> | |
255 | ||
256 | <varlistentry> | |
257 | <term><varname>VERSION_ID=</varname></term> | |
258 | ||
259 | <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, | |
260 | a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information | |
261 | or release code name, and suitable for processing by scripts or usage in generated filenames. This | |
262 | field is optional.</para> | |
263 | ||
264 | <para>Examples: <literal>VERSION_ID=17</literal>, <literal>VERSION_ID=11.04</literal>. | |
265 | </para></listitem> | |
266 | </varlistentry> | |
267 | ||
268 | <varlistentry> | |
269 | <term><varname>VERSION_CODENAME=</varname></term> | |
270 | ||
271 | <listitem><para>A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" | |
272 | and "-") identifying the operating system release code name, excluding any OS name information or | |
273 | release version, and suitable for processing by scripts or usage in generated filenames. This field | |
274 | is optional and may not be implemented on all systems.</para> | |
275 | ||
276 | <para>Examples: <literal>VERSION_CODENAME=buster</literal>, | |
aefdc112 AK |
277 | <literal>VERSION_CODENAME=xenial</literal>.</para> |
278 | ||
279 | <xi:include href="version-info.xml" xpointer="v231"/></listitem> | |
00e3abe0 ZJS |
280 | </varlistentry> |
281 | ||
282 | <varlistentry> | |
283 | <term><varname>BUILD_ID=</varname></term> | |
284 | ||
8fd67ab5 ZJS |
285 | <listitem><para>A string uniquely identifying the system image originally used as the installation |
286 | base. In most cases, <varname>VERSION_ID</varname> or | |
287 | <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> are updated when the entire system | |
288 | image is replaced during an update. <varname>BUILD_ID</varname> may be used in distributions where | |
289 | the original installation image version is important: <varname>VERSION_ID</varname> would change | |
290 | during incremental system updates, but <varname>BUILD_ID</varname> would not. This field is | |
291 | optional.</para> | |
00e3abe0 ZJS |
292 | |
293 | <para>Examples: <literal>BUILD_ID="2013-03-20.3"</literal>, <literal>BUILD_ID=201303203</literal>. | |
aefdc112 AK |
294 | </para> |
295 | ||
296 | <xi:include href="version-info.xml" xpointer="v200"/></listitem> | |
00e3abe0 ZJS |
297 | </varlistentry> |
298 | ||
299 | <varlistentry> | |
300 | <term><varname>IMAGE_ID=</varname></term> | |
301 | ||
302 | <listitem><para> A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" | |
303 | and "-"), identifying a specific image of the operating system. This is supposed to be used for | |
304 | environments where OS images are prepared, built, shipped and updated as comprehensive, consistent | |
305 | OS images. This field is optional and may not be implemented on all systems, in particularly not on | |
306 | those that are not managed via images but put together and updated from individual packages and on | |
307 | the local system.</para> | |
308 | ||
309 | <para>Examples: <literal>IMAGE_ID=vendorx-cashier-system</literal>, | |
ec07c3c8 AK |
310 | <literal>IMAGE_ID=netbook-image</literal>.</para> |
311 | ||
312 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
00e3abe0 ZJS |
313 | </varlistentry> |
314 | ||
315 | <varlistentry> | |
316 | <term><varname>IMAGE_VERSION=</varname></term> | |
317 | ||
318 | <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, | |
319 | a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with | |
320 | <varname>IMAGE_ID</varname> described above, to discern different versions of the same image. | |
321 | </para> | |
322 | ||
323 | <para>Examples: <literal>IMAGE_VERSION=33</literal>, <literal>IMAGE_VERSION=47.1rc1</literal>. | |
ec07c3c8 AK |
324 | </para> |
325 | ||
326 | <xi:include href="version-info.xml" xpointer="v249"/></listitem> | |
00e3abe0 ZJS |
327 | </varlistentry> |
328 | </variablelist> | |
8fd67ab5 ZJS |
329 | |
330 | <para>To summarize: if the image updates are built and shipped as comprehensive units, | |
331 | <varname>IMAGE_ID</varname>+<varname>IMAGE_VERSION</varname> is the best fit. Otherwise, if updates | |
332 | eventually completely replace previously installed contents, as in a typical binary distribution, | |
333 | <varname>VERSION_ID</varname> should be used to identify major releases of the operating system. | |
334 | <varname>BUILD_ID</varname> may be used instead or in addition to <varname>VERSION_ID</varname> when | |
335 | the original system image version is important.</para> | |
00e3abe0 ZJS |
336 | </refsect2> |
337 | ||
338 | <refsect2> | |
339 | <title>Presentation information and links</title> | |
340 | ||
341 | <variablelist class='environment-variables'> | |
342 | <varlistentry> | |
343 | <term><varname>HOME_URL=</varname></term> | |
344 | <term><varname>DOCUMENTATION_URL=</varname></term> | |
345 | <term><varname>SUPPORT_URL=</varname></term> | |
346 | <term><varname>BUG_REPORT_URL=</varname></term> | |
347 | <term><varname>PRIVACY_POLICY_URL=</varname></term> | |
348 | ||
349 | <listitem><para>Links to resources on the Internet related to the operating system. | |
350 | <varname>HOME_URL=</varname> should refer to the homepage of the operating system, or alternatively | |
351 | some homepage of the specific version of the operating system. | |
352 | <varname>DOCUMENTATION_URL=</varname> should refer to the main documentation page for this | |
353 | operating system. <varname>SUPPORT_URL=</varname> should refer to the main support page for the | |
354 | operating system, if there is any. This is primarily intended for operating systems which vendors | |
355 | provide support for. <varname>BUG_REPORT_URL=</varname> should refer to the main bug reporting page | |
356 | for the operating system, if there is any. This is primarily intended for operating systems that | |
357 | rely on community QA. <varname>PRIVACY_POLICY_URL=</varname> should refer to the main privacy | |
358 | policy page for the operating system, if there is any. These settings are optional, and providing | |
359 | only some of these settings is common. These URLs are intended to be exposed in "About this system" | |
360 | UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a | |
361 | Bug", or "Privacy Policy". The values should be in <ulink | |
362 | url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be | |
363 | <literal>http:</literal> or <literal>https:</literal> URLs, and possibly <literal>mailto:</literal> | |
364 | or <literal>tel:</literal>. Only one URL shall be listed in each setting. If multiple resources | |
365 | need to be referenced, it is recommended to provide an online landing page linking all available | |
366 | resources.</para> | |
367 | ||
368 | <para>Examples: <literal>HOME_URL="https://fedoraproject.org/"</literal>, | |
369 | <literal>BUG_REPORT_URL="https://bugzilla.redhat.com/"</literal>.</para></listitem> | |
370 | </varlistentry> | |
371 | ||
2615c1f1 ZJS |
372 | <varlistentry> |
373 | <term><varname>SUPPORT_END=</varname></term> | |
374 | ||
375 | <listitem><para>The date at which support for this version of the OS ends. (What exactly "lack of | |
376 | support" means varies between vendors, but generally users should assume that updates, including | |
caa779ab ZJS |
377 | security fixes, will not be provided.) The value is a date in the ISO 8601 format |
378 | <literal>YYYY-MM-DD</literal>, and specifies the first day on which support <emphasis>is | |
379 | not</emphasis> provided.</para> | |
380 | ||
381 | <para>For example, <literal>SUPPORT_END=2001-01-01</literal> means that the system was supported | |
ec07c3c8 AK |
382 | until the end of the last day of the previous millennium.</para> |
383 | ||
384 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
2615c1f1 ZJS |
385 | </varlistentry> |
386 | ||
00e3abe0 ZJS |
387 | <varlistentry> |
388 | <term><varname>LOGO=</varname></term> | |
389 | ||
390 | <listitem><para>A string, specifying the name of an icon as defined by <ulink | |
41d6f3bf | 391 | url="https://standards.freedesktop.org/icon-theme-spec/latest">freedesktop.org Icon Theme |
00e3abe0 ZJS |
392 | Specification</ulink>. This can be used by graphical applications to display an operating system's |
393 | or distributor's logo. This field is optional and may not necessarily be implemented on all | |
394 | systems.</para> | |
395 | ||
396 | <para>Examples: <literal>LOGO=fedora-logo</literal>, <literal>LOGO=distributor-logo-opensuse</literal> | |
aefdc112 AK |
397 | </para> |
398 | ||
399 | <xi:include href="version-info.xml" xpointer="v240"/></listitem> | |
00e3abe0 ZJS |
400 | </varlistentry> |
401 | ||
402 | <varlistentry> | |
403 | <term><varname>ANSI_COLOR=</varname></term> | |
404 | ||
405 | <listitem><para>A suggested presentation color when showing the OS name on the console. This should | |
406 | be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting | |
407 | graphical rendition. This field is optional.</para> | |
408 | ||
409 | <para>Examples: <literal>ANSI_COLOR="0;31"</literal> for red, <literal>ANSI_COLOR="1;34"</literal> | |
410 | for light blue, or <literal>ANSI_COLOR="0;38;2;60;110;180"</literal> for Fedora blue. | |
411 | </para></listitem> | |
412 | </varlistentry> | |
e6d71243 PW |
413 | |
414 | <varlistentry> | |
415 | <term><varname>VENDOR_NAME=</varname></term> | |
416 | ||
417 | <listitem><para>The name of the OS vendor. This is the name of the organization or company which | |
418 | produces the OS. This field is optional.</para> | |
419 | ||
420 | <para>This name is intended to be exposed in "About this system" UIs or software update UIs when | |
421 | needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.</para> | |
422 | ||
423 | <para>Examples: <literal>VENDOR_NAME="Fedora Project"</literal> for Fedora Linux, | |
ec07c3c8 AK |
424 | <literal>VENDOR_NAME="Canonical"</literal> for Ubuntu.</para> |
425 | ||
426 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
e6d71243 PW |
427 | </varlistentry> |
428 | ||
429 | <varlistentry> | |
430 | <term><varname>VENDOR_URL=</varname></term> | |
431 | ||
432 | <listitem><para>The homepage of the OS vendor. This field is optional. The | |
433 | <varname>VENDOR_NAME=</varname> field should be set if this one is, although clients must be | |
434 | robust against either field not being set.</para> | |
435 | ||
436 | <para>The value should be in <ulink | |
437 | url="https://tools.ietf.org/html/rfc3986">RFC3986 format</ulink>, and should be | |
438 | <literal>http:</literal> or <literal>https:</literal> URLs. Only one URL shall be listed in the | |
439 | setting.</para> | |
440 | ||
441 | <para>Examples: <literal>VENDOR_URL="https://fedoraproject.org/"</literal>, | |
ec07c3c8 AK |
442 | <literal>VENDOR_URL="https://canonical.com/"</literal>.</para> |
443 | ||
444 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
e6d71243 | 445 | </varlistentry> |
00e3abe0 ZJS |
446 | </variablelist> |
447 | </refsect2> | |
448 | ||
449 | <refsect2> | |
450 | <title>Distribution-level defaults and metadata</title> | |
451 | ||
452 | <variablelist class='environment-variables'> | |
453 | <varlistentry> | |
454 | <term><varname>DEFAULT_HOSTNAME=</varname></term> | |
455 | ||
456 | <listitem><para>A string specifying the hostname if | |
457 | <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry> is not | |
458 | present and no other configuration source specifies the hostname. Must be either a single DNS label | |
459 | (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the | |
460 | format allowed for DNS domain name labels), or a sequence of such labels separated by single dots | |
461 | that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux | |
462 | limitation (DNS allows longer names).</para> | |
463 | ||
464 | <para>See <citerefentry><refentrytitle>org.freedesktop.hostname1</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
465 | for a description of how | |
466 | <citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
aefdc112 AK |
467 | determines the fallback hostname.</para> |
468 | ||
469 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
00e3abe0 ZJS |
470 | </varlistentry> |
471 | ||
16c1ca0d KL |
472 | <varlistentry> |
473 | <term><varname>ARCHITECTURE=</varname></term> | |
474 | <listitem><para>A string that specifies which CPU architecture the userspace binaries require. | |
475 | The architecture identifiers are the same as for <varname>ConditionArchitecture=</varname> | |
476 | described in <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
477 | The field is optional and should only be used when just single architecture is supported. | |
478 | It may provide redundant information when used in a GPT partition with a GUID type that already | |
479 | encodes the architecture. If this is not the case, the architecture should be specified in | |
480 | e.g., an extension image, to prevent an incompatible host from loading it. | |
ec07c3c8 AK |
481 | </para> |
482 | ||
483 | <xi:include href="version-info.xml" xpointer="v252"/></listitem> | |
16c1ca0d KL |
484 | </varlistentry> |
485 | ||
00e3abe0 ZJS |
486 | <varlistentry> |
487 | <term><varname>SYSEXT_LEVEL=</varname></term> | |
488 | ||
489 | <listitem><para>A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, | |
490 | a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which | |
9c8b6eaa | 491 | extension images are supported. See <filename>/usr/lib/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename>, |
0e685823 | 492 | <ulink url="https://docs.kernel.org/admin-guide/initrd.html">initrd</ulink> and |
00e3abe0 ZJS |
493 | <citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry>) |
494 | for more information.</para> | |
495 | ||
496 | <para>Examples: <literal>SYSEXT_LEVEL=2</literal>, <literal>SYSEXT_LEVEL=15.14</literal>. | |
aefdc112 AK |
497 | </para> |
498 | ||
499 | <xi:include href="version-info.xml" xpointer="v248"/></listitem> | |
00e3abe0 | 500 | </varlistentry> |
60c5f700 | 501 | |
1f4f1666 | 502 | <varlistentry> |
503 | <term><varname>CONFEXT_LEVEL=</varname></term> | |
504 | ||
505 | <listitem><para>Semantically the same as <varname>SYSEXT_LEVEL=</varname> but for confext images. | |
506 | See <filename>/etc/extension-release.d/extension-release.<replaceable>IMAGE</replaceable></filename> | |
507 | for more information.</para> | |
508 | ||
509 | <para>Examples: <literal>CONFEXT_LEVEL=2</literal>, <literal>CONFEXT_LEVEL=15.14</literal>. | |
ec07c3c8 AK |
510 | </para> |
511 | ||
512 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
1f4f1666 | 513 | </varlistentry> |
514 | ||
60c5f700 LP |
515 | <varlistentry> |
516 | <term><varname>SYSEXT_SCOPE=</varname></term> | |
517 | <listitem><para>Takes a space-separated list of one or more of the strings | |
518 | <literal>system</literal>, <literal>initrd</literal> and <literal>portable</literal>. This field is | |
519 | only supported in <filename>extension-release.d/</filename> files and indicates what environments | |
b66a6e1a ZJS |
520 | the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service |
521 | images. If unspecified, <literal>SYSEXT_SCOPE=system portable</literal> is implied, i.e. any system | |
522 | extension without this field is applicable to regular systems and to portable service environments, | |
ec07c3c8 AK |
523 | but not to initrd environments.</para> |
524 | ||
525 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
60c5f700 | 526 | </varlistentry> |
8a129c80 | 527 | |
1f4f1666 | 528 | <varlistentry> |
529 | <term><varname>CONFEXT_SCOPE=</varname></term> | |
530 | ||
ec07c3c8 AK |
531 | <listitem><para>Semantically the same as <varname>SYSEXT_SCOPE=</varname> but for confext images.</para> |
532 | ||
533 | <xi:include href="version-info.xml" xpointer="v254"/></listitem> | |
1f4f1666 | 534 | </varlistentry> |
535 | ||
8a129c80 LP |
536 | <varlistentry> |
537 | <term><varname>PORTABLE_PREFIXES=</varname></term> | |
538 | <listitem><para>Takes a space-separated list of one or more valid prefix match strings for the | |
de6d05d7 | 539 | <ulink url="https://systemd.io/PORTABLE_SERVICES">Portable Services</ulink> logic. |
8b9f0921 ZJS |
540 | This field serves two purposes: it is informational, identifying portable service images as such |
541 | (and thus allowing them to be distinguished from other OS images, such as bootable system images). | |
542 | It is also used when a portable service image is attached: the specified or implied portable | |
543 | service prefix is checked against the list specified here, to enforce restrictions how images may | |
ec07c3c8 AK |
544 | be attached to a system.</para> |
545 | ||
546 | <xi:include href="version-info.xml" xpointer="v250"/></listitem> | |
8a129c80 | 547 | </varlistentry> |
00e3abe0 ZJS |
548 | </variablelist> |
549 | </refsect2> | |
550 | ||
551 | <refsect2> | |
552 | <title>Notes</title> | |
553 | ||
e839ebe5 ZJS |
554 | <para>If you are using this file to determine the OS or a specific version of it, use the |
555 | <varname>ID</varname> and <varname>VERSION_ID</varname> fields, possibly with | |
00e3abe0 ZJS |
556 | <varname>ID_LIKE</varname> as fallback for <varname>ID</varname>. When looking for an OS identification |
557 | string for presentation to the user use the <varname>PRETTY_NAME</varname> field.</para> | |
558 | ||
559 | <para>Note that operating system vendors may choose not to provide version information, for example to | |
560 | accommodate for rolling releases. In this case, <varname>VERSION</varname> and | |
561 | <varname>VERSION_ID</varname> may be unset. Applications should not rely on these fields to be | |
562 | set.</para> | |
563 | ||
564 | <para>Operating system vendors may extend the file format and introduce new fields. It is highly | |
565 | recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications | |
566 | reading this file must ignore unknown fields.</para> | |
567 | ||
568 | <para>Example: <literal>DEBIAN_BTS="debbugs://bugs.debian.org/"</literal>.</para> | |
569 | ||
570 | <para>Container and sandbox runtime managers may make the host's identification data available to | |
571 | applications by providing the host's <filename>/etc/os-release</filename> (if available, otherwise | |
572 | <filename>/usr/lib/os-release</filename> as a fallback) as | |
573 | <filename>/run/host/os-release</filename>.</para> | |
574 | </refsect2> | |
798d3a52 ZJS |
575 | </refsect1> |
576 | ||
577 | <refsect1> | |
e839ebe5 | 578 | <title>Examples</title> |
798d3a52 | 579 | |
e839ebe5 ZJS |
580 | <example> |
581 | <title><filename>os-release</filename> file for Fedora Workstation</title> | |
582 | ||
583 | <programlisting>NAME=Fedora | |
f4ff71b3 | 584 | VERSION="32 (Workstation Edition)" |
e17fb729 | 585 | ID=fedora |
f4ff71b3 LP |
586 | VERSION_ID=32 |
587 | PRETTY_NAME="Fedora 32 (Workstation Edition)" | |
588 | ANSI_COLOR="0;38;2;60;110;180" | |
589 | LOGO=fedora-logo-icon | |
590 | CPE_NAME="cpe:/o:fedoraproject:fedora:32" | |
62ca938d | 591 | HOME_URL="https://fedoraproject.org/" |
f4ff71b3 LP |
592 | DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/" |
593 | SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help" | |
594 | BUG_REPORT_URL="https://bugzilla.redhat.com/" | |
595 | REDHAT_BUGZILLA_PRODUCT="Fedora" | |
596 | REDHAT_BUGZILLA_PRODUCT_VERSION=32 | |
597 | REDHAT_SUPPORT_PRODUCT="Fedora" | |
598 | REDHAT_SUPPORT_PRODUCT_VERSION=32 | |
599 | PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy" | |
600 | VARIANT="Workstation Edition" | |
601 | VARIANT_ID=workstation</programlisting> | |
e839ebe5 ZJS |
602 | </example> |
603 | ||
9c8b6eaa LB |
604 | <example> |
605 | <title><filename>extension-release</filename> file for an extension for Fedora Workstation 32</title> | |
606 | ||
607 | <programlisting>ID=fedora | |
608 | VERSION_ID=32</programlisting> | |
609 | </example> | |
610 | ||
e839ebe5 ZJS |
611 | <example> |
612 | <title>Reading <filename>os-release</filename> in | |
ff9412c1 | 613 | <citerefentry project='man-pages'><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry></title> |
e839ebe5 ZJS |
614 | |
615 | <programlisting><xi:include href="check-os-release.sh" parse="text" /></programlisting> | |
616 | </example> | |
3ca606d1 ZJS |
617 | |
618 | <example> | |
619 | <title>Reading <filename>os-release</filename> in | |
ff9412c1 | 620 | <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (versions >= 3.10)</title> |
ee6fd6a5 ZJS |
621 | |
622 | <programlisting><xi:include href="check-os-release-simple.py" parse="text" /></programlisting> | |
623 | ||
624 | <para>See docs for <ulink url="https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release"> | |
625 | <function>platform.freedesktop_os_release</function></ulink> for more details. | |
626 | </para> | |
627 | </example> | |
628 | ||
629 | <example> | |
630 | <title>Reading <filename>os-release</filename> in | |
ff9412c1 | 631 | <citerefentry project='die-net'><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry> (any version)</title> |
3ca606d1 ZJS |
632 | |
633 | <programlisting><xi:include href="check-os-release.py" parse="text" /></programlisting> | |
ee6fd6a5 ZJS |
634 | |
635 | <para>Note that the above version that uses the built-in implementation is preferred | |
636 | in most cases, and the open-coded version here is provided for reference.</para> | |
3ca606d1 ZJS |
637 | </example> |
638 | ||
798d3a52 ZJS |
639 | </refsect1> |
640 | ||
641 | <refsect1> | |
642 | <title>See Also</title> | |
13a69c12 DT |
643 | <para><simplelist type="inline"> |
644 | <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
645 | <member><citerefentry project='die-net'><refentrytitle>lsb_release</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> | |
646 | <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
647 | <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
648 | <member><citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> | |
649 | </simplelist></para> | |
798d3a52 | 650 | </refsect1> |
e17fb729 LP |
651 | |
652 | </refentry> |