1=== VM test suite to run build in guests === 2 3== Intro == 4 5This test suite contains scripts that bootstrap various guest images that have 6necessary packages to build QEMU. The basic usage is documented in Makefile 7help which is displayed with "make vm-test". 8 9== Quick start == 10 11Run "make vm-test" to list available make targets. Invoke a specific make 12command to run build test in an image. For example, "make vm-build-freebsd" 13will build the source tree in the FreeBSD image. The command can be executed 14from either the source tree or the build dir; if the former, ./configure is not 15needed. The command will then generate the test image in ./tests/vm/ under the 16working directory. 17 18Note: images created by the scripts accept a well-known RSA key pair for SSH 19access, so they SHOULD NOT be exposed to external interfaces if you are 20concerned about attackers taking control of the guest and potentially 21exploiting a QEMU security bug to compromise the host. 22 23== QEMU binary == 24 25By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there 26isn't one, or if it is older than 2.10, the test won't work. In this case, 27provide the QEMU binary in env var: QEMU=/path/to/qemu-2.10+. 28 29== Make jobs == 30 31The "-j$X" option in the make command line is not propagated into the VM, 32specify "J=$X" to control the make jobs in the guest. 33 34== Debugging == 35 36Add "DEBUG=1" and/or "V=1" to the make command to allow interactive debugging 37and verbose output. If this is not enough, see the next section. 38 39== Manual invocation == 40 41Each guest script is an executable script with the same command line options. 42For 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 62Please look at existing guest scripts for how to add new guests. 63 64Most importantly, create a subclass of BaseVM and implement build_image() 65method and define BUILD_SCRIPT, then finally call basevm.main() from the 66script'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. 90