xref: /openbmc/qemu/tests/vm/README (revision 44b1ff31) 
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