This tutorial will walk you through how to do robust system level updates with rollback. These types of updates cover the whole system including system level applications and the Linux kernel and ensure the device comes back in a consistent state even if the update process is interrupted for any reason such as power loss.
You should:
If you already installed mender-artifact
on your system, you can skip this step.
Prepare destination directory:
mkdir -p ${HOME}/bin
Download the mender-artifact
binary. If you're on Linux
wget https://downloads.mender.io/mender-artifact/3.8.0/linux/mender-artifact -O ${HOME}/bin/mender-artifact
On MacOS
wget https://downloads.mender.io/mender-artifact/3.8.0/darwin/mender-artifact -O ${HOME}/bin/mender-artifact
Make the mender-artifact
binary executable:
chmod +x ${HOME}/bin/mender-artifact
Add ${HOME}/bin
to PATH
:
export PATH="${PATH}:${HOME}/bin"
Add above to ~/.bashrc
or equivalent to make it persistent across multiple
terminal sessions.
Setup the IP_ADDRESS
shell variable with correct IP address of your device:
IP_ADDRESS="<DEVICE-IP-ADDRESS>"
On Mender, check ipv4_eth0
or ipv4_wlan0
inventory attributes of your
Raspberry Pi device
On Mender, check ipv4_docker
inventory attribute of your Virtual device
Setup USER
environment variable to match an existing user on the device, e.g
for Raspberry Pi devices:
USER="pi"
USER="root"
Mender Artifacts require a device compatibility value as input, which must match what the device is reporting to the Mender server or it will refuse to install it. This is a safety mechanism to avoid installing software to incompatible hardware.
If you are unsure, you can check what the device is reporting on the server:
Use the result from above to assign that value to DEVICE_TYPE
shell variable:
DEVICE_TYPE="raspberrypi4"
Make sure to replace raspberrypi4
with the specific value that you are
seeing in your setup
Set SSH_ARG
shell variable to specify the SSH access port:
SSH_ARG="-p 22"
SSH_ARG="-p 8822"
The easiest way to create system level updates is to use the snapshot functionality in Mender, which will create a snapshot of the full system on a currently running device and package it as a Mender Artifact that you can deploy to other devices.
Run the following command on your workstation to generate a snapshot Mender Artifact from your device:
mender-artifact write rootfs-image \
-f ssh://"${USER}@${IP_ADDRESS}" \
-t "${DEVICE_TYPE}" \
-n system-v1 \
-o system-v1.mender \
-S "${SSH_ARG}"
Your device is not usable while the snapshot operation is in progress. Mender will freeze the storage device during this operation in order to create a consistent snapshot.
Depending on your local network and storage speed, this will take up to 10-20 minutes to finish. You will see a progress indicator, and when it reaches 100% it will package the Mender Artifact which will take a few more minutes because it will need to compress the snapshot image.
The end result is a file called system-v1.mender
. Upload this file to
hosted Mender. You can do that using the UI under the Releases tab, as
demonstrated below.
While your Artifact is uploading we make some modifications to the device so we can see the effect of the deployment later. On your device, run the following command to install a text editor:
sudo apt update && sudo apt install vim --assume-yes
You can now run vim
to verify it is installed, as you would expect. Note that
this modification is not part of your system snapshot created above.
Be careful when running apt upgrade
on a device with Mender system updates enabled. Integration
with apt upgrade
(through the grub.d
framework) is only implemented for x86 as of
mender-convert version 3.0.0. For ARM and other non-x86 architectures, always update single
applications only, because running apt upgrade
may brick your device!. If you need to run apt upgrade
, do it on a pristine system without Mender installed, and then convert it to a Mender
image
afterwards. This restriction may be lifted in the future.
Once the Artifact upload in Step 3 has finished, go to the DEPLOYMENTS tab and click CREATE DEPLOYMENT in order to deploy it to your device.
Once this deployment finishes it will have the effect of restoring your full
device root file system to the same state as when you created the snapshot in Step 3.
You can verify this by trying to run vim
again after the deployment has finished.
It is gone! This is because your device file system did not have this application
at the time you created the snapshot. This works for any change in the file system,
including removing or installing software and changing any configuration.
Please take a moment to experiment at this stage to familiarize yourself with robust system updates with Mender.
As an example you can iterate this flow:
Make a change on the device, e.g change a configuration file or install an application.
Create a snapshot of the device changes you made
Mender will skip a deployment to a device if the Artifact is already
installed, in order to limit resource usage, downtime and ensure consistency
across the fleet. Make sure to use different names for new Artifacts you
generate (instead of the two instances of system-v1
above).
Upload the generated Artifact (.mender
) to hosted Mender and deploy it.
Once you have two or more Artifacts uploaded you can switch between the software you have on your devices by deploying the respective Artifacts.
Deploy to many devices in order to effectively replicate the device software and configuration.
To read more about system snapshots, see the documentation on Artifact from system snapshot.
Using the snapshot feature is one way to create system updates and additional resources on more advanced ways you will find here:
Proceed to Deploy a Docker container update.
© 2022 Northern.tech AS