tests/vm/README

   1 === VM test suite to run build in guests ===
   2
   3 == Intro ==
   4
   5 This test suite contains scripts that bootstrap various guest images that have
   6 necessary packages to build QEMU. The basic usage is documented in Makefile
   7 help which is displayed with "make vm-test".
   8
   9 == Quick start ==
  10
  11 Run "make vm-test" to list available make targets. Invoke a specific make
  12 command to run build test in an image. For example, "make vm-build-freebsd"
  13 will build the source tree in the FreeBSD image. The command can be executed
  14 from either the source tree or the build dir; if the former, ./configure is not
  15 needed. The command will then generate the test image in ./tests/vm/ under the
  16 working directory.
  17
  18 Note: images created by the scripts accept a well-known RSA key pair for SSH
  19 access, so they SHOULD NOT be exposed to external interfaces if you are
  20 concerned about attackers taking control of the guest and potentially
  21 exploiting a QEMU security bug to compromise the host.
  22
  23 == QEMU binary ==
  24
  25 By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
  26 isn't one, or if it is older than 2.10, the test won't work. In this case,
  27 provide the QEMU binary in env var: QEMU=/path/to/qemu-2.10+.
  28
  29 == Make jobs ==
  30
  31 The "-j$X" option in the make command line is not propagated into the VM,
  32 specify "J=$X" to control the make jobs in the guest.
  33
  34 == Debugging ==
  35
  36 Add "DEBUG=1" and/or "V=1" to the make command to allow interactive debugging
  37 and verbose output. If this is not enough, see the next section.
  38
  39 == Manual invocation ==
  40
  41 Each guest script is an executable script with the same command line options.
  42 For example to work with the netbsd guest, use $QEMU_SRC/tests/vm/netbsd:
  43
  44     $ cd $QEMU_SRC/tests/vm
  45
  46     # To bootstrap the image
  47     $ ./netbsd --build-image --image /var/tmp/netbsd.img
  48     <...>
  49
  50     # To run an arbitrary command in guest (the output will not be echoed unless
  51     # --debug is added)
  52     $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
  53
  54     # To build QEMU in guest
  55     $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
  56
  57     # To get to an interactive shell
  58     $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
  59
  60 == Adding new guests ==
  61
  62 Please look at existing guest scripts for how to add new guests.
  63
  64 Most importantly, create a subclass of BaseVM and implement build_image()
  65 method and define BUILD_SCRIPT, then finally call basevm.main() from the
  66 script's main().
  67
  68   - Usually in build_image(), a template image is downloaded from a predefined
  69     URL. BaseVM._download_with_cache() takes care of the cache and the
  70     checksum, so consider using it.
  71
  72   - Once the image is downloaded, users, SSH server and QEMU build deps should
  73     be set up:
  74
  75     * Root password set to BaseVM.ROOT_PASS
  76     * User BaseVM.GUEST_USER is created, and password set to BaseVM.GUEST_PASS
  77     * SSH service is enabled and started on boot,
  78       $QEMU_SRC/tests/keys/id_rsa.pub is added to ssh's "authorized_keys" file
  79       of both root and the normal user
  80     * DHCP client service is enabled and started on boot, so that it can
  81       automatically configure the virtio-net-pci NIC and communicate with QEMU
  82       user net (10.0.2.2)
  83     * Necessary packages are installed to untar the source tarball and build
  84       QEMU
  85
  86   - Write a proper BUILD_SCRIPT template, which should be a shell script that
  87     untars a raw virtio-blk block device, which is the tarball data blob of the
  88     QEMU source tree, then configure/build it. Running "make check" is also
  89     recommended.