1. Manuals
  2. Tumbleweed
  3. sysextmgr
  4. sysextmgrcli(1)

Scroll to navigation

SYSEXTMGRCLI(1) User Commands SYSEXTMGRCLI(1)

NAME

sysextmgrcli - command line utility to manage systemd-sysext images

SYNOPSIS

sysextmgrcli {COMMAND} [OPTIONS...]

DESCRIPTION

sysextmgrcli is the command-line client for managing systemd-sysext images on openSUSE MicroOS. It delegates most tasks to the sysextmgrd(8) daemon via varlink. This architecture allows unprivileged users to list existing system extension images without needing root permissions.

Image downloads and verifications are handled automatically using systemd-pull.

COMMANDS

create-json

Create a JSON file from a release file.

-n, --name

Name of the image.

-i, --input

Release file in KEY=VALUE format.

-o, --output

Output file in JSON format.

check

Check if updates are available and all installed images are compatible with the installed OS.

-p, --prefix

Prefix to a different root directory.

-q, --quiet

Don't print the list of images, report status via return values.

cleanup

Check all snapshots for referenced images and remove no longer used ones.

-q, --quiet

Return 0 if images were removed, otherwise ENODATA.

dump-json FILE...

Dump the content of the specified JSON files.

dump-manifest FILE...

Dump the content of the specified manifest files.

install NAME...

Install the newest compatible sysext image.

-u, --url URL

Remote directory URL containing the sysext images.

list

List all images and report whether they are compatible.

-u, --url URL

Remote directory URL with sysext images.

-v, --verbose

Enable verbose output.

merge-json FILE...

Merge several JSON files into one JSON array.

-o, --output FILE

Output file in JSON format.

update

Check if newer images are available and update them.

-p, --prefix

Prefix to a different root directory.

-q, --quiet

Return 0 if updates exist, else ENODATA.

-u, --url URL

Remote directory URL with sysext images.

GENERIC OPTIONS

-h, --help

Display a help message and exit.

-v, --version

Print the version number and exit.

ARCHITECTURE AND DIRECTORY STRUCTURE

The architecture focuses on the effective use of Btrfs snapshots:

/var/lib/sysext-store

Stores the actual sysext images. Being located in /var, these images are shared across all snapshots, saving disk space.

/etc/extensions

Contains symlinks pointing to the images in the store. Because it resides in /etc, every snapshot only sees the extensions relevant to it. Performing a system rollback gracefully rolls back the active sysext images as well.

Importing Images:

When a full image name is provided, the specific image is downloaded and symlinked immediately. If only a base name is provided, the tool downloads the SHA256SUM file, verifies the OS compatibility via the JSON manifest, downloads the image, and creates the symlink in the running snapshot.

Updating Images:

During an update, local files in /var/lib/sysext-store are checked against remote manifests. If a new version compatible with the new snapshot's OS version is found, it is downloaded and symlinked inside the new snapshot.

Enabling/Disabling:

sysextmgrcli does not directly activate images. Activation is managed by systemd-sysext.

•Manual merge: systemd-sysext merge

•Manual unmerge: systemd-sysext unmerge

•At boot: systemctl enable systemd-sysext.service

DEPENDENCIES AND MANIFESTS

To prevent large files from being downloaded just to resolve dependencies, images should be accompanied by a lightweight <image>.manifest file (such as those generated by mkosi). This contains the necessary OS configuration and constraints.

SEE ALSO

sysextmgr.conf(5), sysextmgrd(8), systemd-sysext(8)

03/10/2026 sysextmgr 0.2.1