In this tutorial we will deploy a full rootfs update to a physical device, a Raspberry Pi 3, using the Mender server.
We will use two devices: one as our local "golden" device, which we use to prepare the update, and other as a remote device that receives the OTA update. It is also possible to use the same device for both roles if you have only one device available.
The test environment should be set up and working successfully as described in Install a Mender demo server.
We also strongly recommend that you complete the tutorial that comes with the Mender GUI so that you have a basic understanding of how Mender works before moving on to connecting a physical device.
You need one or more Raspberry Pi 3 devices. To make it easy to provision the device we will use a SD card to store the OS, so you will need one SD card (8 GB or larger) per device.
Get the disk image for your board(s) from the Downloads section.
It is possible to use this tutorial with any physical board, as long as you have integrated Mender with it. In this case you cannot use the demo Artifacts we provide in this tutorial, but you need to build your own artifacts as described in Building a Mender Yocto Project image.
Download the prebuilt
mender-artifact binary for your platform following the links
in Downloads section.
Please see Modifying a Mender Artifact for a more detailed overview.
The device needs to have network set up so it can connect directly to your workstation (where you have the Mender server running).
By default the Mender client will use ports 443 and 9000 to connect to the server. You can test the connection from your client later with networking tools like
If you have just one device, you could connect your workstation and the device using a direct Ethernet cable and use static IP addresses at both ends. For multiple devices, you need a router or switch.
For the rest of the tutorial we will assume
$IP_OF_MENDER_SERVER_FROM_DEVICE will expand to the IP address
that your device(s) can connect to the Mender server.
If you are using
bash, you can set a variable to make the rest of the tutorial easier, for example
Using static IP addresses with one device and workstation is quite easy. If you are using several devices, we strongly recommend using a setup with dynamic IP assignment like a router with DHCP support. Otherwise you need to take care to preserve the unique IP address configuration of each device when provisioning the storage and deploying rootfs updates.
If the device does not have internet connectivity, the device will not be able
to sync the system time. This will in turn cause the server certificate check to
fail. Thus if your device is not connected to the internet, you have to manually
set the system time correctly. This can be done with the
date -s command.
Locate the demo disk image (
*.sdimg) you downloaded for your device.
This image contains all the partitions of the storage device, as described in Partition
You can decompress a
.xz image like the following:
Or, if it is a
.gz image, like this:
The Mender images come with a predetermined size for the root filesystems, which may be too small for some use cases where a lot of space is required for applications. If you are building your own disk image by following Building a Mender Yocto Project image, you can configure the desired space usage with the Yocto Project variable MENDER_STORAGE_TOTAL_SIZE_MB.
If you are connecting your device with an Ethernet cable to the same LAN network that your workstation, skip the following subsections and jump to the next section
Else, if you are using Wifi or an static IP address setup, we need to change some configuration settings in this image so that the Mender client can successfully reach your Mender server.
First set a shell variable describing the image name, by replacing
<sdimg> in this snippet:
This section assumes you use a static IP setup, for example if you are plugging your device directly into your workstation with an Ethernet cable. If your device uses a DHCP setup, this section can be skipped.
In this section, we assume that
$IP_OF_MENDER_SERVER_FROM_DEVICE are the IP address you assign to your device.
If you are using
bash, you can set variables before running the command
below, for example
Run the command below to fill the
networking configuration files of the rootfs partitions:
echo -n "\ [Match] Name=eth0 [Network] Address=$IP_OF_MENDER_CLIENT Gateway=$IP_OF_MENDER_SERVER_FROM_DEVICE " | mender-artifact cp - $MENDER_IMGPATH:/etc/systemd/network/eth.network
If you have a static IP address setup for several devices, you need several disk images so each get different IP addresses.
The raspberrypi demo image comes with Wifi connectivity enabled by default, thus the only thing needed in order for your device to connect to your network is setting the correct
<password> in the
firstname.lastname@example.org file on your device. First set your
<ssid> path as shell variables:
And then running:
mender-artifact cat "$MENDER_IMGPATH":/etc/wpa_supplicant/wpa_supplicant-nl80211-wlan0.conf | sed "s#psk=\"password\"#psk=\"$NW_PASSWORD\"#" | sed "s#ssid=\"ssid\"#ssid=\"$NW_SSID\"#" > tmpf; mender-artifact cp tmpf "$MENDER_IMGPATH":/etc/wpa_supplicant/wpa_supplicant-nl80211-wlan0.conf && rm tmpf
should have your wpa configuration set up correctly on start up.
Please see Write the disk image to the SD card
for steps how to provision the device disk using the
image you downloaded and modified above.
If you have several devices, please write the disk image to all their SD cards.
Make sure that the Mender server is running as described in Install a Mender demo server and that the device can reach it on the IP address you configured above (
$IP_OF_MENDER_SERVER_FROM_DEVICE). You might need to set a static IP address where the Mender server runs and disable any firewalls.
First, insert the SD card you just provisioned into the device. Then connect the device to power.
You need to connect a USB keyboard and an HDMI monitor at least for the first boot.
Once the device has booted, log in. On Raspbian, the default user is "pi", and the password is "raspberry".
If you want to enable SSH on startup for further boots, execute'
sudo systemctl start ssh
Once you have logged in, run the Mender setup command, like this:
sudo mender setup
This will start the text based interactive setup of the Mender client. Below you can see a typical session, with example answers given throughout.
Mender Client Setup =================== Setting up the Mender client: The client will regularly poll the server to check for updates and report its inventory data. Get started by first configuring the device type and settings for communicating with the server. The device type property is used to determine which Mender Artifact are compatible with this device. Enter a name for the device type (e.g. raspberrypi3-raspbian): [raspberrypi] Are you connecting this device to hosted.mender.io? [Y/n] n Demo mode uses short poll intervals and assumes the default demo server setup. (Recommended for testing.) Do you want to run the client in demo mode? [Y/n] y Set the IP of the Mender Server: [127.0.0.1] 184.108.40.206 Mender setup successfully.
In the question about "IP of the Mender Server", use the value of
$IP_OF_MENDER_SERVER_FROM_DEVICE that you defined earlier. It is not possible
to use the variable itself in the setup, you have to type the IP value. In the
example above, the value is
220.127.116.11, but it will be different in your setup.
After the setup has been done, restart the client with the following command:
sudo systemctl restart mender-client
If you refresh the Mender server UI (by default found at https://localhost/), you should see one or more devices pending authorization. If you do not see your device listed in the UI, please review troubleshooting steps.
Once you authorize these devices, Mender will auto-discover inventory about the devices, including the device type (e.g. beaglebone) and the IP addresses, as shown in the example with a BeagleBone Black below. Which information is collected about devices is fully configurable; see the documentation on Identity and Inventory for more information.
If your device does not show up for authorization in the UI, you need to
diagnose what went wrong. Most commonly this is due to problems with the
network. You can test if your workstation can reach the device by trying to ping
it, e.g. with
ping 192.168.10.2 (replace with the IP address of your
device). If you can reach the device, you can ssh into it, e.g.
ssh email@example.com, or connect a USB keyboard and a HDMI monitor to it to have
direct access. Check the log output from Mender with
journalctl -u mender-client. If you get stuck, please feel free to reach
out on the Mender Hub discussion forum!
Now upgrade or install custom software on your golden device. This represents the update that will be sent to the rest of your device fleet.
For example, upgrade all packages of your Raspbian OS with:
sudo apt-get update && sudo apt-get dist-upgrade
In addition, you can install other packages or copy your own application files over SSH.
In this section, we assume that
$IP_OF_MENDER_CLIENT is the IP address of your
If you are using
bash, you can set a variable before running the command
below, for example
IP_OF_MENDER_CLIENT="192.168.10.2". If you don't know
hostname -I on your device.
This section will create a Mender Artifact from a running device using the snapshots feature of Mender. See Snapshots to learn more details about this feature.
First you need to start SSH service in your device. For Raspbian image, start it with:
sudo systemctl start ssh
For Yocto based images, it is enabled and started by default.
Now we will create the Mender Artifact. Run from your workstation:
mender-artifact write rootfs-image -f ssh://pi@$IP_OF_MENDER_CLIENT -n my_update_release_1 -o my_update_release_1.mender -t raspberrypi3
my_update_release_1 to the desired Artifact name and
to the device type you selected during Run Mender setup
This command will create a file
my_update_release_1.mender which is a Mender
Artifact containing the golden image currently running software.
Before we can deploy the Artifact we prepared above, it needs to be uploaded to the server.
Go to the Mender server UI, click the Releases tab and upload this Artifact.
Take now a new device that will play the role of the remote device. Follow again the previous steps to Prepare the disk image, Write the disk image to the SD card, Boot the device, Run Mender setup and See the device in the Mender UI
If you have only one device, just reflash it again and use it as if it was your second remote device.
Now that we have the device connected and the Artifact uploaded to the server, all that remains is to go to the Deployments tab and click Create a deployment.
Select the Artifact you just uploaded and All devices, then Create deployment.
If you deploy across several device types (e.g.
raspberrypi), the Mender server will skip these if no compatible artifact
is available. This condition is indicated by the noartifact status in the
deployment report. Mender does this to avoid deployments of incompatible
rootfs images. However, if you have Artifacts for these other device types,
identified by the same Artifact name, then Mender will deploy to all the
devices there are compatible Artifacts for.
As the deployment progresses, you can click on it to view more details about the current status across all devices. In the example below, we can see that a BeagleBone is installing the update.
Once the deployment completes, you should see its report in Past deployments.
Congratulations! You have used the Mender server to deploy your first physical device update!
In order to deploy another update, we need to create another Artifact with a different Artifact Name (than the one already installed at the devices). This is because Mender skips a deployment for a device if it detects that the Artifact is already installed, in order to avoid unnecessary deployments.
You can do this by making more changes on your golden device and then repeating the steps at Generate an Artifact from the golden device.
Alternatively, to change the name of our existing Artifact, we can simply use
modify and the
-n option of the
mender-artifact tool, first making a copy
of the original. To do this, run these two commands (adjust the Artifact file
cp my_update_release_1.mender my_update_release_2.mender mender-artifact modify my_update_release_2.mender -n release-2
mender-artifact modify, you can easily modify several configuration settings in existing disk image (
.sdimg) and Mender Artifact (
.mender) files, such as the server URI and certificate. See
mender-artifact help modify for more options.
mender-artifact modify command only supports modifying ext4 payloads.
Upload this modified Artifact file to your Mender server and deploy it to your device. You should see that the Artifact Name has changed after the deployment. Now that you have two Mender Artifact files that are configured for your network with different names, you can deploy updates back and forth between them.
Now that you have seen how Mender works with a reference board, you might be wondering what it would take to port it to your own board.
To get support for robust system updates with rollback, Mender must be integrated with production boards.
On the other hand, if you only need support for application updates (not full system updates), no board integration is required. In this case you can install Mender on an existing device and OS by following the documentation on installing the Mender client.