QEMU, the FAST! processor emulator (Ubuntu)

Board description

QEMU (short for Quick Emulator ) is a free and open-source emulator that performs hardware virtualization.

QEMU is a hosted virtual machine monitor, it emulates the machine’s processor through dynamic and provides a set of different hardware and device models for the machine, enabling it to run a variety of guest operating systems. It also can be used with KVM to run virtual machines at near-native speed (by taking advantage of hardware extensions such as Intel VT-x).

QEMU machines are something that we at Mender use heavily during development and this is also the primary target for our integration tests.

URL: https://qemu.weilnetz.de/doc/qemu-doc.html
Wiki: https://wiki.qemu.org/Documentation

Test results

The Ubuntu releases in the table below have been tested by the Mender community. Please update it if you have tested this integration on other Ubuntu releases.

Debian Build Runtime
Ubuntu-Bionic-x86-64 :test_works: :test_works:

Build Means that the image generation completes without errors and outputs images.
Runtime Means that Mender has been verified to work on the board.

Getting started

Convert your own image


  • A Linux-based laptop/workstation (Ubuntu has been verified to work)
  • You need to install Docker Engine to use this tutorial

Build Docker image for mender-convert

Open a terminal and clone the mender-convert repository, e.g.

git clone -b 2.0.x https://github.com/mendersoftware/mender-convert.git

Enter your mender-convert environment:

cd mender-convert

There is a utility script which can be used to generate the appropriate docker image to run mender-convert:


This will create a container image you can use to run mender-convert.

Download the pre-generated Ubuntu Bionic image

Download the raw Ubuntu disk image into a subdirectory input:

mkdir -p input
cd input
wget https://d1b0l86ne08fsf.cloudfront.net/mender-convert/images/Ubuntu-Bionic-x86-64.img.gz

Extract the raw Ubuntu disk image:

gunzip Ubuntu-Bionic-x86-64.img.gz && cd ..

Convert the Ubuntu disk image to support Mender

With the raw disk image and the container configured above, we can convert the

You can get your Mender Professional tenant token at the My organization page in Mender Professional.

Configure the Mender client for hosted Mender server:

./scripts/bootstrap-rootfs-overlay-hosted-server.sh \
    --output-dir ${PWD}/rootfs_overlay_demo \
    --tenant-token "Paste token from Mender Professional"

There are additional scripts in the scripts/ directory to configure with a local demo server, or production server.

Run mender-convert inside the container by running:

MENDER_ARTIFACT_NAME=release-1 ./docker-mender-convert \
    --disk-image input/Ubuntu-Bionic-x86-64.img \
    --config configs/qemux86-64_config \
    --overlay ./rootfs_overlay_demo

Conversion will take 10-15 minutes, depending on your storage and resources available.


You will need an SD card with an capacity of at least 8GB when using the default arguments. The SD card layout will be the following using the default arguments:

Part Type Purpose Size Configure size
sda1 vfat Store the bootloader 44MB MENDER_BOOT_PART_SIZE_MB
sda2 ext4 Store the root file system and kernel (active) 3908MB MENDER_STORAGE_TOTAL_SIZE_MB 1
sda3 ext4 Store the root file system and kernel (inactive) 3908MB MENDER_STORAGE_TOTAL_SIZE_MB 1
sd4 ext4 Store persistent data, preserved during Mender updates. 128MB MENDER_DATA_PART_SIZE_MB 2

1. The rootfs partition size is calculated using the following formula:

 (storage-total-size-mb - data-part-size-mb - boot-part-size) / 2

2. You rarely need to adjust the data part size using MENDER_DATA_PART_SIZE_MB as this will expanded on first boot to occupy the remaining free blocks of the SD card.

You can read more about the partition layout required for Mender here

Use the output images

After a successful conversion, the images and artifacts are:

  • deploy/Ubuntu-Bionic-x86-64-qemux86_64-mender.img.gz
  • deploy/Ubuntu-Bionic-x86-64-qemux86_64-mender.ext4
  • deploy/Ubuntu-Bionic-x86-64-qemux86_64-mender.mender

The disk image (with .sdimg.gz suffix) can be used to start a QEMU instance with Mender integrated. On the other hand, if you already have Mender running on your device and want to deploy a rootfs update from this conversion, you should use the Mender Artifact files, which have .mender suffix. You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in Standalone deployments.

Boot generated disk image using qemu-system-x86_64

First we need to unpack the disk image:

cd deploy
gunzip Ubuntu-Bionic-x86-64-qemux86_64-mender.img.gz
cd ..

Start the QEMU:

qemu-system-x86_64 -enable-kvm -m 512 -smp 2 -bios /usr/share/ovmf/x64/OVMF_CODE.fd -drive format=raw,file=deploy/Ubuntu-Bionic-x86-64-qemux86_64-mender.img

Login is: root / password

After about 10 minutes, you should see your device Pending authorization under the Devices tab in your Mender server. Authorize your device to join your Mender server.

You can now deploy software updates to your QEMU device using the Mender server!


  • The documentation on Building a Mender Debian image contains more information about using Mender with the Debian family of distributions.

  • The official Mender documentation explains how Mender works. This is simply a board-specific complement to the official documentation.

Known issues

If this post was useful to you, please press like, or leave a thank you note to the contributor who put valuable time into this and made it available to you. It will be much appreciated!

1 Like

10 posts were split to a new topic: Issue with connecting QEMU (Ubuntu) image to demo server

4 posts were split to a new topic: Issue with starting QEMU after conversion with mender-convert

3 posts were split to a new topic: Running mender-client-qemu