ia64/xen-unstable

view docs/Xeno-HOWTO @ 928:8dd462437867

bitkeeper revision 1.590 (3fb015den6iTCedknkVEV3Wfg-Ql1Q)

Now contains a fairly complete list of instructions from downloading source codes, compilation to configure, start and stop domains.
author br260@laudney.cl.cam.ac.uk
date Mon Nov 10 22:49:02 2003 +0000 (2003-11-10)
parents 7fa999639eb7
children b5c1b4c684f2
line source
1 ###########################################
2 Xeno HOWTO
4 University of Cambridge Computer Laboratory
6 http://www.cl.cam.ac.uk/netos/xen
7 #############################
10 Get Xeno Source Codes
11 ==========================
13 The public master BK repository for the 1.1 release lives at:
14 'bk://xen.bkbits.net/xeno-1.1.bk'
16 To fetch a local copy, first download the BitKeeper tools at:
17 http://www.bitmover.com/download with username 'bitkeeper' and
18 password 'get bitkeeper'.
20 Then install it and run:
21 # cd /
22 # bk clone bk://xen.bkbits.net/xeno-1.1.bk
24 Under your current directory, a new directory named 'xeno-1.1.bk' has
25 been created, which contains all the source codes for Xen and
26 XenoLinux. Here we suppose you put it under '/'.
28 To get newest changes to the repository, run
29 # cd /xeno-1.1.bk
30 # bk pull
33 Build Xen
34 =============================
36 Hint: To see how to build Xen and all the control tools, inspect the
37 tools/misc/xen-clone script in the BK repository. This script can be
38 used to clone the repostitory and perform a full build.
40 To build Xen manually:
42 # cd /xeno-1.1.bk/xen
43 # make clean
44 # make
46 This will (should) produce a file called 'image' in the current
47 directory. This is the ELF 32-bit LSB executable file of Xen. You
48 can also find a gzip version, named 'image.gz'.
50 Hint: There is a 'make install' rule which also and then copies it to
51 ../../install ; if this suits your setup, go for it.
54 Build XenoLinux
55 ==============================
57 This is a little more involved since the repository only contains a
58 "sparse" tree -- this is essentially an 'overlay' on a standard linux
59 kernel source tree. It contains only those files currently 'in play'
60 which are either modified versions of files in the vanilla linux tree,
61 or brand new files specific to XenoLinux.
63 So, first you need a vanilla linux-2.4.22 tree, which is located at:
64 http://www.kernel.org/pub/linux/kernel/v2.4
66 Then:
67 # mv linux-2.4.22.tar.gz /xeno-1.1.bk
68 # cd /xeno-1.1.bk
69 # tar -zxvf linux-2.4.22.tar.gz
71 You'll find a new directory 'linux-2.4.22' which contains all
72 the vanilla Linux 2.4.22 kernel source codes.
74 Hint: You should choose the vanilla linux kernel tree that has the
75 same version as the "sparse" tree.
77 Next, you need to 'overlay' this sparse tree on the full vanilla Linux
78 kernel tree:
80 # cd /xeno-1.1.bk/xenolinux-2.4.22-sparse
81 # ./mkbuildtree ../linux-2.4.22
83 Finally, rename the buildtree since it is now a xenolinux buildtree.
85 # cd /xeno-1.1.bk
86 # mv linux-2.4.22 xenolinux-2.4.22
88 Now that the buildtree is there, you can build the xenolinux kernel.
90 # cd /xeno-1.1.bk/xenolinux-2.4.22
91 # ARCH=xeno make xconfig { or menuconfig, or oldconfig, or config }
92 # ARCH=xeno make dep bzImage
94 Assuming the build works, you'll end up with
95 /xeno-1.1.bk/xenolinux-2.4.22/arch/xeno/boot/image.gz
96 This is the gzip version of XenoLinux kernel image.
99 Build the Domain Control Tools
100 ==============================
102 Under '/xeno-1.1.bk/tools', there are four sub-directories:
103 'balloon', 'control', 'internal' and 'misc', each containing
104 a group of tools. You can enter any of the four sub-directories
105 and type 'make' to compile the corresponding group of tools.
106 Or you can type 'make' under '/xeno-1.1.bk/tools' to compile
107 all the tools.
109 Particularly, in order to compile tools under 'control', you
110 must have Apache Ant installed. Latest binary can be found at
111 'http://ant.apache.org/bindownload.cgi'.
113 Besides, you must have Java J2SDK 1.4 installed. There seemed
114 to be compilation errors with J2SDK 1.3, but fine with J2SDK 1.4
116 To summarize:
118 # cd /xeno-1.1.bk/tools
119 # make
120 # make install
121 # cd /install/bin
122 # cp * /usr/local/bin
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 Xenctl Configuration
185 ==============================
187 # cd /xeno-1.1.bk/tools/control/examples
188 # cp xenctl.xml xen-mynewdom /etc
190 Then, you need to modify /etc/xen-mynewdom:
192 # cat /etc/xen-mynewdom
193 domain new
194 physical grant -pcdrom_link
195 domain start
197 You should substitue 'cdrom_link' with the
198 root partition, e.g. '/dev/hda3', '/dev/sda1'.
199 Therefore, the second looks like:
200 'physical grant -p/dev/hda3'
202 Then, you need to modify /etc/xenctl.xml:
204 # cat /etc/xenctl.xml
205 <?xml version="1.0"?>
206 <domctl_defaults>
207 <domain_name>XenoLinux</domain_name>
208 <domain_size_kb>98304</domain_size_kb>
209 <domain_image>/boot/xenolinux.gz</domain_image>
210 <domain_vifs>1</domain_vifs>
211 <domain_init_rd>/boot/initrd.gz</domain_init_rd>
212 <root_device>/dev/ram0</root_device>
213 <root_args>rw</root_args>
214 <args>init=/linuxrc 4 DOMID=+</args>
215 <nw_ip>169.254.1.0+</nw_ip>
216 <nw_gw>169.254.1.0</nw_gw>
217 <nw_mask>255.255.0.0</nw_mask>
218 <nw_nfs_server>169.254.1.0</nw_nfs_server>
219 <max_domain_number>1000</max_domain_number>
220 <xi_tools_dir>/usr/local/bin/</xi_tools_dir>
221 </domctl_defaults>
223 The meaning of every line is very straightforward
224 and should be modified according to your configuration.
226 Normally you don't need <domain_init_rd>. And you probably want
227 root_args set to "ro", otherwise fsck will complain. Assuming you've
228 installed a standard linux installation, you probably don't want to
229 explicit set the init program, or the run level,
230 e.g. <args>DOMID=+</args>
233 Boot into Domain 0
234 ==============================
236 Reboot your computer; After selecting the kernel to boot, stand back
237 and watch Xen boot, closely followed by "domain 0" running the
238 XenoLinux kernel. Depending on which root partition you have assigned
239 to XenoLinux kernel in Grub configuration file, you can use the
240 corresponding username / password to log in.
242 Once logged in, it should look just like any regular linux box. All
243 the usual tools and commands should work as per usual.
246 Start New Domains
247 ==============================
249 You must be 'root' to start new domains.
251 Make sure you have successfully configured at least one
252 physical network interface. Then:
254 # xen_nat_enable
255 # xen_read_console &
257 When new domains are created and started, they will send output via
258 UDP packets to the local virtual network. Those packets are received
259 by xen_read_console running in Domain 0 and output are printed out to
260 the standard output.
262 # xenctl script -f/etc/xen-mynewdom
264 This will create and start a new domain based on /etc/xen-mynewdom and
265 /etc/xenctl.xml
267 You should be able to see XenoLinux boot message on standard output
268 with each line prepended [domain_id].
271 List and Stop Domains
272 ==============================
274 You can see a list of existing domains with:
276 # xi_list
277 or
278 # xenctl domain list
280 In order to stop a domain, you use:
282 # xi_stop domain_id
283 or
284 # xenctl domain stop -ndomain_id
286 followed by
287 # xi_destroy domain_id
288 or
289 # xenctl domain destroy -ndomain_id