Skip to content

Building OSTree-based images

OSTree is a Git-like tool that maintains and updates immutable system images. When you manage images with OSTree, each image is tracked as a branch in a repository with a history of commits. OSTree branches are also called refs. The active OS that runs on a device is the live system. The live system is deployed from a specific commit from a specific branch.

When you update an image, OSTree pulls the latest commit from the remote branch and checks it out locally next to the commit deployed in the live system. The system is then restarted and it uses the new commit as the active OS. The prior deployment is still available and you can manually boot into it or perform a rollback to reactivate the older commit. You can also remove older OS versions to avoid unnecessary disk use.

AutoSD manifests support the ostree image type. Building images based on the ostree image type happens in two stages:

  • An OSTree commit is created with all of the content required for the image.
  • A bootable system is created by pulling and deploying the new OSTree commit.

Prerequisites

Procedure

  1. Build the image and include the --ostree-repo option to use OSTree to update an existing OSTree repo or create a new one. The --ostree-repo option grants access to the intermediate OSTree commit:

    $ automotive-image-builder build --target qemu --mode image --ostree-repo <ostree-repo-name> \
    --export qcow2  <path>/<my-manifest>.aib.yml <my-image>.qcow2

    The example command builds the <image-name>.qcow2 image and extracts the OSTree commits generated during the build. It also pulls the commits into the local ostree-repo-name directory. If a pre-existing ref exists in the repo, the commit ID of the existing ref becomes the parent commit of the new image to create an unbroken history of commits for your OSTree images. Also notice that the version equals 1; in a later procedure, you will increment this value to distinguish one build from another.

  2. List the OSTree repo reference name:

    $ ostree refs --repo=<ostree-repo-name>

    The command output produces a reference name that includes the distro, architecture, target, and manifest name used to build the image, for example:

    $ ostree refs --repo=my-repo
autosd9-sig/x86_64/qemu-ostree_upgrade

  3. Use the reference name to inspect the OSTree repo commit history:

    $ ostree log --repo=<ostree-repo-name> <distro>/<architecture>/<target>-<manifest-name>

    For example:

    $ ostree log --repo=my-repo autosd9-sig/x86_64/qemu-ostree_upgrade
commit 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
ContentChecksum:  422d0de2ea20a009a754b699d3ca65ea7db1881bfa7c6c254258b84fa3c9ce9b
Date:  2025-05-06 18:11:26 +0000
Version: 1.0
(no subject)

  4. Run the image:

    $ automotive-image-runner <my-image>.qcow2

  5. After the image boots, log in as root using the password password.

  6. From the image console, verify the status of the OSTree repo:

    # rpm-ostree status
State: idle
Deployments:
● auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade
                   Version: 1 (2025-05-06T18:11:26Z)
                    Commit: 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae

    In this example, there is only one ref installed, autosd9-sig/x86_64/qemu-ostree_upgrade Version 1. The dot symbol (●) indicates the active commit. Notice that the remote from which the ref was installed is auto-sig. For more information about the remote, run the following command:

    # ostree remote list -u
auto-sig  http://10.0.2.100/

    The default URL is http://10.0.2.100/. You can override the URL by changing the ostree_repo_url, but keeping the default URL is beneficial. The default URL is significant, because it matches the URL used by the automotive-image-runner --publish-dir command. Keeping the default URL enables the VM that contains your image to receive updates from the auto-sig remote.

© Red Hat