Software update (basic)¶

Overview¶

In this tutorial, we'll manually update a partition and experiment with confirmation and rollback. We'll also test installing some unsigned package.

What you'll learn:

How to use Welma's software update feature
How to troubleshoot software update failures

What you'll need:

A device with Welma installed and running welma-image-minimal-dev, built with WELMA_UPDATE="swupdate" and WELMA_SECURE_BOOT="0" (see our Quick start if needed)
A host computer with a Linux-based operating system;
The device is reachable from the host through an IP network by SSH, using the name device-under-test.

Step 1: initial setup¶

Work in a dedicated directory and get the tools that we need for the next steps:

git clone git@gitlab.com:witekio/rnd/theembeddedkit/welma/meta-welma.git
git clone git@gitlab.com:witekio/rnd/theembeddedkit/welma/welma-test.git
git clone git@gitlab.com:witekio/rnd/theembeddedkit/welma/welma-signing-tools.git

Step 2: create a simple package for testing¶

You can skip this step if you download the sample appro1.swu file instead.

On your host, create a new package appro1:

mkdir appro1
echo hello1 > appro1/README-1.txt
dd if=/dev/zero of=appro1.ext4 bs=5M count=1
mkfs.ext4 -F -L appro appro1.ext4 -d appro1

meta-welma/recipes-support/update-tools/files/swu \
    create appro1.swu \
    --image appro1.ext4 --device /dev/disk/partitions/inactive/appro

welma-signing-tools/swupdate/sign-swu \
    appro1.swu \
    welma-signing-tools/default-dev-keys/SWK1.key

Step 3: install the package¶

From your host, upload the package to the device:

scp appro1.swu device-under-test:/var

From your host, log onto your device and get a shell prompt:

ssh device-under-test

First take a look at the status of Welma's update mechanism:

# updatectl status
state               normal
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p7
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p8
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

The state is normal, which tells that the system is ready for software update. The active, inactive and single partitions are displayed, but your mileage may vary as the types and number of partitions depend on the machine being used.

On your device, start the installation:

# updatectl install /var/appro1.swu

# updatectl status
state               normal,test-scheduled
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p7
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p8
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

You can see that the state is normal,test-scheduled, which means that the device is running a valid system and a package has been installed and is pending for test.

To activate the installed package in test mode, a reboot is needed:

# reboot

Step 4: confirm installation¶

The SSH connection is severed, and after reboot, log again onto your device and get a shell prompt:

ssh device-under-test

On your device:

# updatectl status
state               under-test
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p8
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p7
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

You can now see that the state is under-test, which means that the device is running the newly installed version, and awaits a confirmation from the application. You can also see that partition 8 has become active and partition 7 has become inactive. This can also be seen when looking at the files in /app:

# ls -l /app/
-rw-rw-r--    1 1001     1001             7 Jan 20 15:49 README-1.txt
drwx------    2 root     root         16384 Jan 20 15:49 lost+found

The file README-1.txt that we created in our update package is there and active. But to make the installation persistent, you need to confirm that everything is fine:

# updatectl confirm

And now:

# updatectl status
state               normal
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p8
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p7
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

The state is now normal, which means that the software update procedure is completed. This need for a confirmation can be considered as a safeguard against installing packages that turn out to be defective. In a real world project, the application should verify if everything looks good before confirming the installation.

Welma expects the application to confirm before a given timeout (2 minutes by default), or it triggers a rollback to the previous version of the system. If you missed the timeout, you can start again at step 3.

You're now done the installation.

Step 5: install and roll back¶

In this step, we will install a package, abort the installation and have your system roll back to its previous version. We will mostly use the same commands as seen before, so we're not repeating the detailed comments.

On your host, create a new package appro2:

mkdir appro2
echo hello2 > appro2/README-2.txt
dd if=/dev/zero of=appro2.ext4 bs=5M count=1
mkfs.ext4 -F -L appro appro2.ext4 -d appro2

meta-welma/recipes-support/update-tools/files/swu \
    create appro2.swu \
    --image appro2.ext4 --device /dev/disk/partitions/inactive/appro

welma-signing-tools/swupdate/sign-swu \
    appro2.swu \
    welma-signing-tools/default-dev-keys/SWK1.key

From your host, upload the new package:

scp appro2.swu device-under-test:/var

On your device, install the package and reboot:

# updatectl install /var/appro2.swu

# updatectl status
state               normal,test-scheduled
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p8
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p7
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

# reboot

On your device, after reboot and relogging via SSH:

# updatectl status
state               under-test
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p7
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p8
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

# ls -l /app/
-rw-rw-r--    1 1001     1001             7 Jan 20 15:52 README-2.txt
drwx------    2 root     root         16384 Jan 20 15:52 lost+found

The new package appro2 is installed, but not persistent yet, because under-test. Now abort the installation:

# updatectl abort

This will trigger a reboot of the device. Alternatively, you could also have waited for 2 minutes until Welma automatically triggers a reboot.

On your device, after reboot and relogging via SSH, we can see that we're back to the previous version of our system:

# updatectl status
state               normal
partitions-active   /dev/mmcblk0p3 /dev/mmcblk0p5 /dev/mmcblk0p8
partitions-inactive /dev/mmcblk0p4 /dev/mmcblk0p6 /dev/mmcblk0p7
partitions-single   /dev/mmcblk0boot0 /dev/mmcblk0p2

# ls -l /app/
-rw-rw-r--    1 1001     1001             7 Jan 20 15:49 README-1.txt
drwx------    2 root     root         16384 Jan 20 15:49 lost+found

Step 6: install an unsigned package¶

In this step, we will install an unsigned package, see how Welma's mechanism rejects the installation request.

On your host, create a new package appro3, but do not sign it:

mkdir appro3
echo hello3 > appro3/README-2.txt
dd if=/dev/zero of=appro3.ext4 bs=5M count=1
mkfs.ext4 -F -L appro appro3.ext4 -d appro3

meta-welma/recipes-support/update-tools/files/swu \
    create appro3.swu \
    --image appro3.ext4 --device /dev/disk/partitions/inactive/appro

From your host, upload the new package:

scp appro3.swu device-under-test:/var

On your device, install the package and reboot:

# updatectl install /var/appro3.swu
Error org.freedesktop.DBus.Error.Failed: Failed to install module

The system's journal will tell us a little more about the error:

# journalctl --lines=20
...
... updated[381]: InstallLocalFile: /var/appro3.swu
...
... swupdate.sh[372]: [TRACE] : SWUPDATE running :  [extract_file_to_tmp] : description file name not the first of the list: appro3.ext4 instead of sw-description.sig
...
... swupdate.sh[372]: [ERROR] : SWUPDATE failed [1] Image invalid or corrupted. Not installing ...
...
... update-artifact-swupdate[521]: fatal: Error in swupdate-client /var/appro3.swu
... updatectl[522]: Cannot InstallLocalFile /var/appro3.swu
... updated[381]: recv-dbus: AbortUpdate

Summary¶

You learned the basic principles of software update in Welma, how to make an update and how rollback works. You also experimented installation errors and found out how to get more information from the journal. You're ready to step to our next tutorial about automating this from an application.