ia64/xen-unstable

view docs/HOWTOs/Xen-HOWTO @ 1776:c2f673cea5e4

bitkeeper revision 1.1072.1.1 (40f4e51fLMgcKX4Sn6FNYePX6EqkGA)

Merge http://xen.bkbits.net:8080/xeno-unstable.bk
into gandalf.hpl.hp.com:/var/bk/xeno-unstable.bk
author xenbk@gandalf.hpl.hp.com
date Wed Jul 14 07:47:43 2004 +0000 (2004-07-14)
parents 5bfc0d01717c a37ede4b5d41
children e91945007886
line source
1 ###########################################
2 Xen HOWTO
4 University of Cambridge Computer Laboratory
6 http://www.cl.cam.ac.uk/netos/xen
7 #############################
10 Get Xen Source Code
11 =============================
13 The public master BK repository for the 1.2 release lives at:
14 'bk://xen.bkbits.net/xeno-1.2.bk'
15 The current unstable release (1.3) is available at:
16 'bk://xen.bkbits.net/xeno-unstable.bk'
18 To fetch a local copy, first download the BitKeeper tools at:
19 http://www.bitmover.com/download with username 'bitkeeper' and
20 password 'get bitkeeper'.
22 Then install the tools and then run:
23 # bk clone bk://xen.bkbits.net/xeno-1.2.bk
25 Under your current directory, a new directory named 'xeno-1.2.bk' has
26 been created, which contains all the necessary source codes for the
27 Xen hypervisor and Linux guest OSes.
29 To get newest changes to the repository, run
30 # cd xeno-1.2.bk
31 # bk pull
34 Configuring Xen
35 =============================
37 Xen's build configuration is managed via a set of environment
38 variables. These should be set before invoking make
39 (e.g., 'export debug=y; make', 'debug=y make').
41 The options that can be configured are as follows (all options default
42 to 'n' or off):
44 debug=y -- Enable debug assertions and console output.
45 (Primarily useful for tracing bugs in Xen).
47 debugger=y -- Enable the in-Xen pervasive debugger (PDB).
48 This can be used to debug Xen, guest OSes, and
49 applications. For more information see the
50 XenDebugger-HOWTO.
52 perfc=y -- Enable performance-counters for significant events
53 within Xen. The counts can be reset or displayed
54 on Xen's console via console control keys.
56 trace=y -- Enable per-cpu trace buffers which log a range of
57 events within Xen for collection by control
58 software.
61 Build Xen
62 =============================
64 Hint: To see how to build Xen and all the control tools, inspect the
65 tools/misc/xen-clone script in the BK repository. This script can be
66 used to clone the repository and perform a full build.
68 To build Xen manually:
70 # cd xeno-1.2.bk/xen
71 # make clean
72 # make
74 This will (should) produce a file called 'xen' in the current
75 directory. This is the ELF 32-bit LSB executable file of Xen. You
76 can also find a gzip version, named 'xen.gz'.
78 To install the built files on your server under /usr, type 'make
79 install' at the root of the BK repository. You will need to be root to
80 do this!
82 Hint: There is also a 'make dist' rule which copies built files to an
83 install directory just outside the BK repo; if this suits your setup,
84 go for it.
87 Build Linux as a Xen guest OS
88 ==============================
90 This is a little more involved since the repository only contains a
91 "sparse" tree -- this is essentially an 'overlay' on a standard linux
92 kernel source tree. It contains only those files currently 'in play'
93 which are either modified versions of files in the vanilla linux tree,
94 or brand new files specific to the Xen port.
96 So, first you need a vanilla linux-2.4.26 tree, which is located at:
97 http://www.kernel.org/pub/linux/kernel/v2.4
99 Then:
100 # mv linux-2.4.26.tar.gz /xeno-1.2.bk
101 # cd /xeno-1.2.bk
102 # tar -zxvf linux-2.4.26.tar.gz
104 You'll find a new directory 'linux-2.4.26' which contains all
105 the vanilla Linux 2.4.26 kernel source codes.
107 Hint: You should choose the vanilla linux kernel tree that has the
108 same version as the "sparse" tree.
110 Next, you need to 'overlay' this sparse tree on the full vanilla Linux
111 kernel tree:
113 # cd /xeno-1.2.bk/xenolinux-2.4.26-sparse
114 # ./mkbuildtree ../linux-2.4.26
116 Finally, rename the buildtree since it is now a 'xenolinux' buildtree.
118 # cd /xeno-1.2.bk
119 # mv linux-2.4.26 xenolinux-2.4.26
121 Now that the buildtree is there, you can build the xenolinux kernel.
122 The default configuration should work fine for most people (use 'make
123 oldconfig') but you can customise using one of the other config tools
124 if you want.
126 # cd /xeno-1.2.bk/xenolinux-2.4.26
127 # ARCH=xen make oldconfig { or menuconfig, or xconfig, or config }
128 # ARCH=xen make dep
129 # ARCH=xen make bzImage
131 Assuming the build works, you'll end up with
132 /xeno-1.2.bk/xenolinux-2.4.26/arch/xen/boot/xenolinux.gz. This is the
133 gzip version of XenoLinux kernel image.
136 Build the Domain Control Tools
137 ==============================
139 Under '/xeno-1.2.bk/tools', there are three sub-directories:
140 'balloon', 'xc' and 'misc', each containing
141 a group of tools. You can enter any of the four sub-directories
142 and type 'make' to compile the corresponding group of tools.
143 Or you can type 'make' under '/xeno-1.2.bk/tools' to compile
144 all the tools.
146 In order to compile the control-interface library in 'xc' you must
147 have zlib and development headers installed. Also you will need at
148 least Python v2.2.
150 'make install' in the tools directory will place executables and
151 libraries in /usr/bin and /usr/lib. You will need to be root to do this!
153 As noted earlier, 'make dist' installs files to a local 'install'
154 directory just outside the BK repository. These files will then need
155 to be installed manually onto the server.
157 The Example Scripts
158 ===================
160 The scripts in tools/examples/ are generally useful for
161 administering a Xen-based system. You can install them by running
162 'make install' in that directory.
164 The python scripts (*.py) are the main tools for controlling
165 Xen domains.
167 'defaults' and 'democd' are example configuration files for starting
168 new domains.
170 'xendomains' is a Sys-V style init script for starting and stopping
171 Xen domains when the system boots / shuts down.
173 These will be discussed below in more detail.
176 Installation
177 ==============================
179 First:
180 # cp /xen-1.2.bk/xen/xen.gz /boot/xen.gz
181 # cp /xen-1.2.bk/xenolinux-2.4.26/arch/xen/boot/xenolinux.gz /boot/xenolinux.gz
183 Second, you must have 'GNU Grub' installed. Then you need to edit
184 the Grub configuration file '/boot/grub/menu.lst'.
186 A typical Grub menu option might look like:
188 title Xen 1.2 / XenoLinux 2.4.26
189 kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1 noht
190 module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
192 The first line specifies which Xen image to use, and what command line
193 arguments to pass to Xen. In this case we set the maximum amount of
194 memory to allocate to domain0, and enable serial I/O at 115200 baud.
195 We could also disable smp support (nosmp) or disable hyper-threading
196 support (noht). If you have multiple network interface you can use
197 ifname=ethXX to select which one to use. If your network card is
198 unsupported, use ifname=dummy
200 The second line specifies which XenoLinux image to use, and the
201 standard linux command line arguments to pass to the kernel. In this
202 case, we're configuring the root partition and stating that it should
203 (initially) be mounted read-only (normal practice).
205 The following is a list of command line arguments to pass to Xen:
207 ignorebiostables Disable parsing of BIOS-supplied tables. This may
208 help with some chipsets that aren't fully supported
209 by Xen. If you specify this option then ACPI tables are
210 also ignored, and SMP support is disabled.
212 noreboot Don't reboot the machine automatically on errors.
213 This is useful to catch debug output if you aren't
214 catching console messages via the serial line.
216 nosmp Disable SMP support.
217 This option is implied by 'ignorebiostables'.
219 noacpi Disable ACPI tables, which confuse Xen on some chipsets.
220 This option is implied by 'ignorebiostables'.
222 watchdog Enable NMI watchdog which can report certain failures.
224 noht Disable Hyperthreading.
226 ifname=ethXX Select which Ethernet interface to use.
228 ifname=dummy Don't use any network interface.
230 com1=<baud>,DPS[,<io_base>,<irq>]
231 com2=<baud>,DPS[,<io_base>,<irq>]
232 Xen supports up to two 16550-compatible serial ports.
233 For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
234 9600-baud port, 8 data bits, no parity, 1 stop bit,
235 I/O port base 0x408, IRQ 5.
236 If the I/O base and IRQ are standard (com1:0x3f8,4;
237 com2:0x2f8,3) then they need not be specified.
239 console=<specifier list>
240 Specify the destination for Xen console I/O.
241 This is a comma-separated list of, for example:
242 vga: use VGA console and allow keyboard input
243 com1: use serial port com1
244 com2H: use serial port com2. Transmitted chars will
245 have the MSB set. Received chars must have
246 MSB set.
247 com2L: use serial port com2. Transmitted chars will
248 have the MSB cleared. Received chars must
249 have MSB cleared.
250 The latter two examples allow a single port to be
251 shared by two subsystems (eg. console and
252 debugger). Sharing is controlled by MSB of each
253 transmitted/received character.
254 [NB. Default for this option is 'com1,tty']
256 conswitch=<switch-char><auto-switch-char>
257 Specify how to switch serial-console input between
258 Xen and DOM0. The required sequence is CTRL-<switch_char>
259 pressed three times. Specifying '`' disables switching.
260 The <auto-switch-char> specifies whether Xen should
261 auto-switch input to DOM0 when it boots -- if it is 'x'
262 then auto-switching is disabled. Any other value, or
263 omitting the character, enables auto-switching.
264 [NB. Default for this option is 'a']
266 dom0_mem=xxx Set the maximum amount of memory for domain0.
268 tbuf_size=xxx Set the size of the per-cpu trace buffers, in pages
269 (default 1). Note that the trace buffers are only
270 enabled in debug builds. Most users can ignore
271 this feature completely.
273 sched=xxx Select the CPU scheduler Xen should use. The current
274 possibilities are 'bvt', 'atropos' and 'rrobin'. The
275 default is 'bvt'. For more information see
276 Sched-HOWTO.txt.
278 Boot into Domain 0
279 ==============================
281 Reboot your computer; After selecting the kernel to boot, stand back
282 and watch Xen boot, closely followed by "domain 0" running the
283 XenoLinux kernel. Depending on which root partition you have assigned
284 to XenoLinux kernel in Grub configuration file, you can use the
285 corresponding username / password to log in.
287 Once logged in, it should look just like any regular linux box. All
288 the usual tools and commands should work as per usual.
291 Start New Domains
292 ==============================
294 You must be 'root' to start new domains.
296 Make sure you have successfully configured at least one
297 physical network interface. Then:
299 # xen_nat_enable
301 The xc_dom_create.py program is useful for starting Xen domains.
302 You can specify configuration files using the -f switch on the command
303 line. The default configuration is in /etc/xc/defaults. You can
304 create custom versions of this to suit your local configuration.
306 You can override the settings in a configuration file using command
307 line arguments to xc_dom_create.py. However, you may find it simplest
308 to create a separate configuration file for each domain you start.
310 xc_dom_create.py will print the local TCP port to which you should
311 connect to perform console I/O. A suitable console client is provided
312 by the Python module xenctl.console_client: running this module from
313 the command line with <host> and <port> parameters will start a
314 terminal session. This module is also installed as /usr/bin/xencons,
315 from a copy in tools/misc/xencons. An alternative to manually running
316 a terminal client is to specify '-c' to xc_dom_create.py, or add
317 'auto_console=True' to the defaults file. This will cause
318 xc_dom_create.py to automatically become the console terminal after
319 starting the domain.
321 Boot-time output will be directed to this console by default, because
322 the console name is tty0. It is also possible to log in via the
323 virtual console --- once again, your normal startup scripts will work
324 as normal (e.g., by running mingetty on tty1-7). The device node to
325 which the virtual console is attached can be configured by specifying
326 'xencons=' on the OS command line:
327 'xencons=off' --> disable virtual console
328 'xencons=tty' --> attach console to /dev/tty1 (tty0 at boot-time)
329 'xencons=ttyS' --> attach console to /dev/ttyS0
332 Manage Running Domains
333 ==============================
335 You can see a list of existing domains with:
336 # xc_dom_control.py list
338 In order to stop a domain, you use:
339 # xc_dom_control.py stop <domain_id>
341 To shutdown a domain cleanly use:
342 # xc_dom_control.py shutdown <domain_id>
344 To destroy a domain immediately:
345 # xc_dom_control.py destroy <domain_id>
347 There are other more advanced options, including pinning domains to
348 specific CPUs and saving / resuming domains to / from disk files. To
349 get more information, run the tool without any arguments:
350 # xc_dom_control.py
352 There is more information available in the Xen README files, the
353 VBD-HOWTO and the contributed FAQ / HOWTO documents on the web.
356 Other Control Tasks using Python
357 ================================
359 A Python module 'Xc' is installed as part of the tools-install
360 process. This can be imported, and an 'xc object' instantiated, to
361 provide access to privileged command operations:
363 # import Xc
364 # xc = Xc.new()
365 # dir(xc)
366 # help(xc.domain_create)
368 In this way you can see that the class 'xc' contains useful
369 documentation for you to consult.
371 A further package of useful routines (xenctl) is also installed:
373 # import xenctl.utils
374 # help(xenctl.utils)
376 You can use these modules to write your own custom scripts or you can
377 customise the scripts supplied in the Xen distribution.
380 Automatically start / stop domains at boot / shutdown
381 =====================================================
383 A Sys-V style init script for RedHat systems is provided in
384 tools/examples/xendomains. When you run 'make install' in that
385 directory, it should be automatically copied to /etc/init.d/. You can
386 then enable it using the chkconfig command, e.g.:
388 # chkconfig --add xendomains
390 By default, this will start the boot-time domains in runlevels 3, 4
391 and 5. To specify a domain is to start at boot-time, place its
392 configuration file (or a link to it) under /etc/xc/auto/.
394 The script will also stop ALL domains when the system is shut down,
395 even domains that it did not start originally.
397 You can also use the "service" command (part of the RedHat standard
398 distribution) to run this script manually, e.g:
400 # service xendomains start
402 Starts all the domains with config files under /etc/xc/auto/.
404 # service xendomains stop
406 Shuts down ALL running Xen domains.