Extension Images #
Extension Images are DDIs (
Discoverable Disk Images) that are
built to extend a base system via an overlay. A base system or a root DDI can be extended by several extension
DDIs via, usually, a read-only OverlayFS. The defining characteristic of an Extension Image is that it contains
extension-release.<IMAGE> file that identifies itself and the base system or root DDI it applies to,
and must not contain an
The default order in which extensions are applied is based on lexicographic sorting as defined in the Version Format Specification, with images sorting as older being placed lower in the overlay. Implementations may allow a different order to be explicitly specified instead.
Image Format #
Extensions are DDIs ( Discoverable Disk Images), so the file format will not be redefined here.
Extension Types #
There are two types of extension images, sysext (System Extension) and confext (Configuration Extension). They are differentiated by the directory hierarchies they contain.
sysext (System Extension) #
sysext images extend
/usr/ (OS vendor tree) and/or
/opt/ (third-party vendor tree). They must contain a
/usr/lib/extension-release.d/extension-release.<IMAGE> file to identify them.
confext (Configuration Extension) #
confext images extend
/etc. They must contain a
to identify them.
Image Content #
Extension Images should be additive, and not override content present in the base image or other DDIs, but this will not be enforced.
File Suffix #
Since extensions images are DDIs, they should carry the
.raw suffix. In order to make discerning system
extensions and configuration extensions easy it is recommended to use the
.sysext.raw suffix for system
.confext.raw for configuration extensions.
An Extension Image must contain a
extension-release.<IMAGE> file, where
<IMAGE> must either match the
name of the sysext minus the suffix, or alternatively
extension-release.<IMAGE> must be tagged with a
user.extension-release.strict xattr set to the string
"0" in order to be valid. This is to make it
obvious to users that a sysext is used for its purpose.
The format of
extension-release.<IMAGE> is the same as the
os-release file, and it is a
newline-separated list of environment-like shell-compatible variable assignments. New fields
CONFEXT_LEVEL= have been introduced to allow an implementation to match a sysext or
a confext with the base image upon which it is layered: if the field is present, it must match between the
layers or the Extension Image must be ignored, while if it is not present, but
VERSION_ID= is, then the
latter must match instead.
In addition, the
ID= field must be present and match the base image’s, or be set to the special value
_any, in case the Extension Image can be used on any Linux distribution.
Fields in extension-release — Matching with the base system or DDI #
The following fields are used in order to match with the base system or DDI.
A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, “.”, “_” and “-”) identifying the operating system extensions support level, to indicate which extension images are supported.
If not present, and if
VERSION_ID= is present instead, then this will be checked instead.
ID= are used to match the Extension Image with the root DDI, and
ARCHITECTURE= is used
to match with the host’s CPU architecture, as defined in the
ARCHITECTURE= also support specifying the
_any wildcard, which allows the matching mechanism
to be bypassed.
Fields in extension-release — Identifying the Extension Image #
The identification fields defined in the
can be used to also identify the sysext itself, by prefixing them with
SYSEXT_. For example,
SYSEXT_VERSION_ID=0.1 denotes a ‘myext’ sysext of version ‘0.1’.
There are also extension-specific fields that do not apply to ‘os-release’,
Takes a space-separated list of one or more of the strings
"portable". This field
is optional and indicates what environments the system extension is applicable to: i.e. to regular systems,
to initrds, or to
portable service images. If unspecified,
"SYSEXT_SCOPE=system portable" is implied, i.e. any system extension without this field is applicable to
regular systems and to portable service environments, but not to initrd environments.
A string that specifies which CPU architecture the userspace binaries require. This field is optional and should only be used when just single architecture is supported. It may provide redundant information when used in a GPT partition with a GUID type that already encodes the architecture. If this is not the case, the architecture should be specified in e.g., an extension image, to prevent an incompatible host from loading it.