OpenWrt Integration

This first blog post will quickly demonstrate the functionalities offered by the Thistle Update Client around a common router platform: OpenWrt.

We’ve planned to support OpenWrt from the beginning, as it's the router solution that many of us at Thistle love and use ourselves! We hope this example will provide a strong foundation for integrators that are using OpenWrt as the base of their system implementation.

Fleet administrators will also see immediate benefits using our update platform, as it offers a clear and straightforward way to safely and reliably manage a fleet of devices.

Running OpenWrt for a fleet of institutional devices (library, university, non-profit...)? Feel free to reach us out at support@thistle.tech, we provide free support for devices running institutional networks.

Thistle Update Client

This solution revolves around the Thistle Update Client. This update client fully leverages A/B boot and modern cryptographic primitives in order to provide a safe and secure update mechanism. The update client is lightweight, and will even run on smaller devices with constrained resources.

Special attention has been put into software supply chain security, and all binaries are bit-for-bit reproducible (more on this coming soon in another blogpost!)

Platform chosen and configuration

We chose as an example device a mid-range Wi-Fi router that fully supports OpenWrt, the Linksys MR8300. This device comes with U-Boot as a bootloader platform, making the integration with A/B rootfs update very easy.

Once OpenWrt is installed (see wiki), we will proceed with setting up the Update Client.

Integration work

Aside from standard device configuration (setting up partitions, release name etc...), it was necessary to write two integration script to adapt our software to this platform.

These two scripts are leveraging platform specific internal tooling to indicate the currently used root partition the update client, and how to switch the currently used boot partition.

The first command allows the update client to locate the currently used root partition. This is a simple way around OverlayFS, and it only revolves around executing the following command:

$ cat currently_booted.sh
#!/bin/sh
(cat /sys/devices/virtual/ubi/ubi0/mtd_num | grep -q 13) && printf "/dev/mtdblock13" || printf "/dev/mtdblock11"

The second command instructs the bootloader to attempt using "other" partition - i.e. not the one currently being used as root partition. It uses U-Boot's `fw_setenv` tool to set bootloader environment variable from userland.

$ cat switch_bootpart.sh
#!/bin/sh
fw_setenv auto_recovery yes && (fw_printenv -n boot_part | grep -q 1) && fw_setenv boot_part 2 || fw_setenv boot_part 1

The integration work is now done. Let's now have a look at how we can package and update and release it.

Amending OpenWrt image to include update client

The default OpenWrt image does not include the Thistle Update Client out of the box, but it is trivial to include it on the image with OpenWrt's provided tooling. We made a small gist to show the steps necessary in order to modify an existing OpenWrt image, so that it includes the Thistle Update Client, as well as configuration and supporting scripts.

OpenWrt make image provides a very flexible way to amend an existing OpenWrt image without recompiling all its content. See the FILE variable to amend the filesystem, and PACKAGES to add packages to an existing image.

Testing an update with the release helper

We can now use the Thistle Release Helper to release our OpenWrt image. The release helper is here to assist with the packaging of updates - and it will help with compressing the update artifact, securely signing the update package, and distribution through the Thistle Platform.

We can now release the update:

# prepare the manifest with a single rootfs and release
$ ./trh prepare -t=openwrt-22.03.2-ipq40xx-generic-linksys_mr8300-squashfs-factory.bin

# upload assets and manifest
$ ./trh release

Conclusion

Now that the update has been crafted and uploaded, administrators can monitor the deployment of updates throughout the fleet using our online dashboard. We plan on adding features in the near future to fully support alerting upon failed update process, and an easy way to rollback the fleet to the previous known working state, if an issue is detected.

We hope you liked this first blogpost! As always, feel free to drop us an email if you need any assistance regarding implementation of the Update Client.