Skip to main content

Sysexts

Sysexts (system extension images) allow users to extend the base OS filesystem with additional functionality and tooling. Sysexts are activated by systemd-sysext, a utility which extends the /usr and /opt directory trees by mounting a read-only overlay over /usr and /opt. Please reference the systemd-sysext man page for more information.

Trident supports servicing sysexts as part of the Clean Install and A/B Update flows. Please reference the sysexts API documentation for how to configure sysexts in the Trident Host Configuration.

Trident Configuration Notes​

Sysext Path​

If no path is specified for a sysext in the Host Configuration, Trident will default to placing the sysext in /var/lib/extensions/. Trident currently supports two other directories for placing sysexts: /etc/extensions/ and /.extra/sysext/. If A/B volumes are configured in the Host Configuration, all sysexts must be placed on an A/B volume. In other words, Trident will return an error if /var/lib/extensions/, or any path specified in the Host Configuration for a sysext, is located on a shared volume. Additionally, the volume must not be read-only.

Sysext Format​

All sysexts must be packaged as a Discoverable Disk Image (DDI). Trident expects to find exactly one valid extension-release file in the sysext. In addition, Trident requires that the sysext contain the field SYSEXT_ID in the extension-release file. This field is used to determine which sysexts require update during an A/B update flow. Each sysext's SYSEXT_ID must be unique among the IDs of all sysexts listed in the Host Configuration.

Read-Only Mount​

Per systemd-sysext documentation, "system extension images are strictly read-only by default". Mutable sysexts are not currently supported in Azure Linux 3.0 (systemd v255), thus all sysexts will result in a read-only overlay over /usr and /opt (if sysexts contain files in /opt).

SELinux​

Servicing of sysexts is not currently compatible with SELinux in systemd 255, as mounting the sysext overlays will result in /usr and /opt being mislabeled. Therefore, SELinux should be configured to disabled in the Host Configuration.