ia64/xen-unstable

changeset 2870:94ac39a10a8d

bitkeeper revision 1.1159.1.360 (41899c7cm7xkHe4NiL90NhQhjLDYlw)

Merge ssh://srg//auto/groups/xeno/BK/xeno.bk
into equilibrium.research:/export/scratch/xeno-docs.bk
author mwilli2@equilibrium.research
date Thu Nov 04 03:05:32 2004 +0000 (2004-11-04)
parents aeaa8b6b072d 1cdb1a107c48
children a881f5bde9d3
files docs/src/user.tex
line diff
     1.1 --- a/docs/src/user.tex	Thu Nov 04 01:08:36 2004 +0000
     1.2 +++ b/docs/src/user.tex	Thu Nov 04 03:05:32 2004 +0000
     1.3 @@ -90,8 +90,8 @@ applications and libraries {\em do not} 
     1.4  Xen support is available for increasingly many operating systems:
     1.5  right now, Linux 2.4, Linux 2.6 and NetBSD are available for Xen 2.0.
     1.6  We expect that Xen support will ultimately be integrated into the
     1.7 -official releases of Linux, NetBSD, FreeBSD and Dragonfly BSD. 
     1.8 -Other OS ports, including Plan 9, are in progress.
     1.9 +official releases of Linux, NetBSD and FreeBSD.  Other OS ports,
    1.10 +including Plan 9, are in progress.
    1.11  
    1.12  Possible usage scenarios for Xen include:
    1.13  \begin{description}
    1.14 @@ -106,8 +106,8 @@ Possible usage scenarios for Xen include
    1.15  \item [Cluster computing.] Management at VM granularity provides more
    1.16        flexibility than separately managing each physical host, but
    1.17        better control and isolation than single-system image solutions.
    1.18 -\item [Hardware support for custom OSes.] Allow devlopment of new OSes
    1.19 -      while benefitting from the wide-ranging hardware support of
    1.20 +\item [Hardware support for custom OSes.] Allow development of new OSes
    1.21 +      while benefiting from the wide-ranging hardware support of
    1.22        existing OSes such as Linux.
    1.23  \end{description}
    1.24  
    1.25 @@ -173,7 +173,7 @@ isolation and accounting.  The project w
    1.26  information along with pointers to papers and technical reports:
    1.27  {\small {\tt http://www.cl.cam.ac.uk/xeno}}
    1.28  
    1.29 -Xen has since grown into a fully-fledgd project in its own right,
    1.30 +Xen has since grown into a fully-fledged project in its own right,
    1.31  enabling us to investigate interesting research issues regarding the
    1.32  best techniques for virtualising resources such as the CPU, memory,
    1.33  disk and network.  The project has been bolstered by support from
    1.34 @@ -228,7 +228,7 @@ Xen download page (pre-built tarballs ar
    1.35  {\tt http://xen.sf.net}
    1.36  \end{quote} 
    1.37  
    1.38 -\subsection{Using Bitkeeper}
    1.39 +\subsection{Using BitKeeper}
    1.40  
    1.41  If you wish to install Xen from a clone of our latest BitKeeper
    1.42  repository then you will need to install the BitKeeper tools.
    1.43 @@ -242,7 +242,7 @@ The public master BK repository for the 
    1.44  \begin{quote}
    1.45  {\tt bk://xen.bkbits.net/xen-2.0.bk}  
    1.46  \end{quote} 
    1.47 -You can use Bitkeeper to
    1.48 +You can use BitKeeper to
    1.49  download it and keep it updated with the latest features and fixes.
    1.50  
    1.51  Change to the directory in which you want to put the source code, then
    1.52 @@ -333,10 +333,9 @@ necessary to build the NetBSD kernel und
    1.53  If you have an existing Linux kernel configuration that you would like
    1.54  to use for domain 0, you should copy it to
    1.55  \path{dist/install/boot/config-2.6.9-xen0}; for example, certain
    1.56 -distributions require a kernel with either {\tt udev} or {\tt devfs}
    1.57 -support at boot time.  During the first build, you may be prompted with
    1.58 -some Xen-specific options.  We advise accepting the defaults for
    1.59 -these options.
    1.60 +distributions require a kernel with {\tt devfs} support at boot time.
    1.61 +During the first build, you may be prompted with some Xen-specific
    1.62 +options.  We advise accepting the defaults for these options.
    1.63  
    1.64  %% \framebox{\parbox{5in}{
    1.65  %% {\bf Distro specific:} \\
    1.66 @@ -405,7 +404,7 @@ XenLinux kernel that Xen should start an
    1.67  be passed to it (these are standard Linux parameters, identifying the
    1.68  root device and specifying it be initially mounted read only and
    1.69  instructing that console output be sent both to the screen and to the
    1.70 -serial port). Some distributions such as SUSE do not require the 
    1.71 +serial port). Some distributions such as SuSE do not require the 
    1.72  {\small {\tt ro}} parameter. 
    1.73  
    1.74  %% \framebox{\parbox{5in}{
    1.75 @@ -475,7 +474,7 @@ by restoring the directory to its origin
    1.76  {\tt mv /lib/tls.disabled /lib/tls}}).
    1.77  
    1.78  The reason for this is that the current TLS implementation uses
    1.79 -segmentation in a way that is not permissable under Xen.  If TLS is
    1.80 +segmentation in a way that is not permissible under Xen.  If TLS is
    1.81  not disabled, an emulation mode is used within Xen which reduces
    1.82  performance substantially and is not guaranteed to work perfectly.
    1.83  
    1.84 @@ -487,7 +486,7 @@ as usual but choose the new Xen option w
    1.85  What follows should look much like a conventional Linux boot.  The
    1.86  first portion of the output comes from Xen itself, supplying low level
    1.87  information about itself and the machine it is running on.  The
    1.88 -following portion of the output comes from XenLinux itself.
    1.89 +following portion of the output comes from XenLinux.
    1.90  
    1.91  You may see some errors during the XenLinux boot.  These are not
    1.92  necessarily anything to worry about --- they may result from kernel
    1.93 @@ -514,10 +513,10 @@ special user-space tools. To proceed fur
    1.94  to install the prerequisites described in Section~\ref{sec:prerequisites}
    1.95  and the Xen control tools. The control tools are installed by entering
    1.96  the tools subdirectory of the repository and typing \\
    1.97 -\verb!# LINUX_SRC=/path/to/linux2.4/source make linux24! \\
    1.98 +\verb!# make install! \\
    1.99  
   1.100 -To start the control daemon, type \\ \verb!# xend start! \\ If you
   1.101 -wish to start the daemon automatically, see the instructions in
   1.102 +To start the \xend control daemon, type \\ \verb!# xend start! \\ If you
   1.103 +wish the daemon to start automatically, see the instructions in
   1.104  Section~\ref{s:xend}. Once the daemon is running, you can use the
   1.105  {\tt xm} tool to monitor and maintain the domains running on your
   1.106  system. This chapter provides only a brief tutorial: we provide full
   1.107 @@ -550,6 +549,7 @@ to be reused for multiple virtual machin
   1.108  fills in parts of this template.
   1.109  
   1.110  Both of them can be found in \path{/etc/xen/}
   1.111 +
   1.112  \section{Editing \path{xmdefconfig}}
   1.113  
   1.114  At minimum, you should edit the following 
   1.115 @@ -557,8 +557,7 @@ variables in \path{/etc/xen/xmdefconfig}
   1.116  
   1.117  \begin{description}
   1.118  \item[kernel] Set this to the path of the kernel you compiled for use
   1.119 -              with Xen. [e.g. {\tt kernel =
   1.120 -              '/root/xen-2.0.bk/install/boot/vmlinuz-2.4.27-xenU'}]
   1.121 +              with Xen. [e.g. {\tt kernel = '/boot/vmlinuz-2.6.9-xenU'}]
   1.122  \item[memory] Set this to the size of the domain's memory in
   1.123  megabytes. [e.g. {\tt memory = 64} ]
   1.124  \item[disk] Set the first entry in this list to calculate the offset
   1.125 @@ -599,7 +598,7 @@ was specified on the command line.
   1.126  Ttylinux is a very small Linux distribution, designed to
   1.127  require very few resources.  We will use it as a concrete example of
   1.128  how to start a Xen domain.  Most users will probably want to install a
   1.129 -more complex mainstream distribution once they have mastered the
   1.130 +full-featured distribution once they have mastered the
   1.131  basics.
   1.132  
   1.133  \begin{enumerate}
   1.134 @@ -671,7 +670,7 @@ tool.  For online help for the commands 
   1.135  The most important {\tt xm} commands are: \\
   1.136  \verb_# xm list_ : Lists all domains running. \\
   1.137  \verb_# xm consoles_ : Gives information about the domain consoles. \\
   1.138 -\verb_# xm console_: open a console to a domain.
   1.139 +\verb_# xm console_: Opens a console to a domain.
   1.140  e.g. \verb_# xm console 1_ (open console to domain 1)
   1.141  
   1.142  \subsection{\tt xm list}
   1.143 @@ -711,7 +710,7 @@ ttylinux           5       63    0  -b--
   1.144  \end{verbatim}
   1.145  
   1.146  Here we can see the details for the ttylinux domain, as well as for
   1.147 -domain 0 (which of course is always running).  Note that the console
   1.148 +domain 0 (which, of course, is always running).  Note that the console
   1.149  port for the ttylinux domain is 9605.  This can be connected to by TCP
   1.150  using a terminal program (e.g. {\tt telnet} or, better, {\tt
   1.151  xencons}).  The simplest way to connect is to use the {\tt xm console}
   1.152 @@ -770,7 +769,7 @@ the command:
   1.153  There will be a delay whilst the domain is moved to the destination
   1.154  machine.  During this time, the Xen migration daemon copies as much
   1.155  information as possible about the domain (configuration, memory
   1.156 -contents, etc.) to the destination host as possible.  The domain is
   1.157 +contents, etc.) to the destination host.  The domain is
   1.158  then stopped for a fraction of a second in order to update the state
   1.159  on the destination machine with any changes in memory contents, etc.
   1.160  The domain will then continue on the new machine having been halted
   1.161 @@ -793,7 +792,7 @@ memory at the request of the administrat
   1.162  
   1.163  \subsection{Setting memory footprints from dom0}
   1.164  
   1.165 -The machine administator can request that a domain alter its memory
   1.166 +The machine administrator can request that a domain alter its memory
   1.167  footprint using the {\tt xm balloon} command.  For instance, we can
   1.168  request that our example ttylinux domain reduce its memory footprint
   1.169  to 32 megabytes.
   1.170 @@ -833,12 +832,13 @@ Xen associates a memory size limit with 
   1.171  is the amount of memory the domain is originally started with,
   1.172  preventing the domain from ever growing beyond this size.  To permit a
   1.173  domain to grow beyond its original allocation or to prevent a domain
   1.174 -you've shrunk from reclaiming the memory it reliquished, use the {\tt
   1.175 +you've shrunk from reclaiming the memory it relinquished, use the {\tt
   1.176  xm maxmem} command.
   1.177  
   1.178  \chapter{Domain filesystem storage}
   1.179  
   1.180 -It is possible to directly export any Linux block device to a virtual,
   1.181 +It is possible to directly export any Linux block device in dom0 to
   1.182 +another domain,
   1.183  or to export filesystems / devices to virtual machines using standard
   1.184  network protocols (e.g. NBD, iSCSI, NFS, etc).  This chapter covers
   1.185  some of the possibilities.
   1.186 @@ -917,7 +917,7 @@ the domain's configuration file:
   1.187  \begin{verbatim}
   1.188  root       = '/dev/nfs'
   1.189  nfs_server = 'a.b.c.d'       # Substitute the IP for the server here
   1.190 -nfs_root   = '/path/to/root' # Path to root FS on the server machine
   1.191 +nfs_root   = '/path/to/root' # Path to root FS on the server
   1.192  \end{verbatim}
   1.193  
   1.194  The domain will need network access at boot-time, so either statically
   1.195 @@ -925,11 +925,11 @@ configure an IP address (Using the confi
   1.196  netmask}, {\tt gateway}, {\tt hostname}) or enable DHCP ({\tt
   1.197  dhcp='dhcp'}).
   1.198  
   1.199 -\section{LVM-backed virtual block devices}
   1.200 +%% \section{LVM-backed virtual block devices}
   1.201  
   1.202 -XXX Put some simple examples here - would be nice if an LVM user could
   1.203 -contribute some, although obviously users would have to read the LVM
   1.204 -docs to do advanced stuff.
   1.205 +%% XXX Put some simple examples here - would be nice if an LVM user could
   1.206 +%% contribute some, although obviously users would have to read the LVM
   1.207 +%% docs to do advanced stuff.
   1.208  
   1.209  \part{User Reference Documentation}
   1.210  
   1.211 @@ -1027,8 +1027,7 @@ machine.  It can be used to perform some
   1.212  management tasks that can be done using the xm tool.
   1.213  
   1.214  It can be started using:\\ \verb_# xensv start_ \\ and
   1.215 -stopped using: \verb_# xensv stop_ \\ It will automatically start \xend
   1.216 -if it is not already running.
   1.217 +stopped using: \verb_# xensv stop_ \\
   1.218  
   1.219  By default, Xensv will serve out the web interface on port 8080.  This
   1.220  can be changed by editing {\tt
   1.221 @@ -1097,7 +1096,8 @@ vif = [ 'mac=aa:00:00:00:00:11, bridge=x
   1.222  
   1.223  For additional flexibility, it is also possible to include Python
   1.224  scripting commands in configuration files.  An example of this is the
   1.225 -\path{xmexample} file in order to handle the {\tt vmid} variable.
   1.226 +\path{xmexample2} file, which uses Python code to handle the {\tt
   1.227 +vmid} variable.
   1.228  
   1.229  
   1.230  %\part{Advanced Topics}
   1.231 @@ -1125,8 +1125,8 @@ names and locations of the scripts can b
   1.232  \begin{description} 
   1.233  
   1.234  \item[network:] This script is called whenever \xend is started or
   1.235 -stopped to respectively initialize or tear down the Xen virtual
   1.236 -network. In the default configuration initialization creates the
   1.237 +stopped to respectively initialise or tear down the Xen virtual
   1.238 +network. In the default configuration initialisation creates the
   1.239  bridge `xen-br0' and moves eth0 onto that bridge, modifying the
   1.240  routing accordingly. When \xend exits, it deletes the Xen bridge and
   1.241  removes eth0, restoring the normal IP and routing configuration.
   1.242 @@ -1229,7 +1229,7 @@ domains), but this can be compensated fo
   1.243  
   1.244  \begin{description}
   1.245  \item[ctx\_allow]
   1.246 -  the context switch allowance is similar to the "quantum"
   1.247 +  the context switch allowance is similar to the `quantum'
   1.248    in traditional schedulers.  It is the minimum time that
   1.249    a scheduled domain will be allowed to run before being
   1.250    pre-empted. 
   1.251 @@ -1243,7 +1243,7 @@ domains), but this can be compensated fo
   1.252    proportional share of the CPU that a domain receives.  It
   1.253    is set inversely proportionally to a domain's sharing weight.
   1.254  \item[warp]
   1.255 -  the amount of ``virtual time'' the domain is allowed to warp
   1.256 +  the amount of `virtual time' the domain is allowed to warp
   1.257    backwards
   1.258  \item[warpl]
   1.259    the warp limit is the maximum time a domain can run warped for
   1.260 @@ -1456,7 +1456,7 @@ do not need to configure them.
   1.261  
   1.262  \section{XenLinux Boot Options}
   1.263  
   1.264 -In addition to the standard linux kernel boot options, we support: 
   1.265 +In addition to the standard Linux kernel boot options, we support: 
   1.266  \begin{description} 
   1.267  \item[xencons=xxx ] Specify the device node to which the Xen virtual
   1.268  console driver is attached. The following options are supported:
   1.269 @@ -1565,8 +1565,8 @@ Xen domain:
   1.270  dd if=/dev/zero of=/path/diskimage bs=1024k count=size_in_mbytes
   1.271  dd if=/dev/zero of=/path/swapimage bs=1024k count=size_in_mbytes
   1.272  \end{verbatim}\end{small}
   1.273 -      If you're going to use this filesystem / diskimage only as a
   1.274 -      `template' for other vm diskimages, something like 300 MB should
   1.275 +      If you're going to use this filesystem / disk image only as a
   1.276 +      `template' for other vm disk images, something like 300 MB should
   1.277        be enough.. (of course it depends what kind of packages you are
   1.278        planning to install to the template)
   1.279  
   1.280 @@ -1576,7 +1576,7 @@ mkfs.ext3 /path/diskimage
   1.281  mkswap /path/swapimage
   1.282  \end{verbatim}\end{small}
   1.283  
   1.284 -\item Mount the diskimage for installation
   1.285 +\item Mount the disk image for installation
   1.286  \begin{small}\begin{verbatim}
   1.287  mount -o loop /path/diskimage /mnt/disk
   1.288  \end{verbatim}\end{small}
   1.289 @@ -1588,7 +1588,7 @@ running Debian sarge (3.1 / testing) or 
   1.290  running {\small {\tt apt-get install debootstrap}}.  Otherwise, it can be
   1.291  downloaded from the Debian project website.
   1.292  
   1.293 -\item Install debian base to the diskimage:
   1.294 +\item Install Debian base to the disk image:
   1.295  \begin{small}\begin{verbatim}
   1.296  debootstrap --arch i386 sarge /mnt/disk  \
   1.297              http://ftp.<countrycode>.debian.org/debian
   1.298 @@ -1631,13 +1631,13 @@ proc            /proc   proc    defaults
   1.299  
   1.300  Logout
   1.301  
   1.302 -\item      Umount the diskimage
   1.303 +\item      Unmount the disk image
   1.304  \begin{small}\begin{verbatim}
   1.305  umount /mnt/disk
   1.306  \end{verbatim}\end{small}
   1.307  
   1.308  \item Create Xen 2.0 configuration file for the new domain. You can
   1.309 -        use the example-configurations coming with xen as a template.
   1.310 +        use the example-configurations coming with Xen as a template.
   1.311  
   1.312          Make sure you have the following set up:
   1.313  \begin{small}\begin{verbatim}
   1.314 @@ -1664,7 +1664,7 @@ Started domain testdomain2, console on p
   1.315          
   1.316          There you can see the ID of the console: 26. You can also list
   1.317          the consoles with {\small {\tt xm consoles}} (ID is the last two
   1.318 -        digits of the portnumber.)
   1.319 +        digits of the port number.)
   1.320  
   1.321          Attach to the console:
   1.322  
   1.323 @@ -1673,7 +1673,7 @@ xm console 26
   1.324  \end{verbatim}\end{small}
   1.325  
   1.326          or by telnetting to the port 9626 of localhost (the xm console
   1.327 -        progam works better).
   1.328 +        program works better).
   1.329  
   1.330  \item   Log in and run base-config
   1.331  
   1.332 @@ -1700,7 +1700,7 @@ image-specific settings (hostname, netwo
   1.333  
   1.334  \chapter{Installing Xen / XenLinux on Redhat or Fedora Core}
   1.335  
   1.336 -When using Xen / Xenlinux on a standard Linux distribution there are
   1.337 +When using Xen / XenLinux on a standard Linux distribution there are
   1.338  a couple of things to watch out for:
   1.339  
   1.340  Note that, because domains>0 don't have any privileged access at all,
   1.341 @@ -1715,7 +1715,7 @@ startup scripts.  Deleting the following
   1.342  
   1.343  If you want to use a single root file system that works cleanly for
   1.344  both domain 0 and unprivileged domains, a useful trick is to use
   1.345 -different 'init' run levels. For example, on the Xen Demo CD we use
   1.346 +different 'init' run levels. For example, use
   1.347  run level 3 for domain 0, and run level 4 for other domains. This
   1.348  enables different startup scripts to be run in depending on the run
   1.349  level number passed on the kernel command line.
   1.350 @@ -1800,7 +1800,7 @@ statically-linked C program would solve 
   1.351  
   1.352  \item[Domain ID]           A unique identifier for a {\bf domain},
   1.353                             analogous to a process ID in an operating
   1.354 -                           system.  Apart from domain
   1.355 +                           system.
   1.356  
   1.357  \item[Full virtualisation] An approach to virtualisation which
   1.358                             requires no modifications to the hosted