Commit 46071036 authored by Emanuele Aina's avatar Emanuele Aina

system-updates-and-rollback: Reduce the nesting of the Implementation section

Move the whole Implementation section one level up.
Signed-off-by: Emanuele Aina's avatarEmanuele Aina <emanuele.aina@collabora.com>
parent 8fa6d113
......@@ -575,7 +575,7 @@ system is reset to a clean state.
![](media/full_update.svg)
### Implementation
## Implementation
This section provides some more details about the implementation of offline
system updates and rollback in Apertis, which is split in three main
......@@ -585,7 +585,7 @@ components:
* the bootloader integration
* the command-line HMI
#### The general flow
### The general flow
The Apertis update process deals with selecting the OSTree deployment to boot,
rolling back to known-good deployments in case of failure and preparing the new
......@@ -598,7 +598,7 @@ the dual-partition approach chosen by ChromeOS and the different bootloaders,
the update/rollback process is largely the same as [the one in
ChromeOS](https://www.chromium.org/chromium-os/chromiumos-design-docs/filesystem-autoupdate#TOC-Diagram).
#### The boot count
### The boot count
To keep track of failed updates the system maintains a persistent counter that
it is increased every time a boot is attempted.
......@@ -624,7 +624,7 @@ However, in the reference implementation the focus is on the most general
solution first, while being flexible enough to accomodate other solutions
whenever needed.
#### The bootloader integration
### The bootloader integration
Since bootloaders are largely platform-specific the integration needs to be
done per-platform.
......@@ -655,13 +655,13 @@ the rollback persistent and prevent the faulty updates to be tried again. To do
so, it adds any deployment more recent than the current one to a local
blacklist and then drops them.
#### The updater daemon
### The updater daemon
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.
##### Detecting new available updates
#### Detecting new available updates
The [GVolumeMonitor](https://developer.gnome.org/gio/stable/GVolumeMonitor.html)
API provided by GLib/GIO is used to detect when a mass storage device is
......@@ -670,17 +670,17 @@ plugged into the device, and the
used to scan for the offline update stored as a plain file in the root
of the plugged filesystem named `apertis-system-update.bundle`.
##### Initiating the update process
#### Initiating the update process
Once the offline update bundle is detected, functions from `libostree` are used
to unpack and verify it.
##### Reporting the status to interested clients
#### Reporting the status to interested clients
The updater daemon exports a simple D-Bus interface which allows to check the
state of the update process and to mark the current boot as successful.
##### Resetting the boot count
#### Resetting the boot count
During the boot process the boot count is reset to zero using an interface that
abstracts over the platform-specific approach.
......@@ -689,7 +689,7 @@ While product-specific policies dictate when the boot should be considered
successful, the reference images consider a boot to be successful if the
`multi-user.target` target is reached.
##### Marking deployments
#### Marking deployments
Rolled back deployments are added to a blacklist to avoid trying them again
over and over.
......@@ -703,7 +703,7 @@ To do so, the boot counting is stopped once the current boot is considered
succesful, effectively marking the current boot as known-good without the need
to maintain a whitelist and synchronize it with the bootloader.
#### Command line HMI
### Command line HMI
A command line tool is provided to query the status using
[the `org.apertis.ApertisUpdateManager` D-Bus API](https://gitlab.apertis.org/appfw/apertis-update-manager/blob/master/data/apertis-update-manager-dbus.xml):
......@@ -724,7 +724,7 @@ It can also be used to mark the boot as successful:
$ updatectl --mark-update-successful
```
#### Update validation
### Update validation
Before installing updates the updater check their validity and appropriateness
for the current system, using the metadata carried by the update itself as
......@@ -737,7 +737,7 @@ The updater also checks that the update version is newer than the one on the
system, to prevent downgrade attacks where a older update with known
vulnerabilities is used to gain privileged access to a target.
#### Testing
### Testing
Testing ensures that the following system properties for each image
are maintained:
......@@ -757,26 +757,26 @@ To do so, a few components are needed:
At least initially, testing is done manually. Automation from LAVA will be
researched later.
##### Images can be updated
#### Images can be updated
Plugging a device with the known-good test update on it bundle the expectation
is that the system detects it, initiates the update and on reboot the
deployment from the known-good test bundle is used.
#### The update process is robust in case of errors
### The update process is robust in case of errors
To test that errors during the update process don't affect the system, the
device is unplugged while the update is in progress. Re-plugging it after that
checks that updates are gracefully restarted after transient errors.
#### Images roll back in case of error
### Images roll back in case of error
Injecting an error in the boot process checks that the image initiates the roll
back to a previous deployment. Since a newly-flashed image doesn't have any
previous deployment available, one needs to be manually set up beforehand by
downloading an older OSTree commit.
#### Images are a suitable rollback target
### Images are a suitable rollback target
A known-bad deployment similar to the known-good one can be used to ensure that
the current image works as intended when it is the destination of a rollback
......
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