Support for update modules is soon coming to Mender!
Technically, an update module implements one or more of the actions that the Mender client carries out when installing an Artifact payload. The “core” action all update modules must implement is the Install action, which implements how an Artifact payload is installed on the device. However, there are other actions that may be implemented depending on the desired functionality and use case for an update module, such as Rollback.
Common update modules for application updates will be provided, such as support for file-based, package based and container-based updates!
But this is just the beginning. Anyone can write their own update module that is reusable or tied to a custom use case or hardware environment. For example, one could use update modules to update bootloaders, peripherals and even integrate existing homegrown and client-only updaters right into the management infrastructure of Mender!
Today, support for update modules is not yet released, but we wanted to show you a way to test an early version of update modules so you can test usability, check your own use cases and give feedback to further development.
In this short tutorial we will:
- Set up a development environment that includes experimental support for update modules
- Create a new update module from scratch that installs files to the /data partition
- Build a Mender Artifact with a custom payload for this update module
- Deploy the Artifact to the device
- Verify the payload is installed
Note that these steps are meant for experimentation and testing only, so we advice holding off on any production release until the next Mender version with official support for update modules is released.
Prerequisites
Your workstation needs 10 GB free disk space and 2 GB RAM available to be on the safe side.
Also, you need some common development tools installed, including git, docker engine and docker compose.
If you are not using 64-bit Linux or for some other reason want to build mender-artifact from source, you also need to install the Golang compiler.
Set up the update module development environment
Change to a working directory:
mkdir mender-update-modules
cd mender-update-modules
Download development sources and virtual device images
git clone -b update_modules_demo https://github.com/kacf/integration
docker pull mendersoftware/deployments:update_modules_demo
docker pull mendersoftware/mender-client-qemu:update_modules_demo
Download a version of mender-artifact that supports update modules for Linux 64-bit:
wget https://s3.amazonaws.com/mender/update-modules-development-demo/mender-artifact
chmod +x mender-artifact
Alternatively, if you want / need to build mender-artifact from source, use the mender-artifact-v3_demo branch of kacf’s fork: https://github.com/kacf/mender-artifact/tree/mender-artifact-v3_demo. In this case you will need to clone it into a working Golang environment and build it from there.
Start the Mender server and see the virtual device
Start the Mender server:
cd integration
./up
Set first-login password:
sudo ./demo exec mender-useradm /usr/bin/useradm create-user --username=myusername@example.com --password=mysecretpassword
Log in to the server at https://localhost.
Now verify that the virtual device, which supports update modules, shows up. Accept this device into the server.
SSH into the virtual device
First, find the IP address of the virtual device:
docker inspect integration_mender-client_1|grep -e 'IPAddress": "[0-9].*'
Then SSH into the device:
ssh -p8822 root@<IP FROM PREVIOUS COMMAND>
Keep this terminal open as it will enable you to look inside and modify the device.
Create a file-based update module installer on the device
In the device terminal, change directory to where the Mender update modules are:
cd /usr/share/mender/modules
Create a new update module installer that simply writes the payload to /data:
cat << "EOF" > data-file
set -e
STATE="$1"
FILES="$2"
case "$STATE" in
ArtifactInstall)
cp "$FILES"/files/* /data
;;
esac
exit 0
EOF
chmod +x data-file
Your Mender client is now extended to be able to install payloads to /data!
NOTE: A more interesting case would be to install a package, such as a .deb. There is an existing experimental update module available for this you can use, however our virtual device is very limited so it does not have a package manager.
Create an Artifact with a payload for the new update module
Now switch back to a terminal on your workstation/laptop. We will use the mender-artifact CLI downloaded and built above to create a Mender Artifact with a data-installer payload.
Change directory to where you downloaded (or built) mender-artifact above.
First, simply create a file you want to install to the data partition:
echo 'Installed by Mender!' > data-file-1
Now we use mender-artifact to create a new Mender Artifact with this as the only payload, for our new data-installer update module.
./mender-artifact write module-image -t qemux86-64 -o ~/data-file-1.mender -T data-file -n data-file-1 -f data-file-1
Upload and deploy your Artifact
Go to Artifacts in the Mender server UI and upload your newly generated Mender Artifact; we put it in your HOME directory above (using -o ~/data-file-1.mender).
Now go to Deployments and deploy the Artifact to All devices. It should finish within a minute or so.
NOTE: In this experimental version, the new Artifact name is not yet reported, so you will still see the old Artifact name as Current software under Devices. Also, running Standalone deployments (i.e. mender -install …) is not yet supported. Both these issues will be resolved in the final version.
Verify the deployment on the device
Now that our deployment finished, you should find the payload you created and our data-installer update module installed:
cat /data/data-file-1
Installed by Mender!
Provide feedback and ask questions
The Mender project relies heavily on feedback from users like yourself to improve and support new use cases! Update modules is no exception, so please consider posting your feedback or questions in the Mender Hub forum.
