RPM-OSTREE(1)

okay bestie, welcome to the rpm-ostree manual — yes it's long, yes it's iconic, and yes we're gonna get through it together. It's giving hybrid image/package system for host operating system updates, and this is part one. No cap. 🫶

✨ NAME ✨

rpm-ostree — hybrid image/package system for host operating system updates.

🦋 SYNOPSIS 🦋

rpm-ostree {COMMAND} [OPTIONS...]

💖 DESCRIPTION 💖

rpm-ostree is a hybrid image and package system; as the name suggests, it uses OSTree for the image side, and RPM for the package side. It supports composing RPMs server-side into an OSTree commit (like an image), and clients can replicate that bit-for-bit, with fast incremental updates. Also, the hybrid nature comes to the fore with client-side package layering and overrides. 💅

On an rpm-ostree managed system, the traditional yum (if installed) and rpm tools operate in a read-only state; the RPM database is stored in /usr/share/rpm which is underneath a read-only bind mount. 😭

Instead of live package-by-package upgrades, the underlying OSTree layer replicates a complete filesystem tree from a compose server into a new deployment, available on the next reboot. One benefit of this is that there will always be a previous deployment, available for rollback. This also makes it easier to reliably "queue" an update without destabilizing the running system at all. (Currently though there's an experimental livefs command that supports changing the running filesystem). ✨

Note in this "pure replication" model, there is no per-client packaging overhead. Dependency resolution, SELinux labeling, all of the scripts etc. were run on the server side and captured in the OSTree commit. 👑

👑 CLIENT SIDE COMMANDS 👑

cancel

Cancel a pending transaction. Exits successfully and does nothing if no transaction is running. Note that it is fully safe to cancel transactions such as upgrade in general. 🫶

db

Gives information pertaining to rpm data within the file system trees within the ostree commits. There are three sub-commands:

diff

diff to see how the packages are different between the trees in two revs. If no revs are provided, the booted commit is compared to the pending commit. If only a single rev is provided, the booted commit is compared to that rev. The --format=diff option uses - for removed packages, + for added packages, and finally ! for the old version of an updated package, with a following = for the new version. 💅

list

list to see which packages are within the commit(s) (works like yum list). At least one commit must be specified, but more than one or a range will also work.

version

version to see the rpmdb version of the packages within the commit (works like yum version nogroups). At least one commit must be specified, but more than one or a range will also work.

deploy

Takes version, branch, or commit ID as an argument, and creates a new deployment using it, setting it up as the default for the next boot. Unlike most other commands, this will automatically fetch and traverse the origin history to find the target. By design, this has no effect on your running filesystem tree. You must reboot for any changes to take effect. 🌸

This will also queue an update for any layered packages. 🎀

• --unchanged-exit-77 — exit status 77 to indicate that the system is already on the specified commit. This tristate return model is intended to support idempotency-oriented systems automation tools like Ansible.
• --reboot, -r — initiate a reboot after the upgrade is prepared.
• --preview — download enough metadata to inspect the RPM diff, but do not actually create a new deployment.
• --cache-only, -C — perform the operation without trying to download the target tree from the remote nor the latest packages.
• --download-only — only download the target ostree and layered RPMs without actually performing the deployment. This can be used with a subsequent --cache-only invocation to perform the operation completely offline.

install

Takes one or more packages as arguments. The packages are fetched from the enabled repositories in the system repository configuration directories and are overlayed on top of a new deployment. It is also possible to specify a local RPM package that resides on the host. Overlayed packages can later be removed with the uninstall command. 💖

If this is the first time a machine-local change is made, note that this will change rpm-ostree to operate in full hybrid mode. Concretely, rpm-ostree will also start fetching all enabled rpm-md (yum) repositories and use those for package updates every time rpm-ostree upgrade is invoked, as well as during other operations such as rebase. 😳

rpm-ostree remembers these requests even if a later host update includes those packages already: if the packages are subsequently dropped out again, rpm-ostree will go back to layering them. 🔁

Note that by default, specifying a package that is already in the base layer is an error unless the --allow-inactive option is provided. This can be useful when anticipating the removal of a base package. ⚠️

• --idempotent — do nothing if a package request is already present instead of erroring out.
• --reboot, -r — initiate a reboot after the deployment is prepared.
• --dry-run, -n — exit after printing the transaction rather than downloading the packages and creating a new deployment.
• --allow-inactive — allow requests for packages that are already in the base layer.
• --cache-only, -C — perform the operation without trying to download the latest packages.
• --download-only — only download the target layered RPMs without actually performing the deployment. This can be used with a subsequent --cache-only invocation to perform the operation completely offline.
• --apply-live — will perform a subsequent apply-live operation to apply changes to the booted deployment.
• --force-replacefiles — allows one package to overwrite files from another without having to rebuild the whole kernel package.

uninstall

Takes one or more packages as arguments. The packages are removed from the set of packages that are currently overlayed. The remaining packages in the set (if any) are fetched from the enabled repositories in the system repository configuration directories and are overlayed on top of a new deployment. 🦋

• --reboot, -r — initiate a reboot after the deployment is prepared.
• --dry-run, -n — exit after printing the transaction rather than downloading the packages and creating a new deployment.

search

Takes one or more query terms as arguments. The packages are searched within the enabled repositories in the system repository configuration directories. Packages can be overlayed and removed using the install and uninstall commands. 🔍

rebase

Switch to a different base image, while preserving all of the state that upgrade does, such as /etc changes, any layered RPM packages, etc. 🌈

For rebasing to container images, the syntax uses ostree container image references, which combine container image transports (see man skopeo) along with a required integrity scheme. The ostree model encourages container images to be signed, because they must be ultimately trusted. 🔐

• ostree-image-signed:docker://quay.io/exampleos/custom:latest — this will pull from a remote registry, and error out if the container backend does not require signatures.
• ostree-unverified-registry:quay.io/exampleos/custom:latest — this will pull from a remote registry, and no signature will be required. In practice, this is just a shorthand for ostree-unverified-image:docker://quay.io/exampleos/custom:latest.
• ostree-unverified-image:oci:/path/to/dir.oci — Fetch from a local unsigned OCI directory (integrity of this directory may have been verified out of band).

For rebasing to OSTree branches, the full syntax is rebase REMOTENAME:BRANCHNAME. Alternatively, you can use the --branch or --remote options mentioned below. With the argument syntax, specifying just BRANCHNAME will reuse the same remote. You may also omit one of REMOTENAME or BRANCHNAME (keeping the colon). In the former case, the branch refers to a local branch; in the latter case, the same branch will be used on a different remote. 🌀

This will also queue an update for any layered packages. 🎀

• --branch, -b — pick a branch name.
• --remote, -m — pick a remote name.
• --cache-only, -C — perform the rebase without trying to download the target tree from the remote nor the latest packages.
• --download-only — only download the target ostree and layered RPMs without actually performing the deployment. This can be used with a subsequent --cache-only invocation to perform the operation completely offline.

rollback

OSTree manages an ordered list of bootloader entries, called "deployments". The entry at index 0 is the default bootloader entry. Each entry has a separate /etc, but they all share a single /var. You can use the bootloader to choose between entries by pressing Tab to interrupt startup. 👑

This command then changes the default bootloader entry. If the current default is booted, then set the default to the previous entry. Otherwise, make the currently booted tree the default. 💫

• --reboot, -r — initiate a reboot after rollback is prepared.

status

Gives information pertaining to the current deployment in use. Lists the names and refspecs of all possible deployments in order, such that the first deployment in the list is the default upon boot. The deployment marked with * is the current booted deployment, and marking with 'r' indicates the most recent upgrade (the newest deployment version). 📊

• --verbose, -v — display more information, such as package diff, advisories, GPG signature user IDs, and StateRoot names.
• --advisories, -a — expand the advisories listing, if any.
• --booted, -b — only print information about the booted deployment.
• --pending-exit-77 — exit status 77 if a pending deployment is available. This can be useful in scripting.
• --json — output the status information in JSON format for easier scripting.
• --jsonpath=EXPRESSION, -J — filter JSON output by JSONPath expression.

upgrade

Download the latest version of the current tree, and deploy it, setting it up as the default for the next boot. By design, this has no effect on your running filesystem tree. You must reboot for any changes to take effect. 🚀

• --unchanged-exit-77 — bails out with exit status 77 to signal that the system is already up to date. This tristate return model is literally there to support idempotency-oriented systems automation tools like Ansible. 🫶
• --reboot, -r — kicks off a reboot right after the upgrade is prepared. 🔁
• --allow-downgrade — lets you deploy chronologically older trees. (going backwards, we love a time machine moment 💅)
• --preview — downloads only /usr/share/rpm so you can do a package-level diff between the two versions. ✨
• --check — just checks whether an upgrade is available, without downloading it or performing a package-level diff. Heads up though: using this flag will force an update of the RPM metadata from the enabled repos in the system repository configuration directories, if there are any layered packages.
• --cache-only, -C — does the upgrade without trying to download the latest tree from the remote nor the latest packages.
• --download-only — only downloads the target ostree and layered RPMs without actually performing the deployment. Pair it with a later --cache-only invocation to do the whole thing completely offline. 🛜

💅 override 💅

Gives you subcommands for overriding (modifying) the base OSTree layer. Bestie, do these with care — they're normally not intended to be long-lasting. Like, maybe you swap out a base package for its older version to dodge a regression. Overrides are automatically carried over during new deployments. The subcommands are:

• remove — removes base packages.
• replace — replaces base packages. Requires explicitly specifying a set of RPMs to install via HTTP or local file paths. On Fedora systems, it is also supported to pull from the Fedora Koji/Bodhi systems. For example:

rpm-ostree override replace https://objstore.int.example.com/hotfixes/kernel.rpm
rpm-ostree override replace ./podman.rpm
rpm-ostree override replace https://bodhi.fedoraproject.org/updates/FEDORA-2020-XXXXXXX
rpm-ostree override replace https://koji.fedoraproject.org/koji/buildinfo?buildID=XXXXXXX

• reset — resets previous overrides. Currently, the full NEVRA of the target packages must be specified. ✍️

📦 refresh-md 📦

Downloads the latest rpm repo metadata if necessary and generates the cache.

🧠 kargs 🧠

Without options, displays the current default kernel arguments. Modify arguments using the following parameters — and heads up, these create a new deployment with the modified kernel arguments. Previous deployments are never changed. 👑

• --editor — uses an editor to modify the kernel arguments.
• --append — appends a kernel argument. For example, --append=panic=1.
• --append-if-missing — appends a kernel argument if it is not present.
• --delete — deletes a kernel argument. For example, --delete=panic=1.
• --delete-if-present — deletes a kernel argument if it is already present. For example, --delete-if-present=panic=1.
• --replace — replaces an existing kernel argument, and it lets you pass a KEY=VALUE. It also supports "KEY=VALUE=NEWVALUE" to replace the value of an argument only if one value exists for that argument. For example, --replace=panic=1 or --replace=panic=1=0.
• --unchanged-exit-77 — exits with status 77 to indicate that the kernel arguments have not changed.

By default, modifications are applied to the kernel arguments of the default deployment to get the final arguments. Use --deploy-index or --import-proc-cmdline to instead base them off of a specific deployment or the current boot.

🧹 cleanup 🧹

Commands such as upgrade create new deployments, which affect the next boot, and take up additional storage space. In some cases, you may want to undo and clean up these operations. This command supports both removing additional deployments such as the "pending" deployment (the next boot) as well as the default rollback deployment. Use -p/--pending to remove the pending deployment, and -r/--rollback to remove the rollback.

The -b/--base option does not affect finished deployments, but will clean up any transient allocated space that may result from interrupted operations. If you want to free up disk space safely, use this option first.

The -m/--repomd option cleans up cached RPM repodata and any partially downloaded (but not imported) packages.

NOTE: the cleanup will not affect any deployments that have been "pinned" via the ostree admin pin operation.

🔄 reload 🔄

Some configuration and state data such as /etc/ostree/remotes.d changes may not be reflected until a daemon reload is invoked. Use this command to initiate a reload.

🦋 usroverlay 🦋

Mounts a writable overlay filesystem on /usr which is active only for the remainder of the system boot. This is intended for development, testing, and debugging. Changes will not persist across upgrades, or rebooting in general.

One important goal of this is to support traditional rpm -Uvh /path/to/rpms or equivalent where changes are applied live. However, an intended future feature for rpm-ostree will be a variant of rpm-ostree override which also supports applying changes live, for the cases which one wants persistence as well.

This command is equivalent to ostree admin unlock.

🌱 initramfs 🌱

By default, the primary use case mode for rpm-ostree is to replicate an initramfs as part of a base layer. However, some use cases require locally regenerating it to add configuration or drivers. Use rpm-ostree initramfs to inspect the current status.

Use --enable to turn on client side initramfs regeneration. This runs dracut to create the new initramfs. A new deployment will be generated with this new initramfs, and after reboot, further upgrades will continue regenerating. You must reboot for the new initramfs to take effect.

To append additional custom arguments to the initramfs program (currently dracut), use --arg. For example, --arg=-I --arg=/etc/someconfigfile.

The --disable option will disable regeneration. You must reboot for the change to take effect.

Note that for the simpler use case of adding a few files to the initramfs, you can use rpm-ostree initramfs-etc instead. It is more lightweight and does not involve running dracut.

🍓 initramfs-etc 🍓

Adds configuration (/etc) files into the initramfs without regenerating the entire initramfs. This is useful to be able to configure services backing the root block device as well as early-boot services like systemd and journald.

Use --track to start tracking a specific file. Can be specified multiple times. A new deployment will be generated. Use --untrack or --untrack-all to stop tracking files.

When there are tracked files, any future created deployment (e.g. when doing an upgrade) will ensure that they are synced. You can additionally use --force-sync to simply generate a new deployment with the latest versions of tracked files without upgrading.

✨ apply-live ✨

Given a target OSTree commit (defaults to the pending deployment), creates a transient overlayfs filesystem for the booted /usr, and synchronizes the changes from the source to the booted filesystem tree. By default, to ensure safety, only package additions are allowed.

• --reset — resets the filesystem tree to the booted commit.
• --target — may be used to target an arbitrary OSTree commit. This is an advanced feature, exposed mainly for testing.
• --allow-replacement — enables live updates and removals for existing packages.

Example 1. Install postgresql live

$ rpm-ostree install postgresql-server
$ rpm-ostree apply-live
$ systemctl start postgresql  # Some setup required

This is also the same as:

$ rpm-ostree install -A postgresql-server

Currently, this just synchronizes the filesystem; no systemd units are restarted for example.

A major implicit benefit of the overlayfs approach is that if something goes wrong in the middle of a apply-live operation, a system reboot will implicitly remove the overlay, restoring the system to the pristine deployment state. 🫧

🧪 ex 🧪

This command offers access to experimental features; command line stability is not guaranteed. The available subcommands will be listed by invoking rpm-ostree ex.

🫶 update 🫶

Alias for the upgrade command.

---

🌈 SERVER SIDE COMMANDS 🌈

🏗️ compose 🏗️

Entrypoint for tree composition; most typically used on servers to prepare trees for replication by client systems. The tree subcommand processes a treefile, installs packages, and commits the result to an OSTree repository. There are also split commands install, postprocess, and commit.

---

🔑 REPOSITORY CONFIGURATION AND GPG KEYS 🔑

rpm-ostree uses the libdnf shared library, which honors both /etc/yum.repos.d (for user configuration) and /usr/share/dnf5/repos.d (for distribution-provided configuration). Note that rpm-md (yum/dnf) repositories are only checked if client-side package layering is enabled. 👀

However, the behavior for GPG keys is slightly different from a traditional rpm system. Essentially, all GPG keys in /etc/pki/rpm-gpg and /usr/share/pki/rpm-gpg are loaded and trusted. The .repo file should reference the file path in there.

The rpm --import /path/to/key.gpg command will not function today on a live/booted system because rpm tries to write directly to the RPM database.

However, during a container build process, the RPM database is writable and such changes will persist. 🎀

---

👀 SEE ALSO 👀

• rpm-ostreed.conf(5)
• ostree(1)
• rpm(8)

---

and that's the whole page bestie, no cap 💖 signed off as rpm-ostree, filed under RPM-OSTREE(1), and you absolutely ate this read 🌟🫶