Basic use

The basic core capabilities of rpm-ostree bring such concepts as version control and atomic updating to the management and maintenance of the operating system.

View status and version of deployment

The rpm-ostree status command provides the current system state as well as deployed operating system images. It displays the currently active deployment, its commit ID, and any pending upgrades.

Note

As with git status you can use the rpm-ostree status to better understand the status of your system and to learn of any pending changes.

To view basic status:

rpm-ostree status

Example system response:

State: idle
Deployments:
- mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    Commit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91

To view detailed status:

rpm-ostree status -v

Example system response:

State: idle
AutomaticUpdates: disabled
Deployments:
- mkex:mkex/8/x86_64/mcr/23.0-devel (index: 0)
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    Commit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
      ├─ appstream (2023-04-26T15:44:31Z)
      ├─ baseos (2023-04-26T15:44:36Z)
      └─ docker-ee-stable-23.0 (2023-04-04T16:02:39Z)
     Staged: no
     StateRoot: mkex

To display the status and version of the booted deployment:

rpm-ostree status --booted --verbose

Perform system upgrades

Use the rpm-ostree upgrade command to update the system to the latest available operating system image.

Note

As with git pull in a Git repository, rpm-ostree upgrade pulls in the latest packages, dependencies, and configuration changes to update your system.

**To perform system upgrade:

rpm-ostree upgrade

Example system response:

Checking out tree abcdefg...done
Enabled rpm-md repositories: fedora-34
Updating metadata for 'fedora-34'...done
Delta RPMs reduced 50% of update size
Upgraded:
  package-1.2.3-4.fc34.x86_64
  Package-foo-2.0.1-1.fc34.x86_64

Revert to previously booted tree

You can revert the system to a previous known state with the rpm-ostree rollback command, specifying a specific deployment. This command undoes any system changes made following the specified deployment, effectively rolling back the entire system to a previous commit.

Note

The rpm-ostree rollback operation is similar to using git checkout in a Git repository to revert to a previous commit.

To revert to previously booted tree:

Note

For example purposes, the target deployment shown is the original deployment without the additional tmux package installed.

  1. Rollback the current deployment to the target deployment.

    rpm-ostree rollback

    Example system response:

    Moving '0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91.1' to be
first deployment

Transaction complete; bootconfig swap: no; bootversion: boot.1.0, deployment count change: 0
Removed:
  libevent-2.1.8-5.el8.x86_64
  tmux-2.7-1.el8.x86_64
Changes queued for next boot. Run "systemctl reboot" to start a reboot

  2. Reboot the system to use the target deployment:

    systemctl reboot

  3. Switch the deployment and initiate a system reboot once the rollback operation is complete:

    rpm-ostree rollback -r

    Example system response:

    Moving '8b6ffd83adcf6c6a37941cade3a8ffea0a80d3d311e5ee8b7f0a074be6143ca9.0' to be
first deployment
Transaction complete; bootconfig swap: no; bootversion: boot.1.1,
deployment count change: 0

Overlay additional packages

You can use the rpm-ostree install command to install additional packages on top of the base operating system image. The command adds the packages you specify to the current deployment, thus enabling you to extend your system functionality.

To overlay additional packages:

  1. Install the tmux package:

    rpm-ostree install tmux

    Example system response:

    Checking out tree 0572d28... done
Enabled rpm-md repositories: appstream baseos extras
Updating metadata for 'appstream'... done
Updating metadata for 'baseos'... done
...<OUTPUT TRUNCATED>...
Staging deployment... done
Added:
  libevent-2.1.8-5.el8.x86_64
  tmux-2.7-1.el8.x86_64
Changes queued for next boot. Run "systemctl reboot" to start a reboot

  2. Once the package is installed, verify the status of the current deployment:

    rpm-ostree status

    Example system response:

    State: idle
Deployments:
- mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    BaseCommit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
      Diff: 2 added
    LayeredPackages: tmux
- mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    Commit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
```

    The system response shows that the current deployment has been modified and there are now two deployments in total.

  3. Reboot the system into the deployment that has the newly installed tmux package.

  4. Verify the status of the running deployed image following the system reboot:

    rpm-ostree status

    Example system response:

    State: idle
Deployments:
- mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    BaseCommit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
    LayeredPackages: tmux
- mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    Commit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91

Query the RPM database

Use the rpm-ostree db command to query and manipulate the package information stored in the database of a rpm-ostree system.

To show the package changes between two commits:

rpm-ostree db diff

Example system response:

ostree diff commit from: rollback deployment
(0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91)

ostree diff commit to: booted deployment
(8b6ffd83adcf6c6a37941cade3a8ffea0a80d3d311e5ee8b7f0a074be6143ca9)
Added:
  libevent-2.1.8-5.el8.x86_64
  tmux-2.7-1.el8.x86_64

To list packages within commits:

rpm-ostree db list

Clear unused deployments

Use the rpm-ostree cleanup command to remove old or unused deployments for the purpose of freeing up disk space. Following invoication, a configurable number of recent deployments is retained and the rest are deleted.

Note

The rpm-ostree cleanup operatåion is similar to using git gc in a Git repository, in that it serves to optimize disk usage and keeps the system clean.

To clear temporary files and leave deployments unchanged:

rpm-ostree cleanup --base

To remove a pending deployment:

rpm-ostree cleanup --pending

Example system response:

Transaction complete; bootconfig swap: yes; bootversion: boot.0.1, deployment count change:
-1

Query or modify kernel arguments

Use the rpm-ostree kargs command to manage kernel arguments (kargs) for the system. With this command, you can modify the kernel command-line parameters for the next reboot, as well as customize the kernel parameters for specific deployments.

To modify kernel arguments:

  1. View the kernel arguments for the currently booted deployment:

    rpm-ostree kargs

    Example system response:

    rw crashkernel=auto resume=/dev/mapper/rlo-swap rd.lvm.lv=rlo/root rd.lvm.lv=rlo/swap root=/dev/mapper/rlo-root \
ostree=/ostree/boot.1/mkex/6f043f707b4bdd83304c977d39ead06da68e85e7786e42e7da673e53f3a7a2ca/0

  2. Add a new custom argument to the deployment, for example foo=bar:

    rpm-ostree kargs --append="foo=bar"

    Example system response:

    Checking out tree 0572d28... done
Resolving dependencies... done
Checking out packages... done
Running pre scripts... done
Running post scripts... done
Running posttrans scripts... done
Writing rpmdb... done
Writing OSTree commit... done
Staging deployment... done
Freed: 67.3 MB (pkgcache branches: 0)
Changes queued for next boot. Run "systemctl reboot" to start a reboot

  3. Review the pending change prior to rebooting the system:

    rpm-ostree kargs

    Example system response:

    rw crashkernel=auto resume=/dev/mapper/rlo-swap rd.lvm.lv=rlo/root rd.lvm.lv=rlo/swap \
root=/dev/mapper/rlo-root ostree=/ostree/boot.1/mkex/6f043f707b4bdd83304c977d39ead06da68e85e7786e42e7da673e53f3a7a2ca/0 \
foo=bar

  4. Reboot the system to enable it to begin using the deployment with the custom kernel argument:

    systemctl reboot

  5. Verify that the changes are in effect on the booted deployment:

    cat /proc/cmdline

    Example system response:

    BOOT_IMAGE=(hd0,msdos1)/ostree/mkex-6f043f707b4bdd83304c977d39ead06da68e85e7786e42e7da673e53f3a7a2ca/vmlinuz-4.18.0-425.19.2.el8_7.x86_64 \
rw crashkernel=auto resume=/dev/mapper/rlo-swap rd.lvm.lv=rlo/root rd.lvm.lv=rlo/swap root=/dev/mapper/rlo-root \
ostree=/ostree/boot.0/mkex/6f043f707b4bdd83304c977d39ead06da68e85e7786e42e7da673e53f3a7a2ca/0 \
foo=bar

To delete the custom kernel argument that was appended to the booted deployment and force the system to automatically reboot after the command completes:

rpm-ostree kargs --delete="foo=bar" --reboot

Example system response:

Checking out tree 0572d28... done
Resolving dependencies... done
...<OUTPUT TRUNCATED>...
Writing OSTree commit... done
Staging deployment... done
Freed: 67.3 MB (pkgcache branches: 0)

Switch to a different tree

Use the rpm-ostree rebase command to update the base operating system image of the system.

Note

The rpm-ostree rebase operation is similar to using git rebase in a Git repository, in that it pulls in a newer version of the base operating system image and updates the system accordingly.

To update the base operating system image:

Note

For example purposes, mkex:mkex/8/x86_64/mcr/20.10-devel is the different base operating system image maintained in the repository.

  1. Rebase the current deployment on a different base operating system image maintained in this repository:

    rpm-ostree rebase mkex:mkex/8/x86_64/mcr/20.10-devel

    Example system response:

    Writing objects: 1
Writing objects: 1... done
Checking out tree 2c92ce7... done
...<OUTPUT TRUNCATED>...
Downgraded:
  docker-ee 3:23.0.3-3.el8 -> 3:20.10.16-3.el8
  docker-ee-cli 1:23.0.3-3.el8 -> 1:20.10.16-3.el8
  docker-ee-rootless-extras 23.0.3-3.el8 -> 20.10.16-3.el8
Changes queued for next boot. Run "systemctl reboot" to start a reboot

    Note

    You can use the ostree remote refs mkex command to list the remote refs that are available to your system.

  2. View the status of deployments on the system:

    rpm-ostree status

    Example system response:

    State: idle
Deployments:
- mkex:mkex/8/x86_64/mcr/20.10-devel
  Version: MKEx/8/MCR/20.10-devel 2023.05.0 (2023-05-01T20:59:26Z)
  BaseCommit: 2c92ce7c0c06af56dfba57f24529ffa94b59cb5103126024126fa5fb72966b87
    Diff: 3 downgraded
  LayeredPackages: tmux
- mkex:mkex/8/x86_64/mcr/23.0-devel
  Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
  BaseCommit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
  LayeredPackages: tmux
...<OUTPUT TRUNCATED>...

  3. Reboot the system to begin using the new base image:

    systemctl reboot

  4. Verify the rebase operation by checking the status of the newly booted deployment:

    rpm-ostree status --booted

    Example system response:

    State: idle
BootedDeployment:
- mkex:mkex/8/x86_64/mcr/20.10-devel
  Version: MKEx/8/MCR/20.10-devel 2023.05.0 (2023-05-01T20:59:26Z)
  BaseCommit: 2c92ce7c0c06af56dfba57f24529ffa94b59cb5103126024126fa5fb72966b87
  LayeredPackages: tmux

Using experimental commands

Use the rpm-ostree ex command to execute experimental commands in the context of a specific deployment. Invocation of this command executes a command that uses the files and environment of the specified deployment.

Example experimental command: To view the rpm-ostree history of the system:

rpm-ostree ex history

Example system response:

NOTICE: Experimental commands are subject to change.
BootTimestamp: 2023-06-01T03:40:34Z (19min ago)
└─ BootCount: 2; first booted on 2023-06-01T03:30:12Z (29min ago)
CreateTimestamp: 2023-05-31T22:56:15Z (5h 3min ago)
CreateCommand: install tmux
  mkex:mkex/8/x86_64/mcr/23.0-devel
    Version: MKEx/8/MCR/23.0-devel 2023.05.0 (2023-05-01T21:01:22Z)
    BaseCommit: 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91
    LayeredPackages: tmux
...<OUTPUT TRUNCATED>...

Deploy a specific commit

Use the rpm-ostree deploy` command to trigger the deployment of a specific operating image on the system.

Note

Similar to checking out to a specific commit in Git, the rpm-ostree deploy` command enables you to switch to a different version of the operating system by specifying the desired deployment through its commit ID.

To deploy the image with the commit ID:

Note

For example purposes, 0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91 serves as the commit ID.

rpm-ostree deploy \
0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91

Example system response:

Validating checksum
'0572d2897c74afb1d123461728e17e7204cb1f0a55fb7f4c13c1fda87de50d91'
1 metadata, 0 content objects fetched; 153 B transferred in 0 seconds; 0 bytes content written
2 metadata, 0 content objects fetched; 306 B transferred in 0 seconds; 0 bytes content written
Checking out tree 0572d28... done
...<OUTPUT TRUNCATED>...
Writing rpmdb... done
Writing OSTree commit... done
Staging deployment... done
Run "systemctl reboot" to start a reboot

Remove overlayed packages

Use the rpm-ostree uninstall command to remove installed packages from the system. This command removes the specified packages from the current deployment, similar to uninstalling packages from a Git repository.

Uninstall the tmux package previously added to the current deployment:

rpm-ostree uninstall tmux

Example system response:

Staging deployment... done
Removed:
  libevent-2.1.8-5.el8.x86_64
  tmux-2.7-1.el8.x86_64
Changes queued for next boot. Run "systemctl reboot" to start a reboot