Skip to content

Creating static deltas

OSTree downloads updates from a remote OSTree repository. OSTree repositories contain all the files that compose some version of an image. When you create and manage images with OSTree, you can also create static deltas. Static deltas are a collection of updates generated between two OSTree commits. Static deltas optimize updates by fetching only objects from the new commit that do not already exist in the image. If a static delta is available for a specific transaction, OSTree will automatically use it.

Prerequisites

Procedure

  1. Run ostree log to get the commit IDs of the available versions:

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

    For example:

    $ ostree log --repo=my-repo autosd9-sig/x86_64/qemu-ostree_upgrade
commit 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee
Parent:  8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
ContentChecksum:  8c82a9801802d726e546bf9475f719c3760e660f8165bd034876e04aa84092d1
Date:  2025-05-06 18:28:23 +0000
Version: 1.1
(no subject)

commit 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
ContentChecksum:  422d0de2ea20a009a754b699d3ca65ea7db1881bfa7c6c254258b84fa3c9ce9b
Date:  2025-05-06 18:11:26 +0000
Version: 1.0

    There are two commits. Version 1.1, the most recent commit, has the ID 5c94cb5ee2. Its parent commit, 8be6158fa1, matches the commit ID for Version 1.0.

  2. Generate a static delta using the following syntax:

    $ sudo ostree static-delta generate --repo=<ostree-repo-name> --from=REV --to=REV

    The REV values are the commit IDs of the versions between which you want to create a static delta. The example, which uses partial commit IDs, creates a static delta from Version 1.0 to Version 1.1:

    $ sudo ostree static-delta generate --repo=my-repo --from=8be6158fa1 --to=5c94cb5ee2

Making offline updates

An offline update is an update that you manually apply to your system using a locally stored image. An offline update using a static delta is an efficient way to update your system because a static delta represents only the objects from a new commit that do not exist in the current image. The result is a smaller, simpler update. Offline updates are useful in scenarios where bandwidth is limited or there is no network connection to an OSTree repository.

Procedure

  1. Update your image by changing the version:

    automotive image builder manifest
    version: '2.0'

  2. Build the updated version of your image:

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

  3. Create a generate-deltas script that contains these instructions:

    #!/usr/bin/bash

if [ "$#" -lt 2 ]; then
    echo "Usage generate-deltas REPODIR DESTDIR [REFS..]"
    exit 1
fi

REPO=$1
DIR=$2

shift 2

if [ "$#" -gt 0 ]; then
    REFS="$@"
else
    REFS=$(ostree --repo=$REPO refs)
fi

mkdir -p $DIR

NUM_DELTAS=3
for REF in $REFS; do
    REF_AS_FILE=$(echo $REF | sed "s%/%-%g" )
    HEAD=$(ostree --repo=$REPO rev-parse $REF)

    # Generate full update for HEAD:
    echo Generating non-delta update for $REF commit $HEAD
    ostree static-delta generate --repo=$REPO  --inline --min-fallback-size=0 --empty --filename=$DIR/$REF_AS_FILE-$HEAD.update $HEAD

    # Generate deltas to HEAD from up to the last 3 parents
    PARENT=$HEAD
    for i in seq $NUM_DELTAS; do
        if ! PARENT=$(ostree --repo=$REPO rev-parse $PARENT^ 2>/dev/null); then
            break;
        fi
        echo Generating delta update for $REF commit $HEAD from commit $PARENT
        ostree static-delta generate --repo=$REPO  --inline --min-fallback-size=0 --from=$PARENT --filename=$DIR/$REF_AS_FILE-$PARENT-$HEAD.update $HEAD
    done

done

  4. Run the generate-deltas script:

    $ chmod +x generate-deltas.sh
$ sudo ./generate-deltas.sh <ostree-repo-name>/ <ostree-repo-name>/updates/

    When you run the generate-deltas script against an OSTree repository, it generates update files that contain per-commit deltas for each of the last three parent commits and a larger update file that contains the full delta for all changes applied to the image between the latest HEAD commit and up to three prior parent commits.

  5. Display the disk usage of the files in the updates directory:

    $ du -h  <ostree-repo-name>/updates/*

    For example:

    $ du -h my-repo/updates/*
7.5M my-repo/updates/autosd9-sig-x86_64-qemu-ostree_upgrade-5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee-d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9.update
16M my-repo/updates/autosd9-sig-x86_64-qemu-ostree_upgrade-8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae-d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9.update
256M my-repo/updates/autosd9-sig-x86_64-qemu-ostree_upgrade-d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9.update

    Notice the size of the three delta update files:

    • The 7.5M delta file contains the deltas to update a system running commit 5c94cb5ee2 (Version 1.1) to commit d21453daf0 (Version 2.0).
    • The 16M delta file contains the deltas to update a system running commit 8be6158fa1 (Version 1.0) to commit d21453daf0 (Version 2.0).
    • The 256M delta file is the largest update file and contains the delta between the first and last commits in the repository.

  6. Run ostree log to get the commit IDs of the available versions:

    $ 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 d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9
Parent:  5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee
ContentChecksum:  f91536afb38ffb320caffa72d1f5d439a25b6d3d0781a8d395b6032b1bfe9414
Date:  2025-05-06 19:04:44 +0000
Version: 2.0
(no subject)

commit 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee
Parent:  8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
ContentChecksum:  8c82a9801802d726e546bf9475f719c3760e660f8165bd034876e04aa84092d1
Date:  2025-05-06 18:28:23 +0000
Version: 1.1
(no subject)

commit 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae
ContentChecksum:  422d0de2ea20a009a754b699d3ca65ea7db1881bfa7c6c254258b84fa3c9ce9b
Date:  2025-05-06 18:11:26 +0000
Version: 1.0
(no subject)

  7. Run the image:

    $ automotive-image-runner --publish-dir=<ostree-repo-name> <image-name>.qcow2

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

  9. Download the delta update:

    # curl --remote-name http://10.0.2.100/updates/<deployment-name>-<hash-from>-<hash-to>.update

    The example command downloads the delta update from Version 1.0 to Version 2.0:

    # curl --remote-name http://10.0.2.100/updates/autosd9-sig-x86_64-qemu-ostree_upgrade-8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae-d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9.update

  10. Install the delta update by using ostree static-delta apply-offline:

    # ostree static-delta apply-offline <distro>-<architecture>-<target>-<manifest-name>-f56f6573b5f5d2a1bf990c9030ee8fefcdd35c6fd5db106e4e7236806483e6d2-410b97c4ca59df58f33fce3d1e389a3eb8f7c1367c1afacb7c8842576d8daeed.update
# rpm-ostree rebase 410b97c4ca59df58f33fce3d1e389a3eb8f7c1367c1afacb7c8842576d8daeed

    For example:

    # ostree static-delta apply-offline autosd9-sig-x86_64-qemu-ostree_upgrade-8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae-d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9.update

# rpm-ostree rebase d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9
Staging deployment... done
Changes queued for next boot. Run "systemctl reboot" to start a reboot
# rpm-ostree status
State: idle
Deployments:
  auto-sig:d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9
              Version: 2.0 (2025-05-06T19:04:44Z)
               Commit: d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9

● auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade
              Version: 1.1 (2025-05-06T18:28:23Z)
               Commit: 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee

  auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade
              Version: 1.0 (2025-05-06T18:11:26Z)
               Commit: 8be6158fa1862950d8751663728bdb82d1c7d537770b1f0fc9b8eba4939480ae

    The rpm-ostree status command is optional, but it is used here to show that the system has multiple versions of the image. The rpm-ostree rebase command configures the system to reboot to the next version (Version 2.0, commit d21453daf0). If you unintentionally install the wrong delta, you will receive an error similar to Commit XYZ, which is the delta source, is not in repository. If this occurs, repeat this step using the correct delta.

  11. Reboot the VM:

    $ systemctl reboot

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

  13. From the VM, run rpm-ostree status to confirm that you successfully installed the update:

    # rpm-ostree status
State: idle
Deployments:
● auto-sig:d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9
              Version: 2.0 (2025-05-06T19:04:44Z)
               Commit: d21453daf04545c8346d83d3edf48696a7d7689ddbf39e2f5c096d1d671843b9

  auto-sig:autosd9-sig/x86_64/qemu-ostree_upgrade
              Version: 1.1 (2025-05-06T18:28:23Z)
               Commit: 5c94cb5ee2409b0219e8d3cf3bda1b56dafb9dcbc0846da97309491524e4fcee

© Red Hat