ia64/xen-unstable

changeset 9655:591555bc4acb

Updated to reflect new KERNELS defaults, and properly describe make install and
make dist.
author emellor@leeni.uk.xensource.com
date Mon Apr 10 16:21:44 2006 +0100 (2006-04-10)
parents fb174770f426
children 7af0d54f598c
files README
line diff
     1.1 --- a/README	Fri Apr 07 11:52:00 2006 +0100
     1.2 +++ b/README	Mon Apr 10 16:21:44 2006 +0100
     1.3 @@ -1,158 +1,176 @@
     1.4 -################################
     1.5 - __  __            _____  ___  
     1.6 - \ \/ /___ _ __   |___ / / _ \ 
     1.7 -  \  // _ \ '_ \    |_ \| | | |
     1.8 -  /  \  __/ | | |  ___) | |_| |
     1.9 - /_/\_\___|_| |_| |____(_)___/ 
    1.10 -
    1.11 -################################
    1.12 -
    1.13 -http://www.xensource.com/xen/about.html
    1.14 -
    1.15 -What is Xen?
    1.16 -============
    1.17 -
    1.18 -Xen is a Virtual Machine Monitor (VMM) originally developed by the
    1.19 -Systems Research Group of the University of Cambridge Computer
    1.20 -Laboratory, as part of the UK-EPSRC funded XenoServers project.  Xen
    1.21 -is freely-distributable Open Source software, released under the GNU
    1.22 -GPL. Since its initial public release, Xen has grown a large
    1.23 -development community, spearheaded by XenSource Inc, a company created
    1.24 -by the original Xen development team to build enterprise products
    1.25 -around Xen.
    1.26 -
    1.27 -The 3.0 release offers excellent performance, hardware support and
    1.28 -enterprise-grade features such as x86_32-PAE, x86_64, SMP guests and
    1.29 -live relocation of VMs. This install tree contains source for a Linux
    1.30 -2.6 guest; ports to Linux 2.4, NetBSD, FreeBSD and Solaris will follow
    1.31 -later (and are already available for previous Xen releases).
    1.32 -
    1.33 -This file contains some quick-start instructions to install Xen on
    1.34 -your system. For full documentation, see the Xen User Manual. If this
    1.35 -is a pre-built release then you can find the manual at:
    1.36 - dist/install/usr/share/doc/xen/pdf/user.pdf
    1.37 -If you have a source release, then 'make -C docs' will build the
    1.38 -manual at docs/pdf/user.pdf.
    1.39 -
    1.40 -Quick-Start Guide - Pre-Built Binary Release
    1.41 -============================================
    1.42 -
    1.43 -[NB. Unless noted otherwise, all the following steps should be
    1.44 -performed with root privileges.]
    1.45 -
    1.46 -1. Install the binary distribution onto your filesystem:
    1.47 -
    1.48 -    # sh ./install.sh
    1.49 -
    1.50 -   Among other things, this will install Xen and Xen-ready Linux
    1.51 -   kernel files in /boot, kernel modules and Python packages in /lib,
    1.52 -   and various control tools in standard 'bin' directories.
    1.53 -
    1.54 -2. Configure your bootloader to boot Xen and an initial Linux virtual
    1.55 -   machine. Note that Xen currently only works with GRUB and pxelinux
    1.56 -   derived boot loaders: less common alternatives such as LILO are
    1.57 -   *not* supported. You can most likely find your GRUB menu file at
    1.58 -   /boot/grub/menu.lst: edit this file to include an entry like the
    1.59 -   following:
    1.60 -
    1.61 -    title Xen 3.0 / XenLinux 2.6
    1.62 -       kernel /boot/xen-3.0.gz console=vga
    1.63 -       module /boot/vmlinuz-2.6-xen root=<root-dev> ro console=tty0
    1.64 -       module /boot/initrd-2.6-xen.img
    1.65 -
    1.66 -   NB: Not all kernel configs need an initial ram disk (initrd), but
    1.67 -   if you do specify one you'll need to use the 'module' grub directive
    1.68 -   rather than 'initrd'.
    1.69 -
    1.70 -   The linux command line takes all the usual options, such as
    1.71 -   root=<root-dev> to specify your usual root partition (e.g.,
    1.72 -   /dev/hda1).  
    1.73 -
    1.74 -   The Xen command line takes a number of optional arguments described
    1.75 -   in the manual. The most common is 'dom0_mem=xxxM' which sets the
    1.76 -   amount of memory to allocate for use by your initial virtual
    1.77 -   machine (known as domain 0). Note that Xen itself reserves about
    1.78 -   32MB memory for internal use, which is not available for allocation
    1.79 -   to virtual machines.  
    1.80 -
    1.81 -3. Reboot your system and select the "Xen 3.0 / XenLinux 2.6" menu
    1.82 -   option. After booting Xen, Linux will start and your initialisation
    1.83 -   scripts should execute in the usual way.
    1.84 -
    1.85 -Quick-Start Guide - Source Release
    1.86 -==================================
    1.87 -
    1.88 -First, there are a number of prerequisites for building a Xen source
    1.89 -release. Make sure you have all the following installed, either by
    1.90 -visiting the project webpage or installing a pre-built package
    1.91 -provided by your Linux distributor:
    1.92 -    * GCC (preferably v3.2.x or v3.3.x; older versions are unsupported) 
    1.93 -    * GNU Make
    1.94 -    * GNU Binutils
    1.95 -    * Development install of zlib (e.g., zlib-dev)
    1.96 -    * Development install of Python v2.3 or later (e.g., python-dev)
    1.97 -    * bridge-utils package (/sbin/brctl)
    1.98 -    * iproute package (/sbin/ip)
    1.99 -    * hotplug or udev
   1.100 -
   1.101 -[NB. Unless noted otherwise, all the following steps should be
   1.102 -performed with root privileges.]
   1.103 -
   1.104 -1. Download and untar the source tarball file. This will be a
   1.105 -   file named xen-unstable-src.tgz, or xen-$version-src.tgz.
   1.106 -   You can also pull the current version from the SCMS
   1.107 -   that is being used (Bitkeeper, scheduled to change shortly).
   1.108 -
   1.109 -    # tar xzf xen-unstable-src.tgz
   1.110 -
   1.111 -   Assuming you are using the unstable tree, this will
   1.112 -   untar into xen-unstable. The rest of the instructions
   1.113 -   use the unstable tree as an example, substitute the
   1.114 -   version for unstable.
   1.115 -
   1.116 -2. cd to xen-unstable (or whatever you sensibly rename it to).
   1.117 -   The Linux, netbsd and freebsd kernel source trees are in
   1.118 -   the $os-$version-xen-sparse directories.
   1.119 -
   1.120 -On Linux:
   1.121 -
   1.122 -3. For the very first build, or if you want to destroy existing
   1.123 -   .configs and build trees, perform the following steps:
   1.124 -
   1.125 -    # make KERNELS=linux-2.6-xen world
   1.126 -    # make install
   1.127 -
   1.128 -   It will create and install into the dist/ directory which is the
   1.129 -   default install location. It will build the xen binary (xen.gz),
   1.130 -   and a linux kernel and modules that can be used in both dom0 and an
   1.131 -   unprivileged guest kernel (vmlinuz-2.6.x-xen), the tools and the
   1.132 -   documentation.
   1.133 -
   1.134 -   If you don't specify KERNELS= on the make command line it will
   1.135 -   default to building two kernels, vmlinuz-2.6.x-xen0 and
   1.136 -   vmlinuz-2.6.x-xenU. These are smaller builds with just selected
   1.137 -   modules, intended primarilly for developers that don't like to wait
   1.138 -   for a -xen kernel to build. The -xenU kernel is particularly small
   1.139 -   as it does not contain any physical device drivers, and hence is
   1.140 -   only useful for guest domains.
   1.141 -
   1.142 -   If you want to build an x86_32 PAE capable xen and kernel to work
   1.143 -   on machines with >= 4GB of memory, use XEN_TARGET_X86_PAE=y on the
   1.144 -   make command line.
   1.145 -
   1.146 -4. To rebuild an existing tree without modifying the config:
   1.147 -    # make dist
   1.148 -
   1.149 -   This will build and install xen, kernels, tools, and
   1.150 -   docs into the local dist/ directory.
   1.151 -
   1.152 -5. To rebuild a kernel with a modified config:
   1.153 -
   1.154 -    # make linux-2.6-xen-config CONFIGMODE=menuconfig     (or xconfig)
   1.155 -    # make linux-2.6-xen-build
   1.156 -    # make linux-2.6-xen-install
   1.157 -
   1.158 -   Depending on your config, you may need to use 'mkinitrd' to create
   1.159 -   an initial ram disk, just like a native system e.g. 
   1.160 -    # depmod 2.6.12.6-xen
   1.161 -    # mkinitrd -v -f --with=aacraid --with=sd_mod --with=scsi_mod initrd-2.6.12.6-xen.img 2.6.12.6-xen
   1.162 +################################
   1.163 + __  __            _____  ___  
   1.164 + \ \/ /___ _ __   |___ / / _ \ 
   1.165 +  \  // _ \ '_ \    |_ \| | | |
   1.166 +  /  \  __/ | | |  ___) | |_| |
   1.167 + /_/\_\___|_| |_| |____(_)___/ 
   1.168 +
   1.169 +################################
   1.170 +
   1.171 +http://www.xensource.com/xen/about.html
   1.172 +
   1.173 +What is Xen?
   1.174 +============
   1.175 +
   1.176 +Xen is a Virtual Machine Monitor (VMM) originally developed by the
   1.177 +Systems Research Group of the University of Cambridge Computer
   1.178 +Laboratory, as part of the UK-EPSRC funded XenoServers project.  Xen
   1.179 +is freely-distributable Open Source software, released under the GNU
   1.180 +GPL. Since its initial public release, Xen has grown a large
   1.181 +development community, spearheaded by XenSource Inc, a company created
   1.182 +by the original Xen development team to build enterprise products
   1.183 +around Xen.
   1.184 +
   1.185 +The 3.0 release offers excellent performance, hardware support and
   1.186 +enterprise-grade features such as x86_32-PAE, x86_64, SMP guests and
   1.187 +live relocation of VMs. This install tree contains source for a Linux
   1.188 +2.6 guest; ports to Linux 2.4, NetBSD, FreeBSD and Solaris will follow
   1.189 +later (and are already available for previous Xen releases).
   1.190 +
   1.191 +This file contains some quick-start instructions to install Xen on
   1.192 +your system. For full documentation, see the Xen User Manual. If this
   1.193 +is a pre-built release then you can find the manual at:
   1.194 + dist/install/usr/share/doc/xen/pdf/user.pdf
   1.195 +If you have a source release, then 'make -C docs' will build the
   1.196 +manual at docs/pdf/user.pdf.
   1.197 +
   1.198 +Quick-Start Guide - Pre-Built Binary Release
   1.199 +============================================
   1.200 +
   1.201 +[NB. Unless noted otherwise, all the following steps should be
   1.202 +performed with root privileges.]
   1.203 +
   1.204 +1. Install the binary distribution onto your filesystem:
   1.205 +
   1.206 +    # sh ./install.sh
   1.207 +
   1.208 +   Among other things, this will install Xen and Xen-ready Linux
   1.209 +   kernel files in /boot, kernel modules and Python packages in /lib,
   1.210 +   and various control tools in standard 'bin' directories.
   1.211 +
   1.212 +2. Configure your bootloader to boot Xen and an initial Linux virtual
   1.213 +   machine. Note that Xen currently only works with GRUB and pxelinux
   1.214 +   derived boot loaders: less common alternatives such as LILO are
   1.215 +   *not* supported. You can most likely find your GRUB menu file at
   1.216 +   /boot/grub/menu.lst: edit this file to include an entry like the
   1.217 +   following:
   1.218 +
   1.219 +    title Xen 3.0 / XenLinux 2.6
   1.220 +       kernel /boot/xen-3.0.gz console=vga
   1.221 +       module /boot/vmlinuz-2.6-xen root=<root-dev> ro console=tty0
   1.222 +       module /boot/initrd-2.6-xen.img
   1.223 +
   1.224 +   NB: Not all kernel configs need an initial ram disk (initrd), but
   1.225 +   if you do specify one you'll need to use the 'module' grub directive
   1.226 +   rather than 'initrd'.
   1.227 +
   1.228 +   The linux command line takes all the usual options, such as
   1.229 +   root=<root-dev> to specify your usual root partition (e.g.,
   1.230 +   /dev/hda1).  
   1.231 +
   1.232 +   The Xen command line takes a number of optional arguments described
   1.233 +   in the manual. The most common is 'dom0_mem=xxxM' which sets the
   1.234 +   amount of memory to allocate for use by your initial virtual
   1.235 +   machine (known as domain 0). Note that Xen itself reserves about
   1.236 +   32MB memory for internal use, which is not available for allocation
   1.237 +   to virtual machines.  
   1.238 +
   1.239 +3. Reboot your system and select the "Xen 3.0 / XenLinux 2.6" menu
   1.240 +   option. After booting Xen, Linux will start and your initialisation
   1.241 +   scripts should execute in the usual way.
   1.242 +
   1.243 +Quick-Start Guide - Source Release
   1.244 +==================================
   1.245 +
   1.246 +First, there are a number of prerequisites for building a Xen source
   1.247 +release. Make sure you have all the following installed, either by
   1.248 +visiting the project webpage or installing a pre-built package
   1.249 +provided by your Linux distributor:
   1.250 +    * GCC (preferably v3.2.x or v3.3.x; older versions are unsupported) 
   1.251 +    * GNU Make
   1.252 +    * GNU Binutils
   1.253 +    * Development install of zlib (e.g., zlib-dev)
   1.254 +    * Development install of Python v2.3 or later (e.g., python-dev)
   1.255 +    * bridge-utils package (/sbin/brctl)
   1.256 +    * iproute package (/sbin/ip)
   1.257 +    * hotplug or udev
   1.258 +
   1.259 +[NB. Unless noted otherwise, all the following steps should be
   1.260 +performed with root privileges.]
   1.261 +
   1.262 +1. Download and untar the source tarball file. This will be a
   1.263 +   file named xen-unstable-src.tgz, or xen-$version-src.tgz.
   1.264 +   You can also pull the current version from the SCMS
   1.265 +   that is being used (Bitkeeper, scheduled to change shortly).
   1.266 +
   1.267 +    # tar xzf xen-unstable-src.tgz
   1.268 +
   1.269 +   Assuming you are using the unstable tree, this will
   1.270 +   untar into xen-unstable. The rest of the instructions
   1.271 +   use the unstable tree as an example, substitute the
   1.272 +   version for unstable.
   1.273 +
   1.274 +2. cd to xen-unstable (or whatever you sensibly rename it to).
   1.275 +   The Linux, netbsd and freebsd kernel source trees are in
   1.276 +   the $os-$version-xen-sparse directories.
   1.277 +
   1.278 +On Linux:
   1.279 +
   1.280 +3. For the very first build, or if you want to destroy existing
   1.281 +   .configs and build trees, perform the following steps:
   1.282 +
   1.283 +    # make world
   1.284 +    # make install
   1.285 +
   1.286 +   This will create and install onto the local machine. It will build 
   1.287 +   the xen binary (xen.gz), and a linux kernel and modules that can be
   1.288 +   used in both dom0 and an unprivileged guest kernel (vmlinuz-2.6.x-xen),
   1.289 +   the tools and the documentation.
   1.290 +
   1.291 +   You can override the destination for make install by setting DESTDIR 
   1.292 +   to some value.
   1.293 +
   1.294 +   The make command line defaults to building the kernel vmlinuz-2.6.x-xen. 
   1.295 +   You can override this default by specifying KERNELS=kernelname. For 
   1.296 +   example, you can make two kernels - linux-2.6.16-xen0 
   1.297 +   and linux-2.6.16-xenU - which are smaller builds containing only selected 
   1.298 +   modules, intended primarilly for developers that don't like to wait 
   1.299 +   for a full -xen kernel to build. The -xenU kernel is particularly small,
   1.300 +   as it does not contain any physical device drivers, and hence is
   1.301 +   only useful for guest domains.
   1.302 +
   1.303 +   To make these two kernels, simply specify
   1.304 +
   1.305 +   KERNELS="linux-2.6.16-xen0 linux-2.6.16-xenU"
   1.306 +
   1.307 +   in the make command line.
   1.308 +
   1.309 +   If you want to build an x86_32 PAE capable xen and kernel to work
   1.310 +   on machines with >= 4GB of memory, use XEN_TARGET_X86_PAE=y on the
   1.311 +   make command line.
   1.312 +
   1.313 +4. To rebuild an existing tree without modifying the config:
   1.314 +    # make dist
   1.315 +
   1.316 +   This will build and install xen, kernels, tools, and
   1.317 +   docs into the local dist/ directory. 
   1.318 +
   1.319 +   You can override the destination for make install by setting DISTDIR 
   1.320 +   to some value.
   1.321 +
   1.322 +   make install and make dist differ in that make install does the 
   1.323 +   right things for your local machine (installing the appropriate 
   1.324 +   version of hotplug or udev scripts, for example), but make dist 
   1.325 +   includes all versions of those scripts, so that you can copy the dist 
   1.326 +   directory to another machine and install from that distribution.
   1.327 +
   1.328 +5. To rebuild a kernel with a modified config:
   1.329 +
   1.330 +    # make linux-2.6-xen-config CONFIGMODE=menuconfig     (or xconfig)
   1.331 +    # make linux-2.6-xen-build
   1.332 +    # make linux-2.6-xen-install
   1.333 +
   1.334 +   Depending on your config, you may need to use 'mkinitrd' to create
   1.335 +   an initial ram disk, just like a native system e.g. 
   1.336 +    # depmod 2.6.12.6-xen
   1.337 +    # mkinitrd -v -f --with=aacraid --with=sd_mod --with=scsi_mod initrd-2.6.12.6-xen.img 2.6.12.6-xen