1OS-RELEASE(5)                     os-release                     OS-RELEASE(5)
2
3
4

NAME

6       os-release, initrd-release - Operating system identification
7

SYNOPSIS

9       /etc/os-release
10
11       /usr/lib/os-release
12
13       /etc/initrd-release
14

DESCRIPTION

16       The /etc/os-release and /usr/lib/os-release files contain operating
17       system identification data.
18
19       The basic file format of os-release is a newline-separated list of
20       environment-like shell-compatible variable assignments. It is possible
21       to source the configuration from shell scripts, however, beyond mere
22       variable assignments, no shell features are supported (this means
23       variable expansion is explicitly not supported), allowing applications
24       to read the file without implementing a shell compatible execution
25       engine. Variable assignment values must be enclosed in double or single
26       quotes if they include spaces, semicolons or other special characters
27       outside of A–Z, a–z, 0–9. Shell special characters ("$", quotes,
28       backslash, backtick) must be escaped with backslashes, following shell
29       style. All strings should be in UTF-8 format, and non-printable
30       characters should not be used. It is not supported to concatenate
31       multiple individually quoted strings. Lines beginning with "#" shall be
32       ignored as comments. Blank lines are permitted and ignored.
33
34       The file /etc/os-release takes precedence over /usr/lib/os-release.
35       Applications should check for the former, and exclusively use its data
36       if it exists, and only fall back to /usr/lib/os-release if it is
37       missing. Applications should not read data from both files at the same
38       time.  /usr/lib/os-release is the recommended place to store OS release
39       information as part of vendor trees.  /etc/os-release should be a
40       relative symlink to /usr/lib/os-release, to provide compatibility with
41       applications only looking at /etc/. A relative symlink instead of an
42       absolute symlink is necessary to avoid breaking the link in a chroot or
43       initrd environment such as dracut.
44
45       os-release contains data that is defined by the operating system vendor
46       and should generally not be changed by the administrator.
47
48       As this file only encodes names and identifiers it should not be
49       localized.
50
51       The /etc/os-release and /usr/lib/os-release files might be symlinks to
52       other files, but it is important that the file is available from
53       earliest boot on, and hence must be located on the root file system.
54
55       For a longer rationale for os-release please refer to the Announcement
56       of /etc/os-release[1].
57
58   /etc/initrd-release
59       In the initrd[2], /etc/initrd-release plays the same role as os-release
60       in the main system. Additionally, the presence of that file means that
61       the system is in the initrd phase.  /etc/os-release should be symlinked
62       to /etc/initrd-release (or vice versa), so programs that only look for
63       /etc/os-release (as described above) work correctly. The rest of this
64       document that talks about os-release should be understood to apply to
65       initrd-release too.
66

OPTIONS

68       The following OS identifications parameters may be set using
69       os-release:
70
71   General information identifying the operating system
72       NAME=
73           A string identifying the operating system, without a version
74           component, and suitable for presentation to the user. If not set, a
75           default of "NAME=Linux" may be used.
76
77           Examples: "NAME=Fedora", "NAME="Debian GNU/Linux"".
78
79       ID=
80           A lower-case string (no spaces or other characters outside of 0–9,
81           a–z, ".", "_" and "-") identifying the operating system, excluding
82           any version information and suitable for processing by scripts or
83           usage in generated filenames. If not set, a default of "ID=linux"
84           may be used.
85
86           Examples: "ID=fedora", "ID=debian".
87
88       ID_LIKE=
89           A space-separated list of operating system identifiers in the same
90           syntax as the ID= setting. It should list identifiers of operating
91           systems that are closely related to the local operating system in
92           regards to packaging and programming interfaces, for example
93           listing one or more OS identifiers the local OS is a derivative
94           from. An OS should generally only list other OS identifiers it
95           itself is a derivative of, and not any OSes that are derived from
96           it, though symmetric relationships are possible. Build scripts and
97           similar should check this variable if they need to identify the
98           local operating system and the value of ID= is not recognized.
99           Operating systems should be listed in order of how closely the
100           local operating system relates to the listed ones, starting with
101           the closest. This field is optional.
102
103           Examples: for an operating system with "ID=centos", an assignment
104           of "ID_LIKE="rhel fedora"" would be appropriate. For an operating
105           system with "ID=ubuntu", an assignment of "ID_LIKE=debian" is
106           appropriate.
107
108       PRETTY_NAME=
109           A pretty operating system name in a format suitable for
110           presentation to the user. May or may not contain a release code
111           name or OS version of some kind, as suitable. If not set, a default
112           of "PRETTY_NAME="Linux"" may be used
113
114           Example: "PRETTY_NAME="Fedora 17 (Beefy Miracle)"".
115
116       CPE_NAME=
117           A CPE name for the operating system, in URI binding syntax,
118           following the Common Platform Enumeration Specification[3] as
119           proposed by the NIST. This field is optional.
120
121           Example: "CPE_NAME="cpe:/o:fedoraproject:fedora:17""
122
123       VARIANT=
124           A string identifying a specific variant or edition of the operating
125           system suitable for presentation to the user. This field may be
126           used to inform the user that the configuration of this system is
127           subject to a specific divergent set of rules or default
128           configuration settings. This field is optional and may not be
129           implemented on all systems.
130
131           Examples: "VARIANT="Server Edition"", "VARIANT="Smart Refrigerator
132           Edition"".
133
134           Note: this field is for display purposes only. The VARIANT_ID field
135           should be used for making programmatic decisions.
136
137       VARIANT_ID=
138           A lower-case string (no spaces or other characters outside of 0–9,
139           a–z, ".", "_" and "-"), identifying a specific variant or edition
140           of the operating system. This may be interpreted by other packages
141           in order to determine a divergent default configuration. This field
142           is optional and may not be implemented on all systems.
143
144           Examples: "VARIANT_ID=server", "VARIANT_ID=embedded".
145
146   Information about the version of the operating system
147       VERSION=
148           A string identifying the operating system version, excluding any OS
149           name information, possibly including a release code name, and
150           suitable for presentation to the user. This field is optional.
151
152           Examples: "VERSION=17", "VERSION="17 (Beefy Miracle)"".
153
154       VERSION_ID=
155           A lower-case string (mostly numeric, no spaces or other characters
156           outside of 0–9, a–z, ".", "_" and "-") identifying the operating
157           system version, excluding any OS name information or release code
158           name, and suitable for processing by scripts or usage in generated
159           filenames. This field is optional.
160
161           Examples: "VERSION_ID=17", "VERSION_ID=11.04".
162
163       VERSION_CODENAME=
164           A lower-case string (no spaces or other characters outside of 0–9,
165           a–z, ".", "_" and "-") identifying the operating system release
166           code name, excluding any OS name information or release version,
167           and suitable for processing by scripts or usage in generated
168           filenames. This field is optional and may not be implemented on all
169           systems.
170
171           Examples: "VERSION_CODENAME=buster", "VERSION_CODENAME=xenial".
172
173       BUILD_ID=
174           A string uniquely identifying the system image originally used as
175           the installation base. In most cases, VERSION_ID or
176           IMAGE_ID+IMAGE_VERSION are updated when the entire system image is
177           replaced during an update.  BUILD_ID may be used in distributions
178           where the original installation image version is important:
179           VERSION_ID would change during incremental system updates, but
180           BUILD_ID would not. This field is optional.
181
182           Examples: "BUILD_ID="2013-03-20.3"", "BUILD_ID=201303203".
183
184       IMAGE_ID=
185           A lower-case string (no spaces or other characters outside of 0–9,
186           a–z, ".", "_" and "-"), identifying a specific image of the
187           operating system. This is supposed to be used for environments
188           where OS images are prepared, built, shipped and updated as
189           comprehensive, consistent OS images. This field is optional and may
190           not be implemented on all systems, in particularly not on those
191           that are not managed via images but put together and updated from
192           individual packages and on the local system.
193
194           Examples: "IMAGE_ID=vendorx-cashier-system",
195           "IMAGE_ID=netbook-image".
196
197       IMAGE_VERSION=
198           A lower-case string (mostly numeric, no spaces or other characters
199           outside of 0–9, a–z, ".", "_" and "-") identifying the OS image
200           version. This is supposed to be used together with IMAGE_ID
201           described above, to discern different versions of the same image.
202
203           Examples: "IMAGE_VERSION=33", "IMAGE_VERSION=47.1rc1".
204
205       To summarize: if the image updates are built and shipped as
206       comprehensive units, IMAGE_ID+IMAGE_VERSION is the best fit. Otherwise,
207       if updates eventually completely replace previously installed contents,
208       as in a typical binary distribution, VERSION_ID should be used to
209       identify major releases of the operating system.  BUILD_ID may be used
210       instead or in addition to VERSION_ID when the original system image
211       version is important.
212
213   Presentation information and links
214       HOME_URL=, DOCUMENTATION_URL=, SUPPORT_URL=, BUG_REPORT_URL=,
215       PRIVACY_POLICY_URL=
216           Links to resources on the Internet related to the operating system.
217           HOME_URL= should refer to the homepage of the operating system, or
218           alternatively some homepage of the specific version of the
219           operating system.  DOCUMENTATION_URL= should refer to the main
220           documentation page for this operating system.  SUPPORT_URL= should
221           refer to the main support page for the operating system, if there
222           is any. This is primarily intended for operating systems which
223           vendors provide support for.  BUG_REPORT_URL= should refer to the
224           main bug reporting page for the operating system, if there is any.
225           This is primarily intended for operating systems that rely on
226           community QA.  PRIVACY_POLICY_URL= should refer to the main privacy
227           policy page for the operating system, if there is any. These
228           settings are optional, and providing only some of these settings is
229           common. These URLs are intended to be exposed in "About this
230           system" UIs behind links with captions such as "About this
231           Operating System", "Obtain Support", "Report a Bug", or "Privacy
232           Policy". The values should be in RFC3986 format[4], and should be
233           "http:" or "https:" URLs, and possibly "mailto:" or "tel:". Only
234           one URL shall be listed in each setting. If multiple resources need
235           to be referenced, it is recommended to provide an online landing
236           page linking all available resources.
237
238           Examples: "HOME_URL="https://fedoraproject.org/"",
239           "BUG_REPORT_URL="https://bugzilla.redhat.com/"".
240
241       LOGO=
242           A string, specifying the name of an icon as defined by
243           freedesktop.org Icon Theme Specification[5]. This can be used by
244           graphical applications to display an operating system's or
245           distributor's logo. This field is optional and may not necessarily
246           be implemented on all systems.
247
248           Examples: "LOGO=fedora-logo", "LOGO=distributor-logo-opensuse"
249
250       ANSI_COLOR=
251           A suggested presentation color when showing the OS name on the
252           console. This should be specified as string suitable for inclusion
253           in the ESC [ m ANSI/ECMA-48 escape code for setting graphical
254           rendition. This field is optional.
255
256           Examples: "ANSI_COLOR="0;31"" for red, "ANSI_COLOR="1;34"" for
257           light blue, or "ANSI_COLOR="0;38;2;60;110;180"" for Fedora blue.
258
259   Distribution-level defaults and metadata
260       DEFAULT_HOSTNAME=
261           A string specifying the hostname if hostname(5) is not present and
262           no other configuration source specifies the hostname. Must be
263           either a single DNS label (a string composed of 7-bit ASCII
264           lower-case characters and no spaces or dots, limited to the format
265           allowed for DNS domain name labels), or a sequence of such labels
266           separated by single dots that forms a valid DNS FQDN. The hostname
267           must be at most 64 characters, which is a Linux limitation (DNS
268           allows longer names).
269
270           See org.freedesktop.hostname1(5) for a description of how systemd-
271           hostnamed.service(8) determines the fallback hostname.
272
273       SYSEXT_LEVEL=
274           A lower-case string (mostly numeric, no spaces or other characters
275           outside of 0–9, a–z, ".", "_" and "-") identifying the operating
276           system extensions support level, to indicate which extension images
277           are supported. See systemd-sysext(8)) for more information.
278
279           Examples: "SYSEXT_LEVEL=2", "SYSEXT_LEVEL=15.14".
280
281   Notes
282       If you are using this file to determine the OS or a specific version of
283       it, use the ID and VERSION_ID fields, possibly with ID_LIKE as fallback
284       for ID. When looking for an OS identification string for presentation
285       to the user use the PRETTY_NAME field.
286
287       Note that operating system vendors may choose not to provide version
288       information, for example to accommodate for rolling releases. In this
289       case, VERSION and VERSION_ID may be unset. Applications should not rely
290       on these fields to be set.
291
292       Operating system vendors may extend the file format and introduce new
293       fields. It is highly recommended to prefix new fields with an OS
294       specific name in order to avoid name clashes. Applications reading this
295       file must ignore unknown fields.
296
297       Example: "DEBIAN_BTS="debbugs://bugs.debian.org/"".
298
299       Container and sandbox runtime managers may make the host's
300       identification data available to applications by providing the host's
301       /etc/os-release (if available, otherwise /usr/lib/os-release as a
302       fallback) as /run/host/os-release.
303

EXAMPLES

305       Example 1. os-release file for Fedora Workstation
306
307           NAME=Fedora
308           VERSION="32 (Workstation Edition)"
309           ID=fedora
310           VERSION_ID=32
311           PRETTY_NAME="Fedora 32 (Workstation Edition)"
312           ANSI_COLOR="0;38;2;60;110;180"
313           LOGO=fedora-logo-icon
314           CPE_NAME="cpe:/o:fedoraproject:fedora:32"
315           HOME_URL="https://fedoraproject.org/"
316           DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
317           SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
318           BUG_REPORT_URL="https://bugzilla.redhat.com/"
319           REDHAT_BUGZILLA_PRODUCT="Fedora"
320           REDHAT_BUGZILLA_PRODUCT_VERSION=32
321           REDHAT_SUPPORT_PRODUCT="Fedora"
322           REDHAT_SUPPORT_PRODUCT_VERSION=32
323           PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
324           VARIANT="Workstation Edition"
325           VARIANT_ID=workstation
326
327       Example 2. Reading os-release in sh(1)
328
329           #!/bin/sh -eu
330
331           test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
332           . "${os_release}"
333
334           echo "Running on ${PRETTY_NAME:-Linux}"
335
336           if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then
337               echo "Looks like Debian!"
338           fi
339
340       Example 3. Reading os-release in python(1)
341
342           #!/usr/bin/python
343
344           import ast
345           import re
346           import sys
347
348           def read_os_release():
349               try:
350                   filename = '/etc/os-release'
351                   f = open(filename)
352               except FileNotFoundError:
353                   filename = '/usr/lib/os-release'
354                   f = open(filename)
355
356               for line_number, line in enumerate(f):
357                   line = line.rstrip()
358                   if not line or line.startswith('#'):
359                       continue
360                   if m := re.match(r'([A-Z][A-Z_0-9]+)=(.*)', line):
361                       name, val = m.groups()
362                       if val and val[0] in '"\'':
363                           val = ast.literal_eval(val)
364                       yield name, val
365                   else:
366                       print(f'{filename}:{line_number + 1}: bad line {line!r}',
367                             file=sys.stderr)
368
369           os_release = dict(read_os_release())
370
371           pretty_name = os_release.get('PRETTY_NAME', 'Linux')
372           print(f'Running on {pretty_name}')
373
374           if 'debian' in [os_release.get('ID', 'linux'),
375                           *os_release.get('ID_LIKE', '').split()]:
376               print('Looks like Debian!')
377

SEE ALSO

379       systemd(1), lsb_release(1), hostname(5), machine-id(5), machine-info(5)
380

NOTES

382        1. Announcement of /etc/os-release
383           http://0pointer.de/blog/projects/os-release
384
385        2. initrd
386           https://www.kernel.org/doc/html/latest/admin-guide/initrd.html
387
388        3. Common Platform Enumeration Specification
389           http://scap.nist.gov/specifications/cpe/
390
391        4. RFC3986 format
392           https://tools.ietf.org/html/rfc3986
393
394        5. freedesktop.org Icon Theme Specification
395           http://standards.freedesktop.org/icon-theme-spec/latest
396
397
398
399systemd 249                                                      OS-RELEASE(5)
Impressum