systemd-sysext

List installed extension images

$ systemd-sysext list

$ systemd-sysext merge

$ systemd-sysext status

$ systemd-sysext unmerge

$ systemd-sysext refresh

systemd-sysext [OPTIONS...] {COMMAND} [ARGUMENTS...]

-h, --help
    Shows a short help text and exits.

--version
    Shows a short version string and exits.

--root=PATH
    Operates on a specified alternate root directory PATH instead of the running system's root.

--force
    Forces the operation, overriding certain checks or conditions.

--dry-run
    Performs a trial run without actually making any changes, useful for previewing operations.

--no-pager
    Do not pipe output into a pager.

--json=MODE
    Output log data as JSON. MODE can be 'short', 'pretty', 'oneline', or 'json-pretty'.

--full
    Shows full details in 'status' or 'list' commands, instead of truncated output.

--all
    When used with 'list', shows all available extensions, including inactive ones.

--suffix=SUFFIX
    Specifies an alternate filename suffix for extension images to consider, defaulting to '.sysext'.

status
    Shows the currently active system extension images and their mount points.

list [PATTERN...]
    Lists available system extension images. An optional PATTERN can filter the results.

activate [PATH...]
    Activates the specified system extension images by mounting them as overlays. If no PATH is given, all available extensions are activated.

deactivate [PATH...]
    Deactivates the specified system extension images by unmounting them. If no PATH is given, all currently active extensions are deactivated.

merge
    Re-merges the currently active system extension images. Useful after system updates or changes to the base OS that might affect the overlay.

unmerge
    Unmerges all currently active system extension images, effectively deactivating all extensions.

shutdown
    Unmerges all system extensions and cleans up any temporary mount points. Typically used during system shutdown or before a reboot.

systemd-sysext is a command-line utility used for managing and activating/deactivating system extension images. These extensions are read-only root directory overlays, typically distributed as SquashFS images or plain directories, designed to augment the /usr and /opt hierarchies of a base operating system.

It works by mounting these images via the Linux kernel's OverlayFS feature, creating a union file system that combines the base system with the contents of the extension. This approach is particularly useful in immutable operating system designs, allowing for the flexible addition of software, development tools, or specialized configurations without modifying the underlying base system.

Extensions can be activated dynamically at runtime or automatically during boot by systemd-sysext-generator, providing a robust mechanism for system customization and software distribution in modern Linux environments.

systemd-sysext relies on the Linux kernel's OverlayFS feature, which must be enabled and available. Creating .sysext images is typically done with tools like mkosi or similar image builders, as systemd-sysext focuses on their management and activation rather than creation. Incorrectly structured or untrusted extension images can potentially compromise system stability or security. Extensions provide global overlays and affect all users on the system.

This command is primarily used in scenarios where a base operating system needs to remain immutable, but certain applications, development tools, or custom configurations must be added. Common use cases include: providing specific software stacks on container hosts, creating specialized development environments without polluting the base system, or deploying security-hardened configurations as overlays.

systemd-sysext looks for extension images in a predefined set of directories, typically in the order:
/var/lib/sysext/
/etc/sysext/
/run/sysext/
Images in these locations are automatically considered for activation, either manually or during boot via the systemd-sysext-generator.

systemd-sysext is part of the systemd project, which continually evolves to manage various aspects of Linux systems. It was introduced to standardize and robustify the process of layering read-only filesystem images on top of the base operating system. This addresses a growing need for immutable system designs, container hosts, and development environments where additional software components need to be added or updated without directly modifying the core OS installation, building upon prior, less standardized methods of system augmentation.

systemd(1), sysext(5), systemd-sysext-generator(8), mkosi(1), overlayfs