Updex

Updex downloads, verifies, installs, updates, rolls back, and removes system extension images. Every Frostyard bootc image ships it as the frostyard-updex package. This guide follows Updex v2.1.3.

Check your version

Show the version, the build commit, the build date, and the builder:

updex --version

Everyday commands

Run the commands that change the system with sudo. Manage system extensions walks through each one on a Frostyard image.

To do this	Run	Steps
List the features	`updex features list`	Find an extension
Enable a feature and download it	`sudo updex features enable <name> --now`	Enable an extension
See what you can update to	`updex features check`	Update
Install the newest versions	`sudo updex features update`	Update
Go back to the previous version	`sudo updex features rollback <name>`	Roll back
Stop updates, or remove an extension	`sudo updex features disable <name>`	Stop updates or remove
Turn off automatic updates	`sudo systemctl mask --now updex-update.timer`	Automatic updates

features check and features list show a RUNNING and a LINKED version. RUNNING is the version merged now. LINKED is the version the next boot merges. When they differ, the output ends with a PENDING REBOOT: line.

A Frostyard image ships each extension as a feature in /usr/lib/sysupdate.<name>.d/, switched off. Limit a features command to one extension with --component=<name>.

Automatic updates

A Frostyard image enables updex-update.timer. It runs updex features update --no-refresh, which downloads, verifies, and links new versions. They take effect at the next boot. To turn automatic updates off on the whole host, and keep them off across image updates, run sudo systemctl mask --now updex-update.timer. To stop one extension, run sudo updex features disable <name>. See Automatic updates for the schedule and the checks.

On a system without the Frostyard image, the package ships the timer switched off. Turn it on with sudo updex daemon enable. Preview the change first with sudo updex --dry-run daemon enable.

Roll back an extension

Link the previous staged version:

sudo updex features rollback <name>

The rollback takes effect at the next boot. Add --now to apply it with a refresh, and --to VERSION to pick the version. Updex then holds the feature until a newer version is published. Delete the hold with sudo updex features rollback --clear <name>. See Roll back for the steps and the rules.

A rollback of the image with bootc rollback is separate. See Roll back the image.

Stop updates or remove

Stop updates and keep the extension merged:

sudo updex features disable <name>

Remove it now, then reboot:

sudo updex features disable <name> --now --force

Updex v2.0.4 and later refuse to remove a merged extension without --force:

Extension docker (version 5+29.9.1-1~debian.13~trixie) is active. Removing requires --force and a reboot to take effect.

When another enabled feature still needs a transfer, disable --now keeps it and prints kept: still active through feature(s) <name>.

Install Updex on another system

On a Frostyard image, Updex is already installed. It updates and rolls back with the image. Follow Install and update an image.

On another system, download the package for your system from the Updex releases page, and check it before you install it. The Updex README lists the artifacts and the checks. The host needs systemd with systemd-sysext, and commands that change the system need root.

Catalogs

Frostyard extensions need no catalog: each image ships them as features. The extension catalog page lists them. An Updex catalog is a third-party source of extensions. Updex ships none, and a Frostyard image configures none.

Add a catalog with a .catalog file in /etc/updex/catalogs.d/, then run updex catalog list and sudo updex catalog add <repo>/<name>. A catalog sysext needs a GPG-signed SHA256SUMS by default. AllowUnsigned=yes in one .catalog file lets that catalog’s own Verify= decide. See Sysext catalogs and Unsigned catalogs for the file format, the checks, and the upgrade notes.

Reference

Features and components: every features command, the refresh warning, the minimum image version, and the operation lock.
Automatic updates: the timer, its schedule, and its status output.
Global flags: --json, --dry-run, --no-refresh, and the others.
JSON output: the result format for scripts.
Rollback: the record, the hold, and the vacuum.
Minimum image version: how a revision that needs a newer image stays unlinked.
Running and linked versions: the RUNNING and LINKED columns.
Auto-update daemon: the units and the daemon commands.

Troubleshooting

Symptom	Check	Fix
`updex features list` shows no features	`updex components`	If no component is listed and no `sysupdate.d/` directory in `/etc`, `/run`, `/usr/local/lib`, or `/usr/lib` has definition files, Updex found none. Check the image version.
`features check` shows `UPDATE=error`	The command output and the network	Check the network and the published manifest. The command exits non-zero. Do not read the row as up to date.
`another updex operation is running`	Another `updex` command or the timer	Wait, then run the command again. Only one Updex operation that changes state runs at a time.
`updex-update.service` shows `failed`	`journalctl -u updex-update.service`	A run that no update source answered exits 0 and logs `no update source is reachable; skipping this run`. A partial failure, a source that answered with an error, or a verification failure fails the unit until the next good run.
A catalog command says no catalogs are configured	`ls /etc/updex/catalogs.d/`	Create a `<name>.catalog` file with `SiteURL`.

See Manage system extensions for the rollback, hold, and image-version rows.

Sources

Reviewed 2026-10-30.