view tools/xm-test/README @ 0:7d21f7218375

Exact replica of unstable on 051908 + README-this
author Mukesh Rathor
date Mon May 19 15:34:57 2008 -0700 (2008-05-19)
children b22f9ab1716a
line source
2 xm-test README
4 Copyright (C) International Business Machines Corp., 2005
5 Author(s): Dan Smith <>
6 Woody Marvel <>
8 Overview
9 ========
11 This suite provides a framework for testing the Xen userspace tools.
12 The directory structure is:
14 ./xm-test
15 |
16 +-/lib: Python support libraries
17 |
18 +-/ramdisk: Staging area for building the test ramdisk
19 |
20 +-/tests
21 | |
22 | +-/create: Tests for the 'xm create' command
23 | +-/destroy: Tests for the 'xm destroy' command
24 | . . .
25 |
26 +-/utils: Utility scripts for ramdisk building
28 Reports are posted here:
33 Building
34 ========
36 Before the test suite can be used, the ramdisk must be built from
37 source. All source needed for this process is automatically
38 downloaded, extracted, and compiled. Due to the need to create
39 special files, this process must be done as root:
41 # ./autogen
42 # ./configure
43 # make
45 NB: If you have the initrd.img from another installation of xm-test,
46 you can copy it into the ramdisk directory to eliminate the need to
47 rebuild it. If you do this, there is no need to run 'make' again.
48 Simply copy the initrd-X.Y-ARCH.img file into ramdisk/ and then run:
50 # make existing
52 Or, you can run:
53 # INITRD="http://url.of.initrd.repo/" make existing
55 You do not need to include the name of the image itself in the url,
56 however, an initrd with the right name (initrd.X.Y-ARCH.img) and version
57 number must exist at that location. The script will determine which
58 version of the initrd it needs and try to download the right file from
59 that location.
61 This will set up the link so that xm-test will use the existing
62 ramdisk. Next, just run "" normally. Note that in general,
63 you should not attempt to use a ramdisk from a previous minor version
64 of xm-test (i.e., don't use a ramdisk from 0.4.0 with 0.5.0. 0.5.0
65 should work for 0.5.3 though)
68 BUILDING with HVM Support
69 =========================
71 If you'd like to build and run this with hardware virtual machine assist
72 (HVM) support to test fully virtualized disk images on VMX/SVM hardware,
73 please add the --enable-hvm-support option to configure:
75 # ./autogen
76 # ./configure --enable-hvm-support
77 # make
79 The ramdisk/bin/create_disk_image script, which builds the full virt
80 disk.img, requires Lilo 22.7+ to be installed on the system. Lilo is
81 used to install the bootloader on the disk.img.
83 If HVM support is enabled, the ramdisk/bin/create_disk_image script
84 will be run to create a full virt disk.img in the ramdisk directory. The
85 script, by default, will look in /boot for the first non-Xen kernel it
86 runs across. If you'd like to set xm-test to use a specific kernel,
87 rather than the first one it finds in /boot, you can configure it in
88 with the "--with-hvm-kernel=KERNEL" option:
90 # ./autogen
91 # ./configure --enable-hvm-support --with-hvm-kernel=KERNEL
92 # make
94 Otherwise, you can always rerun the create script using the -k option
95 to use a specific kernel.
97 The disk.img created for HVM testing must contain a pcnet32 driver for
98 network tests. The ramdisk/bin/create_disk_image script will, by default,
99 look in the /lib/modules directory associated with the kernel being
100 used. If you'd like to specify a different location for the driver or
101 want to tell the script that the driver is built into the kernel, please
102 use the "--with-driver-dir=DRVDIR" configure option. If built into
103 the kernel, please use the key word "builtin" with the option:
105 # ./autogen
106 # ./configure --enable-hvm-support --with-driver-dir=builtin
107 - or -
108 # ./configure --enable-hvm-support --with-driver-dir=/driver/directory
109 # make
111 Xm-test will look for disk.img in the ramdisk directory when run by
112 default.
115 BUILDING for ACM Security Testing
116 =================================
118 A number of tests have been added to test the access control module (ACM)
119 in the Xen hypervisor and the tools for supporting ACM. Those tests are
120 located in the security-acm directory. If ACM support is compiled into Xen
121 (see the user guide for how to do this) those tests can be run with the
122 following command from the xm-test directory
124 ./ [...] -g security <report>
126 Some of these tests will work even without support of ACM by Xen.
128 The xm test suite has been extended to support labeling of resources
129 as required by the existing tests. However, by default the test suite
130 is not allowed to automatically label resources since this may affect
131 existing labels. To enable this, the test suite must be configured with
132 the following parameter passed to the configure scripts (in addition to
133 any other desired parameters)
135 ./configure --enable-full-labeling
137 To revoke the privilege at a later time run the configure scripts without
138 this parameter:
140 ./configure
142 If a 'make' has previously been run for building the test suite, it is not
143 necessary to run 'make' again just for enabling or disabling the automatic
144 labeling of resources.
147 Running
148 =======
150 To run the full test suite, do the following as root:
152 # ./ <logfile>
154 This will run all tests, as well as generate and submit a report at
155 the end. All output files will begin with "<logfile>."
156 If you wish to prevent submission of a report, add "-d" to the
157 command line like this:
159 # ./ -d <logfile>
161 It may be useful to run tests without submission as above, and then
162 submit the report at a later time. To do so, run with the
163 -s flag and the name of the previously-generated report:
165 # ./ -s <logfile>
167 Group test sets are supported in xm-test. This is form of layering of
168 tests groups/cases/tests. In the framework directory "grouptest",
169 files exist for group processing. The user can add groups, casenames
170 and test lists as required. Default group run is "grouptest/default".
172 # ./ -g <groupname> <logfile>
174 * NOTE: There is a quick set of tests in group mode, that was added to
175 run certain casenames and tests, and there is a "medium" group, which is a
176 medium-length run (around 20 minutes). Neither is a substitute for the full
177 xm-test test suite.
178 # ./ -g quick <logfile>
179 # ./ -g medium <logfile>
183 It may be desirable to run a specific test group. This can be
184 accomplished by doing the following:
186 # cd tests/create
187 # TEST_VERBOSE=1 make check
189 When developing or debugging a specific feature, a single test can be
190 run to avoid having to run even a whole test group:
192 # cd tests/create
193 # TEST_VERBOSE=1 make check TESTS=01_create_basic_pos.test
195 The script will create several files, including a .report
196 file, which is the cleaned up, email-friendly report of failures.
197 Additionally, the script will submit your results to the development
198 team for trend analysis. This helps us determine the level of success
199 people "out there" are having with different versions of Xen.
201 Note: you should generally run xm-test with a minimum of memory
202 allocated to Dom0. More memory available for allocation to DomUs
203 means a more rigorous test.
205 BIG FAT WARNING: The test framework assumes it is running on a
206 dedicated machine. As such, the library automatically destroys any
207 running DomUs on the system to provide each test with a "clean slate".
210 Testing the XML-RPC and Xen-API interfaces of xend
211 ==================================================
213 The xm-test suite can be used to test xm's interface with xend using
214 either XML-RPC or the Xen-API. In order to use either one of these modes,
215 xm needs to be configured using its configuration file
216 '/etc/xen/xm-config.xml'.
217 Note: The current default configuration after a fresh install of the xen
218 sources currently is to use the XML-RPC interface for communication with xend.
220 Example content for the xm-config.xml for using the Xen-API looks as
221 follows:
223 <xm>
224 <server type='Xen-API'
225 uri='http://localhost:9363/'
226 username='me'
227 password='mypassword' />
228 </xm>
230 This configuration makes xm talk to xend using port 9363. For this to
231 work, also xend needs to be configured to listen to port 9363. Therefore
232 The following line must be in /etc/xen/xend-config.sxp.
234 (xen-api-server (( none )))
236 To communicate via the legacy XML-RPC interface, the file
237 '/etc/xen/xm-config.xml' may simply have the following content or
238 may be complete remove from the /etc/xen directory.
240 <xm>
241 </xm>
243 A few tests have been written for the xm-test suite that test the
244 Xen-API interface directly without relying on 'xm'. These tests can be
245 found in the grouptest 'xapi' and for them to work properly, xm must have
246 been configured to use the Xen-API following the instructions above. To
247 run these test, the following command line can be invoked:
249 # ./ -g xapi <logfile>
253 Extending
254 =========
256 Additional tests may be added in existing groups to test additional
257 cases for a given xm subcommand. Test programs should be named
258 according to the following scheme:
260 XY_group_name_{pos,neg}.py
262 Where:
263 XY is the next number in line
264 group is the name of the subcommand being tested
265 name is the short name of the test
266 {pos,neg} denotes whether this is a positive or negative test case
268 New subcommand groups should be added as directories named after the
269 subcommand itself. The "" should be copied into
270 the new group directory as "".
272 See the Writing_Tests_HOWTO file for more detailed information on
273 adding tests to the suite.
276 Developer Notes
277 ===============
279 Our library provides a DomU console abstraction for automated
280 execution of commands. Please note that this is relatively fragile,
281 and is intended for use only with the ramdisk built by the framework.
282 Because the console experiences some occasional corruption, this
283 method is not completely perfect at the moment, although the authors
284 use it with relatively few problems.
287 Known Issues
288 ============
290 If you create a domain with a small amount of memory, under 32MBs, you
291 may run into out of memory situations for the domain. There's no way
292 to know the amount of memory needed by the kernel and modules used. Xm-test
293 uses 64MBs as default and that should work. If there are out of memory
294 issues, the default can be changed. Edit xm-test/lib/XmTestLib/
295 and change ParavirtDefaults and HVMDefaults "memory".
297 There are two tests that work with small memory,
298 and The first makes sure the default 32 MBs
299 limit works. The second checks a low memory fail situation. These tests
300 are located in the xm-test/tests/create directory and can be easily edited
301 to change the MEM value they should test. If the 32MBs test fails, the
302 failure should be reported to the Xen xen-devel mailing list. The Xen
303 tools use 32MBs as a lower acceptable limit for domain creation. The Xen
304 mailing lists are located here:
309 Reporting Bugs
310 ==============
312 If you find a bug in the test framework, report it to:
314 Dan Smith <>
316 If you find a bug in a specific test case, contact the author of the
317 test case first.