Provided by: autopkgtest_5.25ubuntu1_all bug

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 1024, i. e. 1 GiB.

       --timeout-reboot=SECONDS
              Timeout for waiting for reboot. Default is 60 seconds.

       --show-boot
              Show boot messages from serial console.

       -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

SEE ALSO

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

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.