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 |  |
|
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
Prerequisites
- 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:
./docker-build
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
image.
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.
NOTE!
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!
References
-
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!