ia64/xen-unstable

annotate README @ 10068:c20e766a1f72

Our 10,000th changeset! (Clean up trailing whitespace in README file :-)

Signed-off-by: Keir Fraser <keir@xensource.com>
author kaf24@firebug.cl.cam.ac.uk
date Tue May 16 13:46:57 2006 +0100 (2006-05-16)
parents a5fcffc826f3
children 765654a55245
rev   line source
cl349@9840 1 ################################
kaf24@10068 2 __ __ _____ ___
kaf24@10068 3 \ \/ /___ _ __ |___ / / _ \
cl349@9840 4 \ // _ \ '_ \ |_ \| | | |
cl349@9840 5 / \ __/ | | | ___) | |_| |
kaf24@10068 6 /_/\_\___|_| |_| |____(_)___/
cl349@9840 7
cl349@9840 8 ################################
cl349@9840 9
cl349@9840 10 http://www.xensource.com/xen/about.html
cl349@9840 11
cl349@9840 12 What is Xen?
cl349@9840 13 ============
cl349@9840 14
cl349@9840 15 Xen is a Virtual Machine Monitor (VMM) originally developed by the
cl349@9840 16 Systems Research Group of the University of Cambridge Computer
cl349@9840 17 Laboratory, as part of the UK-EPSRC funded XenoServers project. Xen
cl349@9840 18 is freely-distributable Open Source software, released under the GNU
cl349@9840 19 GPL. Since its initial public release, Xen has grown a large
cl349@9840 20 development community, spearheaded by XenSource Inc, a company created
cl349@9840 21 by the original Xen development team to build enterprise products
cl349@9840 22 around Xen.
cl349@9840 23
cl349@9840 24 The 3.0 release offers excellent performance, hardware support and
cl349@9840 25 enterprise-grade features such as x86_32-PAE, x86_64, SMP guests and
cl349@9840 26 live relocation of VMs. This install tree contains source for a Linux
cl349@9840 27 2.6 guest; ports to Linux 2.4, NetBSD, FreeBSD and Solaris will follow
cl349@9840 28 later (and are already available for previous Xen releases).
cl349@9840 29
cl349@9840 30 This file contains some quick-start instructions to install Xen on
cl349@9840 31 your system. For full documentation, see the Xen User Manual. If this
cl349@9840 32 is a pre-built release then you can find the manual at:
cl349@9840 33 dist/install/usr/share/doc/xen/pdf/user.pdf
cl349@9840 34 If you have a source release, then 'make -C docs' will build the
cl349@9840 35 manual at docs/pdf/user.pdf.
cl349@9840 36
cl349@9840 37 Quick-Start Guide - Pre-Built Binary Release
cl349@9840 38 ============================================
cl349@9840 39
cl349@9840 40 [NB. Unless noted otherwise, all the following steps should be
cl349@9840 41 performed with root privileges.]
cl349@9840 42
cl349@9840 43 1. Install the binary distribution onto your filesystem:
cl349@9840 44
cl349@9840 45 # sh ./install.sh
cl349@9840 46
cl349@9840 47 Among other things, this will install Xen and Xen-ready Linux
cl349@9840 48 kernel files in /boot, kernel modules and Python packages in /lib,
cl349@9840 49 and various control tools in standard 'bin' directories.
cl349@9840 50
cl349@9840 51 2. Configure your bootloader to boot Xen and an initial Linux virtual
cl349@9840 52 machine. Note that Xen currently only works with GRUB and pxelinux
cl349@9840 53 derived boot loaders: less common alternatives such as LILO are
cl349@9840 54 *not* supported. You can most likely find your GRUB menu file at
cl349@9840 55 /boot/grub/menu.lst: edit this file to include an entry like the
cl349@9840 56 following:
cl349@9840 57
cl349@9840 58 title Xen 3.0 / XenLinux 2.6
cl349@9840 59 kernel /boot/xen-3.0.gz console=vga
cl349@9840 60 module /boot/vmlinuz-2.6-xen root=<root-dev> ro console=tty0
cl349@9840 61 module /boot/initrd-2.6-xen.img
cl349@9840 62
cl349@9840 63 NB: Not all kernel configs need an initial ram disk (initrd), but
cl349@9840 64 if you do specify one you'll need to use the 'module' grub directive
cl349@9840 65 rather than 'initrd'.
cl349@9840 66
cl349@9840 67 The linux command line takes all the usual options, such as
cl349@9840 68 root=<root-dev> to specify your usual root partition (e.g.,
kaf24@10068 69 /dev/hda1).
cl349@9840 70
cl349@9840 71 The Xen command line takes a number of optional arguments described
cl349@9840 72 in the manual. The most common is 'dom0_mem=xxxM' which sets the
cl349@9840 73 amount of memory to allocate for use by your initial virtual
cl349@9840 74 machine (known as domain 0). Note that Xen itself reserves about
cl349@9840 75 32MB memory for internal use, which is not available for allocation
kaf24@10068 76 to virtual machines.
cl349@9840 77
cl349@9840 78 3. Reboot your system and select the "Xen 3.0 / XenLinux 2.6" menu
cl349@9840 79 option. After booting Xen, Linux will start and your initialisation
cl349@9840 80 scripts should execute in the usual way.
cl349@9840 81
cl349@9840 82 Quick-Start Guide - Source Release
cl349@9840 83 ==================================
cl349@9840 84
cl349@9840 85 First, there are a number of prerequisites for building a Xen source
cl349@9840 86 release. Make sure you have all the following installed, either by
cl349@9840 87 visiting the project webpage or installing a pre-built package
cl349@9840 88 provided by your Linux distributor:
kaf24@10068 89 * GCC (preferably v3.2.x or v3.3.x; older versions are unsupported)
cl349@9840 90 * GNU Make
cl349@9840 91 * GNU Binutils
cl349@9840 92 * Development install of zlib (e.g., zlib-dev)
cl349@9840 93 * Development install of Python v2.3 or later (e.g., python-dev)
cl349@9840 94 * bridge-utils package (/sbin/brctl)
cl349@9840 95 * iproute package (/sbin/ip)
cl349@9840 96 * hotplug or udev
cl349@9840 97
cl349@9840 98 [NB. Unless noted otherwise, all the following steps should be
cl349@9840 99 performed with root privileges.]
cl349@9840 100
cl349@9840 101 1. Download and untar the source tarball file. This will be a
cl349@9840 102 file named xen-unstable-src.tgz, or xen-$version-src.tgz.
cl349@9840 103 You can also pull the current version from the SCMS
cl349@9840 104 that is being used (Bitkeeper, scheduled to change shortly).
cl349@9840 105
cl349@9840 106 # tar xzf xen-unstable-src.tgz
cl349@9840 107
cl349@9840 108 Assuming you are using the unstable tree, this will
cl349@9840 109 untar into xen-unstable. The rest of the instructions
cl349@9840 110 use the unstable tree as an example, substitute the
cl349@9840 111 version for unstable.
cl349@9840 112
cl349@9840 113 2. cd to xen-unstable (or whatever you sensibly rename it to).
cl349@9840 114 The Linux, netbsd and freebsd kernel source trees are in
cl349@9840 115 the $os-$version-xen-sparse directories.
cl349@9840 116
cl349@9840 117 On Linux:
cl349@9840 118
cl349@9840 119 3. For the very first build, or if you want to destroy existing
cl349@9840 120 .configs and build trees, perform the following steps:
cl349@9840 121
cl349@9840 122 # make world
cl349@9840 123 # make install
cl349@9840 124
kaf24@10068 125 This will create and install onto the local machine. It will build
cl349@9840 126 the xen binary (xen.gz), and a linux kernel and modules that can be
cl349@9840 127 used in both dom0 and an unprivileged guest kernel (vmlinuz-2.6.x-xen),
cl349@9840 128 the tools and the documentation.
cl349@9840 129
kaf24@10068 130 You can override the destination for make install by setting DESTDIR
cl349@9840 131 to some value.
cl349@9840 132
kaf24@10068 133 The make command line defaults to building the kernel vmlinuz-2.6.x-xen.
kaf24@10068 134 You can override this default by specifying KERNELS=kernelname. For
kaf24@10068 135 example, you can make two kernels - linux-2.6-xen0
kaf24@10068 136 and linux-2.6-xenU - which are smaller builds containing only selected
kaf24@10068 137 modules, intended primarily for developers that don't like to wait
cl349@9840 138 for a full -xen kernel to build. The -xenU kernel is particularly small,
cl349@9840 139 as it does not contain any physical device drivers, and hence is
cl349@9840 140 only useful for guest domains.
cl349@9840 141
cl349@9840 142 To make these two kernels, simply specify
cl349@9840 143
cl349@9840 144 KERNELS="linux-2.6-xen0 linux-2.6-xenU"
cl349@9840 145
cl349@9840 146 in the make command line.
cl349@9840 147
cl349@9840 148 If you want to build an x86_32 PAE capable xen and kernel to work
cl349@9840 149 on machines with >= 4GB of memory, use XEN_TARGET_X86_PAE=y on the
cl349@9840 150 make command line.
cl349@9840 151
cl349@9840 152 4. To rebuild an existing tree without modifying the config:
cl349@9840 153 # make dist
cl349@9840 154
cl349@9840 155 This will build and install xen, kernels, tools, and
kaf24@10068 156 docs into the local dist/ directory.
cl349@9840 157
kaf24@10068 158 You can override the destination for make install by setting DISTDIR
cl349@9840 159 to some value.
cl349@9840 160
kaf24@10068 161 make install and make dist differ in that make install does the
kaf24@10068 162 right things for your local machine (installing the appropriate
kaf24@10068 163 version of hotplug or udev scripts, for example), but make dist
kaf24@10068 164 includes all versions of those scripts, so that you can copy the dist
cl349@9840 165 directory to another machine and install from that distribution.
cl349@9840 166
cl349@9840 167 5. To rebuild a kernel with a modified config:
cl349@9840 168
cl349@9840 169 # make linux-2.6-xen-config CONFIGMODE=menuconfig (or xconfig)
cl349@9840 170 # make linux-2.6-xen-build
cl349@9840 171 # make linux-2.6-xen-install
cl349@9840 172
cl349@9840 173 Depending on your config, you may need to use 'mkinitrd' to create
kaf24@10068 174 an initial ram disk, just like a native system e.g.
cl349@9840 175 # depmod 2.6.16-xen
cl349@9840 176 # mkinitrd -v -f --with=aacraid --with=sd_mod --with=scsi_mod initrd-2.6.16-xen.img 2.6.16-xen