man adt-virt-qemu (1): autopkgtest virtualisation server using QEMU

SYNOPSYS

adt-virt-qemu [options] image [ro-image ...]

DESCRIPTION

adt-virt-qemu provides an autopkgtest virtualisation server using QEMU.

Normally adt-virt-qemu will be invoked by adt-run.

You always need to specify at least one QEMU VM image. If your VM needs more disks, you can specify arbitrarily many additional images which will be added in order.

adt-virt-qemu does not modify the given images, but will instead create a temporary overlay for the primary image, and add all other images as read-only.

REQUIREMENTS

adt-virt-qemu assumes that you have already prepared a suitable Debian based QEMU image (see BUILDING IMAGES below for how to create them). but you can use any VM which satisfies one of:

*: They open a root shell on ttyS1, or
*: They have a serial console on ttyS0 where you can log in (getty or similar) with specified user and password. This will then be used to start a root shell on ttyS1, to reduce this to the first case and to not assume that ttyS0 stays operational throughout the whole test.

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 ttyS1 this will be also used for logging in on ttyS0. 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 above user for logging into the VM on ttyS0. This is necessary if the VM is not already prepared to start a root shell on ttyS1.

-q command | --qemu-command=command

QEMU command to run. This defaults to the qemu-system-* that matches your system architecture.

-o dir | --overlay-dir=dir

Directory where the temporary image overlay for the primary image is created. By default this will happen 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 1024, i. e. 1 GiB.

-d | --debug

Enable debugging output.

--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

: adt-run [...] --- adt-virt-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.

INPUT, OUTPUT AND EXIT STATUS

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

NOTES

adt-run 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).

BUILDING IMAGES

Debian

For Debian you can use vmdebootstrap(8) to build a suitable image. E. g. for unstable:

: vmdebootstrap --verbose --serial-console --distribution=sid \

--customize=/usr/share/autopkgtest/adt-setup-vm \

--user=adt/adt --size=10000000000 --image=adt-sid.raw
qemu-img convert -O qcow2 adt-sid.raw adt-sid.img
rm adt-sid.raw

vmdebootstrap can only create a raw format image; it is recommended to convert it to qcow2 as that is much smaller (in the order of 700 MB for qcow2 vs. the 10 GB as specified above) and also supports additional features such as snapshots or compression. You can run that command with setting the environment variable ADT_APT_PROXY to a proxy which will be used by apt in the VM. If you have apt-cacher-ng installed on the host, this will be used automatically; otherwise you can run e. g.

: ADT_APT_PROXY=http://10.0.2.2:8080 vmdebootstrap [...]

Ubuntu

For Ubuntu, autopkgtest provides adt-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:

: adt-buildvm-ubuntu-cloud -v -a i386

This will produce e. g. adt-trusty-i386-cloud.img.

EXAMPLE

Run the tests of the libpng source package, using an Ubuntu cloud image:

: adt-run libpng --- adt-virt-qemu adt-trusty-i386-cloud.img

AUTHORS AND COPYRIGHT

adt-virt-qemu was written by Martin Pitt <[email protected]>

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