Skip to content

Making offline updates

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:

    YAML title="Updated Automotive Image Builder manifest" --8<-- "demos/ostree_upgrade/ostree_upgrade_v2.aib.yml:4:4"

  2. Build the updated version of your image:

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

  3. Create a generate-deltas script that contains the following instructions (or copy the tool from the sample-images repository):

    ```bash

    !/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:

    console $ 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:

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

    For example:

    console $ 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:

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

    For example:

    ```console $ 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:

    console $ 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:

    ```console

    curl --remote-name http://10.0.2.100/updates/-----.update

    ```

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

    ```console

    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:

    ```console

    ostree static-delta apply-offline -----.update

    rpm-ostree rebase

    ```

    For example:

    ```console

    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:

    ```console

    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:

    ```console

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