Tutorial Update

Atomic A/B Updates with IGLOS and SWUpdate

Introduction

In the previous step of this tutorial, we walked through connecting your IGLOS device to a network and accessing it remotely via SSH. Now that your device is networked and accessible, you’re ready to learn about one of the most important features of IGLOS: its built-in software update mechanism.

In this step, you will learn how to:

Understand the built-in software update mechanism (SWUpdate)
Learn about A/B updates and their advantages for embedded systems
Download and install software updates over the network
Access the built-in webserver
Demonstrate the atomic nature of updates through a rollback example

By the end of this guide, you’ll understand how modern embedded systems handle software updates safely and reliably.

Understanding Software Updates with SWUpdate

IGLOS uses SWUpdate as its default software update mechanism. Before diving into how to use it, it’s important to understand how it works and why it’s particularly well-suited for embedded systems.

What is SWUpdate?

SWUpdate is a software update framework for embedded systems running Linux. It provides a flexible interface compatible with many different ways to install software updates and supports integrity protection and mutually authenticated transmission of updates.

A/B Updates vs. Live Installation

There are two fundamentally different approaches to updating Linux systems:

Live Updates (Traditional Approach)

Traditional package managers like apt work by:

Manually (or via an automation framework like Puppet) logging into the system and triggering commands (e.g. apt upgrade)
Having the package manager pull the new packages from a repository
Installing changes directly to the running system
Restarting services or the system as needed

This approach is common on desktop and server systems where human administrators can intervene if something goes wrong. But for embedded systems that are often scattered on factory floors or even in remote outdoor locations and where uptime is critical, human intervention is not feasible. Also, inconsistencies of device state over a large device fleet that would be introduced by human intervention would make maintenance a nightmare. And finally, updating systems this way would require a longer maintenance downtime while the update is downloaded and installed.

Therefore, the update system needs to ensure that only a strictly predefined state is running on the system and that updates will be easily and automatically rolled back to a known state.

A/B Updates (SWUpdate Approach)

A/B updates work very differently. In contrast to the first approach, updates are not provided as single software packages, but always as a complete system image. Imagine it like flashing the microSD card from scratch with the newest system image, just in a more efficient way and with the optional ability to carry application-specific configuration over during the update.

The update will be executed like this:

The device has two complete root filesystems (A and B), each containing a full operating system image.
The system boots from partition A by default.
When an update is available, the new image is written to partition B without disturbing the running system on partition A and while the system is fully operational.
After writing completes, a flag can be actively set to boot from partition B on the next restart.
The system is rebooted (at a time convenient for the operation), and partition B becomes the new active partition.
If the new system boots successfully, partition B is marked as “good” and remains the active partition.
If something goes wrong, the system can automatically fall back to partition A.

How can updates be delivered to the device?

SWUpdate is flexible about how .swu files reach the device. In production, common approaches include:

Fleet management systems: Tools like Eclipse hawkBit provide centralized management of updates across many devices, with scheduling, rollout control, and monitoring.
USB sticks: For secure, air-gapped environments, updates can be transferred via USB and installed locally without any network access.
Direct streaming: For development and lab environments, you can stream updates directly over SSH without any intermediate infrastructure. This is what we will use in the following.

Why A/B updates are advantageous for embedded systems:

Defined state: The system is always in a known, consistent state.
Atomic updates: An update either completes fully or doesn’t apply at all. There’s no risk of a half-applied update.
Simple rollback: If a new version has problems, simply booting from the previous partition provides an instant rollback.
No service interruption during download: The entire update is staged to the inactive partition before the system ever reboots.
Simplified security: With read-only filesystems (which later steps of this tutorial will cover), A/B updates combined with dm-verity protection ensure that the system is protected against tampering attempts.

Executing a Software Update

For demonstration purposes, we provide a software update that will install a simple webserver on the system. The software update image can be downloaded at

https://nextcloud.linutronix.de/public.php/dav/files/4wMznQdFKCitEcb/IGLOS_Tutorial_Web_App_13.6.1.swu

Due to the A/B update principle, we can first stream the update to the device and write it to the currently inactive A/B slot without switching to it or rebooting as follows:

For the first step, the install_update command can be used like this:

cat IGLOS_Tutorial_Web_App_13.6.1.swu | ssh root@YOUR_DEVICE_IP install_update

Note that this requires elevated privileges, so we use the root account (password: iglos). This is only suitable for development and exploration as described below.

Then, activate the update: this switches to the slot you just installed and reboots into it, at a moment convenient for the operation. It will also reset everything you might have done on the system, except for changes under /var (which also covers /home, since /home is bind-mounted from /var/home).

ssh root@YOUR_DEVICE_IP activate_update

The system will automatically reboot after this command.

If you don’t need that split, both steps can be combined into a single command, install_and_activate_update, which simply runs install_update followed by activate_update:

cat IGLOS_Tutorial_Web_App_13.6.1.swu | ssh root@YOUR_DEVICE_IP install_and_activate_update

⚠️ Important
The SSH-based update method shown here is suitable only for development and exploration on a single device or small lab environments. However, it is not suitable for production deployments because it requires manual intervention for each device, doesn’t scale to multiple devices, and exposes SSH access.
As discussed above in the A/B Updates section, production systems should use proper infrastructure like hawkBit for centralized fleet management, or USB sticks for secure, air-gapped deployments. Later steps of this tutorial will cover integration with these production-grade approaches.

Waiting for the Reboot

After running the activate command, the system will reboot automatically. This should take under a minute.

SSH will no longer react and disconnect when the device reboots. Don’t be alarmed. This is expected.

You can check if the device has finished rebooting by trying to reconnect:

ssh iglos@YOUR_DEVICE_IP

Retry every few seconds until the connection succeeds.

Once reconnected, the update is complete and your device is running the new version.

Accessing the Built-in Webserver

After the update completes, your device should now be running with the built-in webserver enabled. This is a simple HTTP service delivering a static website.

Verify the Webserver is Running

Open a web browser on any computer on your network and navigate to:

http://YOUR_DEVICE_IP

You should see a simple webpage, confirming the webserver is running. Notice that this webpage is served via HTTP and not HTTPS (which will also be indicated by your browser with a warning message like “Not Secure” in the address bar). For productive systems, a trusted certificate needs to be installed.

Demonstrating Rollback: Removing the Webserver

Now that we’ve successfully installed an update and verified the webserver is running, let’s demonstrate that the A/B update mechanism truly works by performing another update cycle.

To prove that updates are atomic and reversible, we’ll install an update that removes the webserver. This exercise shows that:

Updates reliably change system state
You can move between different system versions
The A/B mechanism ensures you can always return to a previous state
Updates don’t accumulate changes and each is a complete system image

Note that this switching to previous versions can also be considered a security issue in some scenarios. Imagine the following situation: Version 1.2 has a critical security issue that allows to gain elevated privileges. A security fix is developed and the version 1.3 is distributed and installed on every device. An attacker now takes a software update image of the old version 1.2 and installs it onto a system they want to attack to gain elevated privileges. To prevent this, a mechanism called rollback-protection can be applied, but requires some advanced setup including a proper secure boot chain.

Download and Install the Update

Obtain the update file without webserver from

https://nextcloud.linutronix.de/public.php/dav/files/4wMznQdFKCitEcb/IGLOS_Tutorial_13.6.1.swu

Transfer, install and activate as described before:

cat IGLOS_Tutorial_13.6.1.swu | ssh root@YOUR_DEVICE_IP install_and_activate_update

Verify the Webserver is Removed

After the reboot completes verify the webserver is no longer running. You should receive a “connection refused” error, confirming the webserver is no longer active on this version.

This demonstrates that updates completely replace the system. The webserver didn’t just get disabled. It’s not part of this update image at all. If you were to install the previous update again, the webserver would return immediately after reboot.

Key Takeaways

To summarize what you’ve learned:

SWUpdate: Purpose-built for embedded systems, providing atomic, reliable updates
A/B Updates: Superior to live updates for embedded systems due to atomicity, defined state, and easy rollback
Simple rollback: If a new version has problems, the system boots from the previous partition for instant recovery
Development-friendly: SSH-based streaming is perfect for development. Production systems use e.g. hawkBit or USB transfers which we will cover in the future.

Troubleshooting

Webserver Not Accessible

Problem: Cannot access http://YOUR_DEVICE_IP

Solutions:

Verify the device has the webserver enabled (check the update you installed).
Ensure the IP address is correct and the device is still connected to the network.

What’s Next?

Coming Soon: The next step will be published soon.

Follow our LinkedIn channel to get informed when the next part is online!