ia64/xen-unstable

view tools/xm-test/Writing_Tests_HOWTO @ 16739:33dcf04d7715

tools/docs: Fix example and default IP addresses.

In various places in documentation and code, IP addresses are provided
as examples, defaults, or dummy configuration. In general the
specific IP addresses used in Xen are not always appropriate. (For
example, 1.2.3.4 is used in a few places!)

The following addresses should be used:
* For examples and documentation, 192.0.2.0/24. (See RFC3330.)
* For defaults for private networks, a random network from RFC1918.
I have randomly selected 172.30.206.0/24 for this purpose and
documented this in at the only registry I know of,
www.ucam.org/cam-grin. This network should henceforth be used for
default configurations of local bridges, test networks, etc. in
Xen tools.

The following addresses should NOT be used:
* 10.0.*.*, 10.1.*.*, 192.168.0.*, 192.168.1.*, etc. Using these
addresses gives greatly increased likelihood of collision, as
ignorant network administrators and reckless middlebox vendors
often pick networks from the bottom of 10/8 and 192.168/16.
* 169.254.*.*. These are reserved for zeroconf (ad-hoc networking)
and should not be used for Xen private networks, bridges, etc.,
etc. Use of these addresses by Xen scripts causes trouble on hosts
(eg laptops) which find themselves in ad-hoc networking
environments. I think this is not hypothetical (!) since at least
one Linux distribution have specific code to detect this case and
cause Xen startup to fail iff the host already has an external
zeroconf address.
* 1.2.3.4. WTF !?

I have also used 127.0.255.255 in one place where apparently a dummy
address is needed (some Linux kernels won't accept a lack of an NFS
server address). If 127.0.255.255 is mistakenly used it is unlikely
to do any damage to real traffic even if it does escape into the
network at large.

Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
author Keir Fraser <keir.fraser@citrix.com>
date Thu Jan 17 15:13:40 2008 +0000 (2008-01-17)
parents 39fa9a75d84b
children
line source
2 Writing Tests HOWTO
3 ===================
5 One goal for xm-test is to make test writing very easy. Xm-test includes
6 a library in lib/XmTestLib that contains all the necessary methods for
7 creating and shutting down domains. Include the library in your test by
8 importing it:
10 from XmTestLib import *
13 Guidelines
14 ==========
16 1. Tests should be short and single purposed. This means testing as
17 little as possible in a single test. Do not overload tests. The more
18 that's in a test the more difficult it is to track down what failed.
20 2. Tests should report as much information as possible when calling
21 FAIL() or SKIP().
23 3. A test should report SKIP() only if it cannot be run on the current
24 machine or it makes no sense to run it. SMP tests on an UP system,
25 for example, may not make sense. Or, there are some tests for
26 para-virtualized guests that won't work on a fully virtualized
27 guest.
29 4. Use the traceCommand() function to run commands on Domain0, the
30 Xen management domain. This function logs everything, which is useful
31 in case of failure.
33 5. Use the domain's console.runCmd method to run commands on a guest
34 domain. This ensures logging and consistency. Please see 'Creating
35 and Using Domains' below for an example.
37 6. Tests need to capture and handle libary exceptions such as:
39 - ConsoleError can be raised when sending a command to a console.
40 - DomainError can be raised when a domain is started, indicating
41 a possible configuration error.
42 - TimeoutError can be raised when the traceCommand() method is used.
44 7. Tests shouldn't depend on where the test is being run from or the
45 system on which it is run.
47 8. Please use the existing tests for a guide, especially:
49 - create/01_create_basic_pos.py
50 - create/13_create_multinic_pos.py
51 - memset/01_memset_basic_pos.py
52 - reboot/01_reboot_basic_pos.py
53 - migrate/01_migrate_localhost_pos.py
56 Creating and Using Domains
57 ==========================
59 Xen domains, both full and para virtualized, are represented by the
60 XmTestDomain class. The class contains methods for starting a Xen domain,
61 shutting it down, or destroying it. Consoles, used to execute commands
62 on guest test domains, are opened and closed through the XmTestDomain
63 class. Devices, which are represented by the XenDevice class, are also
64 added and removed using XmTestDomain methods.
66 Here's a simple example for creating a domain, opening a console, running
67 a command, and then shutting down the domain:
69 1) Create a domain:
71 domain = XmTestDomain()
73 2) Start the domain and grab a console:
75 try:
76 console = domain.start()
77 except DomainError, e:
78 if verbose:
79 print "Failed to create test domain because:"
80 print e.extra
81 FAIL(str(e))
83 3) Run a command inside the new domain using the console, saving the
84 console log if an error is encountered:
86 try:
87 # Run 'ls'
88 run = console.runCmd("ls")
89 except ConsoleError, e:
90 saveLog(console.getHistory())
91 FAIL(str(e))
93 4) Stop the domain, which nicely shuts it down:
95 domain.stop()
98 Writing Tests with Networking
99 =============================
101 The xm-test suite includes the ability to test networking for domains.
102 Networking is configured at configuration time. While testing NAT and
103 routing environments in the future, the current xm-test only supports
104 a bridging environment. Xm-test currently only supports a range of
105 IPs, the dhcp feature will be added soon.
107 The network tests will need to know what IPs to use. IPs are
108 configured when you build xm-test. Xm-test by default a range chosen
109 at random from the RFC1918 private use space, and published at
110 www.ucam.org/cam-grin, 172.30.206.1-172.30.206.254 from
111 172.30.206.0/24. If you'd like to set a new range, do so at configure
112 time, a netmask and network address must also be defined:
114 # ./configure --with-net-ip-range=192.0.2.1-192.0.2.100 --with-network-address=192.0.2.0 --with-netmask=255.255.255.0
116 The tests will not need to set network information, this is done by
117 the library once it's configured.
119 As mentioned above, xm-test's goal is to make writing tests easy. Creating
120 domains with networking should also be easy. To create a domain with
121 a single network interface, tests can use a XmTestNetDomain object. It
122 creates a XenNetDevice for the domain automatically using the pre-configured
123 IP information. Otherwise, a network interface can be added to a domain
124 prior to starting it (the ability to attach devices will be added):
126 domain = XmTestDomain()
127 domain.newDevice(XenNetDevice, "eth0")
128 domain.newDevice(XenNetDevice, "eth1")
130 Here, the domain is created and then the XenDomain factory newDevice
131 is called to create a new device of class XenNetDevice to the domain.
132 The xm-test library will automatically assign an IP from the configured
133 list, execute ifconfig on the guest domain console, and create an
134 alias on Domain0.