Commit 5868df82 authored by Emanuele Aina's avatar Emanuele Aina

system-updates-and-rollback: Cover online OTA updates in more detail

Expand the section about web-based updates now that OTA is implemented and
enabled since the v2019pre release.

This should clarify:
* how OSTree over-the-air updates are provided
* what kind of hosting infrastructure is needed
* the changes in the updater agent
* what kind of verification is done on updates
* how updates are triggered
Signed-off-by: Emanuele Aina's avatarEmanuele Aina <>
parent 46071036
......@@ -347,30 +347,64 @@ the update process leaves the current system state unchanged and the update
process can be resumed re-using all the data that has already been already validated
and included in the local repository.
### Web based updates
### Online web-based OTA updates
Updates can be downloaded by devices from a web-based service offering
static files with no knowledge of OSTree while still retaining efficient
bandwidth usage.
OSTree supports bandwidth-efficient retrieval of updates over the network.
The basic workflow involves the actors below:
* the image building pipelines pushes commits to an OSTree repository on
each build;
* a standard web server provides access over HTTPS to the OSTree repository
handling it as a plain hierarchy of static files, with no special knowledge
of OSTree;
* the client devices poll the web server and retrieve updates when they get
The following diagram shows how the data flows across services when using the
web based OSTree upgrade mechanism.
Thanks to its repository format, OSTree client devices can efficiently query
the repository status and retrieve only the changed contents without any
OSTree-specific support in the web server, with the repository files being
served as plain static files.
This means that any web hosting provider can be used without any loss
of efficiency.
By only requiring static files, the web service can easily take advantage of
CDN services to offer a cost efficient solution to get the data out to the
devices in a way that is globally scalable.
The authentication to the web service can be done via HTTP Basic
authentication, SSL/TLS client certificates, or any cookie-based mechanism that
is most suitable for the chosen web service, as OSTree does not impose any
constraint over plain HTTPS. OSTree separatedly checks the chain of trust
linking the downloaded updates to the keys trusted by the system update manager.
By only requiring static files, the web service can easily take advantage of
CDN services to offer a cost efficient solution to get the data out to the
devices in a way that is globally scalable.
See also the [Controlling access to the updates repository] and
[Verified updates] sections in this regard.
Monitoring and management of devices can be built using the same HTTPS access as
used by OSTree or using completely separated mechanisms, enabling the integration
of OSTree updates into existing setups.
The following diagram shows how the data flows across services when using this
web based OSTree upgrade mechanism.
For instance, integration with rollout management suites like [Eclipse
hawkBit]( can happen by disabling the polling
in the OSTree updater and letting the management suite tell OSTree which commit
to download and from where through a dedicated agent running on the devices.
This has the advantage that the rollout management suite would be in complete
control of which updates should be applied to which devices, implementing
any kind of policies like progressive staged rollouts with monitoring from the
backend with minimal integration.
Only the retrival and application of the actual update data on the device would
be offloaded to the OSTree-based update system, preserving its network and
storage efficiency and the atomicity guarantees.
### Offline updates
......@@ -661,19 +695,37 @@ The upgrader daemon is responsible for most of the activities involved, such as
detecting available updates, initiating the update process and managing the
boot count.
It handles both online OTA updates and offline updates made available on
locally mounted devices.
#### Detecting new available updates
The [GVolumeMonitor](
For offline updates, the
API provided by GLib/GIO is used to detect when a mass storage device is
plugged into the device, and the
[GFile]( GLib/GIO API is
used to scan for the offline update stored as a plain file in the root
of the plugged filesystem named `apertis-system-update.bundle`.
of the plugged filesystem named `static-update.bundle`.
For online OTA updates, the
is used to poll the remote repository for new commits in the configured branch.
#### Initiating the update process
Once the offline update bundle is detected, functions from `libostree` are used
to unpack and verify it.
Once the update is detected, it is verified and compared against a local
blacklist to skip updates that have already failed in the past (see [Update validation]).
In the offline case the static delta file is checked for consistency before
being unpacked in the local OSTree repository.
During online updates, files are verified as they get downloaded.
In both cases the new update results in a commit in the local OSTree repository
and from that point the process is identical: a new deployment is created from
the new commit and the bootloader configuration is updated to point to the new
deployment on the next boot.
#### Reporting the status to interested clients
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment