ia64/xen-unstable

changeset 8226:dceb2fcdab5b

Reorg patch 2 to match http://wiki.xensource.com/xenwiki/Xen3DocsToDo

Second patch to reorganize the manual to match the structure in the
Xen3DocsToDo Wiki entry.
author Robb Romans <FMJ@us.ibm.com>
date Fri Dec 02 14:29:26 2005 -0700 (2005-12-02)
parents 63f9c8dd13d4
children 57d5f6c9b9ef
files docs/src/user.tex docs/src/user/booting_xen.tex docs/src/user/building_xen.tex docs/src/user/console_management.tex docs/src/user/control_software.tex docs/src/user/cpu_management.tex docs/src/user/debian.tex docs/src/user/debugging.tex docs/src/user/dom0_installation.tex docs/src/user/domU_installation.tex docs/src/user/domain_filesystem.tex docs/src/user/domain_mgmt.tex docs/src/user/installation.tex docs/src/user/introduction.tex docs/src/user/logfiles.tex docs/src/user/memory_management.tex docs/src/user/migrating_domains.tex docs/src/user/network_management.tex docs/src/user/scheduler_management.tex docs/src/user/xenstat.tex docs/src/user/xentrace.tex
line diff
     1.1 --- a/docs/src/user.tex	Fri Dec 02 14:29:25 2005 -0700
     1.2 +++ b/docs/src/user.tex	Fri Dec 02 14:29:26 2005 -0700
     1.3 @@ -60,8 +60,6 @@
     1.4  \setstretch{1.1}
     1.5  
     1.6  
     1.7 -\part{Introduction}
     1.8 -
     1.9  %% Chapter Introduction moved to introduction.tex
    1.10  \include{src/user/introduction}
    1.11  
    1.12 @@ -80,39 +78,78 @@
    1.13  %% Chapter Installing Xen on Gentoo Linux
    1.14  \include{src/user/gentoo}
    1.15  
    1.16 +%% Chapter Installing Xen on SuSE or SuSE SLES
    1.17 +\include{src/user/suse}
    1.18 +
    1.19  %% Chapter Installing Xen on Red Hat Enterprise Linux (RHEL)
    1.20  \include{src/user/rhel}
    1.21  
    1.22 -%% Chapter Installing Xen on SuSE or SuSE SLES
    1.23 -\include{src/user/suse}
    1.24 +% Chapter dom0 Installation
    1.25 +\include{src/user/dom0_installation}
    1.26 +
    1.27 +% Chapter domU Installation
    1.28 +\include{src/user/domU_installation}
    1.29 +
    1.30 +% Building Xen
    1.31 +\include{src/user/building_xen}
    1.32 +
    1.33 +% Booting Xen
    1.34 +\include{src/user/booting_xen}
    1.35  
    1.36  
    1.37  \part{Configuration and Management}
    1.38  
    1.39 +%% Chapter Domain Management Tools and Daemons
    1.40 +\include{src/user/domain_mgmt}
    1.41 +
    1.42  %% Chapter Starting Additional Domains
    1.43  \include{src/user/start_addl_dom}
    1.44  
    1.45 -%% Chapter Domain Management Tools
    1.46 -\include{src/user/domain_mgmt}
    1.47 +%% Chapter Domain Configuration
    1.48 +\include{src/user/domain_configuration}
    1.49  
    1.50 -%% Chapter Domain Filesystem Storage
    1.51 +% Chapter Console Management
    1.52 +\include{src/user/console_management}
    1.53 +
    1.54 +% Chapter Network Management
    1.55 +\include{src/user/network_management}
    1.56 +
    1.57 +% Chapter Storage and FileSytem Management
    1.58  \include{src/user/domain_filesystem}
    1.59  
    1.60 -%% Chapter Domain Configuration
    1.61 -\include{src/user/domain_configuration}
    1.62 +% Chapter Memory Management
    1.63 +\include{src/user/memory_management}
    1.64 +
    1.65 +% Chapter CPU Management
    1.66 +\include{src/user/cpu_management}
    1.67 +
    1.68 +% Chapter Scheduler Management
    1.69 +\include{src/user/scheduler_management}
    1.70 +
    1.71 +% Chapter Migrating Domains
    1.72 +\include{src/user/migrating_domains}
    1.73  
    1.74  %% Chapter Securing Xen
    1.75  \include{src/user/securing_xen}
    1.76  
    1.77  
    1.78 -\part{Troubleshooting}
    1.79 +\part{Monitoring and Troubleshooting}
    1.80  
    1.81  %% Chapter Monitoring Xen
    1.82  \include{src/user/monitoring_xen}
    1.83  
    1.84 -%% Chapter Debugging and Tracing
    1.85 +% Chapter xenstat
    1.86 +\include{src/user/xenstat}
    1.87 +
    1.88 +% Chapter Log Files
    1.89 +\include{src/user/logfiles}
    1.90 +
    1.91 +%% Chapter Debugging
    1.92  \include{src/user/debugging}
    1.93  
    1.94 +% Chapter xentrace
    1.95 +\include{src/user/xentrace}
    1.96 +
    1.97  %% Chapter Known Problems
    1.98  \include{src/user/known_problems}
    1.99  
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/docs/src/user/booting_xen.tex	Fri Dec 02 14:29:26 2005 -0700
     2.3 @@ -0,0 +1,3 @@
     2.4 +\chapter{Booting Xen}
     2.5 +
     2.6 +Placeholder.
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/docs/src/user/building_xen.tex	Fri Dec 02 14:29:26 2005 -0700
     3.3 @@ -0,0 +1,3 @@
     3.4 +\chapter{Building Xen}
     3.5 +
     3.6 +Placeholder.
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/docs/src/user/console_management.tex	Fri Dec 02 14:29:26 2005 -0700
     4.3 @@ -0,0 +1,3 @@
     4.4 +\chapter{Console Management}
     4.5 +
     4.6 +Placeholder.
     5.1 --- a/docs/src/user/control_software.tex	Fri Dec 02 14:29:25 2005 -0700
     5.2 +++ b/docs/src/user/control_software.tex	Fri Dec 02 14:29:26 2005 -0700
     5.3 @@ -1,101 +1,10 @@
     5.4  \chapter{Control Software} 
     5.5  
     5.6 -The Xen control software includes the \xend\ node control daemon
     5.7 -(which must be running), the xm command line tools, and the prototype
     5.8 -xensv web interface.
     5.9 -
    5.10 -\section{\Xend\ (node control daemon)}
    5.11 -\label{s:xend}
    5.12 -
    5.13 -The Xen Daemon (\Xend) performs system management functions related to
    5.14 -virtual machines.  It forms a central point of control for a machine
    5.15 -and can be controlled using an HTTP-based protocol.  \Xend\ must be
    5.16 -running in order to start and manage virtual machines.
    5.17 -
    5.18 -\Xend\ must be run as root because it needs access to privileged
    5.19 -system management functions.  A small set of commands may be issued on
    5.20 -the \xend\ command line:
    5.21 -
    5.22 -\begin{tabular}{ll}
    5.23 -  \verb!# xend start! & start \xend, if not already running \\
    5.24 -  \verb!# xend stop!  & stop \xend\ if already running       \\
    5.25 -  \verb!# xend restart! & restart \xend\ if running, otherwise start it \\
    5.26 -  % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\
    5.27 -  \verb!# xend status! & indicates \xend\ status by its return code
    5.28 -\end{tabular}
    5.29 -
    5.30 -A SysV init script called {\tt xend} is provided to start \xend\ at
    5.31 -boot time.  {\tt make install} installs this script in
    5.32 -\path{/etc/init.d}.  To enable it, you have to make symbolic links in
    5.33 -the appropriate runlevel directories or use the {\tt chkconfig} tool,
    5.34 -where available.
    5.35 -
    5.36 -Once \xend\ is running, more sophisticated administration can be done
    5.37 -using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv
    5.38 -web interface (see Section~\ref{s:xensv}).
    5.39 -
    5.40 -As \xend\ runs, events will be logged to \path{/var/log/xend.log} and,
    5.41 -if the migration assistant daemon (\path{xfrd}) has been started,
    5.42 -\path{/var/log/xfrd.log}. These may be of use for troubleshooting
    5.43 -problems.
    5.44 -
    5.45 -\section{Xm (command line interface)}
    5.46 -\label{s:xm}
    5.47 -
    5.48 -The xm tool is the primary tool for managing Xen from the console.
    5.49 -The general format of an xm command line is:
    5.50 -
    5.51 -\begin{verbatim}
    5.52 -# xm command [switches] [arguments] [variables]
    5.53 -\end{verbatim}
    5.54 -
    5.55 -The available \emph{switches} and \emph{arguments} are dependent on
    5.56 -the \emph{command} chosen.  The \emph{variables} may be set using
    5.57 -declarations of the form {\tt variable=value} and command line
    5.58 -declarations override any of the values in the configuration file
    5.59 -being used, including the standard variables described above and any
    5.60 -custom variables (for instance, the \path{xmdefconfig} file uses a
    5.61 -{\tt vmid} variable).
    5.62 -
    5.63 -The available commands are as follows:
    5.64 -
    5.65 -\begin{description}
    5.66 -\item[mem-set] Request a domain to adjust its memory footprint.
    5.67 -\item[create] Create a new domain.
    5.68 -\item[destroy] Kill a domain immediately.
    5.69 -\item[list] List running domains.
    5.70 -\item[shutdown] Ask a domain to shutdown.
    5.71 -\item[dmesg] Fetch the Xen (not Linux!) boot output.
    5.72 -\item[consoles] Lists the available consoles.
    5.73 -\item[console] Connect to the console for a domain.
    5.74 -\item[help] Get help on xm commands.
    5.75 -\item[save] Suspend a domain to disk.
    5.76 -\item[restore] Restore a domain from disk.
    5.77 -\item[pause] Pause a domain's execution.
    5.78 -\item[unpause] Un-pause a domain.
    5.79 -\item[pincpu] Pin a domain to a CPU.
    5.80 -\item[bvt] Set BVT scheduler parameters for a domain.
    5.81 -\item[bvt\_ctxallow] Set the BVT context switching allowance for the
    5.82 -  system.
    5.83 -\item[atropos] Set the atropos parameters for a domain.
    5.84 -\item[rrobin] Set the round robin time slice for the system.
    5.85 -\item[info] Get information about the Xen host.
    5.86 -\item[call] Call a \xend\ HTTP API function directly.
    5.87 -\end{description}
    5.88 -
    5.89 -For a detailed overview of switches, arguments and variables to each
    5.90 -command try
    5.91 -\begin{quote}
    5.92 -\begin{verbatim}
    5.93 -# xm help command
    5.94 -\end{verbatim}
    5.95 -\end{quote}
    5.96 -
    5.97  \section{Xensv (web control interface)}
    5.98  \label{s:xensv}
    5.99  
   5.100  Xensv is the experimental web control interface for managing a Xen
   5.101 -machine.  It can be used to perform some (but not yet all) of the
   5.102 +machine. It can be used to perform some (but not yet all) of the
   5.103  management tasks that can be done using the xm tool.
   5.104  
   5.105  It can be started using:
   5.106 @@ -107,7 +16,7 @@ and stopped using:
   5.107    \verb_# xensv stop_
   5.108  \end{quote}
   5.109  
   5.110 -By default, Xensv will serve out the web interface on port 8080.  This
   5.111 +By default, Xensv will serve out the web interface on port 8080. This
   5.112  can be changed by editing
   5.113  \path{/usr/lib/python2.3/site-packages/xen/sv/params.py}.
   5.114  
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/docs/src/user/cpu_management.tex	Fri Dec 02 14:29:26 2005 -0700
     6.3 @@ -0,0 +1,3 @@
     6.4 +\chapter{CPU Management}
     6.5 +
     6.6 +Placeholder.
     7.1 --- a/docs/src/user/debian.tex	Fri Dec 02 14:29:25 2005 -0700
     7.2 +++ b/docs/src/user/debian.tex	Fri Dec 02 14:29:26 2005 -0700
     7.3 @@ -2,11 +2,11 @@
     7.4  
     7.5  The Debian project provides a tool called \path{debootstrap} which
     7.6  allows a base Debian system to be installed into a filesystem without
     7.7 -requiring the host system to have any Debian-specific software (such
     7.8 -as \path{apt}).
     7.9 +requiring the host system to have any Debian-specific software (such as
    7.10 +\path{apt}).
    7.11  
    7.12 -Here's some info how to install Debian 3.1 (Sarge) for an unprivileged
    7.13 -Xen domain:
    7.14 +Here's some info on how to install Debian 3.1 (Sarge) for an
    7.15 +unprivileged Xen domain:
    7.16  
    7.17  \begin{enumerate}
    7.18  
    7.19 @@ -14,13 +14,12 @@ Xen domain:
    7.20    this manual.
    7.21  
    7.22  \item Create disk images for rootfs and swap. Alternatively, you might
    7.23 -  create dedicated partitions, LVM logical volumes, etc.\ if that
    7.24 -  suits your setup.
    7.25 +  create dedicated partitions, LVM logical volumes, etc.\ if that suits
    7.26 +  your setup.
    7.27  \begin{verbatim}
    7.28  dd if=/dev/zero of=/path/diskimage bs=1024k count=size_in_mbytes
    7.29  dd if=/dev/zero of=/path/swapimage bs=1024k count=size_in_mbytes
    7.30  \end{verbatim}
    7.31 -
    7.32    If you're going to use this filesystem / disk image only as a
    7.33    `template' for other vm disk images, something like 300 MB should be
    7.34    enough. (of course it depends what kind of packages you are planning
    7.35 @@ -38,25 +37,25 @@ mount -o loop /path/diskimage /mnt/disk
    7.36  \end{verbatim}
    7.37  
    7.38  \item Install \path{debootstrap}. Make sure you have debootstrap
    7.39 -  installed on the host.  If you are running Debian Sarge (3.1 /
    7.40 -  testing) or unstable you can install it by running \path{apt-get
    7.41 -    install debootstrap}.  Otherwise, it can be downloaded from the
    7.42 -  Debian project website.
    7.43 +  installed on the host. If you are running Debian Sarge (3.1 / testing)
    7.44 +  or unstable you can install it by running \path{apt-get install
    7.45 +    debootstrap}. Otherwise, it can be downloaded from the Debian
    7.46 +  project website.
    7.47  
    7.48  \item Install Debian base to the disk image:
    7.49  \begin{verbatim}
    7.50  debootstrap --arch i386 sarge /mnt/disk  \
    7.51              http://ftp.<countrycode>.debian.org/debian
    7.52  \end{verbatim}
    7.53 -
    7.54 -  You can use any other Debian http/ftp mirror you want.
    7.55 +  You may use any Debian mirror that you want.
    7.56  
    7.57  \item When debootstrap completes successfully, modify settings:
    7.58  \begin{verbatim}
    7.59  chroot /mnt/disk /bin/bash
    7.60  \end{verbatim}
    7.61  
    7.62 -Edit the following files using vi or nano and make needed changes:
    7.63 +  Edit the following files using vi or nano and make any required
    7.64 +  changes:
    7.65  \begin{verbatim}
    7.66  /etc/hostname
    7.67  /etc/hosts
    7.68 @@ -65,36 +64,36 @@ Edit the following files using vi or nan
    7.69  /etc/networks
    7.70  \end{verbatim}
    7.71  
    7.72 -Set up access to the services, edit:
    7.73 +  Set up access to the services. Edit:
    7.74  \begin{verbatim}
    7.75  /etc/hosts.deny
    7.76  /etc/hosts.allow
    7.77  /etc/inetd.conf
    7.78  \end{verbatim}
    7.79  
    7.80 -Add Debian mirror to:   
    7.81 +  Add Debian mirror to:
    7.82  \begin{verbatim}
    7.83  /etc/apt/sources.list
    7.84  \end{verbatim}
    7.85  
    7.86 -Create fstab like this:
    7.87 +  Create fstab like this:
    7.88  \begin{verbatim}
    7.89  /dev/sda1       /       ext3    errors=remount-ro       0       1
    7.90  /dev/sda2       none    swap    sw                      0       0
    7.91  proc            /proc   proc    defaults                0       0
    7.92  \end{verbatim}
    7.93  
    7.94 -Logout
    7.95 +  Logout
    7.96  
    7.97  \item Unmount the disk image
    7.98  \begin{verbatim}
    7.99  umount /mnt/disk
   7.100  \end{verbatim}
   7.101  
   7.102 -\item Create Xen 2.0 configuration file for the new domain. You can
   7.103 -  use the example-configurations coming with Xen as a template.
   7.104 +\item Create Xen 3.0 configuration file for the new domain. You may use
   7.105 +  the example-configurations provided with Xen as a template.
   7.106  
   7.107 -  Make sure you have the following set up:
   7.108 +  Make sure you have the correctly configured:
   7.109  \begin{verbatim}
   7.110  disk = [ 'file:/path/diskimage,sda1,w', 'file:/path/swapimage,sda2,w' ]
   7.111  root = "/dev/sda1 ro"
   7.112 @@ -105,21 +104,20 @@ root = "/dev/sda1 ro"
   7.113  xm create -f domain_config_file
   7.114  \end{verbatim}
   7.115  
   7.116 -Check that the new domain is running:
   7.117 +  Check that the new domain is running:
   7.118  \begin{verbatim}
   7.119  xm list
   7.120  \end{verbatim}
   7.121  
   7.122 -\item Attach to the console of the new domain.  You should see
   7.123 -  something like this when starting the new domain:
   7.124 +\item Attach to the console of the new domain. You should see something
   7.125 +  like this when starting the new domain:
   7.126  
   7.127  \begin{verbatim}
   7.128  Started domain testdomain2, console on port 9626
   7.129  \end{verbatim}
   7.130          
   7.131 -  There you can see the ID of the console: 26. You can also list the
   7.132 -  consoles with \path{xm consoles} (ID is the last two digits of the
   7.133 -  port number.)
   7.134 +  You can see the ID of the console: 26. You can also list the consoles
   7.135 +  with \path{xm consoles}. ID is the last two digits of the port number.
   7.136  
   7.137    Attach to the console:
   7.138  
   7.139 @@ -127,28 +125,26 @@ Started domain testdomain2, console on p
   7.140  xm console 26
   7.141  \end{verbatim}
   7.142  
   7.143 -  or by telnetting to the port 9626 of localhost (the xm console
   7.144 -  program works better).
   7.145 +  or by telnetting to the port 9626 of localhost. The xm console program
   7.146 +  works better.
   7.147  
   7.148  \item Log in and run base-config
   7.149  
   7.150 -  As a default there's no password for the root.
   7.151 +  By default there is no password set for root.
   7.152  
   7.153 -  Check that everything looks OK, and the system started without
   7.154 -  errors.  Check that the swap is active, and the network settings are
   7.155 -  correct.
   7.156 +  Check that everything looks OK, and the system started without errors.
   7.157 +  Check that the swap is active, and the network settings are correct.
   7.158  
   7.159 -  Run \path{/usr/sbin/base-config} to set up the Debian settings.
   7.160 +  Run \path{/usr/sbin/base-config} to configure the Debian settings.
   7.161  
   7.162 -  Set up the password for root using passwd.
   7.163 +  Set the password for root using \path{passwd}.
   7.164  
   7.165 -\item Done. You can exit the console by pressing {\path{Ctrl + ]}}
   7.166 +\item Done. You may exit the console by pressing {\path{Ctrl + ]}}
   7.167  
   7.168  \end{enumerate}
   7.169  
   7.170 -
   7.171 -If you need to create new domains, you can just copy the contents of
   7.172 -the `template'-image to the new disk images, either by mounting the
   7.173 -template and the new image, and using \path{cp -a} or \path{tar} or by
   7.174 -simply copying the image file.  Once this is done, modify the
   7.175 -image-specific settings (hostname, network settings, etc).
   7.176 +If you need to create new domains, you can copy the contents of the
   7.177 +`template'-image to the new disk images, either by mounting the template
   7.178 +and the new image, and using \path{cp -a} or \path{tar} or by simply
   7.179 +copying the image file. Once this is done, modify the image-specific
   7.180 +settings (hostname, network settings, etc).
     8.1 --- a/docs/src/user/debugging.tex	Fri Dec 02 14:29:25 2005 -0700
     8.2 +++ b/docs/src/user/debugging.tex	Fri Dec 02 14:29:26 2005 -0700
     8.3 @@ -1,7 +1,4 @@
     8.4 -\chapter{Debugging and Tracing}
     8.5 -
     8.6 -\section{Debugging}
     8.7 -\label{s:keys}
     8.8 +\chapter{Debugging}
     8.9  
    8.10  Xen has a set of debugging features that can be useful to try and figure
    8.11  out what's going on. Hit ``h'' on the serial line (if you specified a baud
    8.12 @@ -19,7 +16,3 @@ any other Linux kernel.
    8.13  %% null modem cable. Documentation is included.  Alternatively, if the
    8.14  %% Xen machine is connected to a serial-port server then we supply a
    8.15  %% dumb TCP terminal client, {\tt xencons}.
    8.16 -
    8.17 -\section{Tracing}
    8.18 -
    8.19 -Placeholder.
    8.20 \ No newline at end of file
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/docs/src/user/dom0_installation.tex	Fri Dec 02 14:29:26 2005 -0700
     9.3 @@ -0,0 +1,3 @@
     9.4 +\chapter{dom0 Installation}
     9.5 +
     9.6 +Placeholder.
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/docs/src/user/domU_installation.tex	Fri Dec 02 14:29:26 2005 -0700
    10.3 @@ -0,0 +1,3 @@
    10.4 +\chapter{domU Installation}
    10.5 +
    10.6 +Placeholder.
    11.1 --- a/docs/src/user/domain_filesystem.tex	Fri Dec 02 14:29:25 2005 -0700
    11.2 +++ b/docs/src/user/domain_filesystem.tex	Fri Dec 02 14:29:26 2005 -0700
    11.3 @@ -1,4 +1,4 @@
    11.4 -\chapter{Domain Filesystem Storage}
    11.5 +\chapter{Storage and File System Management}
    11.6  
    11.7  It is possible to directly export any Linux block device in dom0 to
    11.8  another domain, or to export filesystems / devices to virtual machines
    12.1 --- a/docs/src/user/domain_mgmt.tex	Fri Dec 02 14:29:25 2005 -0700
    12.2 +++ b/docs/src/user/domain_mgmt.tex	Fri Dec 02 14:29:26 2005 -0700
    12.3 @@ -1,20 +1,98 @@
    12.4  \chapter{Domain Management Tools}
    12.5  
    12.6 -The previous chapter described a simple example of how to configure
    12.7 -and start a domain.  This chapter summarises the tools available to
    12.8 -manage running domains.
    12.9 +This chapter summarises the tools available to manage running domains.
   12.10  
   12.11  
   12.12 -\section{Command-line Management}
   12.13 +\section{\Xend\ }
   12.14 +\label{s:xend}
   12.15 +
   12.16 +The Xen Daemon (\Xend) (node control daemon) performs system management
   12.17 +functions related to virtual machines. It forms a central point of
   12.18 +control for a machine and can be controlled using an HTTP-based
   12.19 +protocol. \Xend\ must be running in order to start and manage virtual
   12.20 +machines.
   12.21 +
   12.22 +\Xend\ must be run as root because it needs access to privileged system
   12.23 +management functions. A small set of commands may be issued on the
   12.24 +\xend\ command line:
   12.25 +
   12.26 +\begin{tabular}{ll}
   12.27 +  \verb!# xend start! & start \xend, if not already running \\
   12.28 +  \verb!# xend stop!  & stop \xend\ if already running       \\
   12.29 +  \verb!# xend restart! & restart \xend\ if running, otherwise start it \\
   12.30 +  % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\
   12.31 +  \verb!# xend status! & indicates \xend\ status by its return code
   12.32 +\end{tabular}
   12.33 +
   12.34 +A SysV init script called {\tt xend} is provided to start \xend\ at boot
   12.35 +time. {\tt make install} installs this script in \path{/etc/init.d}. To
   12.36 +enable it, you have to make symbolic links in the appropriate runlevel
   12.37 +directories or use the {\tt chkconfig} tool, where available.
   12.38 +
   12.39 +Once \xend\ is running, more sophisticated administration can be done
   12.40 +using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv
   12.41 +web interface (see Section~\ref{s:xensv}).
   12.42 +
   12.43 +As \xend\ runs, events will be logged to \path{/var/log/xend.log} and,
   12.44 +if the migration assistant daemon (\path{xfrd}) has been started,
   12.45 +\path{/var/log/xfrd.log}. These may be of use for troubleshooting
   12.46 +problems.
   12.47 +
   12.48 +\section{Xm}
   12.49 +\label{s:xm}
   12.50  
   12.51  Command line management tasks are also performed using the \path{xm}
   12.52 -tool.  For online help for the commands available, type:
   12.53 +tool. For online help for the commands available, type:
   12.54 +
   12.55  \begin{quote}
   12.56 -  \verb_# xm help_
   12.57 +\begin{verbatim}
   12.58 +# xm help
   12.59 +\end{verbatim}
   12.60  \end{quote}
   12.61  
   12.62 -You can also type \path{xm help $<$command$>$} for more information on
   12.63 -a given command.
   12.64 +You can also type \path{xm help $<$command$>$} for more information on a
   12.65 +given command.
   12.66 +
   12.67 +The xm tool is the primary tool for managing Xen from the console. The
   12.68 +general format of an xm command line is:
   12.69 +
   12.70 +\begin{verbatim}
   12.71 +# xm command [switches] [arguments] [variables]
   12.72 +\end{verbatim}
   12.73 +
   12.74 +The available \emph{switches} and \emph{arguments} are dependent on the
   12.75 +\emph{command} chosen. The \emph{variables} may be set using
   12.76 +declarations of the form {\tt variable=value} and command line
   12.77 +declarations override any of the values in the configuration file being
   12.78 +used, including the standard variables described above and any custom
   12.79 +variables (for instance, the \path{xmdefconfig} file uses a {\tt vmid}
   12.80 +variable).
   12.81 +
   12.82 +The available commands are as follows:
   12.83 +
   12.84 +\begin{description}
   12.85 +\item[mem-set] Request a domain to adjust its memory footprint.
   12.86 +\item[create] Create a new domain.
   12.87 +\item[destroy] Kill a domain immediately.
   12.88 +\item[list] List running domains.
   12.89 +\item[shutdown] Ask a domain to shutdown.
   12.90 +\item[dmesg] Fetch the Xen (not Linux!) boot output.
   12.91 +\item[consoles] Lists the available consoles.
   12.92 +\item[console] Connect to the console for a domain.
   12.93 +\item[help] Get help on xm commands.
   12.94 +\item[save] Suspend a domain to disk.
   12.95 +\item[restore] Restore a domain from disk.
   12.96 +\item[pause] Pause a domain's execution.
   12.97 +\item[unpause] Un-pause a domain.
   12.98 +\item[pincpu] Pin a domain to a CPU.
   12.99 +\item[bvt] Set BVT scheduler parameters for a domain.
  12.100 +\item[bvt\_ctxallow] Set the BVT context switching allowance for the
  12.101 +  system.
  12.102 +\item[atropos] Set the atropos parameters for a domain.
  12.103 +\item[rrobin] Set the round robin time slice for the system.
  12.104 +\item[info] Get information about the Xen host.
  12.105 +\item[call] Call a \xend\ HTTP API function directly.
  12.106 +\end{description}
  12.107  
  12.108  \subsection{Basic Management Commands}
  12.109  
  12.110 @@ -82,122 +160,6 @@ following:
  12.111  # xencons localhost 9605
  12.112  \end{verbatim}
  12.113  
  12.114 -\section{Domain Save and Restore}
  12.115 -
  12.116 -The administrator of a Xen system may suspend a virtual machine's
  12.117 -current state into a disk file in domain~0, allowing it to be resumed
  12.118 -at a later time.
  12.119 -
  12.120 -The ttylinux domain described earlier can be suspended to disk using
  12.121 -the command:
  12.122 -\begin{verbatim}
  12.123 -# xm save ttylinux ttylinux.xen
  12.124 -\end{verbatim}
  12.125 -
  12.126 -This will stop the domain named `ttylinux' and save its current state
  12.127 -into a file called \path{ttylinux.xen}.
  12.128 -
  12.129 -To resume execution of this domain, use the \path{xm restore} command:
  12.130 -\begin{verbatim}
  12.131 -# xm restore ttylinux.xen
  12.132 -\end{verbatim}
  12.133 -
  12.134 -This will restore the state of the domain and restart it.  The domain
  12.135 -will carry on as before and the console may be reconnected using the
  12.136 -\path{xm console} command, as above.
  12.137 -
  12.138 -\section{Live Migration}
  12.139 -
  12.140 -Live migration is used to transfer a domain between physical hosts
  12.141 -whilst that domain continues to perform its usual activities --- from
  12.142 -the user's perspective, the migration should be imperceptible.
  12.143 -
  12.144 -To perform a live migration, both hosts must be running Xen / \xend\
  12.145 -and the destination host must have sufficient resources (e.g.\ memory
  12.146 -capacity) to accommodate the domain after the move. Furthermore we
  12.147 -currently require both source and destination machines to be on the
  12.148 -same L2 subnet.
  12.149 -
  12.150 -Currently, there is no support for providing automatic remote access
  12.151 -to filesystems stored on local disk when a domain is migrated.
  12.152 -Administrators should choose an appropriate storage solution (i.e.\
  12.153 -SAN, NAS, etc.) to ensure that domain filesystems are also available
  12.154 -on their destination node. GNBD is a good method for exporting a
  12.155 -volume from one machine to another. iSCSI can do a similar job, but is
  12.156 -more complex to set up.
  12.157 -
  12.158 -When a domain migrates, it's MAC and IP address move with it, thus it
  12.159 -is only possible to migrate VMs within the same layer-2 network and IP
  12.160 -subnet. If the destination node is on a different subnet, the
  12.161 -administrator would need to manually configure a suitable etherip or
  12.162 -IP tunnel in the domain~0 of the remote node.
  12.163 -
  12.164 -A domain may be migrated using the \path{xm migrate} command.  To live
  12.165 -migrate a domain to another machine, we would use the command:
  12.166 -
  12.167 -\begin{verbatim}
  12.168 -# xm migrate --live mydomain destination.ournetwork.com
  12.169 -\end{verbatim}
  12.170 +\section{xenstored}
  12.171  
  12.172 -Without the \path{--live} flag, \xend\ simply stops the domain and
  12.173 -copies the memory image over to the new node and restarts it. Since
  12.174 -domains can have large allocations this can be quite time consuming,
  12.175 -even on a Gigabit network. With the \path{--live} flag \xend\ attempts
  12.176 -to keep the domain running while the migration is in progress,
  12.177 -resulting in typical `downtimes' of just 60--300ms.
  12.178 -
  12.179 -For now it will be necessary to reconnect to the domain's console on
  12.180 -the new machine using the \path{xm console} command.  If a migrated
  12.181 -domain has any open network connections then they will be preserved,
  12.182 -so SSH connections do not have this limitation.
  12.183 -
  12.184 -
  12.185 -\section{Managing Domain Memory}
  12.186 -
  12.187 -XenLinux domains have the ability to relinquish / reclaim machine
  12.188 -memory at the request of the administrator or the user of the domain.
  12.189 -
  12.190 -\subsection{Setting memory footprints from dom0}
  12.191 -
  12.192 -The machine administrator can request that a domain alter its memory
  12.193 -footprint using the \path{xm mem-set} command.  For instance, we can
  12.194 -request that our example ttylinux domain reduce its memory footprint
  12.195 -to 32 megabytes.
  12.196 -
  12.197 -\begin{verbatim}
  12.198 -# xm mem-set ttylinux 32
  12.199 -\end{verbatim}
  12.200 -
  12.201 -We can now see the result of this in the output of \path{xm list}:
  12.202 -
  12.203 -\begin{verbatim}
  12.204 -# xm list
  12.205 -Name              Id  Mem(MB)  CPU  State  Time(s)  Console
  12.206 -Domain-0           0      251    0  r----    172.2        
  12.207 -ttylinux           5       31    0  -b---      4.3    9605
  12.208 -\end{verbatim}
  12.209 -
  12.210 -The domain has responded to the request by returning memory to Xen. We
  12.211 -can restore the domain to its original size using the command line:
  12.212 -
  12.213 -\begin{verbatim}
  12.214 -# xm mem-set ttylinux 64
  12.215 -\end{verbatim}
  12.216 -
  12.217 -\subsection{Setting memory footprints from within a domain}
  12.218 -
  12.219 -The virtual file \path{/proc/xen/balloon} allows the owner of a domain
  12.220 -to adjust their own memory footprint.  Reading the file (e.g.\
  12.221 -\path{cat /proc/xen/balloon}) prints out the current memory footprint
  12.222 -of the domain.  Writing the file (e.g.\ \path{echo new\_target >
  12.223 -  /proc/xen/balloon}) requests that the kernel adjust the domain's
  12.224 -memory footprint to a new value.
  12.225 -
  12.226 -\subsection{Setting memory limits}
  12.227 -
  12.228 -Xen associates a memory size limit with each domain.  By default, this
  12.229 -is the amount of memory the domain is originally started with,
  12.230 -preventing the domain from ever growing beyond this size.  To permit a
  12.231 -domain to grow beyond its original allocation or to prevent a domain
  12.232 -you've shrunk from reclaiming the memory it relinquished, use the
  12.233 -\path{xm maxmem} command.
  12.234 +Placeholder.
    13.1 --- a/docs/src/user/installation.tex	Fri Dec 02 14:29:25 2005 -0700
    13.2 +++ b/docs/src/user/installation.tex	Fri Dec 02 14:29:26 2005 -0700
    13.3 @@ -1,40 +1,39 @@
    13.4  \chapter{Basic Installation}
    13.5  
    13.6  The Xen distribution includes three main components: Xen itself, ports
    13.7 -of Linux and NetBSD to run on Xen, and the userspace
    13.8 -tools required to manage a Xen-based system.  This chapter describes
    13.9 -how to install the Xen~3.0 distribution from source.  Alternatively,
   13.10 -there may be pre-built packages available as part of your operating
   13.11 -system distribution.
   13.12 +of Linux and NetBSD to run on Xen, and the userspace tools required to
   13.13 +manage a Xen-based system. This chapter describes how to install the
   13.14 +Xen~3.0 distribution from source. Alternatively, there may be pre-built
   13.15 +packages available as part of your operating system distribution.
   13.16  
   13.17  
   13.18  \section{Prerequisites}
   13.19  \label{sec:prerequisites}
   13.20  
   13.21 -The following is a full list of prerequisites.  Items marked `$\dag$'
   13.22 -are required by the \xend\ control tools, and hence required if you
   13.23 -want to run more than one virtual machine; items marked `$*$' are only
   13.24 -required if you wish to build from source.
   13.25 +The following is a full list of prerequisites. Items marked `$\dag$' are
   13.26 +required by the \xend\ control tools, and hence required if you want to
   13.27 +run more than one virtual machine; items marked `$*$' are only required
   13.28 +if you wish to build from source.
   13.29  \begin{itemize}
   13.30 -\item A working Linux distribution using the GRUB bootloader and
   13.31 -  running on a P6-class or newer CPU\@.
   13.32 +\item A working Linux distribution using the GRUB bootloader and running
   13.33 +  on a P6-class or newer CPU\@.
   13.34  \item [$\dag$] The \path{iproute2} package.
   13.35  \item [$\dag$] The Linux bridge-utils\footnote{Available from {\tt
   13.36        http://bridge.sourceforge.net}} (e.g., \path{/sbin/brctl})
   13.37  \item [$\dag$] The Linux hotplug system\footnote{Available from {\tt
   13.38 -      http://linux-hotplug.sourceforge.net/}} (e.g., \path{/sbin/hotplug}
   13.39 -      and related scripts)
   13.40 +      http://linux-hotplug.sourceforge.net/}} (e.g.,
   13.41 +  \path{/sbin/hotplug} and related scripts)
   13.42  \item [$*$] Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make).
   13.43  \item [$*$] Development installation of libcurl (e.g.,\ libcurl-devel).
   13.44  \item [$*$] Development installation of zlib (e.g.,\ zlib-dev).
   13.45 -\item [$*$] Development installation of Python v2.2 or later (e.g.,\ 
   13.46 +\item [$*$] Development installation of Python v2.2 or later (e.g.,\
   13.47    python-dev).
   13.48  \item [$*$] \LaTeX\ and transfig are required to build the
   13.49    documentation.
   13.50  \end{itemize}
   13.51  
   13.52 -Once you have satisfied these prerequisites, you can now install
   13.53 -either a binary or source distribution of Xen.
   13.54 +Once you have satisfied these prerequisites, you can now install either
   13.55 +a binary or source distribution of Xen.
   13.56  
   13.57  
   13.58  \section{Installing from Binary Tarball}
   13.59 @@ -51,14 +50,13 @@ Once you've downloaded the tarball, simp
   13.60  # sh ./install.sh
   13.61  \end{verbatim}
   13.62  
   13.63 -Once you've installed the binaries you need to configure your system
   13.64 -as described in Section~\ref{s:configure}.
   13.65 +Once you've installed the binaries you need to configure your system as
   13.66 +described in Section~\ref{s:configure}.
   13.67  
   13.68  
   13.69  \section{Installing from Source}
   13.70  
   13.71 -This section describes how to obtain, build and install Xen from
   13.72 -source.
   13.73 +This section describes how to obtain, build and install Xen from source.
   13.74  
   13.75  \subsection{Obtaining the Source}
   13.76  
   13.77 @@ -106,11 +104,11 @@ following:
   13.78  \begin{itemize}
   13.79  \item Build Xen.
   13.80  \item Build the control tools, including \xend.
   13.81 -\item Download (if necessary) and unpack the Linux 2.6 source code,
   13.82 -  and patch it for use with Xen.
   13.83 -\item Build a Linux kernel to use in domain~0 and a smaller
   13.84 -  unprivileged kernel, which can optionally be used for unprivileged
   13.85 -  virtual machines.
   13.86 +\item Download (if necessary) and unpack the Linux 2.6 source code, and
   13.87 +  patch it for use with Xen.
   13.88 +\item Build a Linux kernel to use in domain~0 and a smaller unprivileged
   13.89 +  kernel, which can optionally be used for unprivileged virtual
   13.90 +  machines.
   13.91  \end{itemize}
   13.92  
   13.93  After the build has completed you should have a top-level directory
   13.94 @@ -187,24 +185,24 @@ architecture being built for is \path{xe
   13.95  \end{verbatim}
   13.96  \end{quote}
   13.97  
   13.98 -You can also copy an existing Linux configuration (\path{.config})
   13.99 -into e.g.\ \path{linux-2.6.11-xen0} and execute:
  13.100 +You can also copy an existing Linux configuration (\path{.config}) into
  13.101 +e.g.\ \path{linux-2.6.11-xen0} and execute:
  13.102  \begin{quote}
  13.103  \begin{verbatim}
  13.104  # make ARCH=xen oldconfig
  13.105  \end{verbatim}
  13.106  \end{quote}
  13.107  
  13.108 -You may be prompted with some Xen-specific options. We advise
  13.109 -accepting the defaults for these options.
  13.110 +You may be prompted with some Xen-specific options. We advise accepting
  13.111 +the defaults for these options.
  13.112  
  13.113  Note that the only difference between the two types of Linux kernels
  13.114 -that are built is the configuration file used for each.  The ``U''
  13.115 +that are built is the configuration file used for each. The ``U''
  13.116  suffixed (unprivileged) versions don't contain any of the physical
  13.117 -hardware device drivers, leading to a 30\% reduction in size; hence
  13.118 -you may prefer these for your non-privileged domains.  The ``0''
  13.119 -suffixed privileged versions can be used to boot the system, as well
  13.120 -as in driver domains and unprivileged domains.
  13.121 +hardware device drivers, leading to a 30\% reduction in size; hence you
  13.122 +may prefer these for your non-privileged domains. The ``0'' suffixed
  13.123 +privileged versions can be used to boot the system, as well as in driver
  13.124 +domains and unprivileged domains.
  13.125  
  13.126  \subsection{Installing Generated Binaries}
  13.127  
  13.128 @@ -217,8 +215,8 @@ locations, do:
  13.129  \end{verbatim}
  13.130  \end{quote}
  13.131  
  13.132 -Alternatively, users with special installation requirements may wish
  13.133 -to install them manually by copying the files to their appropriate
  13.134 +Alternatively, users with special installation requirements may wish to
  13.135 +install them manually by copying the files to their appropriate
  13.136  destinations.
  13.137  
  13.138  %% Files in \path{install/boot/} include:
  13.139 @@ -233,23 +231,23 @@ destinations.
  13.140  The \path{dist/install/boot} directory will also contain the config
  13.141  files used for building the XenLinux kernels, and also versions of Xen
  13.142  and XenLinux kernels that contain debug symbols such as
  13.143 -(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which
  13.144 -are essential for interpreting crash dumps.  Retain these files as the
  13.145 +(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which are
  13.146 +essential for interpreting crash dumps. Retain these files as the
  13.147  developers may wish to see them if you post on the mailing list.
  13.148  
  13.149  
  13.150  \section{Configuration}
  13.151  \label{s:configure}
  13.152  
  13.153 -Once you have built and installed the Xen distribution, it is simple
  13.154 -to prepare the machine for booting and running Xen.
  13.155 +Once you have built and installed the Xen distribution, it is simple to
  13.156 +prepare the machine for booting and running Xen.
  13.157  
  13.158  \subsection{GRUB Configuration}
  13.159  
  13.160  An entry should be added to \path{grub.conf} (often found under
  13.161  \path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot.
  13.162  This file is sometimes called \path{menu.lst}, depending on your
  13.163 -distribution.  The entry should look something like the following:
  13.164 +distribution. The entry should look something like the following:
  13.165  
  13.166  {\small
  13.167  \begin{verbatim}
  13.168 @@ -266,11 +264,11 @@ For more details on the various Xen boot
  13.169  Section~\ref{s:xboot}.
  13.170  
  13.171  The module line of the configuration describes the location of the
  13.172 -XenLinux kernel that Xen should start and the parameters that should
  13.173 -be passed to it. Tthese are standard Linux parameters, identifying the
  13.174 -root device and specifying it be initially mounted read only and
  13.175 -instructing that console output be sent to the screen. Some
  13.176 -distributions such as SuSE do not require the \path{ro} parameter.
  13.177 +XenLinux kernel that Xen should start and the parameters that should be
  13.178 +passed to it. Tthese are standard Linux parameters, identifying the root
  13.179 +device and specifying it be initially mounted read only and instructing
  13.180 +that console output be sent to the screen. Some distributions such as
  13.181 +SuSE do not require the \path{ro} parameter.
  13.182  
  13.183  %% \framebox{\parbox{5in}{
  13.184  %%     {\bf Distro specific:} \\
  13.185 @@ -278,30 +276,26 @@ distributions such as SuSE do not requir
  13.186  %%     kernel command line, since the partition won't be remounted rw
  13.187  %%     during boot.  }}
  13.188  
  13.189 -
  13.190 -If you want to use an initrd, just add another \path{module} line to
  13.191 -the configuration, like:
  13.192 -{\small
  13.193 +If you want to use an initrd, just add another \path{module} line to the
  13.194 +configuration, like: {\small
  13.195  \begin{verbatim}
  13.196    module /boot/my_initrd.gz
  13.197  \end{verbatim}
  13.198  }
  13.199  
  13.200  When installing a new kernel, it is recommended that you do not delete
  13.201 -existing menu options from \path{menu.lst}, as you may wish to boot
  13.202 -your old Linux kernel in future, particularly if you have problems.
  13.203 +existing menu options from \path{menu.lst}, as you may wish to boot your
  13.204 +old Linux kernel in future, particularly if you have problems.
  13.205  
  13.206  \subsection{Serial Console (optional)}
  13.207  
  13.208  %% kernel /boot/xen-2.0.gz dom0_mem=131072 com1=115200,8n1
  13.209  %% module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro
  13.210  
  13.211 -In order to configure Xen serial console output, it is necessary to
  13.212 -add an boot option to your GRUB config; e.g.\ replace the above kernel
  13.213 -line with:
  13.214 -\begin{quote}
  13.215 -{\small
  13.216 -\begin{verbatim}
  13.217 +In order to configure Xen serial console output, it is necessary to add
  13.218 +an boot option to your GRUB config; e.g.\ replace the above kernel line
  13.219 +with:
  13.220 +\begin{quote} {\small \begin{verbatim}
  13.221     kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
  13.222  \end{verbatim}}
  13.223  \end{quote}
  13.224 @@ -309,11 +303,11 @@ line with:
  13.225  This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1
  13.226  stop bit and no parity. Modify these parameters for your environment.
  13.227  
  13.228 -One can also configure XenLinux to share the serial console; to
  13.229 -achieve this append ``\path{console=ttyS0}'' to your module line.
  13.230 +One can also configure XenLinux to share the serial console; to achieve
  13.231 +this append ``\path{console=ttyS0}'' to your module line.
  13.232  
  13.233 -If you wish to be able to log in over the XenLinux serial console it
  13.234 -is necessary to add a line into \path{/etc/inittab}. Add the line:
  13.235 +If you wish to be able to log in over the XenLinux serial console it is
  13.236 +necessary to add a line into \path{/etc/inittab}. Add the line:
  13.237  \begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty ttyS0}}
  13.238  \end{quote}
  13.239  
    14.1 --- a/docs/src/user/introduction.tex	Fri Dec 02 14:29:25 2005 -0700
    14.2 +++ b/docs/src/user/introduction.tex	Fri Dec 02 14:29:26 2005 -0700
    14.3 @@ -1,45 +1,43 @@
    14.4  \chapter{Introduction}
    14.5  
    14.6  
    14.7 -Xen is a \emph{paravirtualizing} virtual machine monitor (VMM), or
    14.8 -``hypervisor'', for the x86 processor architecture.  Xen can securely
    14.9 +Xen is a \emph{para-virtualizing} virtual machine monitor (VMM), or
   14.10 +``hypervisor'', for the x86 processor architecture. Xen can securely
   14.11  execute multiple virtual machines on a single physical system with
   14.12 -close-to-native performance.  The virtual machine technology
   14.13 -facilitates enterprise-grade functionality, including:
   14.14 +close-to-native performance. The virtual machine technology facilitates
   14.15 +enterprise-grade functionality, including:
   14.16  
   14.17  \begin{itemize}
   14.18  \item Virtual machines with performance close to native hardware.
   14.19 -\item Live migration of running virtual machines between physical
   14.20 -  hosts.
   14.21 +\item Live migration of running virtual machines between physical hosts.
   14.22  \item Excellent hardware support. Supports most Linux device drivers.
   14.23 -\item Sandboxed, re-startable device drivers.
   14.24 +\item Sand-boxed, re-startable device drivers.
   14.25  \end{itemize}
   14.26  
   14.27 -Paravirtualisation permits very high performance virtualisation, even
   14.28 +Para-virtualization permits very high performance virtualization, even
   14.29  on architectures like x86 that are traditionally very hard to
   14.30 -virtualise.
   14.31 +virtualize.
   14.32  
   14.33  The drawback of this approach is that it requires operating systems to
   14.34 -be \emph{ported} to run on Xen.  Porting an OS to run on Xen is
   14.35 -similar to supporting a new hardware platform, however the process is
   14.36 -simplified because the paravirtual machine architecture is very
   14.37 -similar to the underlying native hardware. Even though operating
   14.38 -system kernels must explicitly support Xen, a key feature is that user
   14.39 -space applications and libraries \emph{do not} require modification.
   14.40 +be \emph{ported} to run on Xen. Porting an OS to run on Xen is similar
   14.41 +to supporting a new hardware platform, however the process is simplified
   14.42 +because the para-virtual machine architecture is very similar to the
   14.43 +underlying native hardware. Even though operating system kernels must
   14.44 +explicitly support Xen, a key feature is that user space applications
   14.45 +and libraries \emph{do not} require modification.
   14.46  
   14.47 -Xen support is available for increasingly many operating systems:
   14.48 -right now, Linux and NetBSD are available for Xen 3.0.
   14.49 -A FreeBSD port is undergoing testing and will be incorporated into the
   14.50 -release soon. Other OS ports, including Plan 9, are in progress.  We
   14.51 -hope that that arch-xen patches will be incorporated into the
   14.52 -mainstream releases of these operating systems in due course (as has
   14.53 -already happened for NetBSD).
   14.54 +Xen support is available for increasingly many operating systems: right
   14.55 +now, Linux and NetBSD are available for Xen 3.0. A FreeBSD port is
   14.56 +undergoing testing and will be incorporated into the release soon. Other
   14.57 +OS ports, including Plan 9, are in progress. We hope that that arch-xen
   14.58 +patches will be incorporated into the mainstream releases of these
   14.59 +operating systems in due course (as has already happened for NetBSD).
   14.60  
   14.61  Possible usage scenarios for Xen include:
   14.62  
   14.63  \begin{description}
   14.64  \item [Kernel development.] Test and debug kernel modifications in a
   14.65 -  sandboxed virtual machine --- no need for a separate test machine.
   14.66 +  sand-boxed virtual machine --- no need for a separate test machine.
   14.67  \item [Multiple OS configurations.] Run multiple operating systems
   14.68    simultaneously, for instance for compatibility or QA purposes.
   14.69  \item [Server consolidation.] Move multiple servers onto a single
   14.70 @@ -50,7 +48,7 @@ Possible usage scenarios for Xen include
   14.71    control and isolation than single-system image solutions,
   14.72    particularly by using live migration for load balancing.
   14.73  \item [Hardware support for custom OSes.] Allow development of new
   14.74 -  OSes while benefitting from the wide-ranging hardware support of
   14.75 +  OSes while benefiting from the wide-ranging hardware support of
   14.76    existing OSes such as Linux.
   14.77  \end{description}
   14.78  
   14.79 @@ -62,10 +60,10 @@ which is Xen itself.
   14.80  
   14.81  Xen may host multiple \emph{guest} operating systems, each of which is
   14.82  executed within a secure virtual machine. In Xen terminology, a
   14.83 -\emph{domain}. Domains are scheduled by Xen to make effective use of
   14.84 -the available physical CPUs.  Each guest OS manages its own
   14.85 -applications. This management includes the responsibility of
   14.86 -scheduling each application within the time allotted to the VM by Xen.
   14.87 +\emph{domain}. Domains are scheduled by Xen to make effective use of the
   14.88 +available physical CPUs. Each guest OS manages its own applications.
   14.89 +This management includes the responsibility of scheduling each
   14.90 +application within the time allotted to the VM by Xen.
   14.91  
   14.92  The first domain, \emph{domain~0}, is created automatically when the
   14.93  system boots and has special management privileges. Domain~0 builds
   14.94 @@ -73,39 +71,38 @@ other domains and manages their virtual 
   14.95  administrative tasks such as suspending, resuming and migrating other
   14.96  virtual machines.
   14.97  
   14.98 -Within domain~0, a process called \emph{xend} runs to manage the
   14.99 -system.  \Xend\ is responsible for managing virtual machines and
  14.100 -providing access to their consoles.  Commands are issued to \xend\ 
  14.101 -over an HTTP interface, either from a command-line tool or from a web
  14.102 -browser.
  14.103 +Within domain~0, a process called \emph{xend} runs to manage the system.
  14.104 +\Xend\ is responsible for managing virtual machines and providing access
  14.105 +to their consoles. Commands are issued to \xend\ over an HTTP interface,
  14.106 +either from a command-line tool or from a web browser.
  14.107  
  14.108  
  14.109  \section{Hardware Support}
  14.110  
  14.111 -Xen currently runs only on the x86 architecture, requiring a `P6' or
  14.112 +Xen currently runs only on the x86 architecture, requiring a ``P6'' or
  14.113  newer processor (e.g.\ Pentium Pro, Celeron, Pentium~II, Pentium~III,
  14.114 -Pentium~IV, Xeon, AMD~Athlon, AMD~Duron).  Multiprocessor machines are
  14.115 -supported, and there is basic support for HyperThreading (SMT),
  14.116 -although this remains a topic for ongoing research. A port
  14.117 -specifically for x86/64 is in progress. Xen already runs on such
  14.118 -systems in 32-bit legacy mode. In addition, a port to the IA64
  14.119 -architecture is approaching completion. We hope to add other
  14.120 -architectures such as PPC and ARM in due course.
  14.121 +Pentium~IV, Xeon, AMD~Athlon, AMD~Duron). Multiprocessor machines are
  14.122 +supported, and there is basic support for HyperThreading (SMT), although
  14.123 +this remains a topic for ongoing research. A port specifically for
  14.124 +x86/64 is in progress. Xen already runs on such systems in 32-bit legacy
  14.125 +mode. In addition, a port to the IA64 architecture is approaching
  14.126 +completion. We hope to add other architectures such as PPC and ARM in
  14.127 +due course.
  14.128  
  14.129 -Xen can currently use up to 4GB of memory.  It is possible for x86
  14.130 -machines to address up to 64GB of physical memory but there are no
  14.131 -plans to support these systems: The x86/64 port is the planned route
  14.132 -to supporting larger memory sizes.
  14.133 +Xen can currently use up to 4GB of memory. It is possible for x86
  14.134 +machines to address up to 64GB of physical memory but there are no plans
  14.135 +to support these systems: The x86/64 port is the planned route to
  14.136 +supporting larger memory sizes.
  14.137  
  14.138 -Xen offloads most of the hardware support issues to the guest OS
  14.139 -running in Domain~0.  Xen itself contains only the code required to
  14.140 -detect and start secondary processors, set up interrupt routing, and
  14.141 -perform PCI bus enumeration.  Device drivers run within a privileged
  14.142 -guest OS rather than within Xen itself. This approach provides
  14.143 -compatibility with the majority of device hardware supported by Linux.
  14.144 -The default XenLinux build contains support for relatively modern
  14.145 -server-class network and disk hardware, but you can add support for
  14.146 -other hardware by configuring your XenLinux kernel in the normal way.
  14.147 +Xen offloads most of the hardware support issues to the guest OS running
  14.148 +in Domain~0. Xen itself contains only the code required to detect and
  14.149 +start secondary processors, set up interrupt routing, and perform PCI
  14.150 +bus enumeration. Device drivers run within a privileged guest OS rather
  14.151 +than within Xen itself. This approach provides compatibility with the
  14.152 +majority of device hardware supported by Linux. The default XenLinux
  14.153 +build contains support for relatively modern server-class network and
  14.154 +disk hardware, but you can add support for other hardware by configuring
  14.155 +your XenLinux kernel in the normal way.
  14.156  
  14.157  
  14.158  \section{History}
  14.159 @@ -119,20 +116,20 @@ distributed computing''. Xen plays a key
  14.160  efficiently partition a single machine to enable multiple independent
  14.161  clients to run their operating systems and applications in an
  14.162  environment. This environment provides protection, resource isolation
  14.163 -and accounting.  The project web page contains further information
  14.164 -along with pointers to papers and technical reports:
  14.165 +and accounting. The project web page contains further information along
  14.166 +with pointers to papers and technical reports:
  14.167  \path{http://www.cl.cam.ac.uk/xeno}
  14.168  
  14.169 -Xen has grown into a fully-fledged project in its own right, enabling
  14.170 -us to investigate interesting research issues regarding the best
  14.171 -techniques for virtualising resources such as the CPU, memory, disk
  14.172 -and network.  The project has been bolstered by support from Intel
  14.173 -Research Cambridge and HP Labs, who are now working closely with us.
  14.174 +Xen has grown into a fully-fledged project in its own right, enabling us
  14.175 +to investigate interesting research issues regarding the best techniques
  14.176 +for virtualizing resources such as the CPU, memory, disk and network.
  14.177 +The project has been bolstered by support from Intel Research Cambridge
  14.178 +and HP Labs, who are now working closely with us.
  14.179  
  14.180  Xen was first described in a paper presented at SOSP in
  14.181  2003\footnote{\tt
  14.182 -  http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the
  14.183 -first public release (1.0) was made that October.  Since then, Xen has
  14.184 +  http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the first
  14.185 +public release (1.0) was made that October. Since then, Xen has
  14.186  significantly matured and is now used in production scenarios on many
  14.187  sites.
  14.188  
    15.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.2 +++ b/docs/src/user/logfiles.tex	Fri Dec 02 14:29:26 2005 -0700
    15.3 @@ -0,0 +1,3 @@
    15.4 +\chapter{Log Files}
    15.5 +
    15.6 +Placeholder.
    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/docs/src/user/memory_management.tex	Fri Dec 02 14:29:26 2005 -0700
    16.3 @@ -0,0 +1,51 @@
    16.4 +\chapter{Memory Management}
    16.5 +
    16.6 +\section{Managing Domain Memory}
    16.7 +
    16.8 +XenLinux domains have the ability to relinquish / reclaim machine
    16.9 +memory at the request of the administrator or the user of the domain.
   16.10 +
   16.11 +\subsection{Setting memory footprints from dom0}
   16.12 +
   16.13 +The machine administrator can request that a domain alter its memory
   16.14 +footprint using the \path{xm mem-set} command.  For instance, we can
   16.15 +request that our example ttylinux domain reduce its memory footprint
   16.16 +to 32 megabytes.
   16.17 +
   16.18 +\begin{verbatim}
   16.19 +# xm mem-set ttylinux 32
   16.20 +\end{verbatim}
   16.21 +
   16.22 +We can now see the result of this in the output of \path{xm list}:
   16.23 +
   16.24 +\begin{verbatim}
   16.25 +# xm list
   16.26 +Name              Id  Mem(MB)  CPU  State  Time(s)  Console
   16.27 +Domain-0           0      251    0  r----    172.2        
   16.28 +ttylinux           5       31    0  -b---      4.3    9605
   16.29 +\end{verbatim}
   16.30 +
   16.31 +The domain has responded to the request by returning memory to Xen. We
   16.32 +can restore the domain to its original size using the command line:
   16.33 +
   16.34 +\begin{verbatim}
   16.35 +# xm mem-set ttylinux 64
   16.36 +\end{verbatim}
   16.37 +
   16.38 +\subsection{Setting memory footprints from within a domain}
   16.39 +
   16.40 +The virtual file \path{/proc/xen/balloon} allows the owner of a domain
   16.41 +to adjust their own memory footprint.  Reading the file (e.g.\
   16.42 +\path{cat /proc/xen/balloon}) prints out the current memory footprint
   16.43 +of the domain.  Writing the file (e.g.\ \path{echo new\_target >
   16.44 +  /proc/xen/balloon}) requests that the kernel adjust the domain's
   16.45 +memory footprint to a new value.
   16.46 +
   16.47 +\subsection{Setting memory limits}
   16.48 +
   16.49 +Xen associates a memory size limit with each domain.  By default, this
   16.50 +is the amount of memory the domain is originally started with,
   16.51 +preventing the domain from ever growing beyond this size.  To permit a
   16.52 +domain to grow beyond its original allocation or to prevent a domain
   16.53 +you've shrunk from reclaiming the memory it relinquished, use the
   16.54 +\path{xm maxmem} command.
    17.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    17.2 +++ b/docs/src/user/migrating_domains.tex	Fri Dec 02 14:29:26 2005 -0700
    17.3 @@ -0,0 +1,70 @@
    17.4 +\chapter{Migrating Domains}
    17.5 +
    17.6 +\section{Domain Save and Restore}
    17.7 +
    17.8 +The administrator of a Xen system may suspend a virtual machine's
    17.9 +current state into a disk file in domain~0, allowing it to be resumed at
   17.10 +a later time.
   17.11 +
   17.12 +The ttylinux domain described earlier can be suspended to disk using the
   17.13 +command:
   17.14 +\begin{verbatim}
   17.15 +# xm save ttylinux ttylinux.xen
   17.16 +\end{verbatim}
   17.17 +
   17.18 +This will stop the domain named ``ttylinux'' and save its current state
   17.19 +into a file called \path{ttylinux.xen}.
   17.20 +
   17.21 +To resume execution of this domain, use the \path{xm restore} command:
   17.22 +\begin{verbatim}
   17.23 +# xm restore ttylinux.xen
   17.24 +\end{verbatim}
   17.25 +
   17.26 +This will restore the state of the domain and restart it. The domain
   17.27 +will carry on as before and the console may be reconnected using the
   17.28 +\path{xm console} command, as above.
   17.29 +
   17.30 +\section{Live Migration}
   17.31 +
   17.32 +Live migration is used to transfer a domain between physical hosts
   17.33 +whilst that domain continues to perform its usual activities --- from
   17.34 +the user's perspective, the migration should be imperceptible.
   17.35 +
   17.36 +To perform a live migration, both hosts must be running Xen / \xend\ and
   17.37 +the destination host must have sufficient resources (e.g.\ memory
   17.38 +capacity) to accommodate the domain after the move. Furthermore we
   17.39 +currently require both source and destination machines to be on the same
   17.40 +L2 subnet.
   17.41 +
   17.42 +Currently, there is no support for providing automatic remote access to
   17.43 +filesystems stored on local disk when a domain is migrated.
   17.44 +Administrators should choose an appropriate storage solution (i.e.\ SAN,
   17.45 +NAS, etc.) to ensure that domain filesystems are also available on their
   17.46 +destination node. GNBD is a good method for exporting a volume from one
   17.47 +machine to another. iSCSI can do a similar job, but is more complex to
   17.48 +set up.
   17.49 +
   17.50 +When a domain migrates, it's MAC and IP address move with it, thus it is
   17.51 +only possible to migrate VMs within the same layer-2 network and IP
   17.52 +subnet. If the destination node is on a different subnet, the
   17.53 +administrator would need to manually configure a suitable etherip or IP
   17.54 +tunnel in the domain~0 of the remote node.
   17.55 +
   17.56 +A domain may be migrated using the \path{xm migrate} command. To live
   17.57 +migrate a domain to another machine, we would use the command:
   17.58 +
   17.59 +\begin{verbatim}
   17.60 +# xm migrate --live mydomain destination.ournetwork.com
   17.61 +\end{verbatim}
   17.62 +
   17.63 +Without the \path{--live} flag, \xend\ simply stops the domain and
   17.64 +copies the memory image over to the new node and restarts it. Since
   17.65 +domains can have large allocations this can be quite time consuming,
   17.66 +even on a Gigabit network. With the \path{--live} flag \xend\ attempts
   17.67 +to keep the domain running while the migration is in progress, resulting
   17.68 +in typical `downtimes' of just 60--300ms.
   17.69 +
   17.70 +For now it will be necessary to reconnect to the domain's console on the
   17.71 +new machine using the \path{xm console} command. If a migrated domain
   17.72 +has any open network connections then they will be preserved, so SSH
   17.73 +connections do not have this limitation.
    18.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    18.2 +++ b/docs/src/user/network_management.tex	Fri Dec 02 14:29:26 2005 -0700
    18.3 @@ -0,0 +1,3 @@
    18.4 +\chapter{Network Management}
    18.5 +
    18.6 +Placeholder.
    19.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    19.2 +++ b/docs/src/user/scheduler_management.tex	Fri Dec 02 14:29:26 2005 -0700
    19.3 @@ -0,0 +1,3 @@
    19.4 +\chapter{Scheduler Management}
    19.5 +
    19.6 +Placeholder.
    20.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    20.2 +++ b/docs/src/user/xenstat.tex	Fri Dec 02 14:29:26 2005 -0700
    20.3 @@ -0,0 +1,3 @@
    20.4 +\chapter{xenstat}
    20.5 +
    20.6 +Placeholder.
    21.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    21.2 +++ b/docs/src/user/xentrace.tex	Fri Dec 02 14:29:26 2005 -0700
    21.3 @@ -0,0 +1,3 @@
    21.4 +\chapter{xentrace}
    21.5 +
    21.6 +Placeholder.