rpm-ostree man page

rpm-ostree — Operating system upgrade and software management tool

Synopsis

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

Description

rpm-ostree (also called "atomic" if configured) is a system software management tool that combines features of both traditional RPM and OSTree. It has support for both server-side composing of trees, as well as client-side upgrading and management of deployments.

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.

Note in this "pure replication" model, at present there is no dependency resolution on the client machines, nor any ability to add or remove packages. You may however use /usr/local/bin, or an application mechanism such as docker(1).

Commands

compose

Entrypoint for tree composition; most typically used on servers to prepare trees for replication by client systems. Currently has two subcommands, tree and sign.

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

In addition to exit status 0 for success and 1 for error, this command also uses 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.

install (pkg-add)

Takes one or more packages as arguments. The packages are fetched from the enabled repositories in /etc/yum.repos.d/ 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.

uninstall (pkg-remove)

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 /etc/yum.repos.d/ 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.

rebase

Switch to a different remote, or a different tree, while preserving local state in /var and configuration in /etc. This is an extension of upgrade which switches to a newer version of the current tree.

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

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.

In addition to exit status 0 for success and 1 for error, this command also uses exit status 77 to indicate that no upgrade is available.

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

See Also

ostree(1), rpm(8)

Referenced By

rpm-ostree-toolbox(1).

rpm-ostree rpm-ostree