You are browsing documentation for a version other than the latest stable release. Switch to the latest stable release, 2.3.
mender-convert can be used to convert existing disk images for use with
Mender. It will generate a new disk image with two rootfs partitions, install a
bootloader that supports booting either of the root partitions and install the
Mender client and its configuration.
The output of
The recommended workflow for using
mender-convert is to rely on a golden disk
image that should be replicated in a robust way to many devices. The steps in
this workflow are:
mender-convert(continue reading for details)
Note that your golden device or SD card is not running Mender and is not modified during deployments. It is simply the "source" for generating the Artifacts that you deploy to the devices in the field.
In order to create another OTA update, the device with the golden image is booted again, i.e. the steps from 2. and onwards are carried out again.
mender-convert is currently tested on BeagleBone and Raspberry Pi3, using
official Debian or Raspbian images. The intention is to extend and test
mender-convert to cover more boards and OSes and finally make it
The amount of disk space needed depends on the size of your original raw disk image.
You should have at least 4 x the size of the raw disk image available.
For example, if your raw disk image is 4 GB, you should have at least 16 GB free disk space on your workstation where you are running
As described in the workflow above, you need a raw disk image as input to
mender-convert. This is the image that contains the root file system you want to deploy to many devices. Note that this must be a complete disk image (usually they have a
Board manufacturers typically provide a disk image for you to start with so you can download and use
mender-convert directly on this image.
If you have made run-time modifications on your device and want to copy the image from an existing SD card, insert it into your workstation and run the following command:
dd if=<DEVICE> of=golden-image-1.img bs=1M conv=fdatasync
<DEVICE> with the location of your SD card. Normally this would be something like
Follow the documentation to install Docker Engine, version 17.03 or later.
Invoking the docker commands may fail when the local user has insufficient
permissions to connect to the docker daemon. In Ubuntu 18.04, the user must be a
member of the
docker group to be able to access it. Please check the
documentation for your host OS if you encounter connection issues with docker.
mender-convert from the official repository:
git clone -b 1.2.0 https://github.com/mendersoftware/mender-convert.git
Change directory to where you downloaded
Then, run the following command to build the container based on Ubuntu 18.04 with all required dependencies for
Move your golden disk image into an input subdirectory:
mkdir -p input mv <PATH_TO_MY_GOLDEN_IMAGE> input/golden-image-1.img
Then adjust to the correct paths below and run the conversion:
DEVICE_TYPE="raspberrypi3" RAW_DISK_IMAGE="input/golden-image-1.img" ARTIFACT_NAME="golden-image-1-mender-integ" MENDER_DISK_IMAGE="golden-image-1-mender-integ.sdimg" TENANT_TOKEN="<INSERT-TOKEN-FROM Hosted Mender>" ./docker-mender-convert from-raw-disk-image \ --raw-disk-image $RAW_DISK_IMAGE \ --mender-disk-image $MENDER_DISK_IMAGE \ --device-type $DEVICE_TYPE \ --artifact-name $ARTIFACT_NAME \ --bootloader-toolchain arm-buildroot-linux-gnueabihf \ --server-url "https://hosted.mender.io" \ --tenant-token $TENANT_TOKEN
The conversion may take 10 minutes, depending on the resources available on your machine.
After a successful conversion, your images can be found in
The above invocation will use configuration defaults for use with the Hosted
Mender in production environment. If on premise server is used, then adjust
--server-url accordingly, and replace
--tenant-token option with
--server-cert option, specifying a valid path for the server certificate.
If instead you wish to use the Mender demo environment, execute the command with these parameters:
bash DEVICE_TYPE="raspberrypi3" RAW_DISK_IMAGE="input/golden-image-1.img" ARTIFACT_NAME="golden-image-1-mender-integ" MENDER_DISK_IMAGE="golden-image-1-mender-integ.sdimg" DEMO_HOST_IP="192.168.10.2" ./docker-mender-convert from-raw-disk-image \ --raw-disk-image $RAW_DISK_IMAGE \ --mender-disk-image $MENDER_DISK_IMAGE \ --device-type $DEVICE_TYPE \ --artifact-name $ARTIFACT_NAME \ --bootloader-toolchain arm-buildroot-linux-gnueabihf \ --demo \ --demo-host-ip $DEMO_HOST_IP