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

name
synopsis
description
requirements
options
configuration files
input, output and exit status
notes
building images
example
see also
authors and copyright

Provided by: autopkgtest_5.3.1ubuntu1.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.

       The  first image without the overlay is always added 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.

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.

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

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.