ia64/xen-unstable

changeset 1939:5f7f135d0209

bitkeeper revision 1.1108.23.7 (4106b501stHQ9fK16Mi0Amrqf_M30w)

Merge ssh://srg//auto/groups/xeno/BK/xeno.bk
into equilibrium.research.intel-research.net:/export/scratch/mwilli2/temp/xeno.bk
author mwilli2@equilibrium.research.intel-research.net
date Tue Jul 27 20:03:13 2004 +0000 (2004-07-27)
parents 1e13ae874e9c 7165f6c5ed48
children 0e15e81cb8a2
files docs/user.tex
line diff
     1.1 --- a/docs/user.tex	Tue Jul 27 19:37:43 2004 +0000
     1.2 +++ b/docs/user.tex	Tue Jul 27 20:03:13 2004 +0000
     1.3 @@ -162,7 +162,8 @@ This manual describes how to install the
     1.4  source.  Alternatively, there may be packages available for your
     1.5  operating system distribution.
     1.6  
     1.7 -Prerequisites:
     1.8 +\section{Prerequisites}
     1.9 +\label{sec:prerequisites}
    1.10  \begin{itemize}
    1.11  \item A working installation of your favourite Linux distribution.
    1.12  \item A working installation of the GRUB bootloader.
    1.13 @@ -173,33 +174,53 @@ make install-twisted} in the root of the
    1.14  \item The Linux bridge control tools (see {\tt
    1.15  http://bridge.sourceforge.net }).  There may be a packages of these
    1.16  tools available for your distribution.
    1.17 +\item Linux IP Routing Tools
    1.18 +\item make
    1.19 +\item python-dev
    1.20 +\item gcc
    1.21 +\item zlib-dev
    1.22 +\item libcurl
    1.23 +\item python2.3-pycurl
    1.24 +\item python2.3-twisted
    1.25  \end{itemize}
    1.26  
    1.27 -Optional:
    1.28 +\section{Optional}
    1.29  \begin{itemize}
    1.30  \item The Python logging package (see {\tt http://www.red-dove.com/})
    1.31  for additional Xend logging functionality.
    1.32  \end{itemize}
    1.33  
    1.34 -\section{Download the Xen source code}
    1.35 -
    1.36 -The public master BK repository for the 2.0 release lives at:
    1.37 -{\tt bk://xen.bkbits.net/xeno-unstable.bk}.
    1.38 +\section{Install Bitkeeper (Optional)}
    1.39  
    1.40  To fetch a local copy, first download the BitKeeper tools at: {\tt
    1.41  http://www.bitmover.com/download } with username 'bitkeeper' and
    1.42  password 'get bitkeeper'.
    1.43  
    1.44 -Then install the tools and then run:
    1.45 +The BitKeeper install program is designed to be run with X.  If X is
    1.46 +not available, you can specify the install directory on the command
    1.47 +line.
    1.48 +
    1.49 +\section{Download the Xen source code}
    1.50 +
    1.51 +\subsection{Using Bitkeeper}
    1.52 +
    1.53 +The public master BK repository for the 2.0 release lives at:
    1.54 +{\tt bk://xen.bkbits.net/xeno-unstable.bk}.
    1.55 +
    1.56 +Change to the directory in which you want to put the source code, then
    1.57 +run:
    1.58  \begin{verbatim}
    1.59  # bk clone bk://xen.bkbits.net/xeno-unstable.bk
    1.60  \end{verbatim}
    1.61  
    1.62  Under your current directory, a new directory named 'xeno-unstable.bk'
    1.63 -has been created, which contains all the necessary source code for the
    1.64 -Xen hypervisor and Linux guest OSes.
    1.65 +has been created, which contains all the source code for the Xen
    1.66 +hypervisor and the Xen tools.  The directory also contains `sparse'
    1.67 +Linux source trees, containing only the files that differ between
    1.68 +XenLinux and standard Linux.
    1.69  
    1.70 -To update to the newest changes to the repository, run
    1.71 +Once you have cloned the repository, you can update to the newest
    1.72 +changes to the repository by running:
    1.73  \begin{verbatim}
    1.74  # cd xeno-unstable.bk # to change into the local repository
    1.75  # bk pull             # to update the repository
    1.76 @@ -227,7 +248,7 @@ following:
    1.77  \begin{itemize}
    1.78  \item Build Xen
    1.79  \item Build the control tools, including Xend
    1.80 -\item Download the ebtables patch
    1.81 +\item Download the ebtables patch for Linux 2.4
    1.82  \item Download (if necessary) and unpack the Linux 2.4 source code,
    1.83        and patch it for use with Xen
    1.84  \item Build a Linux kernel to use in domain 0 and a smaller
    1.85 @@ -258,16 +279,17 @@ destinations.
    1.86  
    1.87  \section{Configuration}
    1.88  
    1.89 -\subsection{\path{grub.conf}}
    1.90 +\subsection{GRUB Configuration}
    1.91  
    1.92  An entry should be added to \path{grub.conf} (often found under
    1.93 -\path{/boot/grub.conf} or \path{/boot/grub/grub.conf}) to allow Xen /
    1.94 -XenLinux to boot.  The entry should look something like the following:
    1.95 +\path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot.
    1.96 +This file is sometimes called \path{menu.lst}, depending on your
    1.97 +distribution.  The entry should look something like the following:
    1.98  
    1.99  \begin{verbatim}
   1.100  title Xen 2.0 / XenoLinux 2.4.26
   1.101          kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
   1.102 -        module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0
   1.103 +        module /boot/xenolinux.gz root=/dev/sda4 ro console=tty0 console=ttyS0
   1.104  \end{verbatim}
   1.105  
   1.106  The first line of the configuration (kernel...) tells GRUB where to
   1.107 @@ -276,6 +298,11 @@ second line of the configuration describ
   1.108  XenoLinux kernel that Xen should start and the parameters that should
   1.109  be passed to it.
   1.110  
   1.111 +As always when installing a new kernel, it is recommended that you do
   1.112 +not remove the original contents of \path{grub.conf} --- you may want
   1.113 +to boot up with your old Linux kernel in future, particularly if you
   1.114 +have problems.
   1.115 +
   1.116  \subsection{Serial Console}
   1.117  
   1.118  In order to configure serial console output, it is necessary to add a
   1.119 @@ -285,6 +312,26 @@ serial console.  Add the line:
   1.120  
   1.121  {\tt c:2345:respawn:/sbin/mingetty ttyS0}
   1.122  
   1.123 +\section{Test the new install}
   1.124 +
   1.125 +It should now be possible to restart the system and use Xen.  Reboot
   1.126 +as usual but choose the new Xen option when the Grub screen appears.
   1.127 +
   1.128 +What follows should look much like a conventional Linux boot.  The
   1.129 +first portion of the output comes from Xen itself, supplying low level
   1.130 +information about itself and the machine it is running on.  The
   1.131 +following portion of the output comes from XenLinux itself.
   1.132 +
   1.133 +You may see some errors during the XenLinux boot.  These are not
   1.134 +necessarily anything to worry about --- they may result from kernel
   1.135 +configuration differences between your XenLinux kernel and the one you
   1.136 +usually use.
   1.137 +
   1.138 +When the boot completes, you should be able to log into your system as
   1.139 +usual.  If you are unable to log in to your system running Xen, you
   1.140 +should still be able to reboot with your normal Linux kernel.
   1.141 +
   1.142 +
   1.143  \chapter{Starting a domain}
   1.144  
   1.145  The first step in creating a new domain is to prepare a root
   1.146 @@ -295,6 +342,11 @@ A simple way to do this is simply to boo
   1.147  install CD and install the distribution into another partition on your
   1.148  hard drive.
   1.149  
   1.150 +{\em N.b } you can boot with Xen and XenLinux without installing any
   1.151 +special userspace tools but will need to have the prerequisites
   1.152 +described in Section~\ref{sec:prerequisites} and the Xen control tools
   1.153 +are installed before you proceed.
   1.154 +
   1.155  \section{From the web interface}
   1.156  
   1.157  \begin{itemize}
   1.158 @@ -335,6 +387,12 @@ domains). [i.e. {\tt disk = ['phy:your\_
   1.159  receive its IP address from a DHCP server. [i.e. {\tt dhcp=''dhcp''}]
   1.160  \end{description}
   1.161  
   1.162 +You may also want to edit the {\bf vif} variable in order to choose
   1.163 +the MAC address of the virtual ethernet interface yourself.  For
   1.164 +example: \\ \verb_vif = [`mac=00:06:AA:F6:BB:B3']_\\ If you do not set
   1.165 +this variable, Xend will automatically generate a random MAC address
   1.166 +from an unused range.
   1.167 +
   1.168  \subsection{Starting the domain}
   1.169  
   1.170  The {\tt xm} tool provides a variety of commands for managing domains.
   1.171 @@ -351,8 +409,86 @@ the {\tt xmdefaults} file.  The tool use
   1.172  \path{/etc/xen/xmdefaults} file, since no custom configuration file
   1.173  was specified on the command line.
   1.174  
   1.175 +\chapter{Domain management tasks}
   1.176 +
   1.177 +The previous chapter described a simple example of how to configure
   1.178 +and start a domain.  This chapter summarises the tools available to
   1.179 +manage running domains.
   1.180 +
   1.181 +\section{Command line management}
   1.182 +
   1.183 +Command line management tasks are also performed using the {\tt xm}
   1.184 +tool.  For online help for the commands available, type:\\
   1.185 +\verb_# xm help_
   1.186 +
   1.187 +\subsection{Basic management commands}
   1.188 +
   1.189 +The most important {\tt xm} commands are: \\
   1.190 +\verb_# xm list_ : Lists all domains running. \\
   1.191 +\verb_# xm consoles_ : Gives information about the domain consoles. \\
   1.192 +\verb_# xm console_: open a console to a domain.
   1.193 +e.g. \verb_# xm console 1_ (open console to domain 1)
   1.194 +
   1.195   XXX More explanation needed here...
   1.196  
   1.197 +\chapter{Other kinds of storage}
   1.198 +
   1.199 +It is possible to use any Linux block device to store virtual machine
   1.200 +disk images.  This chapter covers some of the possibilities; note that
   1.201 +it is also possible to use network-based block devices and other
   1.202 +unconventional block devices.
   1.203 +
   1.204 +\section{File-backed virtual block devices}
   1.205 +
   1.206 +It is possible to use a file in Domain 0 as the primary storage for a
   1.207 +virtual machine.  As well as being convenient, this also has the
   1.208 +advantage that the virtual block device will be {\em sparse} --- space
   1.209 +will only really be allocated as parts of the file are used.  So if a
   1.210 +virtual machine uses only half its disk space then the file really
   1.211 +takes up a half of the size allocated.
   1.212 +
   1.213 +For example, to create a 2GB sparse file-backed virtual block device
   1.214 +(actually only consumes 1KB of disk):
   1.215 +
   1.216 +\verb_# dd if=/dev/zero of=vm1disk bs=1k seek=2048k count=1_
   1.217 +
   1.218 +Choose a free loop back device, and attach file: \\
   1.219 +\verb_# losetup /dev/loop0 vm1disk_ \\
   1.220 +Make a file system on the loop back device: \\
   1.221 +\verb_# mkfs ­t ext3 /dev/loop0_
   1.222 +
   1.223 +Populate the file system e.g. by copying from the current root:
   1.224 +\begin{verbatim}
   1.225 +# mount /dev/loop0 /mnt
   1.226 +# cp -ax / /mnt
   1.227 +\end{verbatim}
   1.228 +Tailor the file system by editing \path{/etc/fstab},
   1.229 +\path{/etc/hostname}, etc (don't forget to edit the files in the
   1.230 +mounted file system, instead of your domain 0 filesystem, e.g. you
   1.231 +would edit \path{/mnt/etc/fstab} instead of \path{/etc/fstab} ).  For
   1.232 +this example put \path{/dev/sda1} to root in fstab.
   1.233 +
   1.234 +Now unmount (this is important!):\\
   1.235 +\verb_# umount /dev/loop0_
   1.236 +
   1.237 +In the configuration file set:\\
   1.238 +\verb_disk = [`phy:loop0,sda1,w']_
   1.239 +
   1.240 +As the virtual machine writes to its `disk', the sparse file will be
   1.241 +filled in and consume more space up to the original 2GB.
   1.242 +
   1.243 +{\em NB.} You will need to use {\tt losetup} to bind the file to
   1.244 +\path{/dev/loop0} (or whatever loopback device you chose) each time
   1.245 +you reboot domain 0.  In the near future, Xend will track which loop
   1.246 +devices are currently free and do binding itself, making this manual
   1.247 +effort unnecessary.
   1.248 +
   1.249 +\section{LVM-backed virtual block devices}
   1.250 +
   1.251 +XXX Put some simple examples here - would be nice if an LVM user could
   1.252 +contribute some, although obviously users would have to read the LVM
   1.253 +docs to do advanced stuff.
   1.254 +
   1.255  \part{Quick Reference}
   1.256  
   1.257  \chapter{Domain Configuration Files}