view tools/xm-test/README @ 21067:b4a1832a916f

Update Xen version to 4.0.0-rc6
author Keir Fraser <>
date Tue Mar 09 18:18:05 2010 +0000 (2010-03-09)
parents 5126f0847654
line source
2 ----------------------------------------------------------------------
4 Status of xm-test
6 The xm-test environment was written in 2006. It was mostly not
7 updated or adapted to new / changed functionality since then.
8 ("it's slowly rotting", Keir Fraser, xen-devel mailing list,
9 June 2009)
10 During the last weeks there was the attempt to fix most of the
11 problems - but there are still some major issues:
12 o The reporting infrastructure is 'long gone' (Dan Smith, Mail from
13 Aug 2009). Therefore there is no way to send out reports. When
14 running the you should therefore specify the '-d'
15 option.
16 o The initrd.img (which is downloaded) is quite old and needs an
17 update. Especially functionality for migration it is missing.
18 [It should be discussed using an existing distribution instead of
19 compiling a micro distribution and put this into the initrd.)
21 Andreas Florath <>
22 August 2009
24 ----------------------------------------------------------------------
27 xm-test README
29 Copyright (C) International Business Machines Corp., 2005
30 Author(s): Dan Smith <>
31 Woody Marvel <>
33 Overview
34 ========
36 This suite provides a framework for testing the Xen userspace tools.
37 The directory structure is:
39 ./xm-test
40 |
41 +-/lib: Python support libraries
42 |
43 +-/ramdisk: Staging area for building the test ramdisk
44 |
45 +-/tests
46 | |
47 | +-/create: Tests for the 'xm create' command
48 | +-/destroy: Tests for the 'xm destroy' command
49 | . . .
50 |
51 +-/utils: Utility scripts for ramdisk building
53 Reports are posted here:
58 Building
59 ========
61 Before the test suite can be used, the ramdisk must be built from
62 source. All source needed for this process is automatically
63 downloaded, extracted, and compiled. Due to the need to create
64 special files, this process must be done as root:
66 # ./autogen
67 # ./configure
68 # make
70 NB: If you have the initrd.img from another installation of xm-test,
71 you can copy it into the ramdisk directory to eliminate the need to
72 rebuild it. If you do this, there is no need to run 'make' again.
73 Simply copy the initrd-X.Y-ARCH.img file into ramdisk/ and then run:
75 # make existing
77 Or, you can run:
78 # INITRD="http://url.of.initrd.repo/" make existing
80 You do not need to include the name of the image itself in the url,
81 however, an initrd with the right name (initrd.X.Y-ARCH.img) and version
82 number must exist at that location. The script will determine which
83 version of the initrd it needs and try to download the right file from
84 that location.
86 This will set up the link so that xm-test will use the existing
87 ramdisk. Next, just run "" normally. Note that in general,
88 you should not attempt to use a ramdisk from a previous minor version
89 of xm-test (i.e., don't use a ramdisk from 0.4.0 with 0.5.0. 0.5.0
90 should work for 0.5.3 though)
93 BUILDING with HVM Support
94 =========================
96 If you'd like to build and run this with hardware virtual machine assist
97 (HVM) support to test fully virtualized disk images on VMX/SVM hardware,
98 please add the --enable-hvm-support option to configure:
100 # ./autogen
101 # ./configure --enable-hvm-support
102 # make
104 The ramdisk/bin/create_disk_image script, which builds the full virt
105 disk.img, requires Lilo 22.7+ to be installed on the system. Lilo is
106 used to install the bootloader on the disk.img.
108 If HVM support is enabled, the ramdisk/bin/create_disk_image script
109 will be run to create a full virt disk.img in the ramdisk directory. The
110 script, by default, will look in /boot for the first non-Xen kernel it
111 runs across. If you'd like to set xm-test to use a specific kernel,
112 rather than the first one it finds in /boot, you can configure it in
113 with the "--with-hvm-kernel=KERNEL" option:
115 # ./autogen
116 # ./configure --enable-hvm-support --with-hvm-kernel=KERNEL
117 # make
119 Otherwise, you can always rerun the create script using the -k option
120 to use a specific kernel.
122 The disk.img created for HVM testing must contain a pcnet32 driver for
123 network tests. The ramdisk/bin/create_disk_image script will, by default,
124 look in the /lib/modules directory associated with the kernel being
125 used. If you'd like to specify a different location for the driver or
126 want to tell the script that the driver is built into the kernel, please
127 use the "--with-driver-dir=DRVDIR" configure option. If built into
128 the kernel, please use the key word "builtin" with the option:
130 # ./autogen
131 # ./configure --enable-hvm-support --with-driver-dir=builtin
132 - or -
133 # ./configure --enable-hvm-support --with-driver-dir=/driver/directory
134 # make
136 Xm-test will look for disk.img in the ramdisk directory when run by
137 default.
140 BUILDING for ACM Security Testing
141 =================================
143 A number of tests have been added to test the access control module (ACM)
144 in the Xen hypervisor and the tools for supporting ACM. Those tests are
145 located in the security-acm directory. If ACM support is compiled into Xen
146 (see the user guide for how to do this) those tests can be run with the
147 following command from the xm-test directory
149 ./ [...] -g security <report>
151 Some of these tests will work even without support of ACM by Xen.
153 The xm test suite has been extended to support labeling of resources
154 as required by the existing tests. However, by default the test suite
155 is not allowed to automatically label resources since this may affect
156 existing labels. To enable this, the test suite must be configured with
157 the following parameter passed to the configure scripts (in addition to
158 any other desired parameters)
160 ./configure --enable-full-labeling
162 To revoke the privilege at a later time run the configure scripts without
163 this parameter:
165 ./configure
167 If a 'make' has previously been run for building the test suite, it is not
168 necessary to run 'make' again just for enabling or disabling the automatic
169 labeling of resources.
172 Running
173 =======
175 To run the full test suite, do the following as root:
177 # ./ <logfile>
179 This will run all tests, as well as generate and submit a report at
180 the end. All output files will begin with "<logfile>."
181 If you wish to prevent submission of a report, add "-d" to the
182 command line like this:
184 # ./ -d <logfile>
186 It may be useful to run tests without submission as above, and then
187 submit the report at a later time. To do so, run with the
188 -s flag and the name of the previously-generated report:
190 # ./ -s <logfile>
192 Group test sets are supported in xm-test. This is form of layering of
193 tests groups/cases/tests. In the framework directory "grouptest",
194 files exist for group processing. The user can add groups, casenames
195 and test lists as required. Default group run is "grouptest/default".
197 # ./ -g <groupname> <logfile>
199 * NOTE: There is a quick set of tests in group mode, that was added to
200 run certain casenames and tests, and there is a "medium" group, which is a
201 medium-length run (around 20 minutes). Neither is a substitute for the full
202 xm-test test suite.
203 # ./ -g quick <logfile>
204 # ./ -g medium <logfile>
208 It may be desirable to run a specific test group. This can be
209 accomplished by doing the following:
211 # cd tests/create
212 # TEST_VERBOSE=1 make check
214 When developing or debugging a specific feature, a single test can be
215 run to avoid having to run even a whole test group:
217 # cd tests/create
218 # TEST_VERBOSE=1 make check TESTS=01_create_basic_pos.test
220 The script will create several files, including a .report
221 file, which is the cleaned up, email-friendly report of failures.
222 Additionally, the script will submit your results to the development
223 team for trend analysis. This helps us determine the level of success
224 people "out there" are having with different versions of Xen.
226 Note: you should generally run xm-test with a minimum of memory
227 allocated to Dom0. More memory available for allocation to DomUs
228 means a more rigorous test.
230 BIG FAT WARNING: The test framework assumes it is running on a
231 dedicated machine. As such, the library automatically destroys any
232 running DomUs on the system to provide each test with a "clean slate".
235 Testing the XML-RPC and Xen-API interfaces of xend
236 ==================================================
238 The xm-test suite can be used to test xm's interface with xend using
239 either XML-RPC or the Xen-API. In order to use either one of these modes,
240 xm needs to be configured using its configuration file
241 '/etc/xen/xm-config.xml'.
242 Note: The current default configuration after a fresh install of the xen
243 sources currently is to use the XML-RPC interface for communication with xend.
245 Example content for the xm-config.xml for using the Xen-API looks as
246 follows:
248 <xm>
249 <server type='Xen-API'
250 uri='http://localhost:9363/'
251 username='me'
252 password='mypassword' />
253 </xm>
255 This configuration makes xm talk to xend using port 9363. For this to
256 work, also xend needs to be configured to listen to port 9363. Therefore
257 The following line must be in /etc/xen/xend-config.sxp.
259 (xen-api-server (( none )))
261 To communicate via the legacy XML-RPC interface, the file
262 '/etc/xen/xm-config.xml' may simply have the following content or
263 may be complete remove from the /etc/xen directory.
265 <xm>
266 </xm>
268 A few tests have been written for the xm-test suite that test the
269 Xen-API interface directly without relying on 'xm'. These tests can be
270 found in the grouptest 'xapi' and for them to work properly, xm must have
271 been configured to use the Xen-API following the instructions above. To
272 run these test, the following command line can be invoked:
274 # ./ -g xapi <logfile>
278 Extending
279 =========
281 Additional tests may be added in existing groups to test additional
282 cases for a given xm subcommand. Test programs should be named
283 according to the following scheme:
285 XY_group_name_{pos,neg}.py
287 Where:
288 XY is the next number in line
289 group is the name of the subcommand being tested
290 name is the short name of the test
291 {pos,neg} denotes whether this is a positive or negative test case
293 New subcommand groups should be added as directories named after the
294 subcommand itself. The "" should be copied into
295 the new group directory as "".
297 See the Writing_Tests_HOWTO file for more detailed information on
298 adding tests to the suite.
301 Developer Notes
302 ===============
304 Our library provides a DomU console abstraction for automated
305 execution of commands. Please note that this is relatively fragile,
306 and is intended for use only with the ramdisk built by the framework.
307 Because the console experiences some occasional corruption, this
308 method is not completely perfect at the moment, although the authors
309 use it with relatively few problems.
312 Known Issues
313 ============
315 If you create a domain with a small amount of memory, under 32MBs, you
316 may run into out of memory situations for the domain. There's no way
317 to know the amount of memory needed by the kernel and modules used. Xm-test
318 uses 64MBs as default and that should work. If there are out of memory
319 issues, the default can be changed. Edit xm-test/lib/XmTestLib/
320 and change ParavirtDefaults and HVMDefaults "memory".
322 There are two tests that work with small memory,
323 and The first makes sure the default 32 MBs
324 limit works. The second checks a low memory fail situation. These tests
325 are located in the xm-test/tests/create directory and can be easily edited
326 to change the MEM value they should test. If the 32MBs test fails, the
327 failure should be reported to the Xen xen-devel mailing list. The Xen
328 tools use 32MBs as a lower acceptable limit for domain creation. The Xen
329 mailing lists are located here:
334 Reporting Bugs
335 ==============
337 If you find a bug in the test framework, report it to:
339 Dan Smith <>
341 If you find a bug in a specific test case, contact the author of the
342 test case first.