tests/vm/README

=== VM test suite to run build in guests ===

== Intro ==

This test suite contains scripts that bootstrap various guest images that have
necessary packages to build QEMU. The basic usage is documented in Makefile
help which is displayed with "make vm-test".

== Quick start ==

Run "make vm-test" to list available make targets. Invoke a specific make
command to run build test in an image. For example, "make vm-build-freebsd"
will build the source tree in the FreeBSD image. The command can be executed
from either the source tree or the build dir; if the former, ./configure is not
needed. The command will then generate the test image in ./tests/vm/ under the
working directory.

Note: images created by the scripts accept a well-known RSA key pair for SSH
access, so they SHOULD NOT be exposed to external interfaces if you are
concerned about attackers taking control of the guest and potentially
exploiting a QEMU security bug to compromise the host.

== QEMU binary ==

By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
isn't one, or if it is older than 2.10, the test won't work. In this case,
provide the QEMU binary in env var: QEMU=/path/to/qemu-2.10+.

== Make jobs ==

The "-j$X" option in the make command line is not propagated into the VM,
specify "J=$X" to control the make jobs in the guest.

== Debugging ==

Add "DEBUG=1" and/or "V=1" to the make command to allow interactive debugging
and verbose output. If this is not enough, see the next section.

== Manual invocation ==

Each guest script is an executable script with the same command line options.
For example to work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:

    $ cd $QEMU_SRC/tests/vm

    # To bootstrap the image
    $ ./netbsd --build-image --image /var/tmp/netbsd.img
    <...>

    # To run an arbitrary command in guest (the output will not be echoed unless
    # --debug is added)
    $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a

    # To build QEMU in guest
    $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC

    # To get to an interactive shell
    $ ./netbsd --interactive --image /var/tmp/netbsd.img sh

== Adding new guests ==

Please look at existing guest scripts for how to add new guests.

Most importantly, create a subclass of BaseVM and implement build_image()
method and define BUILD_SCRIPT, then finally call basevm.main() from the
script's main().

  - Usually in build_image(), a template image is downloaded from a predefined
    URL. BaseVM._download_with_cache() takes care of the cache and the
    checksum, so consider using it.

  - Once the image is downloaded, users, SSH server and QEMU build deps should
    be set up:

    * Root password set to BaseVM.ROOT_PASS
    * User BaseVM.GUEST_USER is created, and password set to BaseVM.GUEST_PASS
    * SSH service is enabled and started on boot,
      $QEMU_SRC/tests/keys/id_rsa.pub is added to ssh's "authorized_keys" file
      of both root and the normal user
    * DHCP client service is enabled and started on boot, so that it can
      automatically configure the virtio-net-pci NIC and communicate with QEMU
      user net (10.0.2.2)
    * Necessary packages are installed to untar the source tarball and build
      QEMU

  - Write a proper BUILD_SCRIPT template, which should be a shell script that
    untars a raw virtio-blk block device, which is the tarball data blob of the
    QEMU source tree, then configure/build it. Running "make check" is also
    recommended.