Ubuntu Manpage: autopkgtest-virt-qemu - autopkgtest virtualisation server using QEMU

Provided by: autopkgtest_5.47~24.04.1_all

NAME

       autopkgtest-virt-qemu - autopkgtest virtualisation server using QEMU

SYNOPSIS

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

DESCRIPTION

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

       Normally autopkgtest-virt-qemu will be invoked by autopkgtest.

       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.

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

       autopkgtest-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  has  python3  or  python
       installed and either

       *   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 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 be also 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 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 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 2048, i. e. 2 GiB.

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

INPUT, OUTPUT AND EXIT STATUS

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

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

AUTHORS AND COPYRIGHT

       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.

Linux Programmer's Manual                             2014                              autopkgtest-virt-qemu(1)