view docs/Xeno-HOWTO @ 975:0cac9d16969a

bitkeeper revision 1.627.1.1 (3fbf4befPIgRjU40eyhadjRuioWcwA)

Many files:
Lib renames and fixes. Only build shared version of libxc, as the static archive version caused too many problems.
Rename: tools/xc/lib/libxc_vif.c -> tools/xc/lib/xc_vif.c
Rename: tools/xc/lib/libxc_vbd.c -> tools/xc/lib/xc_vbd.c
Rename: tools/xc/lib/libxc_private.h -> tools/xc/lib/xc_private.h
Rename: tools/xc/lib/libxc_private.c -> tools/xc/lib/xc_private.c
Rename: tools/xc/lib/libxc_misc.c -> tools/xc/lib/xc_misc.c
Rename: tools/xc/lib/libxc_linux_restore.c -> tools/xc/lib/xc_linux_restore.c
Rename: tools/xc/lib/libxc_linux_save.c -> tools/xc/lib/xc_linux_save.c
Rename: tools/xc/lib/libxc_linux_build.c -> tools/xc/lib/xc_linux_build.c
Rename: tools/xc/lib/libxc_domain.c -> tools/xc/lib/xc_domain.c
Rename: tools/xc/lib/libxc_bvtsched.c -> tools/xc/lib/xc_bvtsched.c
date Sat Nov 22 11:43:43 2003 +0000 (2003-11-22)
parents 895f1ca085a7
children 6ec887aa9d16
line source
1 ###########################################
2 Xeno HOWTO
4 University of Cambridge Computer Laboratory
7 #############################
10 Get Xeno Source Codes
11 ==========================
13 The public master BK repository for the 1.1 release lives at:
14 'bk://'
16 To fetch a local copy, first download the BitKeeper tools at:
17 with username 'bitkeeper' and
18 password 'get bitkeeper'.
20 Then install the tools and then run:
21 # bk clone bk://
23 Under your current directory, a new directory named 'xeno-1.1.bk' has
24 been created, which contains all the source codes for Xen and
25 XenoLinux.
27 To get newest changes to the repository, run
28 # cd xeno-1.1.bk
29 # bk pull
32 Build Xen
33 =============================
35 Hint: To see how to build Xen and all the control tools, inspect the
36 tools/misc/xen-clone script in the BK repository. This script can be
37 used to clone the repostitory and perform a full build.
39 To build Xen manually:
41 # cd xeno-1.1.bk/xen
42 # make clean
43 # make
45 This will (should) produce a file called 'image' in the current
46 directory. This is the ELF 32-bit LSB executable file of Xen. You
47 can also find a gzip version, named 'image.gz'.
49 To install the built files on your Xenoserver under /usr, type 'make
50 install' at the root of the BK repository. You will need to be root to
51 do this!
53 Hint: There is also a 'make dist' rule which copies built files to an
54 install directory just outside the BK repo; if this suits your setup,
55 go for it.
58 Build XenoLinux
59 ==============================
61 This is a little more involved since the repository only contains a
62 "sparse" tree -- this is essentially an 'overlay' on a standard linux
63 kernel source tree. It contains only those files currently 'in play'
64 which are either modified versions of files in the vanilla linux tree,
65 or brand new files specific to XenoLinux.
67 So, first you need a vanilla linux-2.4.22 tree, which is located at:
70 Then:
71 # mv linux-2.4.22.tar.gz /xeno-1.1.bk
72 # cd /xeno-1.1.bk
73 # tar -zxvf linux-2.4.22.tar.gz
75 You'll find a new directory 'linux-2.4.22' which contains all
76 the vanilla Linux 2.4.22 kernel source codes.
78 Hint: You should choose the vanilla linux kernel tree that has the
79 same version as the "sparse" tree.
81 Next, you need to 'overlay' this sparse tree on the full vanilla Linux
82 kernel tree:
84 # cd /xeno-1.1.bk/xenolinux-2.4.22-sparse
85 # ./mkbuildtree ../linux-2.4.22
87 Finally, rename the buildtree since it is now a xenolinux buildtree.
89 # cd /xeno-1.1.bk
90 # mv linux-2.4.22 xenolinux-2.4.22
92 Now that the buildtree is there, you can build the xenolinux kernel.
94 # cd /xeno-1.1.bk/xenolinux-2.4.22
95 # ARCH=xeno make xconfig { or menuconfig, or oldconfig, or config }
96 # ARCH=xeno make dep bzImage
98 Assuming the build works, you'll end up with
99 /xeno-1.1.bk/xenolinux-2.4.22/arch/xeno/boot/image.gz
100 This is the gzip version of XenoLinux kernel image.
103 Build the Domain Control Tools
104 ==============================
106 Under '/xeno-1.1.bk/tools', there are three sub-directories:
107 'balloon', 'xc' and 'misc', each containing
108 a group of tools. You can enter any of the four sub-directories
109 and type 'make' to compile the corresponding group of tools.
110 Or you can type 'make' under '/xeno-1.1.bk/tools' to compile
111 all the tools.
113 In order to compile the control-interface library in 'xc' you must
114 have zlib and devlopment headers installed. Also you will need at
115 least Python v2.2.
117 'make install' in the tools directory will place executables and
118 libraries in /usr/bin and /usr/lib. You will need to be root to do this!
120 As noted earlier, 'make dist' installs files to a local 'install'
121 directory just outside the BK repository. These files will then need
122 to be installed manually onto the Xenoserver.
125 Installation
126 ==============================
128 First:
129 # cp /xen-1.1.bk/xen/image.gz /boot/xen.gz
130 # cp /xen-1.1.bk/xenolinux-2.4.22/arch/xeno/boot/image.gz /boot/xenolinux.gz
132 Second, you must have 'GNU Grub' installed. Then you need to edit
133 the Grub configuration file '/boot/grub/menu.lst'.
135 A typical Grub menu option might look like:
137 title Xen / XenoLinux 2.4.22
138 kernel /boot/xen.gz dom0_mem=131072 ser_baud=115200 noht
139 module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
141 The first line specifies which Xen image to use, and what command line
142 arguments to pass to Xen. In this case we set the maximum amount of
143 memory to allocate to domain0, and enable serial I/O at 115200 baud.
144 We could also disable smp support (nosmp) or disable hyper-threading
145 support (noht). If you have multiple network interface you can use
146 ifname=ethXX to select which one to use. If your network card is
147 unsupported, use ifname=dummy
149 The second line specifies which XenoLinux image to use, and the
150 standard linux command line arguments to pass to the kernel. In this
151 case, we're configuring the root partition and stating that it should
152 be mounted read-only (normal practice).
154 The following is a list of command line arguments to pass to Xen:
156 ignorebiostables Disable parsing of BIOS-supplied tables. This may
157 help with some chipsets that aren't fully supported
158 by Xen. If you specify this option then ACPI tables are
159 also ignored, and SMP support is disabled.
161 noreboot Don't reboot the machine automatically on errors.
162 This is useful to catch debug output if you aren't
163 catching console messages via the serial line.
165 nosmp Disable SMP support.
166 This option is implied by 'ignorebiostables'.
168 noacpi Disable ACPI tables, which confuse Xen on some chipsets.
169 This option is implied by 'ignorebiostables'.
171 watchdog Enable NMI watchdog which can report certain failures.
173 noht Disable Hyperthreading.
175 ifname=ethXX Select which Ethernet interface to use.
177 ifname=dummy Don't use any network interface.
179 ser_baud=xxx Enable serial I/O and set the baud rate.
181 dom0_mem=xxx Set the maximum amount of memory for domain0.
184 Boot into Domain 0
185 ==============================
187 Reboot your computer; After selecting the kernel to boot, stand back
188 and watch Xen boot, closely followed by "domain 0" running the
189 XenoLinux kernel. Depending on which root partition you have assigned
190 to XenoLinux kernel in Grub configuration file, you can use the
191 corresponding username / password to log in.
193 Once logged in, it should look just like any regular linux box. All
194 the usual tools and commands should work as per usual.
197 Start New Domains
198 ==============================
200 You must be 'root' to start new domains.
202 Make sure you have successfully configured at least one
203 physical network interface. Then:
205 # xen_nat_enable
206 # xen_read_console &
208 When new domains are created and started, they will send output via
209 UDP packets to the local virtual network. Those packets are received
210 by xen_read_console running in Domain 0 and output are printed out to
211 the standard output.
213 Now edit the tools/examples/ script to your taste. This
214 should then be executed as root to create a new domain.
216 You should be able to see XenoLinux boot message on standard output
217 with each line prepended with [domain_id].
220 List and Stop Domains
221 ==============================
223 You can see a list of existing domains with:
224 # tools/examples/
226 In order to stop a domain, you use:
227 # tools/examples/ <domain_id>
229 To destroy a domain use ('force' causes an immediate destruction
230 without waiting for the guest OS to shut down cleanly):
231 # tools/examples/ <domain_id> [force]
234 Other Control Tasks using Python
235 ================================
237 A Python module 'Xc' is installed as part of the tools-install
238 process. This can be imported, and an 'xc object' instantiated, to
239 provide access to privileged command operations:
241 # import Xc
242 # xc =
243 # dir(xc)
244 # help(xc.domain_create)
246 In this way you can see that the class 'xc' contains useful
247 documentation for you to consult.
249 A further module of useful routines (XenoUtil) is also installed:
251 # import XenoUtil
252 # help(XenoUtil)