ia64/xen-unstable

changeset 2889:8002342a47e9

bitkeeper revision 1.1159.164.1 (418a7eafJ2ha0V2Xl9ZuHK9nHZFBYw)

almost there
author smh22@tempest.cl.cam.ac.uk
date Thu Nov 04 19:10:39 2004 +0000 (2004-11-04)
parents e17af491ba26
children 4b5799ad3285
files docs/src/user.tex
line diff
     1.1 --- a/docs/src/user.tex	Thu Nov 04 15:22:27 2004 +0000
     1.2 +++ b/docs/src/user.tex	Thu Nov 04 19:10:39 2004 +0000
     1.3 @@ -6,6 +6,9 @@
     1.4  \def\Xend{{Xend}\xspace}
     1.5  \def\xend{{xend}\xspace}
     1.6  
     1.7 +\latexhtml{\newcommand{\path}[1]{{\small {\tt #1}}}}{\newcommand{\path}[1]{{\tt #1}}}
     1.8 +
     1.9 +
    1.10  
    1.11  \begin{document}
    1.12  
    1.13 @@ -56,8 +59,6 @@ Contributions of material, suggestions a
    1.14  \renewcommand{\floatpagefraction}{.8}
    1.15  \setstretch{1.1}
    1.16  
    1.17 -\latexhtml{\newcommand{\path}[1]{{\small {\tt #1}}}}{\newcommand{\path}[1]{{\tt #1}}}
    1.18 -
    1.19  \part{Introduction and Tutorial}
    1.20  \chapter{Introduction}
    1.21  
    1.22 @@ -68,7 +69,7 @@ close-to-native performance.  The virtua
    1.23  facilitates enterprise-grade functionality, including:
    1.24  
    1.25  \begin{itemize}
    1.26 -\item Virtual machines with performance nearly identical to native
    1.27 +\item Virtual machines with performance close to native
    1.28    hardware.
    1.29  \item Live migration of running virtual machines between physical hosts.
    1.30  \item Excellent hardware support (supports most Linux device drivers).
    1.31 @@ -89,7 +90,7 @@ applications and libraries {\em do not} 
    1.32  Xen support is available for increasingly many operating systems:
    1.33  right now, Linux 2.4, Linux 2.6 and NetBSD are available for Xen 2.0.
    1.34  We expect that Xen support will ultimately be integrated into the
    1.35 -official releases of Linux, NetBSD and FreeBSD.  Other OS ports,
    1.36 +releases of Linux, NetBSD and FreeBSD.  Other OS ports,
    1.37  including Plan 9, are in progress.
    1.38  
    1.39  Possible usage scenarios for Xen include:
    1.40 @@ -104,7 +105,8 @@ Possible usage scenarios for Xen include
    1.41        virtual machine boundaries. 
    1.42  \item [Cluster computing.] Management at VM granularity provides more
    1.43        flexibility than separately managing each physical host, but
    1.44 -      better control and isolation than single-system image solutions.
    1.45 +      better control and isolation than single-system image solutions, 
    1.46 +      particularly by using live migration for load balancing. 
    1.47  \item [Hardware support for custom OSes.] Allow development of new OSes
    1.48        while benefiting from the wide-ranging hardware support of
    1.49        existing OSes such as Linux.
    1.50 @@ -141,12 +143,13 @@ Multiprocessor machines are supported, a
    1.51  for HyperThreading (SMT), although this remains a topic for ongoing
    1.52  research. A port specifically for x86/64 is in
    1.53  progress, although Xen already runs on such systems in 32-bit legacy
    1.54 -mode.
    1.55 +mode. In addition a port to the IA64 architecture is approaching 
    1.56 +completion. 
    1.57  
    1.58  Xen can currently use up to 4GB of memory.  It is possible for x86
    1.59  machines to address up to 64GB of physical memory but there are no
    1.60 -plans to support these systems.  The x86/64 port is the planned route
    1.61 -to supporting larger memory sizes. 
    1.62 +current plans to support these systems.  The x86/64 port is the
    1.63 +planned route to supporting larger memory sizes.
    1.64  
    1.65  Xen offloads most of the hardware support issues to the guest OS
    1.66  running in Domain 0.  Xen itself contains only the code required to
    1.67 @@ -162,7 +165,7 @@ other hardware by configuring your XenLi
    1.68  
    1.69  Xen was originally developed by the Systems Research Group at the
    1.70  University of Cambridge Computer Laboratory as part of the XenoServers
    1.71 -project, funded by UK-EPSRC.
    1.72 +project, funded by the UK-EPSRC.
    1.73  XenoServers aim to provide a `public infrastructure for
    1.74  global distributed computing', and Xen plays a key part in that,
    1.75  allowing us to efficiently partition a single machine to enable
    1.76 @@ -170,7 +173,7 @@ multiple independent clients to run thei
    1.77  applications in an environment providing protection, resource
    1.78  isolation and accounting.  The project web page contains further
    1.79  information along with pointers to papers and technical reports:
    1.80 -{\small {\tt http://www.cl.cam.ac.uk/xeno}}
    1.81 +\path{http://www.cl.cam.ac.uk/xeno} 
    1.82  
    1.83  Xen has since grown into a fully-fledged project in its own right,
    1.84  enabling us to investigate interesting research issues regarding the
    1.85 @@ -194,50 +197,85 @@ definitive open source solution for virt
    1.86  \chapter{Installation}
    1.87  
    1.88  The Xen distribution includes three main components: Xen itself, ports
    1.89 -of Linux and NetBSD to run on Xen, and the user-space tools required
    1.90 -to manage a Xen-based system.  This chapter describes how to install
    1.91 -the Xen 2.0 distribution from source.  Alternatively, there may be
    1.92 -pre-built packages available as part of your operating system
    1.93 -distribution.
    1.94 +of Linux 2.4 and 2.6 and NetBSD to run on Xen, and the user-space
    1.95 +tools required to manage a Xen-based system.  This chapter describes
    1.96 +how to install the Xen 2.0 distribution from source.  Alternatively,
    1.97 +there may be pre-built packages available as part of your operating
    1.98 +system distribution.
    1.99  
   1.100  \section{Prerequisites}
   1.101  \label{sec:prerequisites}
   1.102 +
   1.103 +The following is a full list of prerequisites. Items marked `$*$' are
   1.104 +only required if you wish to build from source; items marked `$\dag$'
   1.105 +are only required if you wish to run more than one virtual machine.
   1.106 +
   1.107  \begin{itemize}
   1.108  \item A working Linux distribution using the GRUB bootloader and
   1.109  running on a P6-class (or newer) CPU.
   1.110 -\item The Linux bridge control tools\footnote{{\tt
   1.111 -http://bridge.sourceforge.net}}.
   1.112 -\item Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make).
   1.113 -\item Development installation of libcurl.
   1.114 -\item Development installation of zlib (e.g., zlib-dev).
   1.115 -\item Development installation of Python v2.2 or later (e.g., python-dev).
   1.116 -\item An installation of Twisted v1.3 or above\footnote{{\tt
   1.117 +\item [$*$] Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make).
   1.118 +\item [$*$] Development installation of libcurl (e.g., libcurl-devel) 
   1.119 +\item [$*$] Development installation of zlib (e.g., zlib-dev).
   1.120 +\item [$*$] Development installation of Python v2.2 or later (e.g., python-dev).
   1.121 +\item [$*$] \LaTeX, transfig and tgif are required to build the documentation.
   1.122 +\item [$\dag$] The Linux bridge-utils\footnote{Available from 
   1.123 +{\tt http://bridge.sourceforge.net}} (e.g., \path{/sbin/brctl})
   1.124 +\item [$\dag$] An installation of Twisted v1.3 or
   1.125 +above\footnote{Available from {\tt
   1.126  http://www.twistedmatrix.com}}. There may be a binary package
   1.127  available for your distribution; alternatively it can be installed by
   1.128 -running `{\sl make install-twisted}' in the root of the Xen source tree.
   1.129 -\item \LaTeX, transfig and tgif are required to build the documentation.
   1.130 +running `{\sl make install-twisted}' in the root of the Xen source
   1.131 +tree.
   1.132  \end{itemize}
   1.133  
   1.134 -\section{Download the Xen source code}
   1.135 +Once you have satisfied the relevant prerequisites, you can 
   1.136 +now install either a binary or source distribution of Xen. 
   1.137  
   1.138 -\subsection{Tarball}
   1.139 +\section{Installing from Binary Tarball} 
   1.140  
   1.141 -The Xen source tree is available as a compressed tarball from the
   1.142 -Xen download page (pre-built tarballs are also available from this page):
   1.143 +Pre-built tarballs are available for download from the Xen 
   1.144 +download page
   1.145  \begin{quote} 
   1.146  {\tt http://xen.sf.net}
   1.147  \end{quote} 
   1.148  
   1.149 -\subsection{Using BitKeeper}
   1.150 +Once you've downloaded the tarball, simply unpack and install: 
   1.151 +\begin{verbatim}
   1.152 +# tar zxvf xen-2.0-install.tgz
   1.153 +# cd xen-2.0-install
   1.154 +# sh ./install.sh 
   1.155 +\end{verbatim} 
   1.156 +
   1.157 +Once you've installed the binaries you need to configure
   1.158 +your system as described in Section~\ref{s:configure}. 
   1.159 +
   1.160 +\section{Installing from Source} 
   1.161 +
   1.162 +This section describes how to obtain, build, and install 
   1.163 +Xen from source. 
   1.164  
   1.165 +\subsection{Obtaining the Source} 
   1.166 +
   1.167 +The Xen source tree is available as either a compressed source tar
   1.168 +ball or as a clone of our master BitKeeper repository.
   1.169 +
   1.170 +\begin{description} 
   1.171 +\item[Obtaining the Source Tarball]\mbox{} \\  
   1.172 +Stable versions (and daily snapshots) of the Xen source tree are
   1.173 +available as compressed tarballs from the Xen download page
   1.174 +\begin{quote} 
   1.175 +{\tt http://xen.sf.net}
   1.176 +\end{quote} 
   1.177 +
   1.178 +\item[Using BitKeeper]\mbox{} \\  
   1.179  If you wish to install Xen from a clone of our latest BitKeeper
   1.180  repository then you will need to install the BitKeeper tools.
   1.181  Download instructions for BitKeeper can be obtained by filling out the
   1.182  form at:
   1.183 +
   1.184  \begin{quote} 
   1.185  {\tt http://www.bitmover.com/cgi-bin/download.cgi}
   1.186  \end{quote}
   1.187 -
   1.188  The public master BK repository for the 2.0 release lives at: 
   1.189  \begin{quote}
   1.190  {\tt bk://xen.bkbits.net/xen-2.0.bk}  
   1.191 @@ -251,15 +289,15 @@ run:
   1.192  # bk clone bk://xen.bkbits.net/xen-2.0.bk
   1.193  \end{verbatim}
   1.194  
   1.195 -
   1.196 -Under your current directory, a new directory named `xen-2.0.bk' has
   1.197 -been created, which contains all the source code for Xen, the OS
   1.198 +Under your current directory, a new directory named \path{xen-2.0.bk}
   1.199 +has been created, which contains all the source code for Xen, the OS
   1.200  ports, and the control tools. You can update your repository with the
   1.201  latest changes at any time by running:
   1.202  \begin{verbatim}
   1.203  # cd xen-2.0.bk # to change into the local repository
   1.204  # bk pull       # to update the repository
   1.205  \end{verbatim}
   1.206 +\end{description} 
   1.207  
   1.208  %\section{The distribution}
   1.209  %
   1.210 @@ -276,9 +314,9 @@ latest changes at any time by running:
   1.211  %\item[\path{extras/}] Bonus extras.
   1.212  %\end{description}
   1.213  
   1.214 -\section{Build and install}
   1.215 +\subsection{Building from Source} 
   1.216  
   1.217 -The Xen makefile includes a target `world' that will do the
   1.218 +The top-level Xen Makefile includes a target `world' that will do the
   1.219  following:
   1.220  
   1.221  \begin{itemize}
   1.222 @@ -291,6 +329,42 @@ following:
   1.223        unprivileged virtual machines.
   1.224  \end{itemize}
   1.225  
   1.226 +
   1.227 +After the build has completed you should have a top-level 
   1.228 +directory called \path{dist/} in which all resulting targets 
   1.229 +will be placed; of particular interest are the two kernels 
   1.230 +XenLinux kernel images, one with a `-xen0' extension
   1.231 +which contains hardware device drivers and drivers for Xen's virtual
   1.232 +devices, and one with a `-xenU' extension that just contains the
   1.233 +virtual ones. These are found in \path{dist/install/boot/} along
   1.234 +with the image for Xen itself and the configuration files used
   1.235 +during the build. 
   1.236 +
   1.237 +The NetBSD port can be built using: 
   1.238 +\begin{quote}
   1.239 +\begin{verbatim}
   1.240 +# make netbsd20
   1.241 +\end{verbatim} 
   1.242 +\end{quote} 
   1.243 +NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
   1.244 +The snapshot is downloaded as part of the build process, if it is not
   1.245 +yet present in the \path{NETBSD\_SRC\_PATH} search path.  The build
   1.246 +process also downloads a toolchain which includes all the tools
   1.247 +necessary to build the NetBSD kernel under Linux.
   1.248 +
   1.249 +To customize further the set of kernels built you need to edit
   1.250 +the top-level Makefile. Look for the line: 
   1.251 +
   1.252 +\begin{quote}
   1.253 +\begin{verbatim}
   1.254 +KERNELS ?= mk.linux-2.6-xen0 mk.linux-2.6-xenU
   1.255 +\end{verbatim} 
   1.256 +\end{quote} 
   1.257 +
   1.258 +You can edit this line to include any set of operating system 
   1.259 +kernels which have configurations in the top-level 
   1.260 +\path{buildconfigs/} directory. 
   1.261 +
   1.262  %% Inspect the Makefile if you want to see what goes on during a build.
   1.263  %% Building Xen and the tools is straightforward, but XenLinux is more
   1.264  %% complicated.  The makefile needs a `pristine' Linux kernel tree to which
   1.265 @@ -306,36 +380,10 @@ following:
   1.266  %% After untaring the pristine kernel tree, the makefile uses the {\tt
   1.267  %% mkbuildtree} script to add the Xen patches to the kernel. 
   1.268  
   1.269 -After the build has completed you should have a top-level 
   1.270 -directory called {\tt dist/} in which all resulting targets 
   1.271 -will be placed; of particular interest are the two kernels 
   1.272 -XenLinux kernel images, one with a `-xen0' extension
   1.273 -which contains hardware device drivers and drivers for Xen's virtual
   1.274 -devices, and one with a `-xenU' extension that just contains the
   1.275 -virtual ones. These are found in \path{dist/install/boot/} along
   1.276 -with the image for Xen itself and the configuration files used
   1.277 -during the build. 
   1.278  
   1.279  %% The procedure is similar to build the Linux 2.4 port: \\
   1.280  %% \verb!# LINUX_SRC=/path/to/linux2.4/source make linux24!
   1.281  
   1.282 -The NetBSD port can be built using: \\ \verb!# make netbsd20! \\ The
   1.283 -NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
   1.284 -The snapshot is downloaded as part of the build process, if it is not
   1.285 -yet present in the {\tt NETBSD\_SRC\_PATH} search path.  The build
   1.286 -process also downloads a toolchain which includes all the tools
   1.287 -necessary to build the NetBSD kernel under Linux.
   1.288 -
   1.289 -% If you have an SMP machine you may wish to give the {\tt '-j4'}
   1.290 -% argument to make to get a parallel build.
   1.291 -
   1.292 -
   1.293 -If you have an existing Linux kernel configuration that you would like
   1.294 -to use for domain 0, you should copy it to
   1.295 -\path{dist/install/boot/config-2.6.9-xen0}; for example, certain
   1.296 -distributions require a kernel with {\tt devfs} support at boot time.
   1.297 -During the first build, you may be prompted with some Xen-specific
   1.298 -options.  We advise accepting the defaults for these options.
   1.299  
   1.300  %% \framebox{\parbox{5in}{
   1.301  %% {\bf Distro specific:} \\
   1.302 @@ -343,10 +391,54 @@ options.  We advise accepting the defaul
   1.303  %% to enable devfs and devfs mount at boot time in the xen0 config.
   1.304  %% }}
   1.305  
   1.306 +\subsection{Custom XenLinux Builds}
   1.307 +
   1.308 +% If you have an SMP machine you may wish to give the {\tt '-j4'}
   1.309 +% argument to make to get a parallel build.
   1.310 +
   1.311 +If you wish to build a customized XenLinux kernel (e.g. to support
   1.312 +additional devices or enable distribution-required features), you can
   1.313 +use the standard Linux configuration mechanisms, specifying that the
   1.314 +architecture being built for is \path{xen}, e.g:
   1.315 +\begin{quote}
   1.316 +\begin{verbatim} 
   1.317 +# cd linux-2.6.9-xen0 
   1.318 +# make ARCH=xen xconfig 
   1.319 +\end{verbatim} 
   1.320 +\end{quote} 
   1.321 +
   1.322 +You can also copy an existing Linux configuration (\path{.config}) 
   1.323 +into \path{linux-2.6.9-xen0} and execute:  
   1.324 +\begin{quote}
   1.325 +\begin{verbatim} 
   1.326 +# make oldconfig 
   1.327 +\end{verbatim} 
   1.328 +\end{quote} 
   1.329 +
   1.330 +You may be prompted with some Xen-specific options; we 
   1.331 +advise accepting the defaults for these options.
   1.332 +
   1.333 +Note that the only difference between the two types of Linux kernel
   1.334 +that are built is the configuration file used for each.  The "U"
   1.335 +suffixed (unprivileged) versions don't contain any of the physical
   1.336 +hardware device drivers, leading to a 30\% reduction in size; hence
   1.337 +you may prefer these for your non-privileged domains.  The `0'
   1.338 +suffixed privileged versions can be used to boot the system, as well
   1.339 +as in driver domains and unprivileged domains.
   1.340 +
   1.341 +
   1.342 +\subsection{Installing the Binaries}
   1.343 +
   1.344 +
   1.345  The files produced by the build process are stored under the
   1.346 -\path{dist/install/} directory.  To install them in their default
   1.347 -locations, do: \\
   1.348 -\verb_# make install_
   1.349 +\path{dist/install/} directory. To install them in their default
   1.350 +locations, do:
   1.351 +\begin{quote}
   1.352 +\begin{verbatim}
   1.353 +# make install
   1.354 +\end{verbatim} 
   1.355 +\end{quote}
   1.356 +
   1.357  
   1.358  Alternatively, users with special installation requirements may wish
   1.359  to install them manually by copying the files to their appropriate
   1.360 @@ -359,14 +451,6 @@ destinations.
   1.361  %% \item \path{install/boot/vmlinuz-2.6.9-xenU}  Unprivileged XenLinux kernel
   1.362  %% \end{itemize}
   1.363  
   1.364 -The difference between the two Linux kernels that are built is due to
   1.365 -the configuration file used for each.  The "U" suffixed unprivileged
   1.366 -version doesn't contain any of the physical hardware device drivers
   1.367 ---- it is 30\% smaller and hence may be preferred for your
   1.368 -non-privileged domains.  The `0' suffixed privileged version can be
   1.369 -used to boot the system, as well as in driver domains and unprivileged
   1.370 -domains.
   1.371 -
   1.372  The \path{dist/install/boot} directory will also contain the config files
   1.373  used for building the XenLinux kernels, and also versions of Xen and
   1.374  XenLinux kernels that contain debug symbols (\path{xen-syms} and
   1.375 @@ -374,8 +458,12 @@ XenLinux kernels that contain debug symb
   1.376  dumps.  Retain these files as the developers may wish to see them if
   1.377  you post on the mailing list.
   1.378  
   1.379 +
   1.380 +
   1.381 +
   1.382 +
   1.383  \section{Configuration}
   1.384 -
   1.385 +\label{s:configure}
   1.386  Once you have built and installed the Xen distribution, it is 
   1.387  simple to prepare the machine for booting and running Xen. 
   1.388  
   1.389 @@ -403,9 +491,8 @@ The module line of the configuration des
   1.390  XenLinux kernel that Xen should start and the parameters that should
   1.391  be passed to it (these are standard Linux parameters, identifying the
   1.392  root device and specifying it be initially mounted read only and
   1.393 -instructing that console output be sent both to the screen and to the
   1.394 -serial port). Some distributions such as SuSE do not require the 
   1.395 -{\small {\tt ro}} parameter. 
   1.396 +instructing that console output be sent to the screen).  Some
   1.397 +distributions such as SuSE do not require the \path{ro} parameter.
   1.398  
   1.399  %% \framebox{\parbox{5in}{
   1.400  %% {\bf Distro specific:} \\
   1.401 @@ -414,7 +501,7 @@ serial port). Some distributions such as
   1.402  %% }}
   1.403  
   1.404  
   1.405 -If you want to use an initrd, just add another {\small {\tt module}} line to
   1.406 +If you want to use an initrd, just add another \path{module} line to
   1.407  the configuration, as usual:
   1.408  {\small
   1.409  \begin{verbatim}
   1.410 @@ -462,23 +549,26 @@ regular Linux. Simply add the line:
   1.411  \end{quote} 
   1.412  
   1.413  and you should be able to log in. Note that to successfully log in 
   1.414 -as root over the serial will require adding \path{ttyS0} to
   1.415 +as root over the serial line will require adding \path{ttyS0} to
   1.416  \path{/etc/securetty} in most modern distributions. 
   1.417  
   1.418  \subsection{TLS Libraries}
   1.419  
   1.420  Users of the XenLinux 2.6 kernel should disable Thread Local Storage
   1.421 -(e.g. by doing a {\small {\tt mv /lib/tls /lib/tls.disabled}}) before
   1.422 +(e.g. by doing a \path{mv /lib/tls /lib/tls.disabled}) before
   1.423  attempting to run with a XenLinux kernel.  You can always reenable it
   1.424 -by restoring the directory to its original location (i.e. {\small 
   1.425 -{\tt mv /lib/tls.disabled /lib/tls}}).
   1.426 +by restoring the directory to its original location (i.e. 
   1.427 +\path{mv /lib/tls.disabled /lib/tls}).
   1.428  
   1.429  The reason for this is that the current TLS implementation uses
   1.430  segmentation in a way that is not permissible under Xen.  If TLS is
   1.431  not disabled, an emulation mode is used within Xen which reduces
   1.432  performance substantially and is not guaranteed to work perfectly.
   1.433  
   1.434 -\section{Test the new install}
   1.435 +We hope that this issue can be resolved by working 
   1.436 +with Linux distribution vendors. 
   1.437 +
   1.438 +\section{Booting Xen} 
   1.439  
   1.440  It should now be possible to restart the system and use Xen.  Reboot
   1.441  as usual but choose the new Xen option when the Grub screen appears.
   1.442 @@ -498,29 +588,25 @@ usual.  If you are unable to log in to y
   1.443  should still be able to reboot with your normal Linux kernel.
   1.444  
   1.445  
   1.446 -\chapter{Starting a domain}
   1.447 +\chapter{Starting Additional Domains}
   1.448  
   1.449  The first step in creating a new domain is to prepare a root
   1.450  filesystem for it to boot off.  Typically, this might be stored in a
   1.451  normal partition, an LVM or other volume manager partition, a disk
   1.452 -file or on an NFS server.
   1.453 -A simple way to do this is simply to boot from your standard OS
   1.454 -install CD and install the distribution into another partition on your
   1.455 -hard drive.
   1.456 +file or on an NFS server.  A simple way to do this is simply to boot
   1.457 +from your standard OS install CD and install the distribution into
   1.458 +another partition on your hard drive.
   1.459  
   1.460 -You can boot Xen and a single XenLinux instance without installing any
   1.461 -special user-space tools. To proceed further than this you will need
   1.462 -to install the prerequisites described in Section~\ref{sec:prerequisites}
   1.463 -and the Xen control tools. The control tools are installed by entering
   1.464 -the tools subdirectory of the repository and typing \\
   1.465 -\verb!# make install! \\
   1.466 -
   1.467 -To start the \xend control daemon, type \\ \verb!# xend start! \\ If you
   1.468 +To start the \xend control daemon, type
   1.469 +\begin{quote}
   1.470 +\verb!# xend start!
   1.471 +\end{quote}
   1.472 +If you
   1.473  wish the daemon to start automatically, see the instructions in
   1.474  Section~\ref{s:xend}. Once the daemon is running, you can use the
   1.475 -{\tt xm} tool to monitor and maintain the domains running on your
   1.476 +\path{xm} tool to monitor and maintain the domains running on your
   1.477  system. This chapter provides only a brief tutorial: we provide full
   1.478 -details of the {\tt xm} tool in Section~\ref{s:xm}. 
   1.479 +details of the \path{xm} tool in the next chapter. 
   1.480  
   1.481  %\section{From the web interface}
   1.482  %
   1.483 @@ -535,76 +621,87 @@ details of the {\tt xm} tool in Section~
   1.484  %
   1.485  %\section{From the command line}
   1.486  
   1.487 -This example explains how to use the \path{xmdefconfig} file.  If you
   1.488 -require a more complex setup, you will want to write a custom
   1.489 -configuration file --- details of the configuration file formats are
   1.490 -included in Section~\ref{s:cfiles}. 
   1.491 +
   1.492 +\section{Creating a Domain Configuration File} 
   1.493  
   1.494 -The \path{xmexample1} file is a simple template configuration file
   1.495 -for describing a single VM.
   1.496 +Before you can start an additional domain, you must create a
   1.497 +configuration file. We provide two example files which you 
   1.498 +can use as a starting point: 
   1.499 +\begin{itemize} 
   1.500 +  \item \path{/etc/xen/xmexample1} is a simple template configuration file
   1.501 +    for describing a single VM.
   1.502  
   1.503 -The \path{xmexample2} file is a template description that is intended
   1.504 -to be reused for multiple virtual machines.  Setting the value of the
   1.505 -{\tt vmid} variable on the {\tt xm} command line
   1.506 -fills in parts of this template.
   1.507 +  \item \path{/etc/xen/xmexample2} file is a template description that
   1.508 +    is intended to be reused for multiple virtual machines.  Setting
   1.509 +    the value of the \path{vmid} variable on the \path{xm} command line
   1.510 +    fills in parts of this template.
   1.511 +\end{itemize} 
   1.512  
   1.513 -Both of them can be found in \path{/etc/xen/}
   1.514 -
   1.515 -\section{Editing {\tt xmdefconfig}}
   1.516 +Copy one of these files and edit it as appropriate.
   1.517 +Typical values you may wish to edit include: 
   1.518  
   1.519 -At minimum, you should edit the following 
   1.520 -variables in \path{/etc/xen/xmdefconfig}:
   1.521 -
   1.522 +\begin{quote}
   1.523  \begin{description}
   1.524  \item[kernel] Set this to the path of the kernel you compiled for use
   1.525 -              with Xen. [e.g. {\tt kernel = '/boot/vmlinuz-2.6.9-xenU'}]
   1.526 +              with Xen (e.g.\  \path{kernel = '/boot/vmlinuz-2.6.9-xenU'})
   1.527  \item[memory] Set this to the size of the domain's memory in
   1.528 -megabytes. [e.g. {\tt memory = 64} ]
   1.529 +megabytes (e.g.\ \path{memory = 64})
   1.530  \item[disk] Set the first entry in this list to calculate the offset
   1.531  of the domain's root partition, based on the domain ID.  Set the
   1.532 -second to the location of \path{/usr} (if you are sharing it between
   1.533 -domains). [i.e. {\tt disk = ['phy:your\_hard\_drive\%d,sda1,w' \%
   1.534 +second to the location of \path{/usr} if you are sharing it between
   1.535 +domains (e.g.\ \path{disk = ['phy:your\_hard\_drive\%d,sda1,w' \%
   1.536  (base\_partition\_number + vmid), 'phy:your\_usr\_partition,sda6,r' ]}
   1.537  \item[dhcp] Uncomment the dhcp variable, so that the domain will
   1.538 -receive its IP address from a DHCP server. [i.e. {\tt dhcp='dhcp'}]
   1.539 +receive its IP address from a DHCP server (e.g.\ \path{dhcp='dhcp'})
   1.540  \end{description}
   1.541 +\end{quote}
   1.542  
   1.543  You may also want to edit the {\bf vif} variable in order to choose
   1.544  the MAC address of the virtual ethernet interface yourself.  For
   1.545 -example: \\ \verb_vif = ['mac=00:06:AA:F6:BB:B3']_\\ If you do not set
   1.546 -this variable, \xend will automatically generate a random MAC address
   1.547 -from an unused range.
   1.548 +example: 
   1.549 +\begin{quote}
   1.550 +\verb_vif = ['mac=00:06:AA:F6:BB:B3']_
   1.551 +\end{quote}
   1.552 +If you do not set this variable, \xend will automatically generate a
   1.553 +random MAC address from an unused range.
   1.554 +
   1.555  
   1.556 -If you don't have a \path{xmdefconfig} file, simply create your own 
   1.557 -by copying one of the \path{/etc/xen/xmexample} files.
   1.558 -\section{Starting the domain}
   1.559 +\section{Booting the Domain}
   1.560 +
   1.561 +The \path{xm} tool provides a variety of commands for managing domains.
   1.562 +Use the \path{create} command to start new domains. Assuming you've 
   1.563 +created a configuration file \path{myvmconf} based around
   1.564 +\path{/etc/xen/xmexample2}, to start a domain with virtual 
   1.565 +machine ID~1 you should type: 
   1.566  
   1.567 -The {\tt xm} tool provides a variety of commands for managing domains.
   1.568 -Use the {\tt create} command to start new domains.  To start the
   1.569 -virtual machine with virtual machine ID 1.
   1.570 -
   1.571 +\begin{quote}
   1.572  \begin{verbatim}
   1.573 -# xm create -c vmid=1
   1.574 +# xm create -c -f myvmconfig vmid=1
   1.575  \end{verbatim}
   1.576 +\end{quote}
   1.577  
   1.578 -The {\tt -c} switch causes {\tt xm} to turn into the domain's console
   1.579 -after creation.  The {\tt vmid=1} sets the {\tt vmid} variable used in
   1.580 -the {\tt xmdefconfig} file.  The tool uses the
   1.581 -\path{/etc/xen/xmdefconfig} file, since no custom configuration file
   1.582 -was specified on the command line.
   1.583 +
   1.584 +The \path{-c} switch causes \path{xm} to turn into the domain's
   1.585 +console after creation.  The \path{vmid=1} sets the \path{vmid}
   1.586 +variable used in the \path{myvmconf} file.
   1.587 +
   1.588 +
   1.589 +You should see the console boot messages from the new domain 
   1.590 +appearing in the terminal in which you typed the command, 
   1.591 +culminating in a login prompt. 
   1.592 +
   1.593  
   1.594  \section{Example: ttylinux}
   1.595  
   1.596 -Ttylinux is a very small Linux distribution, designed to
   1.597 -require very few resources.  We will use it as a concrete example of
   1.598 -how to start a Xen domain.  Most users will probably want to install a
   1.599 -full-featured distribution once they have mastered the
   1.600 -basics.
   1.601 +Ttylinux is a very small Linux distribution, designed to require very
   1.602 +few resources.  We will use it as a concrete example of how to start a
   1.603 +Xen domain.  Most users will probably want to install a full-featured
   1.604 +distribution once they have mastered the basics.
   1.605  
   1.606  \begin{enumerate}
   1.607  \item Download and extract the ttylinux disk image from the Files
   1.608 -section of the project's SourceForge site (see {\tt
   1.609 -http://sf.net/projects/xen/}).
   1.610 +section of the project's SourceForge site (see 
   1.611 +\path{http://sf.net/projects/xen/}).
   1.612  \item Create a configuration file like the following:
   1.613  \begin{verbatim}
   1.614  kernel = "/boot/vmlinuz-2.6.9-xenU"
   1.615 @@ -623,7 +720,8 @@ xm create -f configfile -c
   1.616  \item Login as root, password root.
   1.617  \end{enumerate}
   1.618  
   1.619 -\section{Starting / Stopping domains automatically}
   1.620 +
   1.621 +\section{Starting / Stopping Domains Automatically}
   1.622  
   1.623  It is possible to have certain domains start automatically at boot
   1.624  time and to have dom0 wait for all running domains to shutdown before
   1.625 @@ -639,47 +737,64 @@ your distribution.
   1.626  
   1.627  For instance, on RedHat:
   1.628  
   1.629 +\begin{quote}
   1.630  \verb_# chkconfig --add xendomains_
   1.631 +\end{quote}
   1.632  
   1.633  By default, this will start the boot-time domains in runlevels 3, 4
   1.634  and 5.
   1.635  
   1.636 -You can also use the {\tt service} command to run this script manually, e.g:
   1.637 +You can also use the \path{service} command to run this script
   1.638 +manually, e.g:
   1.639  
   1.640 +\begin{quote}
   1.641  \verb_# service xendomains start_
   1.642  
   1.643  Starts all the domains with config files under /etc/xen/auto/.
   1.644 +\end{quote}
   1.645  
   1.646 +
   1.647 +\begin{quote}
   1.648  \verb_# service xendomains stop_
   1.649  
   1.650  Shuts down ALL running Xen domains.
   1.651 -
   1.652 +\end{quote}
   1.653  
   1.654 -\chapter{Domain management tasks}
   1.655 +\chapter{Domain Management Tools}
   1.656  
   1.657  The previous chapter described a simple example of how to configure
   1.658  and start a domain.  This chapter summarises the tools available to
   1.659  manage running domains.
   1.660  
   1.661 -\section{Command line management}
   1.662 +\section{Command-line Management}
   1.663  
   1.664 -Command line management tasks are also performed using the {\tt xm}
   1.665 -tool.  For online help for the commands available, type:\\
   1.666 +Command line management tasks are also performed using the \path{xm}
   1.667 +tool.  For online help for the commands available, type:
   1.668 +\begin{quote}
   1.669  \verb_# xm help_
   1.670 +\end{quote}
   1.671  
   1.672 -\subsection{Basic management commands}
   1.673 +You can also type \path{xm help $<$command$>$} for more information 
   1.674 +on a given command. 
   1.675 +
   1.676 +\subsection{Basic Management Commands}
   1.677  
   1.678 -The most important {\tt xm} commands are: \\
   1.679 -\verb_# xm list_ : Lists all domains running. \\
   1.680 -\verb_# xm consoles_ : Gives information about the domain consoles. \\
   1.681 -\verb_# xm console_: Opens a console to a domain.
   1.682 -e.g. \verb_# xm console 1_ (open console to domain 1)
   1.683 +The most important \path{xm} commands are: 
   1.684 +\begin{quote}
   1.685 +\verb_# xm list_: Lists all domains running.\\
   1.686 +\verb_# xm consoles_ : Gives information about the domain consoles.\\
   1.687 +\verb_# xm console_: Opens a console to a domain (e.g.\
   1.688 +  \verb_# xm console myVM_
   1.689 +\end{quote}
   1.690  
   1.691  \subsection{\tt xm list}
   1.692  
   1.693 -The output of {\tt xm list} is in rows of the following format:\\
   1.694 -\verb_name domid memory cpu state cputime console_
   1.695 +The output of \path{xm list} is in rows of the following format:
   1.696 +\begin{center}
   1.697 +{\tt name domid memory cpu state cputime console}
   1.698 +\end{center}
   1.699  
   1.700 +\begin{quote}
   1.701  \begin{description}
   1.702  \item[name]  The descriptive name of the virtual machine.
   1.703  \item[domid] The number of the domain ID this virtual machine is running in.
   1.704 @@ -696,9 +811,10 @@ The output of {\tt xm list} is in rows o
   1.705  \item[cputime] How much CPU time (in seconds) the domain has used so far.
   1.706  \item[console] TCP port accepting connections to the domain's console.
   1.707  \end{description}
   1.708 +\end{quote}
   1.709  
   1.710 -The {\tt xm list} command also supports a long output format when the
   1.711 -{\tt -l} switch is used.  This outputs the fulls details of the
   1.712 +The \path{xm list} command also supports a long output format when the
   1.713 +\path{-l} switch is used.  This outputs the fulls details of the
   1.714  running domains in \xend's SXP configuration format.
   1.715  
   1.716  For example, suppose the system is running the ttylinux domain as
   1.717 @@ -714,8 +830,8 @@ ttylinux           5       63    0  -b--
   1.718  Here we can see the details for the ttylinux domain, as well as for
   1.719  domain 0 (which, of course, is always running).  Note that the console
   1.720  port for the ttylinux domain is 9605.  This can be connected to by TCP
   1.721 -using a terminal program (e.g. {\tt telnet} or, better, {\tt
   1.722 -xencons}).  The simplest way to connect is to use the {\tt xm console}
   1.723 +using a terminal program (e.g. \path{telnet} or, better, 
   1.724 +\path{xencons}).  The simplest way to connect is to use the \path{xm console}
   1.725  command, specifying the domain name or ID.  To connect to the console
   1.726  of the ttylinux domain, we could use:
   1.727  \begin{verbatim}
   1.728 @@ -726,7 +842,7 @@ or:
   1.729  # xm console 5
   1.730  \end{verbatim}
   1.731  
   1.732 -\section{Domain save and restore}
   1.733 +\section{Domain Save and Restore}
   1.734  
   1.735  The administrator of a Xen system may suspend a virtual machine's
   1.736  current state into a disk file in domain 0, allowing it to be resumed
   1.737 @@ -741,16 +857,16 @@ the command:
   1.738  This will stop the domain named `ttylinux' and save its current state
   1.739  into a file called \path{ttylinux.xen}.
   1.740  
   1.741 -To resume execution of this domain, use the {\tt xm restore} command:
   1.742 +To resume execution of this domain, use the \path{xm restore} command:
   1.743  \begin{verbatim}
   1.744  # xm restore ttylinux.xen
   1.745  \end{verbatim}
   1.746  
   1.747  This will restore the state of the domain and restart it.  The domain
   1.748  will carry on as before and the console may be reconnected using the
   1.749 -{\tt xm console} command, as above.
   1.750 +\path{xm console} command, as above.
   1.751  
   1.752 -\section{Live migration}
   1.753 +\section{Live Migration}
   1.754  
   1.755  Live migration is used to transfer a domain between physical hosts
   1.756  whilst that domain continues to perform its usual activities --- from
   1.757 @@ -758,14 +874,16 @@ the user's perspective, the migration sh
   1.758  
   1.759  To perform a live migration, both hosts must be running Xen / \xend and
   1.760  the destination host must have sufficient resources (e.g. memory
   1.761 -capacity) to accommodate the domain after the move.
   1.762 +capacity) to accommodate the domain after the move. Furthermore we
   1.763 +currently require both source and destination machines to be on the 
   1.764 +same L2 subnet. 
   1.765  
   1.766  Currently, there is no support for providing access to disk
   1.767  filesystems when a domain is migrated.  Administrators should choose
   1.768  an appropriate storage solution (i.e. SAN, NAS, etc.) to ensure that
   1.769  domain filesystems are also available on their destination node.
   1.770  
   1.771 -A domain may be migrated using the {\tt xm migrate} command.  To
   1.772 +A domain may be migrated using the \path{xm migrate} command.  To
   1.773  live migrate a domain to another machine, we would use
   1.774  the command:
   1.775  
   1.776 @@ -783,11 +901,11 @@ The domain will then continue on the new
   1.777  for a fraction of a second (usually between about 60 -- 300ms).
   1.778  
   1.779  For now it will be necessary to reconnect to the domain's console on
   1.780 -the new machine using the {\tt xm console} command.  If a migrated
   1.781 +the new machine using the \path{xm console} command.  If a migrated
   1.782  domain has any open network connections then they will be preserved,
   1.783  so SSH connections do not have this limitation.
   1.784  
   1.785 -\section{Managing domain memory (ballooning and memory limits)}
   1.786 +\section{Managing Domain Memory}
   1.787  
   1.788  XenLinux domains have the ability to relinquish / reclaim machine
   1.789  memory at the request of the administrator or the user of the domain.
   1.790 @@ -795,7 +913,7 @@ memory at the request of the administrat
   1.791  \subsection{Setting memory footprints from dom0}
   1.792  
   1.793  The machine administrator can request that a domain alter its memory
   1.794 -footprint using the {\tt xm balloon} command.  For instance, we can
   1.795 +footprint using the \path{xm balloon} command.  For instance, we can
   1.796  request that our example ttylinux domain reduce its memory footprint
   1.797  to 32 megabytes.
   1.798  
   1.799 @@ -803,7 +921,7 @@ to 32 megabytes.
   1.800  # xm balloon ttylinux 32
   1.801  \end{verbatim}
   1.802  
   1.803 -We can now see the result of this in the output of {\tt xm list}:
   1.804 +We can now see the result of this in the output of \path{xm list}:
   1.805  
   1.806  \begin{verbatim}
   1.807  # xm list
   1.808 @@ -823,9 +941,9 @@ can restore the domain to its original s
   1.809  
   1.810  The virtual file \path{/proc/xen/memory\_target} allows the owner of a
   1.811  domain to adjust their own memory footprint.  Reading the file
   1.812 -(e.g. \verb!# cat /proc/xen/memory\_target!) prints out the current
   1.813 +(e.g. \path{cat /proc/xen/memory\_target}) prints out the current
   1.814  memory footprint of the domain.  Writing the file
   1.815 -(e.g. \verb!# echo new\_target > /proc/xen/memory\_target!) requests
   1.816 +(e.g. \path{echo new\_target > /proc/xen/memory\_target}) requests
   1.817  that the kernel adjust the domain's memory footprint to a new value.
   1.818  
   1.819  \subsection{Setting memory limits}
   1.820 @@ -834,30 +952,37 @@ Xen associates a memory size limit with 
   1.821  is the amount of memory the domain is originally started with,
   1.822  preventing the domain from ever growing beyond this size.  To permit a
   1.823  domain to grow beyond its original allocation or to prevent a domain
   1.824 -you've shrunk from reclaiming the memory it relinquished, use the {\tt
   1.825 -xm maxmem} command.
   1.826 +you've shrunk from reclaiming the memory it relinquished, use the 
   1.827 +\path{xm maxmem} command.
   1.828  
   1.829 -\chapter{Domain filesystem storage}
   1.830 +\chapter{Domain Filesystem Storage}
   1.831  
   1.832  It is possible to directly export any Linux block device in dom0 to
   1.833 -another domain,
   1.834 -or to export filesystems / devices to virtual machines using standard
   1.835 -network protocols (e.g. NBD, iSCSI, NFS, etc).  This chapter covers
   1.836 -some of the possibilities.
   1.837 +another domain, or to export filesystems / devices to virtual machines
   1.838 +using standard network protocols (e.g. NBD, iSCSI, NFS, etc).  This
   1.839 +chapter covers some of the possibilities.
   1.840  
   1.841 -\section{Warning: Block device sharing}
   1.842  
   1.843 +\section{Exporting Physical Devices as VBDs} 
   1.844 +
   1.845 +\framebox{\centerline{\bf Warning: Block device sharing} \\
   1.846  Block devices should only be shared between domains in a read-only
   1.847  fashion otherwise the Linux kernels will obviously get very confused
   1.848  as the file system structure may change underneath them (having the
   1.849  same partition mounted rw twice is a sure fire way to cause
   1.850  irreparable damage)!  If you want read-write sharing, export the
   1.851 -directory to other domains via NFS from domain0.
   1.852 +directory to other domains via NFS from domain0.}
   1.853  
   1.854 -\section{File-backed virtual block devices}
   1.855 +In addition to local disks, its possible to export any device
   1.856 +that Linux knows about as a disk in another domain. For example,
   1.857 +if you have iSCSI disks or GNBD volumes imported into domain 0
   1.858 +you can export these to other domains using the "phy:" disk syntax.
   1.859  
   1.860 -It is possible to use a file in Domain 0 as the primary storage for a
   1.861 -virtual machine.  As well as being convenient, this also has the
   1.862 +
   1.863 +\section{Using File-backed VBDs}
   1.864 +
   1.865 +It is also possible to use a file in Domain 0 as the primary storage
   1.866 +for a virtual machine.  As well as being convenient, this also has the
   1.867  advantage that the virtual block device will be {\em sparse} --- space
   1.868  will only really be allocated as parts of the file are used.  So if a
   1.869  virtual machine uses only half of its disk space then the file really
   1.870 @@ -894,7 +1019,65 @@ In the configuration file set:\\
   1.871  As the virtual machine writes to its `disk', the sparse file will be
   1.872  filled in and consume more space up to the original 2GB.
   1.873  
   1.874 -\section{NFS Root}
   1.875 +
   1.876 +\section{Using LVM-backed VBDs}
   1.877 +
   1.878 +initialise a partition to LVM volumes:
   1.879 + pvcreate /dev/sda10		
   1.880 +
   1.881 +Create a volume group named 'vg' on the physical partition:
   1.882 + vgcreate vg /dev/sda10
   1.883 +
   1.884 +Create a logical volume of size 4GB named 'myvmdisk1':
   1.885 + lvcreate -L4096M -n myvmdisk1 vg
   1.886 +
   1.887 +You should now see that you have a /dev/vg/myvmdisk1
   1.888 +Make a filesystem, mount it and populate it. e.g.:
   1.889 + mkfs -t ext3 /dev/vg/myvmdisk1
   1.890 + mount /dev/vg/myvmdisk1 /mnt
   1.891 + cp -ax / /mnt
   1.892 + umount /mnt
   1.893 +
   1.894 +Now configure your VM with the following disk configuration
   1.895 + disk = [ 'phy:vg/myvmdisk1,sda1,w' ]
   1.896 +
   1.897 +LVM enables you to grow the size logical volumes, but you'll need
   1.898 +to resize the corresponding file system to make use of the new
   1.899 +space. Some file systems (e.g. ext3) now support on-line resize.
   1.900 +See the LVM manuals for more details.
   1.901 +
   1.902 +You can also use LVM for creating copy-on-write clones of LVM
   1.903 +volumes (known as writable persistent snapshots in LVM
   1.904 +terminology). This facility is new in Linux 2.6.8, so isn't as
   1.905 +stable as one might hope. In particular, using lots of CoW LVM
   1.906 +disks consumes a lot of dom0 memory, and error conditions such as
   1.907 +running out of disk space are not handled well. Hopefully this
   1.908 +will improve in future.
   1.909 +
   1.910 +To create two copy-on-write clone of the above file system you
   1.911 +would use the following commands:
   1.912 +
   1.913 + lvcreate -s -L1024M -n myclonedisk1 /dev/vg/myvmdisk1
   1.914 + lvcreate -s -L1024M -n myclonedisk2 /dev/vg/myvmdisk1
   1.915 +
   1.916 +Each of these can grow to have 1GB of differences from the master
   1.917 +volume. You can grow the amount of space for storing the
   1.918 +differences using the lvextend command e.g.:
   1.919 + lvextend +100M /dev/vg/myclonedisk1
   1.920 +
   1.921 +Don't let the differences volume ever fill up otherwise LVM gets
   1.922 +rather confused. It may be possible to automate the growing
   1.923 +process by using 'dmsetup wait' to spot the volume getting full
   1.924 +and then issue an lvextend.
   1.925 +
   1.926 +In principle, it is possible to continue writing to the volume
   1.927 +that has been cloned (the changes will not be visible to the
   1.928 +clones), but we wouldn't recommend this: have the cloned volume
   1.929 +as a 'pristine' file system install that isn't mounted directly
   1.930 +by any of the virtual machines.
   1.931 +
   1.932 +
   1.933 +\section{Using NFS Root}
   1.934  
   1.935  The procedure for using NFS root in a virtual machine is basically the
   1.936  same as you would follow for a real machine.  NB. the Linux NFS root
   1.937 @@ -928,11 +1111,6 @@ configure an IP address (Using the confi
   1.938  netmask}, {\tt gateway}, {\tt hostname}) or enable DHCP ({\tt
   1.939  dhcp='dhcp'}).
   1.940  
   1.941 -%% \section{LVM-backed virtual block devices}
   1.942 -
   1.943 -%% XXX Put some simple examples here - would be nice if an LVM user could
   1.944 -%% contribute some, although obviously users would have to read the LVM
   1.945 -%% docs to do advanced stuff.
   1.946  
   1.947  \part{User Reference Documentation}
   1.948  
   1.949 @@ -942,7 +1120,7 @@ The Xen control software includes the \x
   1.950  must be running), the xm command line tools, and the prototype 
   1.951  xensv web interface. 
   1.952  
   1.953 -\section{\Xend (Node control daemon)}
   1.954 +\section{\Xend (node control daemon)}
   1.955  \label{s:xend}
   1.956  
   1.957  The Xen Daemon (\Xend) performs system management functions related to
   1.958 @@ -971,7 +1149,7 @@ Once \xend is running, more sophisticate
   1.959  using the xm tool (see Section~\ref{s:xm}) and the experimental
   1.960  Xensv web interface (see Section~\ref{s:xensv}).
   1.961  
   1.962 -\section{Xm (Command line interface)}
   1.963 +\section{Xm (command line interface)}
   1.964  \label{s:xm}
   1.965  
   1.966  The xm tool is the primary tool for managing Xen from the console.
   1.967 @@ -1022,7 +1200,7 @@ try
   1.968  \end{verbatim}
   1.969  \end{quote}
   1.970  
   1.971 -\section{Xensv (Web control interface)}
   1.972 +\section{Xensv (web control interface)}
   1.973  \label{s:xensv}
   1.974  
   1.975  Xensv is the experimental web control interface for managing a Xen
   1.976 @@ -1294,14 +1472,14 @@ slightly less than 100\% in order to ens
   1.977    should be allowed a share of the system slack time.
   1.978  \end{description}
   1.979  
   1.980 -\section{Round Robin}
   1.981 +\subsection{Round Robin}
   1.982  
   1.983  {\tt sched=rrobin} \\
   1.984  
   1.985  The round robin scheduler is included as a simple demonstration of
   1.986  Xen's internal scheduler API.  It is not intended for production use. 
   1.987  
   1.988 -\subsection{Global parameters}
   1.989 +\subsubsection{Global Parameters}
   1.990  
   1.991  \begin{description}
   1.992  \item[rr\_slice]
   1.993 @@ -1325,7 +1503,7 @@ Xen's internal scheduler API.  It is not
   1.994  This chapter describes the build- and boot-time options 
   1.995  which may be used to tailor your Xen system. 
   1.996  
   1.997 -\section{Xen build options}
   1.998 +\section{Xen Build Options}
   1.999  
  1.1000  Xen provides a number of build-time options which should be 
  1.1001  set as environment variables or passed on make's command-line.  
  1.1002 @@ -1349,7 +1527,7 @@ events within Xen for collection by cont
  1.1003  software. 
  1.1004  \end{description} 
  1.1005  
  1.1006 -\section{Xen boot options}
  1.1007 +\section{Xen Boot Options}
  1.1008  \label{s:xboot}
  1.1009  
  1.1010  These options are used to configure Xen's behaviour at runtime.  They
  1.1011 @@ -1506,7 +1684,7 @@ that bug reports, suggestions and contri
  1.1012  software (or the documentation) should be sent to the Xen developers'
  1.1013  mailing list (address below).
  1.1014  
  1.1015 -\section{Other documentation}
  1.1016 +\section{Other Documentation}
  1.1017  
  1.1018  For developers interested in porting operating systems to Xen, the
  1.1019  {\em Xen Interface Manual} is distributed in the \path{docs/}
  1.1020 @@ -1515,7 +1693,7 @@ directory of the Xen source distribution
  1.1021  %Various HOWTOs are available in \path{docs/HOWTOS} but this content is
  1.1022  %being integrated into this manual.
  1.1023  
  1.1024 -\section{Online references}
  1.1025 +\section{Online References}
  1.1026  
  1.1027  The official Xen web site is found at:
  1.1028  \begin{quote}
  1.1029 @@ -1525,20 +1703,20 @@ The official Xen web site is found at:
  1.1030  This contains links to the latest versions of all on-line 
  1.1031  documentation. 
  1.1032  
  1.1033 -\section{Mailing lists}
  1.1034 +\section{Mailing Lists}
  1.1035  
  1.1036  There are currently three official Xen mailing lists:
  1.1037  
  1.1038  \begin{description}
  1.1039  \item[xen-devel@lists.sourceforge.net] Used for development
  1.1040  discussions and requests for help.  Subscribe at: \\
  1.1041 -{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-devel}}
  1.1042 +\path{http://lists.sourceforge.net/mailman/listinfo/xen-devel}
  1.1043  \item[xen-announce@lists.sourceforge.net] Used for announcements only.
  1.1044  Subscribe at: \\
  1.1045 -{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-announce}}
  1.1046 +\path{http://lists.sourceforge.net/mailman/listinfo/xen-announce}
  1.1047  \item[xen-changelog@lists.sourceforge.net]  Changelog feed
  1.1048  from the unstable and 2.0 trees - developer oriented.  Subscribe at: \\
  1.1049 -{\small {\tt http://lists.sourceforge.net/mailman/listinfo/xen-changelog}}
  1.1050 +\path{http://lists.sourceforge.net/mailman/listinfo/xen-changelog}
  1.1051  \end{description}
  1.1052  
  1.1053  Although there is no specific user support list, the developers try to
  1.1054 @@ -1548,12 +1726,12 @@ list increases, a dedicated user support
  1.1055  \appendix
  1.1056  
  1.1057  
  1.1058 -\chapter{Installing Debian}
  1.1059 +\chapter{Installing Xen / XenLinux on Debian}
  1.1060  
  1.1061 -The Debian project provides a tool called {\small {\tt debootstrap}} which
  1.1062 +The Debian project provides a tool called \path{debootstrap} which
  1.1063  allows a base Debian system to be installed into a filesystem without
  1.1064  requiring the host system to have any Debian-specific software (such
  1.1065 -as {\small {\tt apt}}).
  1.1066 +as \path{apt}. 
  1.1067  
  1.1068  Here's some info how to install Debian 3.1 (Sarge) for an unprivileged
  1.1069  Xen domain:
  1.1070 @@ -1585,11 +1763,11 @@ mkswap /path/swapimage
  1.1071  mount -o loop /path/diskimage /mnt/disk
  1.1072  \end{verbatim}\end{small}
  1.1073  
  1.1074 -\item Install {\small {\tt debootstrap}}
  1.1075 +\item Install \path{debootstrap}
  1.1076  
  1.1077  Make sure you have debootstrap installed on the host.  If you are
  1.1078  running Debian sarge (3.1 / testing) or unstable you can install it by
  1.1079 -running {\small {\tt apt-get install debootstrap}}.  Otherwise, it can be
  1.1080 +running \path{apt-get install debootstrap}.  Otherwise, it can be
  1.1081  downloaded from the Debian project website.
  1.1082  
  1.1083  \item Install Debian base to the disk image:
  1.1084 @@ -1667,7 +1845,7 @@ Started domain testdomain2, console on p
  1.1085  \end{verbatim}\end{small}
  1.1086          
  1.1087          There you can see the ID of the console: 26. You can also list
  1.1088 -        the consoles with {\small {\tt xm consoles}} (ID is the last two
  1.1089 +        the consoles with \path{xm consoles} (ID is the last two
  1.1090          digits of the port number.)
  1.1091  
  1.1092          Attach to the console:
  1.1093 @@ -1687,18 +1865,17 @@ xm console 26
  1.1094          errors.  Check that the swap is active, and the network settings are
  1.1095          correct.
  1.1096  
  1.1097 -        Run {\small {\tt/usr/sbin/base-config}} to set up the Debian settings.
  1.1098 +        Run \path{/usr/sbin/base-config} to set up the Debian settings.
  1.1099  
  1.1100          Set up the password for root using passwd.
  1.1101  
  1.1102 -\item     Done. You can exit the console by pressing {\small {\tt Ctrl + ]}}
  1.1103 +\item     Done. You can exit the console by pressing \path{Ctrl + ]}
  1.1104  
  1.1105  \end{enumerate}
  1.1106  
  1.1107  If you need to create new domains, you can just copy the contents of
  1.1108  the `template'-image to the new disk images, either by mounting the
  1.1109 -template and the new image, and using {\small {\tt cp -a}} or {\small
  1.1110 -    {\tt tar}} or by
  1.1111 +template and the new image, and using \path{cp -a} or \path{tar} or by
  1.1112  simply copying the image file.  Once this is done, modify the
  1.1113  image-specific settings (hostname, network settings, etc).
  1.1114  
  1.1115 @@ -1713,9 +1890,9 @@ to update the hwclock, change the consol
  1.1116  map, start apmd (power management), or gpm (mouse cursor).  Either
  1.1117  ignore the errors (they should be harmless), or remove them from the
  1.1118  startup scripts.  Deleting the following links are a good start:
  1.1119 -{\small\path{S24pcmcia}}, {\small\path{S09isdn}},
  1.1120 -{\small\path{S17keytable}}, {\small\path{S26apmd}},
  1.1121 -{\small\path{S85gpm}}.
  1.1122 +{\path{S24pcmcia}}, {\path{S09isdn}},
  1.1123 +{\path{S17keytable}}, {\path{S26apmd}},
  1.1124 +{\path{S85gpm}}.
  1.1125  
  1.1126  If you want to use a single root file system that works cleanly for
  1.1127  both domain 0 and unprivileged domains, a useful trick is to use
  1.1128 @@ -1726,14 +1903,14 @@ level number passed on the kernel comman
  1.1129  
  1.1130  If using NFS root files systems mounted either from an
  1.1131  external server or from domain0 there are a couple of other gotchas.
  1.1132 -The default {\small\path{/etc/sysconfig/iptables}} rules block NFS, so part
  1.1133 +The default {\path{/etc/sysconfig/iptables}} rules block NFS, so part
  1.1134  way through the boot sequence things will suddenly go dead.
  1.1135  
  1.1136 -If you're planning on having a separate NFS {\small\path{/usr}} partition, the
  1.1137 +If you're planning on having a separate NFS {\path{/usr}} partition, the
  1.1138  RH9 boot scripts don't make life easy - they attempt to mount NFS file
  1.1139  systems way to late in the boot process. The easiest way I found to do
  1.1140 -this was to have a {\small\path{/linuxrc}} script run ahead of
  1.1141 -{\small\path{/sbin/init}} that mounts {\small\path{/usr}}:
  1.1142 +this was to have a {\path{/linuxrc}} script run ahead of
  1.1143 +{\path{/sbin/init}} that mounts {\path{/usr}}:
  1.1144  
  1.1145  \begin{quote}
  1.1146  \begin{small}\begin{verbatim}
  1.1147 @@ -1748,19 +1925,19 @@ this was to have a {\small\path{/linuxrc
  1.1148  %$ XXX SMH: font lock fix :-)  
  1.1149  
  1.1150  The one slight complication with the above is that
  1.1151 -{\small\path{/sbin/portmap}} is dynamically linked against
  1.1152 -{\small\path{/usr/lib/libwrap.so.0}} Since this is in
  1.1153 -{\small\path{/usr}}, it won't work. This can be solved by copying the
  1.1154 +{\path{/sbin/portmap}} is dynamically linked against
  1.1155 +{\path{/usr/lib/libwrap.so.0}} Since this is in
  1.1156 +{\path{/usr}}, it won't work. This can be solved by copying the
  1.1157  file (and link) below the /usr mount point, and just let the file be
  1.1158  'covered' when the mount happens.
  1.1159  
  1.1160 -In some installations, where a shared read-only {\small\path{/usr}} is
  1.1161 +In some installations, where a shared read-only {\path{/usr}} is
  1.1162  being used, it may be desirable to move other large directories over
  1.1163 -into the read-only {\small\path{/usr}}. For example, you might replace
  1.1164 -{\small\path{/bin}}, {\small\path{/lib}} and {\small\path{/sbin}} with
  1.1165 -links into {\small\path{/usr/root/bin}}, {\small\path{/usr/root/lib}}
  1.1166 -and {\small\path{/usr/root/sbin}} respectively. This creates other
  1.1167 -problems for running the {\small\path{/linuxrc}} script, requiring
  1.1168 +into the read-only {\path{/usr}}. For example, you might replace
  1.1169 +{\path{/bin}}, {\path{/lib}} and {\path{/sbin}} with
  1.1170 +links into {\path{/usr/root/bin}}, {\path{/usr/root/lib}}
  1.1171 +and {\path{/usr/root/sbin}} respectively. This creates other
  1.1172 +problems for running the {\path{/linuxrc}} script, requiring
  1.1173  bash, portmap, mount, ifconfig, and a handful of other shared
  1.1174  libraries to be copied below the mount point --- a simple
  1.1175  statically-linked C program would solve this problem.