rollback.adoc

Rollbacks

Note	We recommend that you view this article in our documentation portal. Not all of our articles render correctly in GitHub.

Since Aktualizr is a userspace application and relies on a lot of other software which can be affected by an unsuccessful update, rollback functionality should be implemented in the bootloader.

Some support from Aktualizr is nevertheless required. The most important thing is notifying bootloader on successful boot (Bootloader::setBootOK()). Notifying on the update (Bootloader::updateNotify) can also save the bootloader some write cycles to the environment storage.

Currently only U-boot 'bootcount' rollback mechanism is supported.

U-boot

More info about bootcount feature you can find in U-boot documentation.

When using 'bootcount' the system can be in one of three states:

• No update: booting into main image

• Booting into rollback image

• Updated: update was installed, but it’s not yet clear if it was successful

'Updated' is a transition state, while 'No update' and 'Rollback' are steady states. Transition to 'No update' is confirmed by Aktualizr, while going to 'Rollback' is forced by U-boot

'bootcount' and 'upgrade_available' variables are recognized by U-boot. 'rollback' is Aktualizr-specific, it prevents bootloader to try booting main image after falling back to rollback image.

You can see the whole transition graph below.

                Aktualizr confirms successful update by
           +-----------------------------------------------------+       +-----------------------+
           |    setting upgrade_available=0; bootcount=0         |       |                       |
           |                                                     |       |                       | U-boot increments
           |                                                     |       |                       | bootcount after every
           V                                                     |       V                       | unsuccessful boot ( i.e
+-----------------------+                                    +------------------------+          | (when upgrade_available = 1)
|       No update       |                                    | Updated                |          |
|                       |  Aktualizr announces update by     |                        |          |
| bootcount = 0         |----------------------------------> | bootcount <= bootlimit |----------+
| upgrade_available = 0 |    setting upgrade_available=1     | upgrade_available = 1  |
| rollback = 0          |                                    | rollback = 0           |
|                       |                                    |                        |
+-----------------------+                                    +------------------------+
                                                                   ^            |
                  Aktualizr announces update by                    |            |
           +-------------------------------------------------------+            |
           |       setting upgrade_available=1                                  |
           |                                                                    |
           |                                                                    |
+-----------------------+                                                       |
| Rollback              |                                                       |
|                       |       After bootcount exceeded bootlimit U-boot       |
| bootcount > bootlimit |<------------------------------------------------------+
| upgrade_available = 0 |  boots into rollback image and resets upgrade_avalable
| rollback = 1          |
|                       |
+-----------------------+