Stop Rebuilding the Whole OS Image: Practical systemd-sysext and confext on Linux

Description and use

Immutable Linux images can be quickly extended with systemd-sysext and systemd-confext, which overlay OverlayFS layers on /usr, /opt, or /etc without rebuilding the image.

Problem

Immutable Linux images make adding a single tool or temporary /etc overlay slow and error‑prone because rebuilding the whole image is required.

Outcome

Extensions can be merged and unmerged in seconds, preserving the immutable base image and enabling rapid, reversible changes to /usr, /opt, or /etc.

Workflow

• Create extension directory under /var/lib/extensions/ or /var/lib/confexts/
• Add an identity file /usr/lib/extension-release.d/extension-release.NAME (or /etc/extension-release.d/extension-release.NAME) matching host os-release
• Place payload files (binaries, scripts, config) in the appropriate hierarchy (e.g., /usr/bin for sysext, /etc/ssh/ for confext)
• Run sudo systemd-sysext merge (or systemd-confext merge) to activate the overlay
• Verify overlay with findmnt /usr or systemd-sysext status
• Use sudo systemd-sysext unmerge (or systemd-confext unmerge) to revert the change

Evidence

systemd-sysext and systemd-confext solve a narrower problem cleanly: merge extension images into the live hierarchy with OverlayFS, then unmerge them without rewriting the base OS.

Source

When you merge: systemd finds installed extension images, builds an OverlayFS stack over the host hierarchy, overmounts /usr + /opt (sysext) or /etc (confext).

Source