Description
There is a variety of client-only solutions for installing update artifacts to embedded Linux devices, such as SWupdate or RAUC which do not offer a remote management solution. Those can be wrapped in an Update Module to enable OTA deployments, while keeping known good working integrations intact.
Example use-cases:
- Brownfield migration of existing device fleets using a client-only update solution
- Wrapping a custom flashing solution, as sometimes required for special hardware
This Update Module provides a sample implementation to deploy SWUpdate artifacts using Mender, but it can be easily adapted to other client solutions.
Specification
| Specification | |
|---|---|
| Module name | swu |
| Supports rollback | no |
| Requires reboot | configurable |
| Artifact generation script | no |
| Full operating system updater | no |
| Source code | https://github.com/mendersoftware/mender-update-modules/master/swu |
| Maintainer | josef.holzmayr@northern.tech |
Please be aware that Mender Update modules are meant to update parts of the operating system and if not configured properly they could potentially delete parts or even the full operating system. Always inspect the code carefully and only test modules on device that you can recover easily.
It is not recommended to install a Mender Artifact on your workstation
Prepare the device
This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.
All commands outlined in this section should be run in the device environment.
Prerequisites
This update module has the following prerequisites for the device environment:
- Mender client, version 2.0 or later
- SWUpdate client
- jq
This Update Module has the following prerequisites for the development environment:
- Install mender-artifact , version 3.0.0 or later
- jq
Install the Update Module
Download the latest version of this Update Module by running:
mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/swu/module/swu && chmod +x /usr/share/mender/modules/v3/swu
Prepare the development environment on your workstation
This section describes how to set up your development environment on your workstation.
All commands outlined in this section should be run in the development environment.
Create artifact
To download swu-artifact-gen, run the following:
wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/install_snap/module-artifact-gen/install_snap-artifact-gen && chmod +x swu-artifact-gen
Generate Mender Artifacts using the following command:
ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
./swu-artifact-gen \
--artifact-name ${ARTIFACT_NAME} \
--device-type ${DEVICE_TYPE} \
<name of swu file(s)> ...
Optional reboot
The SWU Update Module supports rebooting after artifact installation. If this is required for the packaged SWU file(s), add the --reboot flag to the swu-artifact-gen invocation.
Possible future improvements
- rollback support
- automatic determination of metadata from SWU file(s)
- enforced ordering of multiple SWUs
- streaming support
You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in Standalone deployments.
Artifact technical details
- The artifact can include an arbitrary number of
*.swufiles, but does not explicitly guarantee an installation order. Theswupdateinvocation uses a*.swuwildcard.
Creating a sample .swu file
In order to test this Update Module, having a device independent swu artifact is useful. To create one, you need the following:
A payload file. We will use this swu-demo.txt as an example:
Demo payload for the Mender SWU Update Module!
The sw-description file:
software =
{
description = "Demo for Mender SWU Update Module"
hardware-compatibility: ["1.0"];
files: (
{
filename = "swu-demo.txt";
path = "/opt/swu-demo.txt";
properties = {
create-destination = "true";
}
}
);
}
An swu file is at its heart a cpio archive, with the sw-description file coming first. You can create one using the following script:
#!/bin/bash
VERSION="1.0"
NAME="swu-demo"
OUTFILE="${NAME}_${VERSION}.swu"
echo "creating SWU artifact ${OUTFILE}"
if [ -f "$OUTFILE" ]; then
echo "$OUTFILE already exists, moving to $OUTFILE.bak"
mv $OUTFILE $OUTFILE.bak
fi
FILES="sw-description swu-demo.txt"
for i in $FILES;do
echo $i;done | cpio -ov -H crc > ${OUTFILE}
The resulting swu-demo_1.0.swu can be used for the swu-artifact-gen script as described above.