Provided by: autopkgtest_5.5ubuntu1_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 ttyS1, or

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

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

       --efi  Configure  QEMU with OVMF or AAVMF firmware images suitable for booting an x86, ARM
              or ARM64 virtual machine using EFI. This requires the ovmf, qemu-efi-arm  or  qemu-
              efi-aarch64 package. The correct firmware image is guessed from the --qemu-command.

       --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 vmdebootstrap(8) to build a suitable image. E. g. for unstable:

              vmdebootstrap --verbose --serial-console --distribution=sid \
                 --customize=/usr/share/autopkgtest/setup-commands/setup-testbed \
                 --user=test/test --size=10000000000 --grub --image=autopkgtest-sid.raw
              qemu-img convert -O qcow2 autopkgtest-sid.raw  autopkgtest-sid.img
              rm autopkgtest-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 AUTOPKGTEST_APT_PROXY to a proxy which
       will be used by apt in the VM. If you have an apt proxy configured on the host, this  will
       be used automatically; otherwise you can run e. g.

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

   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-buildvm-
       ubuntu-cloud(1), vmdebootstrap(8), /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.