Testing with QEMU¶
You can try an Armbian image without a board. QEMU runs the image in a virtual machine on your own computer, which is a quick way to check that an image boots, has network, and accepts SSH before you flash it to real hardware.
This page covers the two cases that come up most:
- a ready-made
uefi-x86cloud image from the download page, run with UEFI firmware, - an image you built yourself for one of the QEMU board targets, run with U-Boot firmware.
Note
A QEMU test only proves the image itself works. It does not test real board hardware, board-specific drivers, or how the board boots from its own storage. Always test on the real board before you call an image good.
What you need¶
- A Linux host. The commands below use Debian or Ubuntu.
- QEMU and, for the UEFI test, the OVMF firmware package.
- An Armbian image: either a downloaded
uefi-x86cloud image, or an image you built for a QEMU board target.
Quick test: a ready-made UEFI cloud image¶
1. Install QEMU and OVMF¶
| Bash | |
|---|---|
2. Download the image¶
Get the current uefi-x86 cloud image from
the UEFI x86 download page.
Pick the cloud file with the qcow2 ending. The file names look like
this, with the version, release, and kernel changing over time:
| Text Only | |
|---|---|
Use the file name you actually downloaded in the command below. Do not copy a file name from an old example: names go stale with every release.
3. Run it¶
A QEMU window opens and the image boots, just like on real hardware.
When you are done, log in and run poweroff, or just close the window.
What each switch does¶
-bios /usr/share/ovmf/OVMF.fdboots the machine with UEFI firmware from the OVMF package. The cloud image needs UEFI, not the old BIOS boot.-m 2048gives the virtual machine 2048 MB of RAM.-display gtk,gl=onshows the guest screen in a GTK window, with OpenGL turned on.-device virtio-net,netdev=net0plugs in a fast virtio network card, connected to a network callednet0.-netdev user,id=net0,hostfwd=tcp:127.0.0.1:5800-:22gives that network user-mode networking, and forwards port 5800 on your host to port 22 (SSH) inside the guest. The127.0.0.1before the port binds the forward to your own computer only, so no other machine can reach the guest over SSH. That is how you reach the guest with SSH.-drive if=none,id=root,file=...,format=qcow2attaches your image file as a drive calledroot, and tells QEMU it is in qcow2 format.-device virtio-blk,drive=rootplugs that drive into the machine as a fast virtio block device, so the guest can boot from it.
Logging in¶
Log in on the graphical window, or over SSH from your host:
| Bash | |
|---|---|
The password is 1234. First boot asks you to set a new root password
and create your own user account, the same as on real hardware. See
First boot and login.
A login prompt on the graphical window only proves the image boots. The quick test has passed only after you log in over SSH with the command above: a successful SSH login proves the image boots, has network, and accepts SSH.
Test an image you built: the QEMU board targets¶
The build framework ships three board targets made for exactly this. None of them are published on the download page, so build one yourself:
qemu-uefi-x86boots with UEFI, like the cloud image above. Run it with the OVMF command from the previous section.qemu-uboot-x86boots through U-Boot on x86. The build also writes au-boot.romfile next to the image, which QEMU uses as firmware with-bios.qemu-uboot-arm64boots through U-Boot on the ARMvirtmachine. The build writes au-boot.binfile next to the image for the same purpose.
Build one like any other board, for example:
| Bash | |
|---|---|
Add ENABLE_EXTENSIONS=image-output-qcow2 for all three targets.
Without it, the build writes only a raw .img file, and the .img.qcow2
file the QEMU commands below expect does not exist.
See Getting started for the full build setup.
U-Boot on x86¶
On Linux with KVM acceleration:
| Bash | |
|---|---|
Replace <version> with the version of the image you built. -nographic
means there is no window: the serial console runs in your terminal.
-accel kvm needs KVM on a Linux x86 host.
On macOS, drop -accel kvm. The macOS accelerator hangs U-Boot, so
plain emulation is used instead, which is slow but works:
| Bash | |
|---|---|
U-Boot on ARM64¶
With virtio networking and storage:
| Bash | |
|---|---|
On a supported ARM64 host, try adding -accel kvm to the same command
for faster emulation. With an NVMe disk instead of virtio storage:
| Bash | |
|---|---|
Log in at the serial console in your terminal: root with password
1234 on first boot, then set a new password when asked. These commands
forward no host port to the guest, so SSH from your host does not work
here.
Other ways to test: Incus¶
Incus can also run the same qcow2 image as a virtual machine, if you prefer it over QEMU. This page does not give an Incus recipe yet. See the Incus documentation if you want to try it.
Producing your own qcow2 image from a build, and an automated check that an image boots, has network, and accepts SSH, are follow-ups that are not covered here yet.