autopkgtest-virt-qemu(1)

📦
version 6.0 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 autopkgtest-virt-qemu 💖

okay so bestie, welcome to the General Commands Manual entry for autopkgtest-virt-qemu(1) — she's the QEMU-based virtualisation server for autopkgtest and she is, genuinely, that girl. ✨

🌸 NAME 🌸

autopkgtest-virt-qemu — the autopkgtest virtualisation server that runs your tests inside QEMU 💅

🎀 SYNOPSIS 🎀

autopkgtest [...] -- qemu [options] image [ro-image ...]

🦋 DESCRIPTION 🦋

So basically autopkgtest-virt-qemu is the autopkgtest virtualisation server, but powered by QEMU. That's the whole vibe. 🔥

Normally you're not even calling her directly — autopkgtest-virt-qemu gets invoked by autopkgtest, like she's the main character's right hand. 👑

You always need to specify at least one QEMU VM image, no exceptions, that's non-negotiable. And if your VM is feeling extra and needs more disks? You can specify arbitrarily many additional images and they get added in order, one after the other. Slay.

Here's the part that matters: autopkgtest-virt-qemu does not modify the images you give her. Instead she creates a temporary overlay for the primary image, and adds all the other images as read-only. She respects your stuff. periodt. 💖

✨ REQUIREMENTS ✨

autopkgtest-virt-qemu assumes you've already prepared a suitable Debian based QEMU image (peep the BUILDING IMAGES section below for how to cook one up). But honestly you can use any VM that has python3 or python installed and does either of these:

  • opens a root shell on hvc1, or
  • opens a root shell on ttyS1 (x86 only), or
  • has a serial console on the first serial port where you can log in (getty or similar) with a specified user and password. This will then be used to start a root shell on hvc1 or ttyS1, to reduce this to the first case and to not assume that the first serial port stays operational throughout the whole test.

Depending on the CPU architecture, the first serial port might be ttyS0, ttyAMA0, hvc0 or something else. 🌀

💅 OPTIONS 💅

  • -u user | --user=user — User name for running tests that don't require root privileges.

If the VM is not already prepared to start a root shell on hvc1 or ttyS1, this will also be used for logging in on the first serial port. If this is not root, it must be able to run sudo without a password to become root for that purpose. 🔑

  • -p password | --password=password — Password for the above user for logging into the VM on the first serial port. This is necessary if the VM is not already prepared to start a root shell on hvc1 or ttyS1. 🤫
  • --qemu-architecture=ARCHITECTURE — Set the architecture according to qemu's vocabulary, for example x86_64 or ppc64le. The default is the --dpkg-architecture if specified, or guessed from the --qemu-command if specified, or the host system's architecture.
  • --dpkg-architecture=ARCHITECTURE — Set the architecture according to dpkg's vocabulary, for example amd64 or ppc64el. If both --qemu-architecture and --dpkg-architecture are specified, the --qemu-architecture takes precedence. 👑
  • -q command | --qemu-command=command — QEMU command to run. If not specified, this defaults to qemu-system-ARCHITECTURE for the architecture chosen by --qemu-architecture or --dpkg-architecture, or the host system's architecture.
  • -o dir | --overlay-dir=dir — Directory where the temporary image overlay for the primary image is created. By default this happens in a work directory in /tmp (or $TMPDIR), but you can use this to e. g. ensure that the overlay is placed on a tmpfs if your /tmp directory is not on tmpfs. This will greatly increase the speed. 🚀
  • -c num | --cpus=num" — Number of (virtual) CPUs in the VM. Default is 1.
  • --ram-size=MiB — VM RAM size in MiB. Default is 2048, i. e. 2 GiB. 🧠
  • --shared-dir=src=/host/path,dst=/guest/path[,rw] — Host directory to share with the guest. The directory SRC on the host will be mounted read-only at DST within the guest. Use 'rw' to mount read-write. This option can be passed multiple times. 🫶
  • --timeout-reboot=SECONDS — Timeout for waiting for reboot. Default is 60 seconds. ⏰
  • --show-boot — Show boot messages from serial console. 👀
  • --timeout-poweroff — Rather than terminating the VM process, initiate poweroff from within the VM, and terminate only when timeout occurs. This can be useful where host devices are shared with the VM, and a clean poweroff is necessary for the host device to be re-initialized by the next test. 🔌
  • -d | --debug — Enable debugging output. 🐛
  • --baseimage — Add a read-only copy of the first image without the overlay as an additional read-only hard drive, which will be available for tests as /dev/baseimage. This allows tests that require nested VMs to reuse the same image.
⚠️ Be aware that /dev/baseimage will not be accessible between calling autopkgtest-reboot-prepare and the next boot, thus make sure to stop accessing it before.
  • --boot=auto|bios|efi|ieee1275|none — Select how the qemu virtual machine will boot the image.

auto chooses a suitable boot mode for the architecture, and is the default.

bios, ieee1275 and none do not do anything special, and assume the image is bootable by a default qemu configuration. auto is equivalent to one of these options on amd64, i386, ppc64el and unknown architectures.

efi loads EFI firmware on supported architectures, currently meaning amd64, arm64, armhf or i386. The --efi option is an alias for this mode. auto selects this mode on arm64 or armhf. This requires the ovmf, qemu-efi-arm or qemu-efi-aarch64 package, as appropriate for the architecture. ✨

  • --qemu-options=arguments — Pass through arguments to QEMU command; e. g. --qemu-options='-readconfig qemu.cfg'

🍓 CONFIGURATION FILES 🍓

If you use lots of options or images, you can put parts of, or the whole command line into a text file, with one line per option. E. g. you can create a file sid-desktop.cfg with contents like

-utestuser
-ps3kr1t
--ram-size=4096
/home/bob/autopkgtest/sid-desktop.img

and then run

autopkgtest [...] -- qemu @sid-desktop.cfg

The contents of the configuration file will be expanded in-place as if you would have given its contents on the command line.

🙈 Please ensure that you don't place spaces between short options and their values — they would become a part of the argument value. like. don't do that bestie.

🌈 INPUT, OUTPUT AND EXIT STATUS 🌈

The behaviour of autopkgtest-virt-qemu is as described by the AutomatedTesting virtualisation regime specification. iykyk 📜

⭐ NOTES ⭐

autopkgtest does not run apt-get update at the start of a package build, which can cause a build failure if you are using a development series template. You will need to run apt-get update in the template yourself (e. g. using --setup-commands). 😭

If the --qemu-command option has not been specified and no custom CPU type was selected in --qemu-options, autopkgtest-virt-qemu will try to enable nested KVM support by default on x86_64 platforms if the hardware supports this. To fully enable this, one needs to additionally set some module parameters on the host, by creating a file /etc/modprobe.d/nested_kvm.conf with the contents

options kvm_intel nested=1
options kvm_amd   nested=1

and rebooting or reloading the KVM modules. It is still possible to use QEMU in tests without this, albeit without hardware acceleration. On Ubuntu systems these module options are typically already set. 🐧

🧚 BUILDING IMAGES 🧚

💜 Debian

For Debian you can use autopkgtest-build-qemu(1) to build a suitable image. E. g. for unstable:

autopkgtest-build-qemu unstable autopkgtest-unstable.img

See autopkgtest-build-qemu(1) for more information.

💙 Ubuntu

For Ubuntu, autopkgtest provides autopkgtest-buildvm-ubuntu-cloud(1) to build a VM based on the Ubuntu cloud images. To create an image for the current development series and the i386 architecture:

autopkgtest-buildvm-ubuntu-cloud -v -a i386

This will produce e. g. autopkgtest-trusty-i386-cloud.img. 🦋

👑 EXAMPLE 👑

Run the tests of the gdk-pixbuf source package, using an Ubuntu cloud image:

autopkgtest gdk-pixbuf -- qemu autopkgtest-trusty-i386-cloud.img

🌸 SEE ALSO 🌸

autopkgtest(1), autopkgtest-schroot(1), autopkgtest-virt-lxc(1), autopkgtest-build-qemu(1), autopkgtest-buildvm-ubuntu-cloud(1), /usr/share/doc/autopkgtest/.

autopkgtest-virt-qemu was written by Martin Pitt <martin.pitt@ubuntu.com> 🫶

This manpage is part of autopkgtest, a tool for testing Debian binary packages. autopkgtest is Copyright (C) 2006-2014 Canonical Ltd and others.

See /usr/share/doc/autopkgtest/CREDITS for the list of contributors and full copying conditions. 📝

and that's the whole page bestie!! this one comes to you straight out of the Linux Programmer's Manual, dated 2014, filed under autopkgtest-virt-qemu(1) — no cap, she ate and left no crumbs. 💅✨🎀

📦 where this page comes from