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 an extension-release.<IMAGE> file that identifies itself and the base system or root DDI it applies to, and must not contain an os-release file.

Ordering #

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 /etc/extension-release.d/extension-release.<IMAGE> file 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 extensions, and .confext.raw for configuration extensions.

Identification #

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 SYSEXT_LEVEL= and 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.

SYSEXT_LEVEL= CONFEXT_LEVEL= #

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.

Examples: "SYSEXT_LEVEL=2", "CONFEXT_LEVEL=15.14".

If not present, and if VERSION_ID= is present instead, then this will be checked instead.

VERSION_ID=, ID=, ARCHITECTURE= #

VERSION_ID= and 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 os-release specification. ID= and 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 os-release specification can be used to also identify the sysext itself, by prefixing them with SYSEXT_. For example, SYSEXT_ID=myext 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’, SYSEXT_SCOPE=, CONFEXT_SCOPE= and ARCHITECTURE=.

SYSEXT_SCOPE=, CONFEXT_SCOPE= #

Takes a space-separated list of one or more of the strings "system", "initrd" and "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.

ARCHITECTURE= #

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.

Valid values: