rpm-ostree - Man Page

• Show rpm-ostree deployments in the order they will appear in the bootloader: rpm-ostree status
• Show packages which are outdated and can be updated: rpm-ostree upgrade --preview
• Prepare a new ostree deployment with upgraded packages and reboot into it: rpm-ostree upgrade [-r|--reboot]
• Reboot into the previous ostree deployment: rpm-ostree rollback [-r|--reboot]
• Install a package into a new ostree deployment and reboot into it: rpm-ostree install package [-r|--reboot]

tldr.sh

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

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​. Additionally, 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​.

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 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 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 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 to 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 or -r to 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 or -C to perform the operation without trying to download the target tree from the remote nor the latest packages​.

--download-only to 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 to do nothing if a package request is already present instead of erroring out​.

--reboot or -r to initiate a reboot after the deployment is prepared​.

--dry-run or -n to exit after printing the transaction rather than downloading the packages and creating a new deployment​.

--allow-inactive to allow requests for packages that are already in the base layer​.

--cache-only or -C to perform the operation without trying to download the latest packages​.

--download-only to 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 or -r to initiate a reboot after the deployment is prepared​.

--dry-run or -n to 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 or -b to pick a branch name​.

--remote or -m to pick a remote name​.

--cache-only or -C to perform the rebase without trying to download the target tree from the remote nor the latest packages​.

--download-only to 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 or -r to 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 or -v to display more information, such as package diff, advisories, GPG signature user IDs, and StateRoot names​.

--advisories or -a to expand the advisories listing, if any​.

--booted or -b to only print information about the booted deployment​.

--pending-exit-77 to exit status 77 if a pending deployment is available​. This can be useful in scripting​.

--json to output the status information in JSON format for easier scripting​.

--jsonpath=EXPRESSION or -J to 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 to exit status 77 to indicate that the system is already up to date​. This tristate return model is intended to support idempotency-oriented systems automation tools like Ansible​.

--reboot or -r to initiate a reboot after upgrade is prepared​.

--allow-downgrade to permit deployment of chronologically older trees​.

--preview to download only /usr/share/rpm in order to do a package-level diff between the two versions​.

--check to just check if an upgrade is available, without downloading it or performing a package-level diff​. 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 or -C to perform the upgrade without trying to download the latest tree from the remote nor the latest packages​.

--download-only to 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​.

override

Provides subcommands for overriding (modifying) the base OSTree layer​. Such modifications should be done with care and are normally not intended to be long-lasting​. For example, one might replace a base package with its older version to avoid a regression​. Overrides are automatically carried over during new deployments​. The subcommands are:

remove to remove base packages​.

replace to replace 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 or rpm-ostree override replace https://koji​.fedoraproject​.org/koji/buildinfo?buildID=XXXXXXX

reset to reset previous overrides​. Currently, the full NEVRA of the target packages must be specified​.

refresh-md

Download the latest rpm repo metadata if necessary and generate the cache​.

kargs

Without options, display current default kernel arguments​. Modify arguments using the following parameters which will create a new deployment with the modified kernel arguments​. Previous deployments are never changed​.

--editor to use an editor to modify the kernel arguments​.

--append to append a kernel argument​. For example, --append=panic=1​.

--append-if-missing to append a kernel argument if it is not present​.

--delete to delete a kernel argument​. For example, --delete=panic=1​.

--delete-if-present to delete a kernel argument if it is already present​. For example, --delete-if-present=panic=1​.

--replace to replace an existing kernel argument, it allows you to pass a KEY=VALUE​. Also, it 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 to exit 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

Mount 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

Add 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), create a transient overlayfs filesystem for the booted /usr, and synchronize the changes from the source to the booted filesystem tree​. By default, to ensure safety, only package additions are allowed​.

--reset to reset 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​.

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​.

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​.

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

rpm-ostree-countme.service(8), rpm-ostreed-automatic.service(8), rpm-ostreed.conf(5).