1OS-RELEASE(5) os-release OS-RELEASE(5)
2
6 os-release, initrd-release, extension-release - Operating system
7 identification
8
10 /etc/os-release
11 /usr/lib/os-release
13 /etc/initrd-release
15 /usr/lib/extension-release.d/extension-release.IMAGE
17
19 The /etc/os-release and /usr/lib/os-release files contain operating
20 system identification data.
21 The basic file format of os-release is a newline-separated list of
23 environment-like shell-compatible variable assignments. It is possible
24 to source the configuration from Bourne shell scripts, however, beyond
25 mere variable assignments, no shell features are supported (this means
26 variable expansion is explicitly not supported), allowing applications
27 to read the file without implementing a shell compatible execution
28 engine. Variable assignment values must be enclosed in double or single
29 quotes if they include spaces, semicolons or other special characters
30 outside of A–Z, a–z, 0–9. (Assignments that do not include these
31 special characters may be enclosed in quotes too, but this is
32 optional.) Shell special characters ("$", quotes, backslash, backtick)
33 must be escaped with backslashes, following shell style. All strings
34 should be in UTF-8 encoding, and non-printable characters should not be
35 used. It is not supported to concatenate multiple individually quoted
36 strings. Lines beginning with "#" shall be ignored as comments. Blank
37 lines are permitted and ignored.
38 The file /etc/os-release takes precedence over /usr/lib/os-release.
40 Applications should check for the former, and exclusively use its data
41 if it exists, and only fall back to /usr/lib/os-release if it is
42 missing. Applications should not read data from both files at the same
43 time. /usr/lib/os-release is the recommended place to store OS release
44 information as part of vendor trees. /etc/os-release should be a
45 relative symlink to /usr/lib/os-release, to provide compatibility with
46 applications only looking at /etc/. A relative symlink instead of an
47 absolute symlink is necessary to avoid breaking the link in a chroot or
48 initrd environment such as dracut.
49 os-release contains data that is defined by the operating system vendor
51 and should generally not be changed by the administrator.
52 As this file only encodes names and identifiers it should not be
54 localized.
55 The /etc/os-release and /usr/lib/os-release files might be symlinks to
57 other files, but it is important that the file is available from
58 earliest boot on, and hence must be located on the root file system.
59 For a longer rationale for os-release please refer to the Announcement
61 of /etc/os-release[1].
62 /etc/initrd-release
64 In the initrd[2], /etc/initrd-release plays the same role as os-release
65 in the main system. Additionally, the presence of that file means that
66 the system is in the initrd phase. /etc/os-release should be symlinked
67 to /etc/initrd-release (or vice versa), so programs that only look for
68 /etc/os-release (as described above) work correctly.
69 The rest of this document that talks about os-release should be
71 understood to apply to initrd-release too.
72 /usr/lib/extension-release.d/extension-release.IMAGE
74 /usr/lib/extension-release.d/extension-release.IMAGE plays the same
75 role for extension images as os-release for the main system, and
76 follows the syntax and rules as described in the Portable Services
77 Documentation[3]. The purpose of this file is to identify the extension
78 and to allow the operating system to verify that the extension image
79 matches the base OS. This is typically implemented by checking that the
80 ID= options match, and either SYSEXT_LEVEL= exists and matches too, or
81 if it is not present, VERSION_ID= exists and matches. This ensures
82 ABI/API compatibility between the layers and prevents merging of an
83 incompatible image in an overlay.
84 In the extension-release.IMAGE filename, the IMAGE part must exactly
86 match the file name of the containing image with the suffix removed. In
87 case it is not possible to guarantee that an image file name is stable
88 and doesn't change between the build and the deployment phases, it is
89 possible to relax this check: if exactly one file whose name matches
90 "extension-release.*" is present in this directory, and the file is
91 tagged with a user.extension-release.strict xattr(7) set to the string
92 "0", it will be used instead.
93 The rest of this document that talks about os-release should be
95 understood to apply to extension-release too.
96
98 The following OS identifications parameters may be set using
99 os-release:
100 General information identifying the operating system
102 NAME=
103 A string identifying the operating system, without a version
104 component, and suitable for presentation to the user. If not set, a
105 default of "NAME=Linux" may be used.
106 Examples: "NAME=Fedora", "NAME="Debian GNU/Linux"".
108 ID=
110 A lower-case string (no spaces or other characters outside of 0–9,
111 a–z, ".", "_" and "-") identifying the operating system, excluding
112 any version information and suitable for processing by scripts or
113 usage in generated filenames. If not set, a default of "ID=linux"
114 may be used. Note that even though this string may not include
115 characters that require shell quoting, quoting may nevertheless be
116 used.
117 Examples: "ID=fedora", "ID=debian".
119 ID_LIKE=
121 A space-separated list of operating system identifiers in the same
122 syntax as the ID= setting. It should list identifiers of operating
123 systems that are closely related to the local operating system in
124 regards to packaging and programming interfaces, for example
125 listing one or more OS identifiers the local OS is a derivative
126 from. An OS should generally only list other OS identifiers it
127 itself is a derivative of, and not any OSes that are derived from
128 it, though symmetric relationships are possible. Build scripts and
129 similar should check this variable if they need to identify the
130 local operating system and the value of ID= is not recognized.
131 Operating systems should be listed in order of how closely the
132 local operating system relates to the listed ones, starting with
133 the closest. This field is optional.
134 Examples: for an operating system with "ID=centos", an assignment
136 of "ID_LIKE="rhel fedora"" would be appropriate. For an operating
137 system with "ID=ubuntu", an assignment of "ID_LIKE=debian" is
138 appropriate.
139 PRETTY_NAME=
141 A pretty operating system name in a format suitable for
142 presentation to the user. May or may not contain a release code
143 name or OS version of some kind, as suitable. If not set, a default
144 of "PRETTY_NAME="Linux"" may be used
145 Example: "PRETTY_NAME="Fedora 17 (Beefy Miracle)"".
147 CPE_NAME=
149 A CPE name for the operating system, in URI binding syntax,
150 following the Common Platform Enumeration Specification[4] as
151 proposed by the NIST. This field is optional.
152 Example: "CPE_NAME="cpe:/o:fedoraproject:fedora:17""
154 VARIANT=
156 A string identifying a specific variant or edition of the operating
157 system suitable for presentation to the user. This field may be
158 used to inform the user that the configuration of this system is
159 subject to a specific divergent set of rules or default
160 configuration settings. This field is optional and may not be
161 implemented on all systems.
162 Examples: "VARIANT="Server Edition"", "VARIANT="Smart Refrigerator
164 Edition"".
165 Note: this field is for display purposes only. The VARIANT_ID field
167 should be used for making programmatic decisions.
168 VARIANT_ID=
170 A lower-case string (no spaces or other characters outside of 0–9,
171 a–z, ".", "_" and "-"), identifying a specific variant or edition
172 of the operating system. This may be interpreted by other packages
173 in order to determine a divergent default configuration. This field
174 is optional and may not be implemented on all systems.
175 Examples: "VARIANT_ID=server", "VARIANT_ID=embedded".
177 Information about the version of the operating system
179 VERSION=
180 A string identifying the operating system version, excluding any OS
181 name information, possibly including a release code name, and
182 suitable for presentation to the user. This field is optional.
183 Examples: "VERSION=17", "VERSION="17 (Beefy Miracle)"".
185 VERSION_ID=
187 A lower-case string (mostly numeric, no spaces or other characters
188 outside of 0–9, a–z, ".", "_" and "-") identifying the operating
189 system version, excluding any OS name information or release code
190 name, and suitable for processing by scripts or usage in generated
191 filenames. This field is optional.
192 Examples: "VERSION_ID=17", "VERSION_ID=11.04".
194 VERSION_CODENAME=
196 A lower-case string (no spaces or other characters outside of 0–9,
197 a–z, ".", "_" and "-") identifying the operating system release
198 code name, excluding any OS name information or release version,
199 and suitable for processing by scripts or usage in generated
200 filenames. This field is optional and may not be implemented on all
201 systems.
202 Examples: "VERSION_CODENAME=buster", "VERSION_CODENAME=xenial".
204 BUILD_ID=
206 A string uniquely identifying the system image originally used as
207 the installation base. In most cases, VERSION_ID or
208 IMAGE_ID+IMAGE_VERSION are updated when the entire system image is
209 replaced during an update. BUILD_ID may be used in distributions
210 where the original installation image version is important:
211 VERSION_ID would change during incremental system updates, but
212 BUILD_ID would not. This field is optional.
213 Examples: "BUILD_ID="2013-03-20.3"", "BUILD_ID=201303203".
215 IMAGE_ID=
217 A lower-case string (no spaces or other characters outside of 0–9,
218 a–z, ".", "_" and "-"), identifying a specific image of the
219 operating system. This is supposed to be used for environments
220 where OS images are prepared, built, shipped and updated as
221 comprehensive, consistent OS images. This field is optional and may
222 not be implemented on all systems, in particularly not on those
223 that are not managed via images but put together and updated from
224 individual packages and on the local system.
225 Examples: "IMAGE_ID=vendorx-cashier-system",
227 "IMAGE_ID=netbook-image".
228 IMAGE_VERSION=
230 A lower-case string (mostly numeric, no spaces or other characters
231 outside of 0–9, a–z, ".", "_" and "-") identifying the OS image
232 version. This is supposed to be used together with IMAGE_ID
233 described above, to discern different versions of the same image.
234 Examples: "IMAGE_VERSION=33", "IMAGE_VERSION=47.1rc1".
236 To summarize: if the image updates are built and shipped as
238 comprehensive units, IMAGE_ID+IMAGE_VERSION is the best fit. Otherwise,
239 if updates eventually completely replace previously installed contents,
240 as in a typical binary distribution, VERSION_ID should be used to
241 identify major releases of the operating system. BUILD_ID may be used
242 instead or in addition to VERSION_ID when the original system image
243 version is important.
244 Presentation information and links
246 HOME_URL=, DOCUMENTATION_URL=, SUPPORT_URL=, BUG_REPORT_URL=,
247 PRIVACY_POLICY_URL=
248 Links to resources on the Internet related to the operating system.
249 HOME_URL= should refer to the homepage of the operating system, or
250 alternatively some homepage of the specific version of the
251 operating system. DOCUMENTATION_URL= should refer to the main
252 documentation page for this operating system. SUPPORT_URL= should
253 refer to the main support page for the operating system, if there
254 is any. This is primarily intended for operating systems which
255 vendors provide support for. BUG_REPORT_URL= should refer to the
256 main bug reporting page for the operating system, if there is any.
257 This is primarily intended for operating systems that rely on
258 community QA. PRIVACY_POLICY_URL= should refer to the main privacy
259 policy page for the operating system, if there is any. These
260 settings are optional, and providing only some of these settings is
261 common. These URLs are intended to be exposed in "About this
262 system" UIs behind links with captions such as "About this
263 Operating System", "Obtain Support", "Report a Bug", or "Privacy
264 Policy". The values should be in RFC3986 format[5], and should be
265 "http:" or "https:" URLs, and possibly "mailto:" or "tel:". Only
266 one URL shall be listed in each setting. If multiple resources need
267 to be referenced, it is recommended to provide an online landing
268 page linking all available resources.
269 Examples: "HOME_URL="https://fedoraproject.org/"",
271 "BUG_REPORT_URL="https://bugzilla.redhat.com/"".
272 LOGO=
274 A string, specifying the name of an icon as defined by
275 freedesktop.org Icon Theme Specification[6]. This can be used by
276 graphical applications to display an operating system's or
277 distributor's logo. This field is optional and may not necessarily
278 be implemented on all systems.
279 Examples: "LOGO=fedora-logo", "LOGO=distributor-logo-opensuse"
281 ANSI_COLOR=
283 A suggested presentation color when showing the OS name on the
284 console. This should be specified as string suitable for inclusion
285 in the ESC [ m ANSI/ECMA-48 escape code for setting graphical
286 rendition. This field is optional.
287 Examples: "ANSI_COLOR="0;31"" for red, "ANSI_COLOR="1;34"" for
289 light blue, or "ANSI_COLOR="0;38;2;60;110;180"" for Fedora blue.
290 Distribution-level defaults and metadata
292 DEFAULT_HOSTNAME=
293 A string specifying the hostname if hostname(5) is not present and
294 no other configuration source specifies the hostname. Must be
295 either a single DNS label (a string composed of 7-bit ASCII
296 lower-case characters and no spaces or dots, limited to the format
297 allowed for DNS domain name labels), or a sequence of such labels
298 separated by single dots that forms a valid DNS FQDN. The hostname
299 must be at most 64 characters, which is a Linux limitation (DNS
300 allows longer names).
301 See org.freedesktop.hostname1(5) for a description of how systemd-
303 hostnamed.service(8) determines the fallback hostname.
304 SYSEXT_LEVEL=
306 A lower-case string (mostly numeric, no spaces or other characters
307 outside of 0–9, a–z, ".", "_" and "-") identifying the operating
308 system extensions support level, to indicate which extension images
309 are supported. See
310 /usr/lib/extension-release.d/extension-release.IMAGE, initrd[2] and
311 systemd-sysext(8)) for more information.
312 Examples: "SYSEXT_LEVEL=2", "SYSEXT_LEVEL=15.14".
314 SYSEXT_SCOPE=
316 Takes a space-separated list of one or more of the strings
317 "system", "initrd" and "portable". This field is only supported in
318 extension-release.d/ files and indicates what environments the
319 system extension is applicable to: i.e. to regular systems, to
320 initial RAM filesystems ("initrd") or to portable service images.
321 If unspecified, "SYSEXT_SCOPE=system portable" is implied, i.e. any
322 system extension without this field is applicable to regular
323 systems and to portable service environments, but not to initrd
324 environments.
325 PORTABLE_PREFIXES=
327 Takes a space-separated list of one or more valid prefix match
328 strings for the Portable Services[3] logic. This field serves two
329 purposes: it is informational, identifying portable service images
330 as such (and thus allowing them to be distinguished from other OS
331 images, such as bootable system images). In is also used when a
332 portable service image is attached: the specified or implied
333 portable service prefix is checked against the list specified here,
334 to enforce restrictions how images may be attached to a system.
335 Notes
337 If you are using this file to determine the OS or a specific version of
338 it, use the ID and VERSION_ID fields, possibly with ID_LIKE as fallback
339 for ID. When looking for an OS identification string for presentation
340 to the user use the PRETTY_NAME field.
341 Note that operating system vendors may choose not to provide version
343 information, for example to accommodate for rolling releases. In this
344 case, VERSION and VERSION_ID may be unset. Applications should not rely
345 on these fields to be set.
346 Operating system vendors may extend the file format and introduce new
348 fields. It is highly recommended to prefix new fields with an OS
349 specific name in order to avoid name clashes. Applications reading this
350 file must ignore unknown fields.
351 Example: "DEBIAN_BTS="debbugs://bugs.debian.org/"".
353 Container and sandbox runtime managers may make the host's
355 identification data available to applications by providing the host's
356 /etc/os-release (if available, otherwise /usr/lib/os-release as a
357 fallback) as /run/host/os-release.
358
360 Example 1. os-release file for Fedora Workstation
361 NAME=Fedora
363 VERSION="32 (Workstation Edition)"
364 ID=fedora
365 VERSION_ID=32
366 PRETTY_NAME="Fedora 32 (Workstation Edition)"
367 ANSI_COLOR="0;38;2;60;110;180"
368 LOGO=fedora-logo-icon
369 CPE_NAME="cpe:/o:fedoraproject:fedora:32"
370 HOME_URL="https://fedoraproject.org/"
371 DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
372 SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
373 BUG_REPORT_URL="https://bugzilla.redhat.com/"
374 REDHAT_BUGZILLA_PRODUCT="Fedora"
375 REDHAT_BUGZILLA_PRODUCT_VERSION=32
376 REDHAT_SUPPORT_PRODUCT="Fedora"
377 REDHAT_SUPPORT_PRODUCT_VERSION=32
378 PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
379 VARIANT="Workstation Edition"
380 VARIANT_ID=workstation
381 Example 2. extension-release file for an extension for Fedora
383 Workstation 32
384 ID=fedora
386 VERSION_ID=32
387 Example 3. Reading os-release in sh(1)
389 #!/bin/sh -eu
391 # SPDX-License-Identifier: CC0-1.0
392 test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
394 . "${os_release}"
395 echo "Running on ${PRETTY_NAME:-Linux}"
397 if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then
399 echo "Looks like Debian!"
400 fi
401 Example 4. Reading os-release in python(1) (versions >= 3.10)
403 #!/usr/bin/python
405 # SPDX-License-Identifier: CC0-1.0
406 import platform
408 os_release = platform.freedesktop_os_release()
409 pretty_name = os_release.get('PRETTY_NAME', 'Linux')
411 print(f'Running on {pretty_name!r}')
412 if 'fedora' in [os_release.get('ID', 'linux'),
414 *os_release.get('ID_LIKE', '').split()]:
415 print('Looks like Fedora!')
416 See docs for platform.freedesktop_os_release[7] for more details.
418 Example 5. Reading os-release in python(1) (any version)
420 #!/usr/bin/python
422 # SPDX-License-Identifier: CC0-1.0
423 import ast
425 import re
426 import sys
427 def read_os_release():
429 try:
430 filename = '/etc/os-release'
431 f = open(filename)
432 except FileNotFoundError:
433 filename = '/usr/lib/os-release'
434 f = open(filename)
435 for line_number, line in enumerate(f, start=1):
437 line = line.rstrip()
438 if not line or line.startswith('#'):
439 continue
440 if m := re.match(r'([A-Z][A-Z_0-9]+)=(.*)', line):
441 name, val = m.groups()
442 if val and val[0] in '"\'':
443 val = ast.literal_eval(val)
444 yield name, val
445 else:
446 print(f'{filename}:{line_number}: bad line {line!r}',
447 file=sys.stderr)
448 os_release = dict(read_os_release())
450 pretty_name = os_release.get('PRETTY_NAME', 'Linux')
452 print(f'Running on {pretty_name!r}')
453 if 'debian' in [os_release.get('ID', 'linux'),
455 *os_release.get('ID_LIKE', '').split()]:
456 print('Looks like Debian!')
457 Note that the above version that uses the built-in implementation is
459 preferred in most cases, and the open-coded version here is provided
460 for reference.
461
463 systemd(1), lsb_release(1), hostname(5), machine-id(5), machine-info(5)
464
466 1. Announcement of /etc/os-release
467 http://0pointer.de/blog/projects/os-release
468 2. initrd
470 https://www.kernel.org/doc/html/latest/admin-guide/initrd.html
471 3. Portable Services Documentation
473 https://systemd.io/PORTABLE_SERVICES
474 4. Common Platform Enumeration Specification
476 http://scap.nist.gov/specifications/cpe/
477 5. RFC3986 format
479 https://tools.ietf.org/html/rfc3986
480 6. freedesktop.org Icon Theme Specification
482 http://standards.freedesktop.org/icon-theme-spec/latest
483 7.
485 platform.freedesktop_os_release
487 https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release
488systemd 250 OS-RELEASE(5)