Requirements
If you don’t have Remote Terminal Access to the device and you want to install the Update Module in runtime, you must have the single-file update module already as part of your rootfs, just check if the /usr/share/mender/modules/v3/single-file file exist. If not, then you must include it as part of a regular image OTA update, either for a Yocto-based system or a Debian-based one.
Context
What counts as an “application update” can vary greatly – a single file, a whole directory, even a container image. This makes it hard to have a single, rigid update method. Mender’s Update Module framework provides a flexible solution, allowing you to tailor application updates to your specific needs.
Update Modules are executable files residing in the /usr/share/mender/modules/v3 directory (note: v3 represents the current protocol version). The Mender Client uses a defined parameter set to execute these modules, facilitating the update process.
The “Single File Update Module” installs a file of your choice into a specified directory on the device, and we are going to take advantage of it in this tutorial. You can read more about this Update Module in here.
Update Module creation
The structure of the Update Module require the definition of one or more states from the Mender State Machine.
For this example, we will take the simplest one described in Mender’s docs:
cat << "EOF" > dummy-mender-module
#!/bin/bash
set -e
STATE="$1"
FILES="$2"
case "$STATE" in
ArtifactInstall)
cp "$FILES"/files/* /opt/
;;
esac
exit 0
EOF
This one will create a Mender Update Module named dummy-mender-module.
Installation
On run time
With Remote Terminal Access
If you already have Remote Terminal access, either by using the Mender’s Troubleshooting add-on, SSH or any other protocol, you can just add the recently created file inside /usr/share/mender/modules/v3, just don’t forget to make it executable with chmod +x my-module.
And that’s it, any folder used in the Update Module like /opt must be created upfront.
Without Remote Terminal Access
For this one, we will create an single-file update module, following pretty similar steps as the ones in this tutorial with some tweaks:
Download single-file-artifact-gen, by running the following command:
wget https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules-artifact-gen/single-file-artifact-gen
Make it executable:
chmod +x single-file-artifact-gen
And let’s create a file that will be used to set the executable permissions:
echo "+x" > permissions
Notice the FILE is the one we created above (dummy-mender-module) and the DEST_DIR the Update Modules path. Feel free to choose any ARTIFACT_NAME, OUTPUT_PATH and select a DEVICE_TYPE that matches with the device_type reported to the client as part of the device’s inventory. Notice the last -f to make sure it will be executable in the device side.
ARTIFACT_NAME="my-update-1.0"
DEVICE_TYPE="my-device-type"
OUTPUT_PATH="my-update-1.0.mender"
DEST_DIR="/usr/share/mender/modules/v3/"
FILE="dummy-mender-module"
./single-file-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -d ${DEST_DIR} -o ${OUTPUT_PATH} ${FILE} -- -f permissions
Now you can deploy this artifact by using Mender and your device will have installed the new Update Module.
On build time
Just add the created Update Module by following: