You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 1.3.

Deploy to physical devices

In this tutorial we will deploy a full rootfs update to a physical device, the Raspberry Pi 3 or BeagleBone Black, using the Mender server.


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 Deploy to virtual devices so that you have a basic understanding of how Mender works before moving on to connecting a physical device.

A device to test with

You need one or more BeagleBone Black or Raspberry Pi 3. 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 (1 GB or larger) per device.

Get the disk image and Artifacts for your device(s) from Download demo images.

It is possible to use this tutorial with any physical device, 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.

Network connectivity

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 telnet.

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 IP_OF_MENDER_SERVER_FROM_DEVICE="".

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.

Prepare the disk image

Please make sure to set a shell variable that expands correctly with $IP_OF_MENDER_SERVER_FROM_DEVICE or edit the commands below accordingly.

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 layout.

You can decompress it like the following:

gunzip <PATH-TO-YOUR-DISK-IMAGE>.sdimg.gz

Mender blocks free space in the disk image so that your root file system is allowed to grow over time. 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.

We need to change some configuration settings in this image so that the Mender client successfully connects to your Mender server when it starts.

Insert the address of Mender server

Please see Modifying a disk image for a description on how to mount partitions for editing within the disk image (*.sdimg).

We assume that both rootfs partitions are mounted read-write below, to /mnt/rootfs1 and /mnt/rootfs2. Then run the following commands to make the Mender client able to find the server when the Mender client starts:

echo "$IP_OF_MENDER_SERVER_FROM_DEVICE" | sudo tee -a /mnt/rootfs[12]/etc/hosts

You should see output similar to the following:

Set a static device IP address and subnet

This section assumes you use a static IP setup. If your device uses a DHCP setup, you can skip to Unmount the disk image. In this section, we assume that $IP_OF_MENDER_CLIENT is the IP address you assign to your device.

If you are using bash, you can set a variable before running the command below, for example IP_OF_MENDER_CLIENT="".

Run the command below to fill the systemd networking configuration files of the rootfs partitions:

echo -n "\

" | sudo tee /mnt/rootfs[12]/etc/systemd/network/

You should see output similar to the following:

[Match] Name=eth0

[Network] Address= Gateway=

If you have a static IP address setup for several devices, you need several disk images so each get different IP addresses. After unmounting (as described below), you can copy it and mount another one.

Unmount the disk image

It is very important to unmount the disk image after modifying it, so all changes are written to the image:

sudo umount /mnt/rootfs1 && sudo umount /mnt/rootfs2

If you do not properly unmount the disk image, changes may be lost or corrupted when it is written to flash.

Write the disk image to the SD card

Please see Write the disk image to the SD card for steps how to provision the device disk using the *.sdimg image you downloaded and modified above.

If you have several devices, please write the disk image to all their SD cards.

Boot the device

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.

For the BeagleBone Black only (N/A to Raspberry Pi 3): Before powering on the BeagleBone Black, please press the S2 button, as shown below. Keep the button pressed for about 5 seconds after connecting power. This will make the BeagleBone Black boot from the SD card instead of internal storage.

Booting BeagleBone Black from SD card

If the BeagleBone Black boots from internal storage, the rollback mechanism of Mender will not work properly. However, the device will still boot so this condition is hard to detect.

There is no need to press the S2 button when rebooting, just when power is lost and it is powered on again.

Now connect the device to power.

See the device in the Mender UI

If you refresh the Mender server UI (by default found at https://localhost/), you should see one or more devices pending authorization.

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.

Mender UI - Device information for BeagleBone Black

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 (replace with the IP address of your device). If you can reach the device, you can ssh into it, e.g. ssh root@ Otherwise, if you have a serial cable, you can log in to the device to diagnose. The root user is present and has an empty password in this test image. Check the log output from Mender with journalctl -u mender. If you get stuck, please feel free to reach out on the Mender community mailing list!

Prepare the Mender Artifact to update to

Please make sure to set shell variables that expand correctly with $IP_OF_MENDER_SERVER_FROM_DEVICE (always) and $IP_OF_MENDER_CLIENT (if you are using static IP addressing) or edit the commands below accordingly.

In order to deploy an update, we need a Mender Artifact to update to. A Mender Artifact is a file format that includes metadata like the checksum and name, as well as the actual root file system that is deployed. See Mender Artifacts for a complete description of this format.

Locate the release_1 demo Artifact file (.mender) for your device that you downloaded earlier.

Using the BeagleBone Black as an example below (adjust the directory and file names if you are using the Raspberry Pi 3), the steps needed to edit the root file system contained in this Artifact are:

mkdir beaglebone_release_1 && tar -C beaglebone_release_1 xvf beaglebone_release_1_1.2.1.mender
cd beaglebone_release_1 && tar zxvf data/0000.tar.gz
sudo mkdir /mnt/rootfs && sudo mount -t ext4 -o loop core-image-base-beaglebone.ext4 /mnt/rootfs/

Please see Modifying a Mender Artifact for a more detailed overview. For the following steps we assume that you have mounted core-image-base-beaglebone.ext4 to /mnt/rootfs.

We carry out exactly the same configuration steps for the rootfs image as we did for the rootfs partitions in the disk image above:

echo "$IP_OF_MENDER_SERVER_FROM_DEVICE" | sudo tee -a /mnt/rootfs/etc/hosts

You should see output similar to the following:

Finally, only if you are using static IP addressing, you need to set the device IP address, as shown below (otherwise skip this step). Please note that the same constraints as described in Set a static device IP address and subnet for the disk image apply here.

echo -n "\

" | sudo tee /mnt/rootfs/etc/systemd/network/

You should see output similar to the following:

[Match] Name=eth0

[Network] Address= Gateway=

The Mender client will roll back the deployment if it is not able to report the final update status to the server when it boots from the updated partition. This helps ensure that you can always deploy a new update to your device, even when fatal conditions like network misconfiguration occur.

You can also make any other modifications you wish in this image prior to deploying it.

Unmount the rootfs image

It is very important to unmount the rootfs image after modifying it, so all changes are written to the image:

sudo umount /mnt/rootfs

Create a new Mender Artifact with the modified rootfs

To create a Mender Artifact from a root file system, it is easiest to download the prebuilt mender-artifact tool available for Linux.

Download the tool and add execute permission (e.g. with chmod +x mender-artifact).

Using the BeagleBone Black as an example below (adjust the file names and use -t raspberrypi3 if you are using the Raspberry Pi 3), run the following command to create a new Mender Artifact:

mender-artifact write rootfs-image -u core-image-base-beaglebone.ext4 -t beaglebone -n release-1_1.2.1 -o beaglebone_release_1_configured.mender

where -u core-image-base-beaglebone.ext4 is the rootfs image we modified above, -t beaglebone is the device type compatible with the given Artifact, -n release-1_1.2.1 is the Artifact name (do not change this as it needs to be in sync with /etc/mender/artifact_info inside the rootfs), and -o beaglebone_release_1_configured.mender is the filename of the created Artifact.

Upload the artifact to the server

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 Artifacts tab and upload this Artifact.

Deploy the Artifact

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. beaglebone and vexpress-qemu), 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.

See the progress of the deployment

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.

Mender UI - Deployment progress - BeagleBone Black

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!

Deploy another update

In order to deploy another update, we can modify the original Artifact as described in Create a new Mender Artifact with the modified rootfs above.

However, note that the Artifact Name needs to change in the updated Artifact; a good candidate would be release-2. This is because Mender skips a deployment for a device if it detects that the Artifact is already installed. This needs to be changed in two places:

  • /etc/mender/artifact_info inside the root file system
  • the -n option to mender-artifact

Please make sure that the Artifact Name is in sync at these two places, otherwise deployments using this Artifact will always fail.

With that in mind, now might be a good time to tweak the rootfs, add some more Raspberry Pi 3 or BeagleBone Black devices to the environment and try to get the required blinkenlights going!

If you want to build your own artifact for the Raspberry Pi 3 or BeagleBone Black, head over to the tutorial Building a Mender Yocto Project image.

Integrate Mender with your device

Development devices like the Raspberry Pi 3 and BeagleBone Black are rarely used in production due to the cost of scaling and specific needs of custom applications.

Now that you have seen how Mender works with a reference device, you might be wondering what it would take to port it to your own platform. The first place to go is Device integration, where you will find out how to integrate the Mender client with your device software, and then look at Creating Artifacts to see how to build images ready to be deployed over the network to your devices.