ia64/xen-unstable

view docs/Xeno-HOWTO.txt @ 1191:2d19a1a32eea

bitkeeper revision 1.805 (405855d4miA78lKONuhS5MJEPyuuhQ)

console_client.py:
Fix Python console module for direct use.
author kaf24@scramble.cl.cam.ac.uk
date Wed Mar 17 13:42:44 2004 +0000 (2004-03-17)
parents b92991cbd303
children 5f1ec88d7c3a
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.2 release lives at:
14 'bk://xen.bkbits.net/xeno-1.2.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 the tools and then run:
21 # bk clone bk://xen.bkbits.net/xeno-1.2.bk
23 Under your current directory, a new directory named 'xeno-1.2.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.2.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 repository and perform a full build.
39 To build Xen manually:
41 # cd xeno-1.2.bk/xen
42 # make clean
43 # make
45 This will (should) produce a file called 'xen' 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 'xen.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.24 tree, which is located at:
68 http://www.kernel.org/pub/linux/kernel/v2.4
70 Then:
71 # mv linux-2.4.24.tar.gz /xeno-1.2.bk
72 # cd /xeno-1.2.bk
73 # tar -zxvf linux-2.4.24.tar.gz
75 You'll find a new directory 'linux-2.4.24' which contains all
76 the vanilla Linux 2.4.24 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.2.bk/xenolinux-2.4.24-sparse
85 # ./mkbuildtree ../linux-2.4.24
87 Finally, rename the buildtree since it is now a xenolinux buildtree.
89 # cd /xeno-1.2.bk
90 # mv linux-2.4.24 xenolinux-2.4.24
92 Now that the buildtree is there, you can build the xenolinux kernel.
93 The default configuration should work fine for most people (use 'make
94 oldconfig') but you can customise using one of the other config tools
95 if you want.
97 # cd /xeno-1.2.bk/xenolinux-2.4.24
98 # ARCH=xeno make oldconfig { or menuconfig, or xconfig, or config }
99 # ARCH=xeno make dep
100 # ARCH=xeno make bzImage
102 Assuming the build works, you'll end up with
103 /xeno-1.2.bk/xenolinux-2.4.24/arch/xeno/boot/xenolinux.gz. This is the
104 gzip version of XenoLinux kernel image.
107 Build the Domain Control Tools
108 ==============================
110 Under '/xeno-1.2.bk/tools', there are three sub-directories:
111 'balloon', 'xc' and 'misc', each containing
112 a group of tools. You can enter any of the four sub-directories
113 and type 'make' to compile the corresponding group of tools.
114 Or you can type 'make' under '/xeno-1.2.bk/tools' to compile
115 all the tools.
117 In order to compile the control-interface library in 'xc' you must
118 have zlib and development headers installed. Also you will need at
119 least Python v2.2.
121 'make install' in the tools directory will place executables and
122 libraries in /usr/bin and /usr/lib. You will need to be root to do this!
124 As noted earlier, 'make dist' installs files to a local 'install'
125 directory just outside the BK repository. These files will then need
126 to be installed manually onto the Xenoserver.
128 The Example Scripts
129 ===================
131 The scripts in tools/examples/ are generally useful for
132 administering a Xen-based system. You can install them by running
133 'make install' in that directory.
135 The python scripts (*.py) are the main tools for controlling
136 Xen domains.
138 'defaults' and 'democd' are example configuration files for starting
139 new domains.
141 'xendomains' is a Sys-V style init script for starting and stopping
142 Xen domains when the system boots / shuts down.
144 These will be discussed below in more detail.
147 Installation
148 ==============================
150 First:
151 # cp /xen-1.2.bk/xen/xen.gz /boot/xen.gz
152 # cp /xen-1.2.bk/xenolinux-2.4.24/arch/xeno/boot/xenolinux.gz /boot/xenolinux.gz
154 Second, you must have 'GNU Grub' installed. Then you need to edit
155 the Grub configuration file '/boot/grub/menu.lst'.
157 A typical Grub menu option might look like:
159 title Xen 1.2 / XenoLinux 2.4.24
160 kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1 noht
161 module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
163 The first line specifies which Xen image to use, and what command line
164 arguments to pass to Xen. In this case we set the maximum amount of
165 memory to allocate to domain0, and enable serial I/O at 115200 baud.
166 We could also disable smp support (nosmp) or disable hyper-threading
167 support (noht). If you have multiple network interface you can use
168 ifname=ethXX to select which one to use. If your network card is
169 unsupported, use ifname=dummy
171 The second line specifies which XenoLinux image to use, and the
172 standard linux command line arguments to pass to the kernel. In this
173 case, we're configuring the root partition and stating that it should
174 (initially) be mounted read-only (normal practice).
176 The following is a list of command line arguments to pass to Xen:
178 ignorebiostables Disable parsing of BIOS-supplied tables. This may
179 help with some chipsets that aren't fully supported
180 by Xen. If you specify this option then ACPI tables are
181 also ignored, and SMP support is disabled.
183 noreboot Don't reboot the machine automatically on errors.
184 This is useful to catch debug output if you aren't
185 catching console messages via the serial line.
187 nosmp Disable SMP support.
188 This option is implied by 'ignorebiostables'.
190 noacpi Disable ACPI tables, which confuse Xen on some chipsets.
191 This option is implied by 'ignorebiostables'.
193 watchdog Enable NMI watchdog which can report certain failures.
195 noht Disable Hyperthreading.
197 ifname=ethXX Select which Ethernet interface to use.
199 ifname=dummy Don't use any network interface.
201 com1=<baud>,DPS[,<io_base>,<irq>]
202 com2=<baud>,DPS[,<io_base>,<irq>]
203 Xen supports up to two 16550-compatible serial ports.
204 For example: 'com1=9600,8n1,0x408,5' maps COM1 to a
205 9600-baud port, 8 data bits, no parity, 1 stop bit,
206 I/O port base 0x408, IRQ 5.
207 If the I/O base and IRQ are standard (com1:0x3f8,4;
208 com2:0x2f8,3) then they need not be specified.
210 console=<specifier list>
211 Specify the destination for Xen console I/O.
212 This is a comma-separated list of, for example:
213 vga: use VGA console and allow keyboard input
214 com1: use serial port com1
215 com2H: use serial port com2. Transmitted chars will
216 have the MSB set. Received chars must have
217 MSB set.
218 com2L: use serial port com2. Transmitted chars will
219 have the MSB cleared. Received chars must
220 have MSB cleared.
221 The latter two examples allow a single port to be
222 shared by two subsystems (eg. console and
223 debugger). Sharing is controlled by MSB of each
224 transmitted/received character.
225 [NB. Default for this option is 'com1,tty']
227 dom0_mem=xxx Set the maximum amount of memory for domain0.
229 tbuf_size=xxx Set the size of the per-cpu trace buffers, in pages
230 (default 1). Note that the trace buffers are only
231 enabled in debug builds. Most users can ignore
232 this feature completely.
234 Boot into Domain 0
235 ==============================
237 Reboot your computer; After selecting the kernel to boot, stand back
238 and watch Xen boot, closely followed by "domain 0" running the
239 XenoLinux kernel. Depending on which root partition you have assigned
240 to XenoLinux kernel in Grub configuration file, you can use the
241 corresponding username / password to log in.
243 Once logged in, it should look just like any regular linux box. All
244 the usual tools and commands should work as per usual.
247 Start New Domains
248 ==============================
250 You must be 'root' to start new domains.
252 Make sure you have successfully configured at least one
253 physical network interface. Then:
255 # xen_nat_enable
257 The xc_dom_create.py program is useful for starting Xen domains.
258 You can specify configuration files using the -f switch on the command
259 line. The default configuration is in /etc/xc/defaults. You can
260 create custom versions of this to suit your local configuration.
262 You can override the settings in a configuration file using command
263 line arguments to xc_dom_create.py. However, you may find it simplest
264 to create a separate configuration file for each domain you start.
266 xc_dom_create.py will print the local TCP port to which you should
267 connect to perform console I/O. A suitable console client is provided
268 by the Python module xend.console_client: running this module from the
269 command line with <host> and <port> parameters will start a terminal
270 session. An alternative is to specify '-c' to xc_dom_create.py, or add
271 'auto_console=True' to the defaults file. This will cause
272 xc_dom_create.py to automatically become teh console terminal after
273 starting the domain.
276 Manage Running Domains
277 ==============================
279 You can see a list of existing domains with:
280 # xc_dom_control.py list
282 In order to stop a domain, you use:
283 # xc_dom_control.py stop <domain_id>
285 To shutdown a domain cleanly use:
286 # xc_dom_control.py shutdown <domain_id>
288 To destroy a domain immediately:
289 # xc_dom_control.py destroy <domain_id>
291 There are other more advanced options, including pinning domains to
292 specific CPUs and saving / resuming domains to / from disk files. To
293 get more information, run the tool without any arguments:
294 # xc_dom_control.py
296 There is more information available in the Xen README files, the
297 VBD-HOWTO and the contributed FAQ / HOWTO documents on the web.
300 Other Control Tasks using Python
301 ================================
303 A Python module 'Xc' is installed as part of the tools-install
304 process. This can be imported, and an 'xc object' instantiated, to
305 provide access to privileged command operations:
307 # import Xc
308 # xc = Xc.new()
309 # dir(xc)
310 # help(xc.domain_create)
312 In this way you can see that the class 'xc' contains useful
313 documentation for you to consult.
315 A further package of useful routines (xenctl) is also installed:
317 # import xenctl.utils
318 # help(xenctl.utils)
320 You can use these modules to write your own custom scripts or you can
321 customise the scripts supplied in the Xen distribution.
324 Automatically start / stop domains at boot / shutdown
325 =====================================================
327 A Sys-V style init script for RedHat systems is provided in
328 tools/examples/xendomains. When you run 'make install' in that
329 directory, it should be automatically copied to /etc/init.d/. You can
330 then enable it using the chkconfig command, e.g.:
332 # chkconfig --add xendomains
334 By default, this will start the boot-time domains in runlevels 3, 4
335 and 5. To specify a domain is to start at boot-time, place its
336 configuration file (or a link to it) under /etc/xc/auto/.
338 The script will also stop ALL domains when the system is shut down,
339 even domains that it did not start originally.
341 You can also use the "service" command (part of the RedHat standard
342 distribution) to run this script manually, e.g:
344 # service xendomains start
346 Starts all the domains with config files under /etc/xc/auto/.
348 # service xendomains stop
350 Shuts down ALL running Xen domains.