ia64/xen-unstable

changeset 8231:8098cc1daac4

Merge docs
author rread@ubuntu.eng.hq.xensource.com
date Sat Dec 03 17:52:38 2005 -0700 (2005-12-03)
parents 757218700a40 bc7567741a4c
children 99b9046a8df2
files
line diff
     1.1 --- a/docs/src/user.tex	Sun Dec 04 01:34:25 2005 +0100
     1.2 +++ b/docs/src/user.tex	Sat Dec 03 17:52:38 2005 -0700
     1.3 @@ -1,3 +1,4 @@
     1.4 +\batchmode
     1.5  \documentclass[11pt,twoside,final,openright]{report}
     1.6  \usepackage{a4,graphicx,html,parskip,setspace,times,xspace}
     1.7  \setstretch{1.15}
     1.8 @@ -29,10 +30,10 @@
     1.9  \end{center}
    1.10  
    1.11  {\bf DISCLAIMER: This documentation is currently under active
    1.12 -  development and as such there may be mistakes and omissions ---
    1.13 -  watch out for these and please report any you find to the
    1.14 -  developers' mailing list.  Contributions of material, suggestions
    1.15 -  and corrections are welcome.}
    1.16 +  development and as such there may be mistakes and omissions --- watch
    1.17 +  out for these and please report any you find to the developers'
    1.18 +  mailing list. Contributions of material, suggestions and corrections
    1.19 +  are welcome.}
    1.20  
    1.21  \vfill
    1.22  \cleardoublepage
    1.23 @@ -60,103 +61,122 @@
    1.24  \setstretch{1.1}
    1.25  
    1.26  
    1.27 -\part{Introduction and Tutorial}
    1.28 -
    1.29  %% Chapter Introduction moved to introduction.tex
    1.30  \include{src/user/introduction}
    1.31  
    1.32 -%% Chapter Installation moved to installation.tex
    1.33 +
    1.34 +\part{Installation}
    1.35 +
    1.36 +%% Chapter Basic Installation
    1.37  \include{src/user/installation}
    1.38  
    1.39 -%% Chapter Starting Additional Domains moved to start_addl_dom.tex
    1.40 -\include{src/user/start_addl_dom}
    1.41 +%% Chapter Installing Xen on Debian
    1.42 +\include{src/user/debian}
    1.43 +
    1.44 +%% Chapter Installing Xen on Fedora Core
    1.45 +\include{src/user/fedora}
    1.46 +
    1.47 +%% Chapter Installing Xen on Gentoo Linux
    1.48 +\include{src/user/gentoo}
    1.49 +
    1.50 +%% Chapter Installing Xen on SuSE or SuSE SLES
    1.51 +\include{src/user/suse}
    1.52 +
    1.53 +%% Chapter Installing Xen on Red Hat Enterprise Linux (RHEL)
    1.54 +\include{src/user/rhel}
    1.55  
    1.56 -%% Chapter Domain Management Tools moved to domain_mgmt.tex
    1.57 +% Chapter dom0 Installation
    1.58 +\include{src/user/dom0_installation}
    1.59 +
    1.60 +% Chapter domU Installation
    1.61 +\include{src/user/domU_installation}
    1.62 +
    1.63 +% Building Xen
    1.64 +\include{src/user/building_xen}
    1.65 +
    1.66 +% Booting Xen
    1.67 +\include{src/user/booting_xen}
    1.68 +
    1.69 +
    1.70 +\part{Configuration and Management}
    1.71 +
    1.72 +%% Chapter Domain Management Tools and Daemons
    1.73  \include{src/user/domain_mgmt}
    1.74  
    1.75 -%% Chapter Domain Filesystem Storage moved to domain_filesystem.tex
    1.76 +%% Chapter Starting Additional Domains
    1.77 +\include{src/user/start_addl_dom}
    1.78 +
    1.79 +%% Chapter Domain Configuration
    1.80 +\include{src/user/domain_configuration}
    1.81 +
    1.82 +% Chapter Console Management
    1.83 +\include{src/user/console_management}
    1.84 +
    1.85 +% Chapter Network Management
    1.86 +\include{src/user/network_management}
    1.87 +
    1.88 +% Chapter Storage and FileSytem Management
    1.89  \include{src/user/domain_filesystem}
    1.90  
    1.91 -
    1.92 +% Chapter Memory Management
    1.93 +\include{src/user/memory_management}
    1.94  
    1.95 -\part{User Reference Documentation}
    1.96 +% Chapter CPU Management
    1.97 +\include{src/user/cpu_management}
    1.98  
    1.99 -%% Chapter Control Software moved to control_software.tex
   1.100 -\include{src/user/control_software}
   1.101 +% Chapter Scheduler Management
   1.102 +\include{src/user/scheduler_management}
   1.103  
   1.104 -%% Chapter Domain Configuration moved to domain_configuration.tex
   1.105 -\include{src/user/domain_configuration}
   1.106 +% Chapter Migrating Domains
   1.107 +\include{src/user/migrating_domains}
   1.108  
   1.109  %% Chapter Securing Xen
   1.110  \include{src/user/securing_xen}
   1.111  
   1.112 -%% Chapter Build, Boot and Debug Options moved to build.tex
   1.113 -\include{src/user/build}
   1.114 +
   1.115 +\part{Monitoring and Troubleshooting}
   1.116 +
   1.117 +%% Chapter Monitoring Xen
   1.118 +\include{src/user/monitoring_xen}
   1.119  
   1.120 +% Chapter xenstat
   1.121 +\include{src/user/xenstat}
   1.122  
   1.123 -\chapter{Further Support}
   1.124 +% Chapter Log Files
   1.125 +\include{src/user/logfiles}
   1.126  
   1.127 -If you have questions that are not answered by this manual, the
   1.128 -sources of information listed below may be of interest to you.  Note
   1.129 -that bug reports, suggestions and contributions related to the
   1.130 -software (or the documentation) should be sent to the Xen developers'
   1.131 -mailing list (address below).
   1.132 +%% Chapter Debugging
   1.133 +\include{src/user/debugging}
   1.134  
   1.135 +% Chapter xentrace
   1.136 +\include{src/user/xentrace}
   1.137  
   1.138 -\section{Other Documentation}
   1.139 +%% Chapter Known Problems
   1.140 +\include{src/user/known_problems}
   1.141  
   1.142 -For developers interested in porting operating systems to Xen, the
   1.143 -\emph{Xen Interface Manual} is distributed in the \path{docs/}
   1.144 -directory of the Xen source distribution.
   1.145 -
   1.146 -% Various HOWTOs are available in \path{docs/HOWTOS} but this content
   1.147 -% is being integrated into this manual.
   1.148 +%% Chapter Testing Xen
   1.149 +\include{src/user/testing}
   1.150  
   1.151  
   1.152 -\section{Online References}
   1.153 +\part{Reference Documentation}
   1.154 +
   1.155 +%% Chapter Control Software
   1.156 +\include{src/user/control_software}
   1.157  
   1.158 -The official Xen web site is found at:
   1.159 -\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/}
   1.160 -\end{quote}
   1.161 +%% Chapter Build and Boot Options
   1.162 +\include{src/user/options}
   1.163  
   1.164 -This contains links to the latest versions of all online
   1.165 -documentation, including the latest version of the FAQ.
   1.166 +%% Chapter Further Support
   1.167 +\include{src/user/further_support}
   1.168  
   1.169  
   1.170 -\section{Mailing Lists}
   1.171 -
   1.172 -There are currently four official Xen mailing lists:
   1.173 -
   1.174 -\begin{description}
   1.175 -\item[xen-devel@lists.xensource.com] Used for development
   1.176 -  discussions and bug reports.  Subscribe at: \\
   1.177 -  {\small {\tt http://lists.xensource.com/xen-devel}}
   1.178 -\item[xen-users@lists.xensource.com] Used for installation and usage
   1.179 -  discussions and requests for help.  Subscribe at: \\
   1.180 -  {\small {\tt http://lists.xensource.com/xen-users}}
   1.181 -\item[xen-announce@lists.xensource.com] Used for announcements only.
   1.182 -  Subscribe at: \\
   1.183 -  {\small {\tt http://lists.xensource.com/xen-announce}}
   1.184 -\item[xen-changelog@lists.xensource.com] Changelog feed
   1.185 -  from the unstable and 2.0 trees - developer oriented.  Subscribe at: \\
   1.186 -  {\small {\tt http://lists.xensource.com/xen-changelog}}
   1.187 -\end{description}
   1.188 -
   1.189 -
   1.190 +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   1.191  
   1.192  \appendix
   1.193  
   1.194 -%% Chapter Installing Xen / XenLinux on Debian moved to debian.tex
   1.195 -\include{src/user/debian}
   1.196 -
   1.197 -%% Chapter Installing Xen on Red Hat moved to redhat.tex
   1.198 -\include{src/user/redhat}
   1.199 -
   1.200  %% Chapter Glossary of Terms moved to glossary.tex
   1.201  \include{src/user/glossary}
   1.202  
   1.203 -
   1.204 -
   1.205  \end{document}
   1.206  
   1.207  
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/docs/src/user/booting_xen.tex	Sat Dec 03 17:52:38 2005 -0700
     2.3 @@ -0,0 +1,170 @@
     2.4 +\chapter{Booting Xen}
     2.5 +
     2.6 +Once Xen is installed and configured as described in the preceding chapter, it
     2.7 +should now be possible to restart the system and use Xen.
     2.8 +
     2.9 +Booting the system into Xen will bring you up into the privileged management d
    2.10 +omain, Domain0. At that point you are ready to create guest domains and "boot" t
    2.11 +hem using the xm create command.
    2.12 +
    2.13 +\section{Booting Domain0}
    2.14 +
    2.15 +After installation and configuration is complete, reboot the system and and ch
    2.16 +oose the new Xen option when the Grub screen appears.
    2.17 +
    2.18 +What follows should look much like a conventional Linux boot.  The
    2.19 +first portion of the output comes from Xen itself, supplying low level
    2.20 +information about itself and the underlying hardware.  The last
    2.21 +portion of the output comes from XenLinux.
    2.22 +
    2.23 +You may see some errors during the XenLinux boot.  These are not
    2.24 +necessarily anything to worry about --- they may result from kernel
    2.25 +configuration differences between your XenLinux kernel and the one you
    2.26 +usually use.
    2.27 +
    2.28 +%% KMSelf Wed Nov 30 18:09:37 PST 2005:  We should specify what these are.
    2.29 +
    2.30 +When the boot completes, you should be able to log into your system as
    2.31 +usual.  If you are unable to log in, you should still be able to
    2.32 +reboot with your normal Linux kernel by selecting it at the GRUB prompt.
    2.33 +
    2.34 +The first step in creating a new domain is to prepare a root
    2.35 +filesystem for it to boot.  Typically, this might be stored in a normal
    2.36 +partition, an LVM or other volume manager partition, a disk file or on
    2.37 +an NFS server.  A simple way to do this is simply to boot from your
    2.38 +standard OS install CD and install the distribution into another
    2.39 +partition on your hard drive.
    2.40 +
    2.41 +To start the \xend\ control daemon, type
    2.42 +\begin{quote}
    2.43 +  \verb!# xend start!
    2.44 +\end{quote}
    2.45 +
    2.46 +If you wish the daemon to start automatically, see the instructions in
    2.47 +Section~\ref{s:xend}. Once the daemon is running, you can use the
    2.48 +\path{xm} tool to monitor and maintain the domains running on your
    2.49 +system. This chapter provides only a brief tutorial. We provide full
    2.50 +details of the \path{xm} tool in the next chapter.
    2.51 +
    2.52 +% \section{From the web interface}
    2.53 +%
    2.54 +% Boot the Xen machine and start Xensv (see Chapter~\ref{cha:xensv}
    2.55 +% for more details) using the command: \\
    2.56 +% \verb_# xensv start_ \\
    2.57 +% This will also start Xend (see Chapter~\ref{cha:xend} for more
    2.58 +% information).
    2.59 +%
    2.60 +% The domain management interface will then be available at {\tt
    2.61 +%   http://your\_machine:8080/}.  This provides a user friendly wizard
    2.62 +% for starting domains and functions for managing running domains.
    2.63 +%
    2.64 +% \section{From the command line}
    2.65 +\section{Booting Guest Domains}
    2.66 +
    2.67 +\subsection{Creating a Domain Configuration File}
    2.68 +
    2.69 +Before you can start an additional domain, you must create a
    2.70 +configuration file. We provide two example files which you can use as
    2.71 +a starting point:
    2.72 +\begin{itemize}
    2.73 +\item \path{/etc/xen/xmexample1} is a simple template configuration
    2.74 +  file for describing a single VM\@.
    2.75 +\item \path{/etc/xen/xmexample2} file is a template description that
    2.76 +  is intended to be reused for multiple virtual machines.  Setting the
    2.77 +  value of the \path{vmid} variable on the \path{xm} command line
    2.78 +  fills in parts of this template.
    2.79 +\end{itemize}
    2.80 +
    2.81 +Copy one of these files and edit it as appropriate.  Typical values
    2.82 +you may wish to edit include:
    2.83 +
    2.84 +\begin{quote}
    2.85 +\begin{description}
    2.86 +\item[kernel] Set this to the path of the kernel you compiled for use
    2.87 +  with Xen (e.g.\ \path{kernel = ``/boot/vmlinuz-2.6-xenU''})
    2.88 +\item[memory] Set this to the size of the domain's memory in megabytes
    2.89 +  (e.g.\ \path{memory = 64})
    2.90 +\item[disk] Set the first entry in this list to calculate the offset
    2.91 +  of the domain's root partition, based on the domain ID\@.  Set the
    2.92 +  second to the location of \path{/usr} if you are sharing it between
    2.93 +  domains (e.g.\ \path{disk = ['phy:your\_hard\_drive\%d,sda1,w' \%
    2.94 +    (base\_partition\_number + vmid),
    2.95 +    'phy:your\_usr\_partition,sda6,r' ]}
    2.96 +\item[dhcp] Uncomment the dhcp variable, so that the domain will
    2.97 +  receive its IP address from a DHCP server (e.g.\ \path{dhcp=``dhcp''})
    2.98 +\end{description}
    2.99 +\end{quote}
   2.100 +
   2.101 +You may also want to edit the {\bf vif} variable in order to choose
   2.102 +the MAC address of the virtual ethernet interface yourself.  For
   2.103 +example:
   2.104 +
   2.105 +\begin{quote}
   2.106 +\verb_vif = ['mac=00:16:3E:F6:BB:B3']_
   2.107 +\end{quote}
   2.108 +If you do not set this variable, \xend\ will automatically generate a
   2.109 +random MAC address from the range 00:16:3E:xx:xx:xx, assigned by IEEE to
   2.110 +XenSource as an OUI (organizationally unique identifier).  XenSource
   2.111 +Inc. gives permission for anyone to use addresses randomly allocated
   2.112 +from this range for use by their Xen domains.
   2.113 +
   2.114 +For a list of IEEE OUI assignments, see \newline
   2.115 +{\tt http://standards.ieee.org/regauth/oui/oui.txt}.
   2.116 +
   2.117 +
   2.118 +\subsection{Booting the Guest Domain}
   2.119 +
   2.120 +The \path{xm} tool provides a variety of commands for managing
   2.121 +domains.  Use the \path{create} command to start new domains. Assuming
   2.122 +you've created a configuration file \path{myvmconf} based around
   2.123 +\path{/etc/xen/xmexample2}, to start a domain with virtual machine
   2.124 +ID~1 you should type:
   2.125 +
   2.126 +\begin{quote}
   2.127 +\begin{verbatim}
   2.128 +# xm create -c myvmconf vmid=1
   2.129 +\end{verbatim}
   2.130 +\end{quote}
   2.131 +
   2.132 +The \path{-c} switch causes \path{xm} to turn into the domain's
   2.133 +console after creation.  The \path{vmid=1} sets the \path{vmid}
   2.134 +variable used in the \path{myvmconf} file.
   2.135 +
   2.136 +You should see the console boot messages from the new domain appearing
   2.137 +in the terminal in which you typed the command, culminating in a login
   2.138 +prompt.
   2.139 +
   2.140 +\subsection{Example: ttylinux}
   2.141 +
   2.142 +Ttylinux is a very small Linux distribution, designed to require very
   2.143 +few resources.  We will use it as a concrete example of how to start a
   2.144 +Xen domain.  Most users will probably want to install a full-featured
   2.145 +distribution once they have mastered the basics\footnote{ttylinux is
   2.146 +  the distribution's home page: {\tt
   2.147 +    http://www.minimalinux.org/ttylinux/}}.
   2.148 +
   2.149 +\begin{enumerate}
   2.150 +\item Download and extract the ttylinux disk image from the Files
   2.151 +  section of the project's SourceForge site (see
   2.152 +  \path{http://sf.net/projects/xen/}).
   2.153 +\item Create a configuration file like the following:
   2.154 +  \begin{quote}
   2.155 +\begin{verbatim}
   2.156 +kernel = "/boot/vmlinuz-2.6-xenU"
   2.157 +memory = 64
   2.158 +name = "ttylinux"
   2.159 +nics = 1
   2.160 +ip = "1.2.3.4"
   2.161 +disk = ['file:/path/to/ttylinux/rootfs,sda1,w']
   2.162 +root = "/dev/sda1 ro"
   2.163 +\end{verbatim}    
   2.164 +  \end{quote}
   2.165 +\item Now start the domain and connect to its console:
   2.166 +  \begin{quote}
   2.167 +\begin{verbatim}
   2.168 +xm create configfile -c
   2.169 +\end{verbatim}
   2.170 +  \end{quote}
   2.171 +\item Login as root, password root.
   2.172 +\end{enumerate}
   2.173 +
     3.1 --- a/docs/src/user/build.tex	Sun Dec 04 01:34:25 2005 +0100
     3.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.3 @@ -1,170 +0,0 @@
     3.4 -\chapter{Build, Boot and Debug Options} 
     3.5 -
     3.6 -This chapter describes the build- and boot-time options which may be
     3.7 -used to tailor your Xen system.
     3.8 -
     3.9 -
    3.10 -\section{Xen Build Options}
    3.11 -
    3.12 -Xen provides a number of build-time options which should be set as
    3.13 -environment variables or passed on make's command-line.
    3.14 -
    3.15 -\begin{description}
    3.16 -\item[verbose=y] Enable debugging messages when Xen detects an
    3.17 -  unexpected condition.  Also enables console output from all domains.
    3.18 -\item[debug=y] Enable debug assertions.  Implies {\bf verbose=y}.
    3.19 -  (Primarily useful for tracing bugs in Xen).
    3.20 -\item[debugger=y] Enable the in-Xen debugger. This can be used to
    3.21 -  debug Xen, guest OSes, and applications.
    3.22 -\item[perfc=y] Enable performance counters for significant events
    3.23 -  within Xen. The counts can be reset or displayed on Xen's console
    3.24 -  via console control keys.
    3.25 -\item[trace=y] Enable per-cpu trace buffers which log a range of
    3.26 -  events within Xen for collection by control software.
    3.27 -\end{description}
    3.28 -
    3.29 -
    3.30 -\section{Xen Boot Options}
    3.31 -\label{s:xboot}
    3.32 -
    3.33 -These options are used to configure Xen's behaviour at runtime.  They
    3.34 -should be appended to Xen's command line, either manually or by
    3.35 -editing \path{grub.conf}.
    3.36 -
    3.37 -\begin{description}
    3.38 -\item [ noreboot ] Don't reboot the machine automatically on errors.
    3.39 -  This is useful to catch debug output if you aren't catching console
    3.40 -  messages via the serial line.
    3.41 -\item [ nosmp ] Disable SMP support.  This option is implied by
    3.42 -  `ignorebiostables'.
    3.43 -\item [ watchdog ] Enable NMI watchdog which can report certain
    3.44 -  failures.
    3.45 -\item [ noirqbalance ] Disable software IRQ balancing and affinity.
    3.46 -  This can be used on systems such as Dell 1850/2850 that have
    3.47 -  workarounds in hardware for IRQ-routing issues.
    3.48 -\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify
    3.49 -  a list of pages not to be allocated for use because they contain bad
    3.50 -  bytes. For example, if your memory tester says that byte 0x12345678
    3.51 -  is bad, you would place `badpage=0x12345' on Xen's command line.
    3.52 -\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
    3.53 -  com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\
    3.54 -  Xen supports up to two 16550-compatible serial ports.  For example:
    3.55 -  `com1=9600, 8n1, 0x408, 5' maps COM1 to a 9600-baud port, 8 data
    3.56 -  bits, no parity, 1 stop bit, I/O port base 0x408, IRQ 5.  If some
    3.57 -  configuration options are standard (e.g., I/O base and IRQ), then
    3.58 -  only a prefix of the full configuration string need be specified. If
    3.59 -  the baud rate is pre-configured (e.g., by the bootloader) then you
    3.60 -  can specify `auto' in place of a numeric baud rate.
    3.61 -\item [ console=$<$specifier list$>$ ] Specify the destination for Xen
    3.62 -  console I/O.  This is a comma-separated list of, for example:
    3.63 -  \begin{description}
    3.64 -  \item[ vga ] Use VGA console and allow keyboard input.
    3.65 -  \item[ com1 ] Use serial port com1.
    3.66 -  \item[ com2H ] Use serial port com2. Transmitted chars will have the
    3.67 -    MSB set. Received chars must have MSB set.
    3.68 -  \item[ com2L] Use serial port com2. Transmitted chars will have the
    3.69 -    MSB cleared. Received chars must have MSB cleared.
    3.70 -  \end{description}
    3.71 -  The latter two examples allow a single port to be shared by two
    3.72 -  subsystems (e.g.\ console and debugger). Sharing is controlled by
    3.73 -  MSB of each transmitted/received character.  [NB. Default for this
    3.74 -  option is `com1,vga']
    3.75 -\item [ sync\_console ] Force synchronous console output. This is
    3.76 -  useful if you system fails unexpectedly before it has sent all
    3.77 -  available output to the console. In most cases Xen will
    3.78 -  automatically enter synchronous mode when an exceptional event
    3.79 -  occurs, but this option provides a manual fallback.
    3.80 -\item [ conswitch=$<$switch-char$><$auto-switch-char$>$ ] Specify how
    3.81 -  to switch serial-console input between Xen and DOM0. The required
    3.82 -  sequence is CTRL-$<$switch-char$>$ pressed three times. Specifying
    3.83 -  the backtick character disables switching.  The
    3.84 -  $<$auto-switch-char$>$ specifies whether Xen should auto-switch
    3.85 -  input to DOM0 when it boots --- if it is `x' then auto-switching is
    3.86 -  disabled.  Any other value, or omitting the character, enables
    3.87 -  auto-switching.  [NB. Default switch-char is `a'.]
    3.88 -\item [ nmi=xxx ]
    3.89 -  Specify what to do with an NMI parity or I/O error. \\
    3.90 -  `nmi=fatal':  Xen prints a diagnostic and then hangs. \\
    3.91 -  `nmi=dom0':   Inform DOM0 of the NMI. \\
    3.92 -  `nmi=ignore': Ignore the NMI.
    3.93 -\item [ mem=xxx ] Set the physical RAM address limit. Any RAM
    3.94 -  appearing beyond this physical address in the memory map will be
    3.95 -  ignored. This parameter may be specified with a B, K, M or G suffix,
    3.96 -  representing bytes, kilobytes, megabytes and gigabytes respectively.
    3.97 -  The default unit, if no suffix is specified, is kilobytes.
    3.98 -\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to
    3.99 -  domain0. In Xen 3.x the parameter may be specified with a B, K, M or
   3.100 -  G suffix, representing bytes, kilobytes, megabytes and gigabytes
   3.101 -  respectively; if no suffix is specified, the parameter defaults to
   3.102 -  kilobytes. In previous versions of Xen, suffixes were not supported
   3.103 -  and the value is always interpreted as kilobytes.
   3.104 -\item [ tbuf\_size=xxx ] Set the size of the per-cpu trace buffers, in
   3.105 -  pages (default 1).  Note that the trace buffers are only enabled in
   3.106 -  debug builds.  Most users can ignore this feature completely.
   3.107 -\item [ sched=xxx ] Select the CPU scheduler Xen should use.  The
   3.108 -  current possibilities are `bvt' (default), `atropos' and `rrobin'.
   3.109 -  For more information see Section~\ref{s:sched}.
   3.110 -\item [ apic\_verbosity=debug,verbose ] Print more detailed
   3.111 -  information about local APIC and IOAPIC configuration.
   3.112 -\item [ lapic ] Force use of local APIC even when left disabled by
   3.113 -  uniprocessor BIOS.
   3.114 -\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if
   3.115 -  enabled by the BIOS.
   3.116 -\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform.
   3.117 -  This can usually be probed automatically.
   3.118 -\end{description}
   3.119 -
   3.120 -In addition, the following options may be specified on the Xen command
   3.121 -line. Since domain 0 shares responsibility for booting the platform,
   3.122 -Xen will automatically propagate these options to its command line.
   3.123 -These options are taken from Linux's command-line syntax with
   3.124 -unchanged semantics.
   3.125 -
   3.126 -\begin{description}
   3.127 -\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and
   3.128 -  domain 0) parses the BIOS ACPI tables.
   3.129 -\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to
   3.130 -  ignore timer-interrupt override instructions specified by the BIOS
   3.131 -  ACPI tables.
   3.132 -\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs
   3.133 -  that are present in the system, and instead continue to use the
   3.134 -  legacy PIC.
   3.135 -\end{description} 
   3.136 -
   3.137 -
   3.138 -\section{XenLinux Boot Options}
   3.139 -
   3.140 -In addition to the standard Linux kernel boot options, we support:
   3.141 -\begin{description}
   3.142 -\item[ xencons=xxx ] Specify the device node to which the Xen virtual
   3.143 -  console driver is attached. The following options are supported:
   3.144 -  \begin{center}
   3.145 -    \begin{tabular}{l}
   3.146 -      `xencons=off': disable virtual console \\
   3.147 -      `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
   3.148 -      `xencons=ttyS': attach console to /dev/ttyS0
   3.149 -    \end{tabular}
   3.150 -\end{center}
   3.151 -The default is ttyS for dom0 and tty for all other domains.
   3.152 -\end{description}
   3.153 -
   3.154 -
   3.155 -\section{Debugging}
   3.156 -\label{s:keys}
   3.157 -
   3.158 -Xen has a set of debugging features that can be useful to try and
   3.159 -figure out what's going on. Hit `h' on the serial line (if you
   3.160 -specified a baud rate on the Xen command line) or ScrollLock-h on the
   3.161 -keyboard to get a list of supported commands.
   3.162 -
   3.163 -If you have a crash you'll likely get a crash dump containing an EIP
   3.164 -(PC) which, along with an \path{objdump -d image}, can be useful in
   3.165 -figuring out what's happened.  Debug a Xenlinux image just as you
   3.166 -would any other Linux kernel.
   3.167 -
   3.168 -%% We supply a handy debug terminal program which you can find in
   3.169 -%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should
   3.170 -%% be built and executed on another machine that is connected via a
   3.171 -%% null modem cable. Documentation is included.  Alternatively, if the
   3.172 -%% Xen machine is connected to a serial-port server then we supply a
   3.173 -%% dumb TCP terminal client, {\tt xencons}.
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/docs/src/user/building_xen.tex	Sat Dec 03 17:52:38 2005 -0700
     4.3 @@ -0,0 +1,3 @@
     4.4 +\chapter{Building Xen}
     4.5 +
     4.6 +Placeholder.
     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/docs/src/user/console_management.tex	Sat Dec 03 17:52:38 2005 -0700
     5.3 @@ -0,0 +1,3 @@
     5.4 +\chapter{Console Management}
     5.5 +
     5.6 +Placeholder.
     6.1 --- a/docs/src/user/control_software.tex	Sun Dec 04 01:34:25 2005 +0100
     6.2 +++ b/docs/src/user/control_software.tex	Sat Dec 03 17:52:38 2005 -0700
     6.3 @@ -1,101 +1,10 @@
     6.4  \chapter{Control Software} 
     6.5  
     6.6 -The Xen control software includes the \xend\ node control daemon
     6.7 -(which must be running), the xm command line tools, and the prototype
     6.8 -xensv web interface.
     6.9 -
    6.10 -\section{\Xend\ (node control daemon)}
    6.11 -\label{s:xend}
    6.12 -
    6.13 -The Xen Daemon (\Xend) performs system management functions related to
    6.14 -virtual machines.  It forms a central point of control for a machine
    6.15 -and can be controlled using an HTTP-based protocol.  \Xend\ must be
    6.16 -running in order to start and manage virtual machines.
    6.17 -
    6.18 -\Xend\ must be run as root because it needs access to privileged
    6.19 -system management functions.  A small set of commands may be issued on
    6.20 -the \xend\ command line:
    6.21 -
    6.22 -\begin{tabular}{ll}
    6.23 -  \verb!# xend start! & start \xend, if not already running \\
    6.24 -  \verb!# xend stop!  & stop \xend\ if already running       \\
    6.25 -  \verb!# xend restart! & restart \xend\ if running, otherwise start it \\
    6.26 -  % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\
    6.27 -  \verb!# xend status! & indicates \xend\ status by its return code
    6.28 -\end{tabular}
    6.29 -
    6.30 -A SysV init script called {\tt xend} is provided to start \xend\ at
    6.31 -boot time.  {\tt make install} installs this script in
    6.32 -\path{/etc/init.d}.  To enable it, you have to make symbolic links in
    6.33 -the appropriate runlevel directories or use the {\tt chkconfig} tool,
    6.34 -where available.
    6.35 -
    6.36 -Once \xend\ is running, more sophisticated administration can be done
    6.37 -using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv
    6.38 -web interface (see Section~\ref{s:xensv}).
    6.39 -
    6.40 -As \xend\ runs, events will be logged to \path{/var/log/xend.log} and,
    6.41 -if the migration assistant daemon (\path{xfrd}) has been started,
    6.42 -\path{/var/log/xfrd.log}. These may be of use for troubleshooting
    6.43 -problems.
    6.44 -
    6.45 -\section{Xm (command line interface)}
    6.46 -\label{s:xm}
    6.47 -
    6.48 -The xm tool is the primary tool for managing Xen from the console.
    6.49 -The general format of an xm command line is:
    6.50 -
    6.51 -\begin{verbatim}
    6.52 -# xm command [switches] [arguments] [variables]
    6.53 -\end{verbatim}
    6.54 -
    6.55 -The available \emph{switches} and \emph{arguments} are dependent on
    6.56 -the \emph{command} chosen.  The \emph{variables} may be set using
    6.57 -declarations of the form {\tt variable=value} and command line
    6.58 -declarations override any of the values in the configuration file
    6.59 -being used, including the standard variables described above and any
    6.60 -custom variables (for instance, the \path{xmdefconfig} file uses a
    6.61 -{\tt vmid} variable).
    6.62 -
    6.63 -The available commands are as follows:
    6.64 -
    6.65 -\begin{description}
    6.66 -\item[mem-set] Request a domain to adjust its memory footprint.
    6.67 -\item[create] Create a new domain.
    6.68 -\item[destroy] Kill a domain immediately.
    6.69 -\item[list] List running domains.
    6.70 -\item[shutdown] Ask a domain to shutdown.
    6.71 -\item[dmesg] Fetch the Xen (not Linux!) boot output.
    6.72 -\item[consoles] Lists the available consoles.
    6.73 -\item[console] Connect to the console for a domain.
    6.74 -\item[help] Get help on xm commands.
    6.75 -\item[save] Suspend a domain to disk.
    6.76 -\item[restore] Restore a domain from disk.
    6.77 -\item[pause] Pause a domain's execution.
    6.78 -\item[unpause] Un-pause a domain.
    6.79 -\item[pincpu] Pin a domain to a CPU.
    6.80 -\item[bvt] Set BVT scheduler parameters for a domain.
    6.81 -\item[bvt\_ctxallow] Set the BVT context switching allowance for the
    6.82 -  system.
    6.83 -\item[atropos] Set the atropos parameters for a domain.
    6.84 -\item[rrobin] Set the round robin time slice for the system.
    6.85 -\item[info] Get information about the Xen host.
    6.86 -\item[call] Call a \xend\ HTTP API function directly.
    6.87 -\end{description}
    6.88 -
    6.89 -For a detailed overview of switches, arguments and variables to each
    6.90 -command try
    6.91 -\begin{quote}
    6.92 -\begin{verbatim}
    6.93 -# xm help command
    6.94 -\end{verbatim}
    6.95 -\end{quote}
    6.96 -
    6.97  \section{Xensv (web control interface)}
    6.98  \label{s:xensv}
    6.99  
   6.100  Xensv is the experimental web control interface for managing a Xen
   6.101 -machine.  It can be used to perform some (but not yet all) of the
   6.102 +machine. It can be used to perform some (but not yet all) of the
   6.103  management tasks that can be done using the xm tool.
   6.104  
   6.105  It can be started using:
   6.106 @@ -107,7 +16,7 @@ and stopped using:
   6.107    \verb_# xensv stop_
   6.108  \end{quote}
   6.109  
   6.110 -By default, Xensv will serve out the web interface on port 8080.  This
   6.111 +By default, Xensv will serve out the web interface on port 8080. This
   6.112  can be changed by editing
   6.113  \path{/usr/lib/python2.3/site-packages/xen/sv/params.py}.
   6.114  
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/docs/src/user/cpu_management.tex	Sat Dec 03 17:52:38 2005 -0700
     7.3 @@ -0,0 +1,44 @@
     7.4 +\chapter{CPU Management}
     7.5 +
     7.6 +Placeholder.
     7.7 +%% KMS Something sage about CPU / processor management.
     7.8 +
     7.9 +Xen allows a domain's virtual CPU(s) to be associated with one or more
    7.10 +host CPUs.  This can be used to allocate real resources among one or
    7.11 +more guests, or to make optimal use of processor resources when
    7.12 +utilizing dual-core, hyperthreading, or other advanced CPU technologies.
    7.13 +
    7.14 +Xen enumerates physical CPUs in a `depth first' fashion.  For a system
    7.15 +with both hyperthreading and multiple cores, this would be all the
    7.16 +hyperthreads on a given core, then all the cores on a given socket,
    7.17 +and then all sockets.  I.e.  if you had a two socket, dual core,
    7.18 +hyperthreaded Xeon the CPU order would be:
    7.19 +
    7.20 +
    7.21 +\begin{center}
    7.22 +\begin{tabular}{|l|l|l|l|l|l|l|r|}
    7.23 +\multicolumn{4}{c|}{socket0}     &  \multicolumn{4}{c|}{socket1} \\ \hline
    7.24 +\multicolumn{2}{c|}{core0}  &  \multicolumn{2}{c|}{core1}  &
    7.25 +\multicolumn{2}{c|}{core0}  &  \multicolumn{2}{c|}{core1} \\ \hline
    7.26 +ht0 & ht1 & ht0 & ht1 & ht0 & ht1 & ht0 & ht1 \\
    7.27 +\#0 & \#1 & \#2 & \#3 & \#4 & \#5 & \#6 & \#7 \\
    7.28 +\end{tabular}
    7.29 +\end{center}
    7.30 +
    7.31 +
    7.32 +Having multiple vcpus belonging to the same domain mapped to the same
    7.33 +physical CPU is very likely to lead to poor performance. It's better to
    7.34 +use `vcpus-set' to hot-unplug one of the vcpus and ensure the others are
    7.35 +pinned on different CPUs.
    7.36 +
    7.37 +If you are running IO intensive tasks, its typically better to dedicate
    7.38 +either a hyperthread or whole core to running domain 0, and hence pin
    7.39 +other domains so that they can't use CPU 0. If your workload is mostly
    7.40 +compute intensive, you may want to pin vcpus such that all physical CPU
    7.41 +threads are available for guest domains.
    7.42 +
    7.43 +
    7.44 +\section{Setting CPU Pinning}
    7.45 +
    7.46 +FIXME:  To specify a domain's CPU pinning use the XXX command/syntax in
    7.47 +XXX.
     8.1 --- a/docs/src/user/debian.tex	Sun Dec 04 01:34:25 2005 +0100
     8.2 +++ b/docs/src/user/debian.tex	Sat Dec 03 17:52:38 2005 -0700
     8.3 @@ -1,154 +1,173 @@
     8.4 -\chapter{Installing Xen / XenLinux on Debian}
     8.5 +\chapter{Installing Xen/XenLinux on Debian}
     8.6  
     8.7 -The Debian project provides a tool called \path{debootstrap} which
     8.8 -allows a base Debian system to be installed into a filesystem without
     8.9 -requiring the host system to have any Debian-specific software (such
    8.10 -as \path{apt}).
    8.11 +This appendix describes installing Xen 3.0 on Debian Linux.
    8.12 +
    8.13 +Xen can be installed on Debian GNU/Linux using the following methods:
    8.14  
    8.15 -Here's some info how to install Debian 3.1 (Sarge) for an unprivileged
    8.16 -Xen domain:
    8.17 -
    8.18 -\begin{enumerate}
    8.19 -
    8.20 -\item Set up Xen and test that it's working, as described earlier in
    8.21 -  this manual.
    8.22 +\begin{itemize}
    8.23 +\item From a binary tarball
    8.24 +\item From source 
    8.25 +\item From debs
    8.26 +\end{itemize}
    8.27  
    8.28 -\item Create disk images for rootfs and swap. Alternatively, you might
    8.29 -  create dedicated partitions, LVM logical volumes, etc.\ if that
    8.30 -  suits your setup.
    8.31 -\begin{verbatim}
    8.32 -dd if=/dev/zero of=/path/diskimage bs=1024k count=size_in_mbytes
    8.33 -dd if=/dev/zero of=/path/swapimage bs=1024k count=size_in_mbytes
    8.34 -\end{verbatim}
    8.35 +\section{Installing from a binary tarball}
    8.36 +This section describes the process of installing Xen on Debian Sarge using the stable binary release tarball.
    8.37 +
    8.38 +\subsection{Required Packages}
    8.39 +Install these Debian packages:
    8.40  
    8.41 -  If you're going to use this filesystem / disk image only as a
    8.42 -  `template' for other vm disk images, something like 300 MB should be
    8.43 -  enough. (of course it depends what kind of packages you are planning
    8.44 -  to install to the template)
    8.45 +\begin{itemize}
    8.46 +\item bridge-utils
    8.47 +\item libcurl3-dev
    8.48 +\item iproute
    8.49 +\item zlib1g-dev
    8.50 +\item python-dev
    8.51 +\end{itemize}
    8.52  
    8.53 -\item Create the filesystem and initialise the swap image
    8.54  \begin{verbatim}
    8.55 -mkfs.ext3 /path/diskimage
    8.56 -mkswap /path/swapimage
    8.57 +apt-get install bridge-utils   libcurl3-dev iproute  zlib1g-dev python-dev
    8.58  \end{verbatim}
    8.59  
    8.60 -\item Mount the disk image for installation
    8.61 -\begin{verbatim}
    8.62 -mount -o loop /path/diskimage /mnt/disk
    8.63 -\end{verbatim}
    8.64 +
    8.65 +\subsection{Download the binary tarball}
    8.66 +Download the Xen 3.0 binary tarball from the XenSource downloads
    8.67 +page:
    8.68  
    8.69 -\item Install \path{debootstrap}. Make sure you have debootstrap
    8.70 -  installed on the host.  If you are running Debian Sarge (3.1 /
    8.71 -  testing) or unstable you can install it by running \path{apt-get
    8.72 -    install debootstrap}.  Otherwise, it can be downloaded from the
    8.73 -  Debian project website.
    8.74 -
    8.75 -\item Install Debian base to the disk image:
    8.76 +\begin{quote} {\tt http://www.xensource.com/downloads/}
    8.77 +\end{quote}
    8.78 + 
    8.79 +\subsection{Extract and Install}
    8.80  \begin{verbatim}
    8.81 -debootstrap --arch i386 sarge /mnt/disk  \
    8.82 -            http://ftp.<countrycode>.debian.org/debian
    8.83 +#  tar zxvf 
    8.84 +xen-2.0.7-install-x86_32.tgz
    8.85 +# cd xen-2.0.7-install-x86_32.tgz
    8.86 +# ./install.sh
    8.87  \end{verbatim}
    8.88  
    8.89 -  You can use any other Debian http/ftp mirror you want.
    8.90 +If everything goes well, you should something like
    8.91  
    8.92 -\item When debootstrap completes successfully, modify settings:
    8.93 -\begin{verbatim}
    8.94 -chroot /mnt/disk /bin/bash
    8.95 -\end{verbatim}
    8.96 -
    8.97 -Edit the following files using vi or nano and make needed changes:
    8.98  \begin{verbatim}
    8.99 -/etc/hostname
   8.100 -/etc/hosts
   8.101 -/etc/resolv.conf
   8.102 -/etc/network/interfaces
   8.103 -/etc/networks
   8.104 -\end{verbatim}
   8.105 -
   8.106 -Set up access to the services, edit:
   8.107 -\begin{verbatim}
   8.108 -/etc/hosts.deny
   8.109 -/etc/hosts.allow
   8.110 -/etc/inetd.conf
   8.111 +Installing Xen from 
   8.112 +'./install' to '/'...
   8.113 +    All done.
   8.114 +    Checking to see whether prerequisite tools are installed...
   8.115 +    All done.
   8.116  \end{verbatim}
   8.117  
   8.118 -Add Debian mirror to:   
   8.119 -\begin{verbatim}
   8.120 -/etc/apt/sources.list
   8.121 -\end{verbatim}
   8.122  
   8.123 -Create fstab like this:
   8.124 +\subsection{Configure grub}
   8.125 +Make an entry in your grub configuration like below.
   8.126 +
   8.127 +{\small
   8.128  \begin{verbatim}
   8.129 -/dev/sda1       /       ext3    errors=remount-ro       0       1
   8.130 -/dev/sda2       none    swap    sw                      0       0
   8.131 -proc            /proc   proc    defaults                0       0
   8.132 -\end{verbatim}
   8.133 -
   8.134 -Logout
   8.135 -
   8.136 -\item Unmount the disk image
   8.137 -\begin{verbatim}
   8.138 -umount /mnt/disk
   8.139 +title          Xen on Debian
   8.140 +kernel         (hd0,5)/boot/xen.gz dom0_mem=131000
   8.141 +module         (hd0,5)/boot/vmlinuz-2.6-xen0 root=/dex/hda6 ro console=tty0
   8.142  \end{verbatim}
   8.143 +}
   8.144  
   8.145 -\item Create Xen 2.0 configuration file for the new domain. You can
   8.146 -  use the example-configurations coming with Xen as a template.
   8.147 +You can now boot into Xen by by choosing the right option from grub menu.
   8.148 +
   8.149 +\section{Installing from source}
   8.150 +\subsection{Required Packages}
   8.151 +Besides packages mentioned under binary tarball install, you will need:
   8.152 +
   8.153 +\begin{itemize}
   8.154 +\item gcc v3.2.x or v3.3.x
   8.155 +\item binutils
   8.156 +\item GNU make
   8.157 +\end{itemize}
   8.158 +
   8.159 +
   8.160 +\subsection{Download the source tree}
   8.161 +The Xen source tree is available as either a compressed source tarball
   8.162 +or as a clone of our master Mercurial repository.
   8.163  
   8.164 -  Make sure you have the following set up:
   8.165 +\begin{description}
   8.166 +\item[Obtaining the Source Tarball]\mbox{} \\
   8.167 +  Stable versions and daily snapshots of the Xen source tree are
   8.168 +  available from the Xen download page:
   8.169 +  \begin{quote} {\tt http://www.xensource.com/downloads/}
   8.170 +  \end{quote}
   8.171 +\item[Obtaining the source via Mercurial]\mbox{} \\
   8.172 +  The source tree may also be obtained via the public Mercurial
   8.173 +  repository hosted at:
   8.174 +  \begin{quote}{\tt http://xenbits.xensource.com}.
   8.175 +  \end{quote} See the instructions and the Getting Started Guide
   8.176 +  referenced at:
   8.177 +  \begin{quote}
   8.178 +    {\tt http://www.xensource.com/downloads/}.
   8.179 +  \end{quote}
   8.180 +\end{description}
   8.181 +
   8.182 +\subsection{Extract, build and install}
   8.183 +
   8.184  \begin{verbatim}
   8.185 -disk = [ 'file:/path/diskimage,sda1,w', 'file:/path/swapimage,sda2,w' ]
   8.186 -root = "/dev/sda1 ro"
   8.187 -\end{verbatim}
   8.188 -
   8.189 -\item Start the new domain
   8.190 -\begin{verbatim}
   8.191 -xm create -f domain_config_file
   8.192 -\end{verbatim}
   8.193 -
   8.194 -Check that the new domain is running:
   8.195 -\begin{verbatim}
   8.196 -xm list
   8.197 +# tar zxvf xen-3.0.0-src.tgz
   8.198 +# cd xen-3.0
   8.199 +# make dist
   8.200 +#./install.sh
   8.201  \end{verbatim}
   8.202  
   8.203 -\item Attach to the console of the new domain.  You should see
   8.204 -  something like this when starting the new domain:
   8.205 +\section{Installing from debs}
   8.206 +This section describes the process of installing Xen on Debian Sarge using debs created by Edward Despard.
   8.207 +
   8.208 +\subsection{Edward's announcement to xen-user list}
   8.209 +"For part of my Google Summer of Code work I've put together debs for xen of 2.0.7 and of unstable. The unstable debs are built off of yesterday's hg tree, but I try to update them fairly regularly when new developments occur." 
   8.210 +
   8.211 +\subsection{Adding apt source}
   8.212 +Add the following lines to \path{/etc/apt/sources.list}:
   8.213 +
   8.214 +\begin{quote}
   8.215 +{\small
   8.216 +\begin{verbatim}
   8.217 +deb http://tinyurl.com/8tpup
   8.218 +\end{verbatim}
   8.219 +}
   8.220 +\end{quote}
   8.221 +   
   8.222 +Note: On Ubuntu, simple replace debian with ubuntu in the above. Replace xen-unstable with with xen-stable for a stable version.
   8.223 +
   8.224 +Now run \path{aptitude update} or \path{apt-get update}. Doing \path{apt-cache search xen}, you should see following packages in the output.
   8.225 +
   8.226 +\begin{itemize}
   8.227 +\item kernel-image-2.6.12-xen0 - Xen 2.6 kernel image
   8.228 +\item kernel-image-2.6.12-xenu - Xen 2.6 kernel image
   8.229 +\item kernel-patch-xen-2.6.12 - patch to kernel to support xen
   8.230 +\item libxen3.0 - control libraries for Xen
   8.231 +\item libxen-dev - development libraries for Xen
   8.232 +\item xen-doc - documentation for Xen
   8.233 +\item xen-hypervisor - Xen hypervisor kernel
   8.234 +\item xen-kernels - Xen kernels
   8.235 +\item xen - Package to install all of Xen
   8.236 +\item xen-tools - Tools for managing xen domains
   8.237 +\end{itemize}
   8.238 +
   8.239 +\subsection{Installing Xen}
   8.240 +You can now install xen using \path{apt-get}, \path{aptitude}, \path{synaptic}, etc. 
   8.241 + 
   8.242 +After doing \path{apt-get install xen}, you will have a working dom0 and should be able boot into it without any problem. By doing \path{apt-cache depends xen}, you will find that the following packages were also installed as a result of dependency.
   8.243  
   8.244  \begin{verbatim}
   8.245 -Started domain testdomain2, console on port 9626
   8.246 -\end{verbatim}
   8.247 -        
   8.248 -  There you can see the ID of the console: 26. You can also list the
   8.249 -  consoles with \path{xm consoles} (ID is the last two digits of the
   8.250 -  port number.)
   8.251 -
   8.252 -  Attach to the console:
   8.253 -
   8.254 -\begin{verbatim}
   8.255 -xm console 26
   8.256 +#  apt-cache  
   8.257 +depends  xen
   8.258 +       xen
   8.259 +           Depends: xen-doc
   8.260 +           Depends: xen-kernels
   8.261 +           Depends: xen-hypervisor
   8.262 +           Depends: xen-tools
   8.263  \end{verbatim}
   8.264  
   8.265 -  or by telnetting to the port 9626 of localhost (the xm console
   8.266 -  program works better).
   8.267  
   8.268 -\item Log in and run base-config
   8.269 -
   8.270 -  As a default there's no password for the root.
   8.271 -
   8.272 -  Check that everything looks OK, and the system started without
   8.273 -  errors.  Check that the swap is active, and the network settings are
   8.274 -  correct.
   8.275 -
   8.276 -  Run \path{/usr/sbin/base-config} to set up the Debian settings.
   8.277 +\subsection{xenkernels.conf}
   8.278 +To automate grub entry for xen, \path{/etc/xenkernels.conf} is used which is installed when the package in installed. Below is a sample entry
   8.279  
   8.280 -  Set up the password for root using passwd.
   8.281 -
   8.282 -\item Done. You can exit the console by pressing {\path{Ctrl + ]}}
   8.283 -
   8.284 -\end{enumerate}
   8.285 +\begin{verbatim}
   8.286 +label=Xen(3.0-unstable082205)/Linux(2.6.12)--
   8.287 +          xen=/boot/xen-3.0-unstable082205.gz
   8.288 +          kernel=/boot/xen/dom0/vmlinuz-2.6.12-xen0
   8.289 +          mem=256000
   8.290 +          root=/dev/hda4
   8.291 +\end{verbatim}
   8.292  
   8.293 -
   8.294 -If you need to create new domains, you can just copy the contents of
   8.295 -the `template'-image to the new disk images, either by mounting the
   8.296 -template and the new image, and using \path{cp -a} or \path{tar} or by
   8.297 -simply copying the image file.  Once this is done, modify the
   8.298 -image-specific settings (hostname, network settings, etc).
   8.299 +You have to run run \path{update-grub-xen} every time \path{xenkernels.conf} is modified. Read \path{man update-grub-xen} for more information.
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/docs/src/user/debugging.tex	Sat Dec 03 17:52:38 2005 -0700
     9.3 @@ -0,0 +1,18 @@
     9.4 +\chapter{Debugging}
     9.5 +
     9.6 +Xen has a set of debugging features that can be useful to try and figure
     9.7 +out what's going on. Hit ``h'' on the serial line (if you specified a baud
     9.8 +rate on the Xen command line) or ScrollLock-h on the keyboard to get a
     9.9 +list of supported commands.
    9.10 +
    9.11 +If you have a crash you'll likely get a crash dump containing an EIP
    9.12 +(PC) which, along with an \path{objdump -d image}, can be useful in
    9.13 +figuring out what's happened. Debug a Xenlinux image just as you would
    9.14 +any other Linux kernel.
    9.15 +
    9.16 +%% We supply a handy debug terminal program which you can find in
    9.17 +%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should
    9.18 +%% be built and executed on another machine that is connected via a
    9.19 +%% null modem cable. Documentation is included.  Alternatively, if the
    9.20 +%% Xen machine is connected to a serial-port server then we supply a
    9.21 +%% dumb TCP terminal client, {\tt xencons}.
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/docs/src/user/dom0_installation.tex	Sat Dec 03 17:52:38 2005 -0700
    10.3 @@ -0,0 +1,3 @@
    10.4 +\chapter{dom0 Installation}
    10.5 +
    10.6 +Placeholder.
    11.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    11.2 +++ b/docs/src/user/domU_installation.tex	Sat Dec 03 17:52:38 2005 -0700
    11.3 @@ -0,0 +1,3 @@
    11.4 +\chapter{domU Installation}
    11.5 +
    11.6 +Placeholder.
    12.1 --- a/docs/src/user/domain_filesystem.tex	Sun Dec 04 01:34:25 2005 +0100
    12.2 +++ b/docs/src/user/domain_filesystem.tex	Sat Dec 03 17:52:38 2005 -0700
    12.3 @@ -1,9 +1,17 @@
    12.4 -\chapter{Domain Filesystem Storage}
    12.5 +\chapter{Storage and File System Management}
    12.6 +
    12.7 +Storage can be made available to virtual machines in a number of
    12.8 +different ways.  This chapter covers some possible configurations.
    12.9  
   12.10 -It is possible to directly export any Linux block device in dom0 to
   12.11 -another domain, or to export filesystems / devices to virtual machines
   12.12 -using standard network protocols (e.g.\ NBD, iSCSI, NFS, etc.).  This
   12.13 -chapter covers some of the possibilities.
   12.14 +The most straightforward method is to export a physical block device (a
   12.15 +hard drive or partition) from dom0 directly to the guest domain as a
   12.16 +virtual block device (VBD).
   12.17 +
   12.18 +Storage may also be exported from a filesystem image or a partitioned
   12.19 +filesystem image as a \emph{file-backed VBD}.
   12.20 +
   12.21 +Finally, standard network storage protocols such as NBD, iSCSI, NFS,
   12.22 +etc., can be used to provide storage to virtual machines.
   12.23  
   12.24  
   12.25  \section{Exporting Physical Devices as VBDs}
    13.1 --- a/docs/src/user/domain_mgmt.tex	Sun Dec 04 01:34:25 2005 +0100
    13.2 +++ b/docs/src/user/domain_mgmt.tex	Sat Dec 03 17:52:38 2005 -0700
    13.3 @@ -1,20 +1,98 @@
    13.4  \chapter{Domain Management Tools}
    13.5  
    13.6 -The previous chapter described a simple example of how to configure
    13.7 -and start a domain.  This chapter summarises the tools available to
    13.8 -manage running domains.
    13.9 +This chapter summarises the tools available to manage running domains.
   13.10  
   13.11  
   13.12 -\section{Command-line Management}
   13.13 +\section{\Xend\ }
   13.14 +\label{s:xend}
   13.15 +
   13.16 +The Xen Daemon (\Xend) (node control daemon) performs system management
   13.17 +functions related to virtual machines. It forms a central point of
   13.18 +control for a machine and can be controlled using an HTTP-based
   13.19 +protocol. \Xend\ must be running in order to start and manage virtual
   13.20 +machines.
   13.21 +
   13.22 +\Xend\ must be run as root because it needs access to privileged system
   13.23 +management functions. A small set of commands may be issued on the
   13.24 +\xend\ command line:
   13.25 +
   13.26 +\begin{tabular}{ll}
   13.27 +  \verb!# xend start! & start \xend, if not already running \\
   13.28 +  \verb!# xend stop!  & stop \xend\ if already running       \\
   13.29 +  \verb!# xend restart! & restart \xend\ if running, otherwise start it \\
   13.30 +  % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\
   13.31 +  \verb!# xend status! & indicates \xend\ status by its return code
   13.32 +\end{tabular}
   13.33 +
   13.34 +A SysV init script called {\tt xend} is provided to start \xend\ at boot
   13.35 +time. {\tt make install} installs this script in \path{/etc/init.d}. To
   13.36 +enable it, you have to make symbolic links in the appropriate runlevel
   13.37 +directories or use the {\tt chkconfig} tool, where available.
   13.38 +
   13.39 +Once \xend\ is running, more sophisticated administration can be done
   13.40 +using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv
   13.41 +web interface (see Section~\ref{s:xensv}).
   13.42 +
   13.43 +As \xend\ runs, events will be logged to \path{/var/log/xend.log} and,
   13.44 +if the migration assistant daemon (\path{xfrd}) has been started,
   13.45 +\path{/var/log/xfrd.log}. These may be of use for troubleshooting
   13.46 +problems.
   13.47 +
   13.48 +\section{Xm}
   13.49 +\label{s:xm}
   13.50  
   13.51  Command line management tasks are also performed using the \path{xm}
   13.52 -tool.  For online help for the commands available, type:
   13.53 +tool. For online help for the commands available, type:
   13.54 +
   13.55  \begin{quote}
   13.56 -  \verb_# xm help_
   13.57 +\begin{verbatim}
   13.58 +# xm help
   13.59 +\end{verbatim}
   13.60  \end{quote}
   13.61  
   13.62 -You can also type \path{xm help $<$command$>$} for more information on
   13.63 -a given command.
   13.64 +You can also type \path{xm help $<$command$>$} for more information on a
   13.65 +given command.
   13.66 +
   13.67 +The xm tool is the primary tool for managing Xen from the console. The
   13.68 +general format of an xm command line is:
   13.69 +
   13.70 +\begin{verbatim}
   13.71 +# xm command [switches] [arguments] [variables]
   13.72 +\end{verbatim}
   13.73 +
   13.74 +The available \emph{switches} and \emph{arguments} are dependent on the
   13.75 +\emph{command} chosen. The \emph{variables} may be set using
   13.76 +declarations of the form {\tt variable=value} and command line
   13.77 +declarations override any of the values in the configuration file being
   13.78 +used, including the standard variables described above and any custom
   13.79 +variables (for instance, the \path{xmdefconfig} file uses a {\tt vmid}
   13.80 +variable).
   13.81 +
   13.82 +The available commands are as follows:
   13.83 +
   13.84 +\begin{description}
   13.85 +\item[mem-set] Request a domain to adjust its memory footprint.
   13.86 +\item[create] Create a new domain.
   13.87 +\item[destroy] Kill a domain immediately.
   13.88 +\item[list] List running domains.
   13.89 +\item[shutdown] Ask a domain to shutdown.
   13.90 +\item[dmesg] Fetch the Xen (not Linux!) boot output.
   13.91 +\item[consoles] Lists the available consoles.
   13.92 +\item[console] Connect to the console for a domain.
   13.93 +\item[help] Get help on xm commands.
   13.94 +\item[save] Suspend a domain to disk.
   13.95 +\item[restore] Restore a domain from disk.
   13.96 +\item[pause] Pause a domain's execution.
   13.97 +\item[unpause] Un-pause a domain.
   13.98 +\item[pincpu] Pin a domain to a CPU.
   13.99 +\item[bvt] Set BVT scheduler parameters for a domain.
  13.100 +\item[bvt\_ctxallow] Set the BVT context switching allowance for the
  13.101 +  system.
  13.102 +\item[atropos] Set the atropos parameters for a domain.
  13.103 +\item[rrobin] Set the round robin time slice for the system.
  13.104 +\item[info] Get information about the Xen host.
  13.105 +\item[call] Call a \xend\ HTTP API function directly.
  13.106 +\end{description}
  13.107  
  13.108  \subsection{Basic Management Commands}
  13.109  
  13.110 @@ -82,122 +160,6 @@ following:
  13.111  # xencons localhost 9605
  13.112  \end{verbatim}
  13.113  
  13.114 -\section{Domain Save and Restore}
  13.115 -
  13.116 -The administrator of a Xen system may suspend a virtual machine's
  13.117 -current state into a disk file in domain~0, allowing it to be resumed
  13.118 -at a later time.
  13.119 -
  13.120 -The ttylinux domain described earlier can be suspended to disk using
  13.121 -the command:
  13.122 -\begin{verbatim}
  13.123 -# xm save ttylinux ttylinux.xen
  13.124 -\end{verbatim}
  13.125 -
  13.126 -This will stop the domain named `ttylinux' and save its current state
  13.127 -into a file called \path{ttylinux.xen}.
  13.128 -
  13.129 -To resume execution of this domain, use the \path{xm restore} command:
  13.130 -\begin{verbatim}
  13.131 -# xm restore ttylinux.xen
  13.132 -\end{verbatim}
  13.133 -
  13.134 -This will restore the state of the domain and restart it.  The domain
  13.135 -will carry on as before and the console may be reconnected using the
  13.136 -\path{xm console} command, as above.
  13.137 -
  13.138 -\section{Live Migration}
  13.139 -
  13.140 -Live migration is used to transfer a domain between physical hosts
  13.141 -whilst that domain continues to perform its usual activities --- from
  13.142 -the user's perspective, the migration should be imperceptible.
  13.143 -
  13.144 -To perform a live migration, both hosts must be running Xen / \xend\
  13.145 -and the destination host must have sufficient resources (e.g.\ memory
  13.146 -capacity) to accommodate the domain after the move. Furthermore we
  13.147 -currently require both source and destination machines to be on the
  13.148 -same L2 subnet.
  13.149 -
  13.150 -Currently, there is no support for providing automatic remote access
  13.151 -to filesystems stored on local disk when a domain is migrated.
  13.152 -Administrators should choose an appropriate storage solution (i.e.\
  13.153 -SAN, NAS, etc.) to ensure that domain filesystems are also available
  13.154 -on their destination node. GNBD is a good method for exporting a
  13.155 -volume from one machine to another. iSCSI can do a similar job, but is
  13.156 -more complex to set up.
  13.157 -
  13.158 -When a domain migrates, it's MAC and IP address move with it, thus it
  13.159 -is only possible to migrate VMs within the same layer-2 network and IP
  13.160 -subnet. If the destination node is on a different subnet, the
  13.161 -administrator would need to manually configure a suitable etherip or
  13.162 -IP tunnel in the domain~0 of the remote node.
  13.163 -
  13.164 -A domain may be migrated using the \path{xm migrate} command.  To live
  13.165 -migrate a domain to another machine, we would use the command:
  13.166 -
  13.167 -\begin{verbatim}
  13.168 -# xm migrate --live mydomain destination.ournetwork.com
  13.169 -\end{verbatim}
  13.170 +\section{xenstored}
  13.171  
  13.172 -Without the \path{--live} flag, \xend\ simply stops the domain and
  13.173 -copies the memory image over to the new node and restarts it. Since
  13.174 -domains can have large allocations this can be quite time consuming,
  13.175 -even on a Gigabit network. With the \path{--live} flag \xend\ attempts
  13.176 -to keep the domain running while the migration is in progress,
  13.177 -resulting in typical `downtimes' of just 60--300ms.
  13.178 -
  13.179 -For now it will be necessary to reconnect to the domain's console on
  13.180 -the new machine using the \path{xm console} command.  If a migrated
  13.181 -domain has any open network connections then they will be preserved,
  13.182 -so SSH connections do not have this limitation.
  13.183 -
  13.184 -
  13.185 -\section{Managing Domain Memory}
  13.186 -
  13.187 -XenLinux domains have the ability to relinquish / reclaim machine
  13.188 -memory at the request of the administrator or the user of the domain.
  13.189 -
  13.190 -\subsection{Setting memory footprints from dom0}
  13.191 -
  13.192 -The machine administrator can request that a domain alter its memory
  13.193 -footprint using the \path{xm mem-set} command.  For instance, we can
  13.194 -request that our example ttylinux domain reduce its memory footprint
  13.195 -to 32 megabytes.
  13.196 -
  13.197 -\begin{verbatim}
  13.198 -# xm mem-set ttylinux 32
  13.199 -\end{verbatim}
  13.200 -
  13.201 -We can now see the result of this in the output of \path{xm list}:
  13.202 -
  13.203 -\begin{verbatim}
  13.204 -# xm list
  13.205 -Name              Id  Mem(MB)  CPU  State  Time(s)  Console
  13.206 -Domain-0           0      251    0  r----    172.2        
  13.207 -ttylinux           5       31    0  -b---      4.3    9605
  13.208 -\end{verbatim}
  13.209 -
  13.210 -The domain has responded to the request by returning memory to Xen. We
  13.211 -can restore the domain to its original size using the command line:
  13.212 -
  13.213 -\begin{verbatim}
  13.214 -# xm mem-set ttylinux 64
  13.215 -\end{verbatim}
  13.216 -
  13.217 -\subsection{Setting memory footprints from within a domain}
  13.218 -
  13.219 -The virtual file \path{/proc/xen/balloon} allows the owner of a domain
  13.220 -to adjust their own memory footprint.  Reading the file (e.g.\
  13.221 -\path{cat /proc/xen/balloon}) prints out the current memory footprint
  13.222 -of the domain.  Writing the file (e.g.\ \path{echo new\_target >
  13.223 -  /proc/xen/balloon}) requests that the kernel adjust the domain's
  13.224 -memory footprint to a new value.
  13.225 -
  13.226 -\subsection{Setting memory limits}
  13.227 -
  13.228 -Xen associates a memory size limit with each domain.  By default, this
  13.229 -is the amount of memory the domain is originally started with,
  13.230 -preventing the domain from ever growing beyond this size.  To permit a
  13.231 -domain to grow beyond its original allocation or to prevent a domain
  13.232 -you've shrunk from reclaiming the memory it relinquished, use the
  13.233 -\path{xm maxmem} command.
  13.234 +Placeholder.
    14.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    14.2 +++ b/docs/src/user/fedora.tex	Sat Dec 03 17:52:38 2005 -0700
    14.3 @@ -0,0 +1,102 @@
    14.4 +\chapter{Installing Xen on Fedora~Core 4}
    14.5 +
    14.6 +This section will help you in installing Xen 3 on Fedora Core 4 using various methods.
    14.7 +
    14.8 +\section{Installing Xen from Source Package and binary package}
    14.9 +
   14.10 +\subsection{Required Packages}
   14.11 +bridge\_utils
   14.12 +
   14.13 +
   14.14 +\subsection{Installing}
   14.15 +
   14.16 +Download the source or binary tarballs available at \begin{quote} {\tt http://www.xensource.com/downloads } \end{quote}.
   14.17 +
   14.18 +Extract the archive using following command:
   14.19 +
   14.20 +\begin{verbatim}
   14.21 +tar -zxvf xen-*****-***.tgz
   14.22 +\end{verbatim}
   14.23 +
   14.24 +cd into the xen directory.
   14.25 +
   14.26 +To compile and install the source do
   14.27 +
   14.28 +\begin{verbatim}
   14.29 +     make dist
   14.30 +     make install
   14.31 +\end{verbatim}
   14.32 +
   14.33 +
   14.34 +To install the binary tarball, all you need to do is run the \path{install.sh} script.
   14.35 +
   14.36 +\begin{verbatim}
   14.37 +     #./install.sh
   14.38 +\end{verbatim}
   14.39 +
   14.40 +\subsection{Installing Xen using yum}
   14.41 +
   14.42 +To install xen, type the command
   14.43 +
   14.44 +\begin{verbatim}
   14.45 +#yum install xen
   14.46 +\end{verbatim}
   14.47 +
   14.48 +This will download the following rpms and install them:
   14.49 +
   14.50 +\begin{itemize}
   14.51 +\item xen
   14.52 +\item bridge-utils
   14.53 +\item sysfsutils
   14.54 +\end{itemize}
   14.55 +
   14.56 +Next we need to install kernel-xen0 and kernel-xenU. Type the command:
   14.57 +
   14.58 +\begin{verbatim}
   14.59 + yum install kernel-xen0 kernel-xenU 
   14.60 +\end{verbatim}
   14.61 +
   14.62 +Note: This installs xen0 and xenU kernels and adds an entry in the grub configuration.
   14.63 +Getting Xen up and running
   14.64 +
   14.65 +Once this finishes, you have xen0 and xenU kernels installed in the /boot filesystem. To boot into Dom0, edit the grub configuration file, which is menu.lst
   14.66 +
   14.67 +Note: Installation using yum doesn't require the configuration of grub as mentioned below.
   14.68 +
   14.69 +An example grub entry would be like:
   14.70 +
   14.71 +{\small
   14.72 +\begin{verbatim}
   14.73 +title Xen Unstable(From Fedora Core 4)
   14.74 +          root (hd0,0)
   14.75 +          kernel /fedora/xen.gz dom0\_mem=230000 console=vga
   14.76 +          module /fedora/vmlinuz-2.6-xen0 root=/dev/Vol1/LV3 ro console=tty0
   14.77 +          module /fedora/initrd-2.6.11-1.1369\_FC4smp.img
   14.78 +\end{verbatim}
   14.79 +}
   14.80 +
   14.81 +Also make sure that \path{/var/run/xenstored} and \path{/var/lib/xenstored} directories have been created. If they are not, manually create them.
   14.82 +
   14.83 +Now reboot and select the xen0 option from the GRUB menu.
   14.84 +
   14.85 +To check whether you are running the xen0 kernel, type \path{uname -r}
   14.86 +
   14.87 +Now start the xend process:
   14.88 +
   14.89 +\begin{verbatim}
   14.90 +xend start
   14.91 +\end{verbatim}
   14.92 +
   14.93 +To check whether xend process is running or not, type the following command which lists the running domains.
   14.94 +
   14.95 +\begin{verbatim}
   14.96 +#xm list
   14.97 +      Name              Id  Mem(MB)  CPU VCPU(s)  State  Time(s)
   14.98 +      Domain-0           0      219    0      1   r-----     28.9
   14.99 +\end{verbatim}
  14.100 +
  14.101 +Since you haven't created any guest domains yet, you would see only Domain0.
  14.102 +
  14.103 +Further Help and documentations
  14.104 +
  14.105 +Besides the usual resources, see the Fedora Quickstart Guide \begin{quote} {\tt http://www.fedoraproject.org/wiki/FedoraXenQuickstart } \end{quote}
    15.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    15.2 +++ b/docs/src/user/further_support.tex	Sat Dec 03 17:52:38 2005 -0700
    15.3 @@ -0,0 +1,52 @@
    15.4 +\chapter{Further Support}
    15.5 +
    15.6 +If you have questions that are not answered by this manual, the
    15.7 +sources of information listed below may be of interest to you.  Note
    15.8 +that bug reports, suggestions and contributions related to the
    15.9 +software (or the documentation) should be sent to the Xen developers'
   15.10 +mailing list (address below).
   15.11 +
   15.12 +
   15.13 +\section{Other Documentation}
   15.14 +
   15.15 +For developers interested in porting operating systems to Xen, the
   15.16 +\emph{Xen Interface Manual} is distributed in the \path{docs/}
   15.17 +directory of the Xen source distribution.
   15.18 +
   15.19 +
   15.20 +\section{Online References}
   15.21 +
   15.22 +The official Xen web site is found at:
   15.23 +\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/}
   15.24 +\end{quote}
   15.25 +
   15.26 +This contains links to the latest versions of all online
   15.27 +documentation, including the latest version of the FAQ.
   15.28 +
   15.29 +Information regarding Xen is also available at the Xen Wiki at
   15.30 +\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote}
   15.31 +The Xen project uses Bugzilla as its bug tracking system. You'll find
   15.32 +the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/.
   15.33 +
   15.34 +
   15.35 +\section{Mailing Lists}
   15.36 +
   15.37 +There are several mailing lists that are used to discuss Xen related
   15.38 +topics. The most widely relevant are listed below. An official page of
   15.39 +mailing lists and subscription information can be found at \begin{quote}
   15.40 +  {\tt http://lists.xensource.com/} \end{quote}
   15.41 +
   15.42 +\begin{description}
   15.43 +\item[xen-devel@lists.xensource.com] Used for development
   15.44 +  discussions and bug reports.  Subscribe at: \\
   15.45 +  {\small {\tt http://lists.xensource.com/xen-devel}}
   15.46 +\item[xen-users@lists.xensource.com] Used for installation and usage
   15.47 +  discussions and requests for help.  Subscribe at: \\
   15.48 +  {\small {\tt http://lists.xensource.com/xen-users}}
   15.49 +\item[xen-announce@lists.xensource.com] Used for announcements only.
   15.50 +  Subscribe at: \\
   15.51 +  {\small {\tt http://lists.xensource.com/xen-announce}}
   15.52 +\item[xen-changelog@lists.xensource.com] Changelog feed
   15.53 +  from the unstable and 2.0 trees - developer oriented.  Subscribe at: \\
   15.54 +  {\small {\tt http://lists.xensource.com/xen-changelog}}
   15.55 +\end{description}
    16.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    16.2 +++ b/docs/src/user/gentoo.tex	Sat Dec 03 17:52:38 2005 -0700
    16.3 @@ -0,0 +1,3 @@
    16.4 +\chapter{Installing Xen on Gentoo Linux}
    16.5 +
    16.6 +Placeholder.
    17.1 --- a/docs/src/user/glossary.tex	Sun Dec 04 01:34:25 2005 +0100
    17.2 +++ b/docs/src/user/glossary.tex	Sat Dec 03 17:52:38 2005 -0700
    17.3 @@ -57,14 +57,19 @@
    17.4  
    17.5  \item[Shadow pagetables] A technique for hiding the layout of machine
    17.6    memory from a virtual machine's operating system.  Used in some {\bf
    17.7 -    VMMs} to provide the illusion of contiguous physical memory, in
    17.8 +  VMMs} to provide the illusion of contiguous physical memory, in
    17.9    Xen this is used during {\bf live migration}.
   17.10  
   17.11 +\item[Virtual Block Device] Persistant storage available to a virtual
   17.12 +  machine, providing the abstraction of an actual block storage device.
   17.13 +  {\bf VBD}s may be actual block devices, filesystem images, or
   17.14 +  remote/network storage.
   17.15 +
   17.16  \item[Virtual Machine] The environment in which a hosted operating
   17.17    system runs, providing the abstraction of a dedicated machine.  A
   17.18    virtual machine may be identical to the underlying hardware (as in
   17.19    {\bf full virtualisation}, or it may differ, as in {\bf
   17.20 -    paravirtualisation}).
   17.21 +  paravirtualisation}).
   17.22  
   17.23  \item[VMM] Virtual Machine Monitor - the software that allows multiple
   17.24    virtual machines to be multiplexed on a single physical machine.
    18.1 --- a/docs/src/user/installation.tex	Sun Dec 04 01:34:25 2005 +0100
    18.2 +++ b/docs/src/user/installation.tex	Sat Dec 03 17:52:38 2005 -0700
    18.3 @@ -1,45 +1,43 @@
    18.4 -\chapter{Installation}
    18.5 +\chapter{Basic Installation}
    18.6  
    18.7  The Xen distribution includes three main components: Xen itself, ports
    18.8 -of Linux and NetBSD to run on Xen, and the userspace
    18.9 -tools required to manage a Xen-based system.  This chapter describes
   18.10 -how to install the Xen~2.0 distribution from source.  Alternatively,
   18.11 -there may be pre-built packages available as part of your operating
   18.12 -system distribution.
   18.13 +of Linux and NetBSD to run on Xen, and the userspace tools required to
   18.14 +manage a Xen-based system. This chapter describes how to install the
   18.15 +Xen~3.0 distribution from source. Alternatively, there may be pre-built
   18.16 +packages available as part of your operating system distribution.
   18.17  
   18.18  
   18.19  \section{Prerequisites}
   18.20  \label{sec:prerequisites}
   18.21  
   18.22 -The following is a full list of prerequisites.  Items marked `$\dag$'
   18.23 -are required by the \xend\ control tools, and hence required if you
   18.24 -want to run more than one virtual machine; items marked `$*$' are only
   18.25 -required if you wish to build from source.
   18.26 +The following is a full list of prerequisites. Items marked `$\dag$' are
   18.27 +required by the \xend\ control tools, and hence required if you want to
   18.28 +run more than one virtual machine; items marked `$*$' are only required
   18.29 +if you wish to build from source.
   18.30  \begin{itemize}
   18.31 -\item A working Linux distribution using the GRUB bootloader and
   18.32 -  running on a P6-class or newer CPU\@.
   18.33 +\item A working Linux distribution using the GRUB bootloader and running
   18.34 +  on a P6-class or newer CPU\@.
   18.35  \item [$\dag$] The \path{iproute2} package.
   18.36  \item [$\dag$] The Linux bridge-utils\footnote{Available from {\tt
   18.37        http://bridge.sourceforge.net}} (e.g., \path{/sbin/brctl})
   18.38  \item [$\dag$] The Linux hotplug system\footnote{Available from {\tt
   18.39 -      http://linux-hotplug.sourceforge.net/}} (e.g., \path{/sbin/hotplug}
   18.40 -      and related scripts)
   18.41 +      http://linux-hotplug.sourceforge.net/}} (e.g.,
   18.42 +  \path{/sbin/hotplug} and related scripts)
   18.43  \item [$*$] Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make).
   18.44  \item [$*$] Development installation of libcurl (e.g.,\ libcurl-devel).
   18.45  \item [$*$] Development installation of zlib (e.g.,\ zlib-dev).
   18.46 -\item [$*$] Development installation of Python v2.2 or later (e.g.,\ 
   18.47 +\item [$*$] Development installation of Python v2.2 or later (e.g.,\
   18.48    python-dev).
   18.49  \item [$*$] \LaTeX\ and transfig are required to build the
   18.50    documentation.
   18.51  \end{itemize}
   18.52  
   18.53 -Once you have satisfied these prerequisites, you can now install
   18.54 -either a binary or source distribution of Xen.
   18.55 -
   18.56 +Once you have satisfied these prerequisites, you can now install either
   18.57 +a binary or source distribution of Xen.
   18.58  
   18.59  \section{Installing from Binary Tarball}
   18.60  
   18.61 -Pre-built tarballs are available for download from the Xen download
   18.62 +Pre-built tarballs are available for download from the XenSource downloads
   18.63  page:
   18.64  \begin{quote} {\tt http://www.xensource.com/downloads/}
   18.65  \end{quote}
   18.66 @@ -51,14 +49,28 @@ Once you've downloaded the tarball, simp
   18.67  # sh ./install.sh
   18.68  \end{verbatim}
   18.69  
   18.70 -Once you've installed the binaries you need to configure your system
   18.71 -as described in Section~\ref{s:configure}.
   18.72 +Once you've installed the binaries you need to configure your system as
   18.73 +described in Section~\ref{s:configure}.
   18.74 +
   18.75 +\section{Installing from RPMs}
   18.76 +Pre-built RPMs are available for download from the XenSource downloads
   18.77 +page:
   18.78 +\begin{quote} {\tt http://www.xensource.com/downloads/}
   18.79 +\end{quote}
   18.80  
   18.81 +Once you've downloaded the RPMs, you typically install them via the RPM commands:
   18.82 +\begin{verbatim}
   18.83 +# rpm -ivh \emph{rpmname}
   18.84 +\end{verbatim}
   18.85  
   18.86 +See the instructions and the Release Notes for each RPM set referenced at:
   18.87 +  \begin{quote}
   18.88 +    {\tt http://www.xensource.com/downloads/}.
   18.89 +  \end{quote}
   18.90 + 
   18.91  \section{Installing from Source}
   18.92  
   18.93 -This section describes how to obtain, build and install Xen from
   18.94 -source.
   18.95 +This section describes how to obtain, build and install Xen from source.
   18.96  
   18.97  \subsection{Obtaining the Source}
   18.98  
   18.99 @@ -90,9 +102,9 @@ or as a clone of our master Mercurial re
  18.100  % \item[\path{tools/}] Xen node controller daemon (Xend), command line
  18.101  %   tools, control libraries
  18.102  % \item[\path{xen/}] The Xen VMM.
  18.103 +% \item[\path{buildconfigs/}] Build configuration files
  18.104  % \item[\path{linux-*-xen-sparse/}] Xen support for Linux.
  18.105 -% \item[\path{linux-*-patches/}] Experimental patches for Linux.
  18.106 -% \item[\path{netbsd-*-xen-sparse/}] Xen support for NetBSD.
  18.107 +% \item[\path{patches/}] Experimental patches for Linux.
  18.108  % \item[\path{docs/}] Various documentation files for users and
  18.109  %   developers.
  18.110  % \item[\path{extras/}] Bonus extras.
  18.111 @@ -106,11 +118,11 @@ following:
  18.112  \begin{itemize}
  18.113  \item Build Xen.
  18.114  \item Build the control tools, including \xend.
  18.115 -\item Download (if necessary) and unpack the Linux 2.6 source code,
  18.116 -  and patch it for use with Xen.
  18.117 -\item Build a Linux kernel to use in domain~0 and a smaller
  18.118 -  unprivileged kernel, which can optionally be used for unprivileged
  18.119 -  virtual machines.
  18.120 +\item Download (if necessary) and unpack the Linux 2.6 source code, and
  18.121 +  patch it for use with Xen.
  18.122 +\item Build a Linux kernel to use in domain~0 and a smaller unprivileged
  18.123 +  kernel, which can optionally be used for unprivileged virtual
  18.124 +  machines.
  18.125  \end{itemize}
  18.126  
  18.127  After the build has completed you should have a top-level directory
  18.128 @@ -122,16 +134,16 @@ just contains the virtual ones. These ar
  18.129  \path{dist/install/boot/} along with the image for Xen itself and the
  18.130  configuration files used during the build.
  18.131  
  18.132 -The NetBSD port can be built using:
  18.133 -\begin{quote}
  18.134 -\begin{verbatim}
  18.135 -# make netbsd20
  18.136 -\end{verbatim}\end{quote}
  18.137 -NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
  18.138 -The snapshot is downloaded as part of the build process if it is not
  18.139 -yet present in the \path{NETBSD\_SRC\_PATH} search path.  The build
  18.140 -process also downloads a toolchain which includes all of the tools
  18.141 -necessary to build the NetBSD kernel under Linux.
  18.142 +%The NetBSD port can be built using:
  18.143 +%\begin{quote}
  18.144 +%\begin{verbatim}
  18.145 +%# make netbsd20
  18.146 +%\end{verbatim}\end{quote}
  18.147 +%NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
  18.148 +%The snapshot is downloaded as part of the build process if it is not
  18.149 +%yet present in the \path{NETBSD\_SRC\_PATH} search path.  The build
  18.150 +%process also downloads a toolchain which includes all of the tools
  18.151 +%necessary to build the NetBSD kernel under Linux.
  18.152  
  18.153  To customize the set of kernels built you need to edit the top-level
  18.154  Makefile. Look for the line:
  18.155 @@ -169,7 +181,7 @@ kernel containing only virtual device dr
  18.156  %%     currently), you'll need to enable devfs and devfs mount at boot
  18.157  %%     time in the xen0 config.  }}
  18.158  
  18.159 -\subsection{Custom XenLinux Builds}
  18.160 +\subsection{Custom Kernels}
  18.161  
  18.162  % If you have an SMP machine you may wish to give the {\tt '-j4'}
  18.163  % argument to make to get a parallel build.
  18.164 @@ -187,26 +199,26 @@ architecture being built for is \path{xe
  18.165  \end{verbatim}
  18.166  \end{quote}
  18.167  
  18.168 -You can also copy an existing Linux configuration (\path{.config})
  18.169 -into e.g.\ \path{linux-2.6.11-xen0} and execute:
  18.170 +You can also copy an existing Linux configuration (\path{.config}) into
  18.171 +e.g.\ \path{linux-2.6.11-xen0} and execute:
  18.172  \begin{quote}
  18.173  \begin{verbatim}
  18.174  # make ARCH=xen oldconfig
  18.175  \end{verbatim}
  18.176  \end{quote}
  18.177  
  18.178 -You may be prompted with some Xen-specific options. We advise
  18.179 -accepting the defaults for these options.
  18.180 +You may be prompted with some Xen-specific options. We advise accepting
  18.181 +the defaults for these options.
  18.182  
  18.183  Note that the only difference between the two types of Linux kernels
  18.184 -that are built is the configuration file used for each.  The ``U''
  18.185 +that are built is the configuration file used for each. The ``U''
  18.186  suffixed (unprivileged) versions don't contain any of the physical
  18.187 -hardware device drivers, leading to a 30\% reduction in size; hence
  18.188 -you may prefer these for your non-privileged domains.  The ``0''
  18.189 -suffixed privileged versions can be used to boot the system, as well
  18.190 -as in driver domains and unprivileged domains.
  18.191 +hardware device drivers, leading to a 30\% reduction in size; hence you
  18.192 +may prefer these for your non-privileged domains. The ``0'' suffixed
  18.193 +privileged versions can be used to boot the system, as well as in driver
  18.194 +domains and unprivileged domains.
  18.195  
  18.196 -\subsection{Installing the Binaries}
  18.197 +\subsection{Installing Generated Binaries}
  18.198  
  18.199  The files produced by the build process are stored under the
  18.200  \path{dist/install/} directory. To install them in their default
  18.201 @@ -217,13 +229,13 @@ locations, do:
  18.202  \end{verbatim}
  18.203  \end{quote}
  18.204  
  18.205 -Alternatively, users with special installation requirements may wish
  18.206 -to install them manually by copying the files to their appropriate
  18.207 +Alternatively, users with special installation requirements may wish to
  18.208 +install them manually by copying the files to their appropriate
  18.209  destinations.
  18.210  
  18.211  %% Files in \path{install/boot/} include:
  18.212  %% \begin{itemize}
  18.213 -%% \item \path{install/boot/xen-2.0.gz} Link to the Xen 'kernel'
  18.214 +%% \item \path{install/boot/xen-3.0.gz} Link to the Xen 'kernel'
  18.215  %% \item \path{install/boot/vmlinuz-2.6-xen0} Link to domain 0
  18.216  %%   XenLinux kernel
  18.217  %% \item \path{install/boot/vmlinuz-2.6-xenU} Link to unprivileged
  18.218 @@ -233,28 +245,30 @@ destinations.
  18.219  The \path{dist/install/boot} directory will also contain the config
  18.220  files used for building the XenLinux kernels, and also versions of Xen
  18.221  and XenLinux kernels that contain debug symbols such as
  18.222 -(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which
  18.223 -are essential for interpreting crash dumps.  Retain these files as the
  18.224 +(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which are
  18.225 +essential for interpreting crash dumps. Retain these files as the
  18.226  developers may wish to see them if you post on the mailing list.
  18.227  
  18.228  
  18.229  \section{Configuration}
  18.230  \label{s:configure}
  18.231  
  18.232 -Once you have built and installed the Xen distribution, it is simple
  18.233 -to prepare the machine for booting and running Xen.
  18.234 +Once you have built and installed the Xen distribution, it is simple to
  18.235 +prepare the machine for booting and running Xen.
  18.236  
  18.237  \subsection{GRUB Configuration}
  18.238  
  18.239  An entry should be added to \path{grub.conf} (often found under
  18.240  \path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot.
  18.241  This file is sometimes called \path{menu.lst}, depending on your
  18.242 -distribution.  The entry should look something like the following:
  18.243 +distribution. The entry should look something like the following:
  18.244  
  18.245 +%% KMSelf Thu Dec  1 19:06:13 PST 2005 262144 is useful for RHEL/RH and
  18.246 +%% related Dom0s.
  18.247  {\small
  18.248  \begin{verbatim}
  18.249  title Xen 3.0 / XenLinux 2.6
  18.250 -  kernel /boot/xen-3.0.gz dom0_mem=131072
  18.251 +  kernel /boot/xen-3.0.gz dom0_mem=262144
  18.252    module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro console=tty0
  18.253  \end{verbatim}
  18.254  }
  18.255 @@ -266,11 +280,11 @@ For more details on the various Xen boot
  18.256  Section~\ref{s:xboot}.
  18.257  
  18.258  The module line of the configuration describes the location of the
  18.259 -XenLinux kernel that Xen should start and the parameters that should
  18.260 -be passed to it. Tthese are standard Linux parameters, identifying the
  18.261 -root device and specifying it be initially mounted read only and
  18.262 -instructing that console output be sent to the screen. Some
  18.263 -distributions such as SuSE do not require the \path{ro} parameter.
  18.264 +XenLinux kernel that Xen should start and the parameters that should be
  18.265 +passed to it. These are standard Linux parameters, identifying the root
  18.266 +device and specifying it be initially mounted read only and instructing
  18.267 +that console output be sent to the screen. Some distributions such as
  18.268 +SuSE do not require the \path{ro} parameter.
  18.269  
  18.270  %% \framebox{\parbox{5in}{
  18.271  %%     {\bf Distro specific:} \\
  18.272 @@ -278,85 +292,174 @@ distributions such as SuSE do not requir
  18.273  %%     kernel command line, since the partition won't be remounted rw
  18.274  %%     during boot.  }}
  18.275  
  18.276 -
  18.277 -If you want to use an initrd, just add another \path{module} line to
  18.278 -the configuration, like:
  18.279 -{\small
  18.280 +To use an initrd, add another \path{module} line to the configuration,
  18.281 +like: {\small
  18.282  \begin{verbatim}
  18.283    module /boot/my_initrd.gz
  18.284  \end{verbatim}
  18.285  }
  18.286  
  18.287 +%% KMSelf Thu Dec  1 19:05:30 PST 2005 Other configs as an appendix?
  18.288 +
  18.289  When installing a new kernel, it is recommended that you do not delete
  18.290 -existing menu options from \path{menu.lst}, as you may wish to boot
  18.291 -your old Linux kernel in future, particularly if you have problems.
  18.292 +existing menu options from \path{menu.lst}, as you may wish to boot your
  18.293 +old Linux kernel in future, particularly if you have problems.
  18.294  
  18.295  \subsection{Serial Console (optional)}
  18.296  
  18.297 +Serial console access allows you to manage, monitor, and interact with
  18.298 +your system over a serial console.  This can allow access from another
  18.299 +nearby system via a null-modem ("LapLink") cable, remotely via a serial
  18.300 +concentrator, or for debugging an emulator such as Qemu.
  18.301 +
  18.302 +You system's BIOS, bootloader (GRUB), Xen, Linux, and login access must
  18.303 +each be individually configured for serial console access.  It is
  18.304 +\emph{not} strictly necessary to have each component fully functional,
  18.305 +but it can be quite useful.
  18.306 +
  18.307 +For general information on serial console configuration under Linux,
  18.308 +refer to the ``Remote Serial Console HOWTO'' at The Linux Documentation
  18.309 +Project:  {\tt http://www.tldp.org}.
  18.310 +
  18.311 +\subsubsection{Serial Console BIOS configuration}
  18.312 +
  18.313 +Enabling system serial console output neither enables nor disables
  18.314 +serial capabilities in GRUB, Xen, or Linux, but may make remote
  18.315 +management of your system more convenient by displaying POST and other
  18.316 +boot messages over serial port and allowing remote BIOS configuration.
  18.317 +
  18.318 +Refer to your hardware vendor's documentation for capabilities and
  18.319 +procedures to enable BIOS serial redirection.
  18.320 +
  18.321 +
  18.322 +\subsubsection{Serial Console GRUB configuration}
  18.323 +
  18.324 +Placeholder
  18.325 +
  18.326 +Enabling GRUB serial console output neither enables nor disables Xen or
  18.327 +Linux serial capabilities, but may made remote management of your system
  18.328 +more convenient by displaying GRUB prompts, menus, and actions over
  18.329 +serial port and allowing remote GRUB management.
  18.330 +
  18.331 +Adding the following two lines to your GRUB configuration file,
  18.332 +typically \path{/boot/grub/menu.lst} or \path{/boot/grub/grub.conf}
  18.333 +depending on your distro, will enable GRUB serial output.
  18.334 +
  18.335 +\begin{quote} {\small \begin{verbatim}
  18.336 +  serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1
  18.337 +  terminal --timeout=10 serial console
  18.338 +\end{verbatim}}
  18.339 +\end{quote}
  18.340 +
  18.341 +Note that when both the serial port and the local monitor and keyboard
  18.342 +are enabled, the text "Press any key to continue." will appear at both.
  18.343 +Pressing a key on one device will cause GRUB to display to that device.
  18.344 +The other device will see no output.  If no key is pressed before the
  18.345 +timeout period expires, the system will boot to the default GRUB boot
  18.346 +entry.
  18.347 +
  18.348 +Please refer to the GRUB info documentation for further information.
  18.349 +
  18.350 +
  18.351 +\subsubsection{Serial Console Xen configuration}
  18.352 +
  18.353 +Enabling Xen serial console output neither enables nor disables Linux
  18.354 +kernel output or logging in to Linux over serial port.  It does however
  18.355 +allow you to monitor and log the Xen boot process via serial console and
  18.356 +can be very useful in debugging.
  18.357 +
  18.358  %% kernel /boot/xen-2.0.gz dom0_mem=131072 com1=115200,8n1
  18.359  %% module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro
  18.360  
  18.361 -In order to configure Xen serial console output, it is necessary to
  18.362 -add an boot option to your GRUB config; e.g.\ replace the above kernel
  18.363 -line with:
  18.364 -\begin{quote}
  18.365 -{\small
  18.366 -\begin{verbatim}
  18.367 +In order to configure Xen serial console output, it is necessary to add
  18.368 +an boot option to your GRUB config; e.g.\ replace the above kernel line
  18.369 +with:
  18.370 +\begin{quote} {\small \begin{verbatim}
  18.371     kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
  18.372  \end{verbatim}}
  18.373  \end{quote}
  18.374  
  18.375  This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1
  18.376 -stop bit and no parity. Modify these parameters for your set up.
  18.377 +stop bit and no parity. Modify these parameters for your environment.
  18.378 +
  18.379 +One can also configure XenLinux to share the serial console; to achieve
  18.380 +this append ``\path{console=ttyS0}'' to your module line.
  18.381 +
  18.382 +
  18.383 +\subsubsection{Serial Console Linux configuration}
  18.384  
  18.385 -One can also configure XenLinux to share the serial console; to
  18.386 -achieve this append ``\path{console=ttyS0}'' to your module line.
  18.387 +Enabling Linux serial console output at boot neither enables nor
  18.388 +disables logging in to Linux over serial port.  It does however allow
  18.389 +you to monitor and log the Linux boot process via serial console and can be
  18.390 +very useful in debugging.
  18.391 +
  18.392 +To enable Linux output at boot time, add the parameter
  18.393 +\path{console=ttyS0} (or ttyS1, ttyS2, etc.) to your kernel GRUB line.
  18.394 +Under Xen, this might be:
  18.395 +\begin{quote} {\small \begin{verbatim}
  18.396 +  module /vmlinuz-2.6-xen0 ro root=/dev/VolGroup00/LogVol00 console=ttyS0, 115200
  18.397 +\end{verbatim}}
  18.398 +\end{quote}
  18.399 +to enable output over ttyS0 at 115200 baud.
  18.400  
  18.401 -If you wish to be able to log in over the XenLinux serial console it
  18.402 -is necessary to add a line into \path{/etc/inittab}. Add the line:
  18.403 -\begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty ttyS0}}
  18.404 -\end{quote}
  18.405 +
  18.406 +
  18.407 +\subsubsection{Serial Console Login configuration}
  18.408 +
  18.409 +Logging in to Linux via serial console, under Xen or otherwise, requires
  18.410 +specifying a login prompt be started on the serial port.  To permit root
  18.411 +logins over serial console, the serial port must be added to
  18.412 +\path{/etc/securetty}.
  18.413  
  18.414 -and you should be able to log in. To successfully log in as root over
  18.415 -the serial line will require adding \path{ttyS0} to
  18.416 -\path{/etc/securetty} if it is not already there.
  18.417 +To automatically start a login prompt over serial port, 
  18.418 +Add the line: \begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty
  18.419 +ttyS0}} \end{quote} to \path{/etc/inittab}.   Run \path{init q} to force
  18.420 +a reload of your inttab and start getty.
  18.421 +
  18.422 +To enable root logins, add \path{ttyS0} to \path{/etc/securetty} if not
  18.423 +already present.
  18.424 +
  18.425 +Your distribution may use an alternate getty, options include getty,
  18.426 +mgetty, agetty, and others.  Consult your distribution's documentation
  18.427 +for further information.
  18.428 +
  18.429  
  18.430  \subsection{TLS Libraries}
  18.431  
  18.432  Users of the XenLinux 2.6 kernel should disable Thread Local Storage
  18.433  (TLS) (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before
  18.434 -attempting to boot a XenLinux kernel\footnote{If you boot without
  18.435 -  first disabling TLS, you will get a warning message during the boot
  18.436 -  process. In this case, simply perform the rename after the machine
  18.437 -  is up and then run \texttt{/sbin/ldconfig} to make it take effect.}.
  18.438 -You can always reenable TLS by restoring the directory to its original
  18.439 -location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
  18.440 +attempting to boot a XenLinux kernel\footnote{If you boot without first
  18.441 +  disabling TLS, you will get a warning message during the boot process.
  18.442 +  In this case, simply perform the rename after the machine is up and
  18.443 +  then run \path{/sbin/ldconfig} to make it take effect.}. You can
  18.444 +always reenable TLS by restoring the directory to its original location
  18.445 +(i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
  18.446  
  18.447  The reason for this is that the current TLS implementation uses
  18.448 -segmentation in a way that is not permissible under Xen.  If TLS is
  18.449 -not disabled, an emulation mode is used within Xen which reduces
  18.450 -performance substantially.
  18.451 +segmentation in a way that is not permissible under Xen. If TLS is not
  18.452 +disabled, an emulation mode is used within Xen which reduces performance
  18.453 +substantially.
  18.454  
  18.455  We hope that this issue can be resolved by working with Linux
  18.456 -distributions to implement a minor backward-compatible change
  18.457 -to the TLS library.
  18.458 +distributions to implement a minor backward-compatible change to the TLS
  18.459 +library.
  18.460  
  18.461  
  18.462  \section{Booting Xen}
  18.463  
  18.464 -It should now be possible to restart the system and use Xen.  Reboot
  18.465 -and choose the new Xen option when the Grub screen appears.
  18.466 +It should now be possible to restart the system and use Xen. Reboot and
  18.467 +choose the new Xen option when the Grub screen appears.
  18.468  
  18.469 -What follows should look much like a conventional Linux boot.  The
  18.470 -first portion of the output comes from Xen itself, supplying low level
  18.471 -information about itself and the underlying hardware.  The last
  18.472 -portion of the output comes from XenLinux.
  18.473 +What follows should look much like a conventional Linux boot. The first
  18.474 +portion of the output comes from Xen itself, supplying low level
  18.475 +information about itself and the underlying hardware. The last portion
  18.476 +of the output comes from XenLinux.
  18.477  
  18.478 -You may see some errors during the XenLinux boot.  These are not
  18.479 +You may see some errors during the XenLinux boot. These are not
  18.480  necessarily anything to worry about --- they may result from kernel
  18.481  configuration differences between your XenLinux kernel and the one you
  18.482  usually use.
  18.483  
  18.484  When the boot completes, you should be able to log into your system as
  18.485 -usual.  If you are unable to log in, you should still be able to
  18.486 -reboot with your normal Linux kernel.
  18.487 +usual. If you are unable to log in, you should still be able to reboot
  18.488 +with your normal Linux kernel by selecting it at the GRUB prompt.
    19.1 --- a/docs/src/user/introduction.tex	Sun Dec 04 01:34:25 2005 +0100
    19.2 +++ b/docs/src/user/introduction.tex	Sat Dec 03 17:52:38 2005 -0700
    19.3 @@ -1,45 +1,56 @@
    19.4  \chapter{Introduction}
    19.5  
    19.6  
    19.7 -Xen is a \emph{paravirtualising} virtual machine monitor (VMM), or
    19.8 -``hypervisor'', for the x86 processor architecture.  Xen can securely
    19.9 +Xen is a \emph{para-virtualizing} virtual machine monitor (VMM), or
   19.10 +``hypervisor'', for the x86 processor architecture. Xen can securely
   19.11  execute multiple virtual machines on a single physical system with
   19.12 -close-to-native performance.  The virtual machine technology
   19.13 -facilitates enterprise-grade functionality, including:
   19.14 +close-to-native performance. The virtual machine technology facilitates
   19.15 +enterprise-grade functionality, including:
   19.16  
   19.17  \begin{itemize}
   19.18 -\item Virtual machines with performance close to native hardware.
   19.19 -\item Live migration of running virtual machines between physical
   19.20 -  hosts.
   19.21 +\item Virtual machines with performance typically 94-98\% of native hardware.
   19.22 +\item Live migration of running virtual machines between physical hosts.
   19.23  \item Excellent hardware support. Supports most Linux device drivers.
   19.24 -\item Sandboxed, re-startable device drivers.
   19.25 +\item Sand-boxed, re-startable device drivers.
   19.26  \end{itemize}
   19.27  
   19.28 -Paravirtualisation permits very high performance virtualisation, even
   19.29 +Para-virtualization permits very high performance virtualization, even
   19.30  on architectures like x86 that are traditionally very hard to
   19.31 -virtualise.
   19.32 +virtualize.
   19.33  
   19.34  The drawback of this approach is that it requires operating systems to
   19.35 -be \emph{ported} to run on Xen.  Porting an OS to run on Xen is
   19.36 -similar to supporting a new hardware platform, however the process is
   19.37 -simplified because the paravirtual machine architecture is very
   19.38 -similar to the underlying native hardware. Even though operating
   19.39 -system kernels must explicitly support Xen, a key feature is that user
   19.40 -space applications and libraries \emph{do not} require modification.
   19.41 +be \emph{ported} to run on Xen. Porting an OS to run on Xen is similar
   19.42 +to supporting a new hardware platform, however the process is simplified
   19.43 +because the para-virtual machine architecture is very similar to the
   19.44 +underlying native hardware. Even though operating system kernels must
   19.45 +explicitly support Xen, a key feature is that user space applications
   19.46 +and libraries \emph{do not} require modification.
   19.47 +
   19.48 +With hardware CPU virtualization as provided by Intel VT and AMD
   19.49 +Pacifica technology, the ability to run an unmodified guest OS kernel is
   19.50 +available.  No porting of the OS is required; however some additional
   19.51 +driver support is necessary within Xen itself.  Unlike traditional full
   19.52 +virtualization hypervisors, which suffer a tremendous performance
   19.53 +overhead, the combination of Xen and VT or Xen and Pacifica technology
   19.54 +complement one another to offer superb performance for para-virtualized
   19.55 +guest operating systems and full support for unmodified guests, which
   19.56 +run natively on the processor without need for emulation, under VT.
   19.57 +Full support for VT and Pacifica chipsets will appear in early 2006.
   19.58  
   19.59  Xen support is available for increasingly many operating systems:
   19.60 -right now, Linux and NetBSD are available for Xen 3.0.
   19.61 -A FreeBSD port is undergoing testing and will be incorporated into the
   19.62 -release soon. Other OS ports, including Plan 9, are in progress.  We
   19.63 -hope that that arch-xen patches will be incorporated into the
   19.64 -mainstream releases of these operating systems in due course (as has
   19.65 -already happened for NetBSD).
   19.66 +currently, Linux and NetBSD are available for Xen 3.0. A FreeBSD port is
   19.67 +undergoing testing and will be incorporated into the release soon. Other
   19.68 +OS ports, including Plan 9, are in progress. We hope that that arch-xen
   19.69 +patches will be incorporated into the mainstream releases of these
   19.70 +operating systems in due course (as has already happened for NetBSD).
   19.71 +
   19.72 +%% KMSelf Thu Dec  1 14:59:02 PST 2005 PPC port status?
   19.73  
   19.74  Possible usage scenarios for Xen include:
   19.75  
   19.76  \begin{description}
   19.77  \item [Kernel development.] Test and debug kernel modifications in a
   19.78 -  sandboxed virtual machine --- no need for a separate test machine.
   19.79 +  sand-boxed virtual machine --- no need for a separate test machine.
   19.80  \item [Multiple OS configurations.] Run multiple operating systems
   19.81    simultaneously, for instance for compatibility or QA purposes.
   19.82  \item [Server consolidation.] Move multiple servers onto a single
   19.83 @@ -50,7 +61,7 @@ Possible usage scenarios for Xen include
   19.84    control and isolation than single-system image solutions,
   19.85    particularly by using live migration for load balancing.
   19.86  \item [Hardware support for custom OSes.] Allow development of new
   19.87 -  OSes while benefitting from the wide-ranging hardware support of
   19.88 +  OSes while benefiting from the wide-ranging hardware support of
   19.89    existing OSes such as Linux.
   19.90  \end{description}
   19.91  
   19.92 @@ -62,10 +73,10 @@ which is Xen itself.
   19.93  
   19.94  Xen may host multiple \emph{guest} operating systems, each of which is
   19.95  executed within a secure virtual machine. In Xen terminology, a
   19.96 -\emph{domain}. Domains are scheduled by Xen to make effective use of
   19.97 -the available physical CPUs.  Each guest OS manages its own
   19.98 -applications. This management includes the responsibility of
   19.99 -scheduling each application within the time allotted to the VM by Xen.
  19.100 +\emph{domain}. Domains are scheduled by Xen to make effective use of the
  19.101 +available physical CPUs. Each guest OS manages its own applications.
  19.102 +This management includes the responsibility of scheduling each
  19.103 +application within the time allotted to the VM by Xen.
  19.104  
  19.105  The first domain, \emph{domain~0}, is created automatically when the
  19.106  system boots and has special management privileges. Domain~0 builds
  19.107 @@ -73,39 +84,38 @@ other domains and manages their virtual 
  19.108  administrative tasks such as suspending, resuming and migrating other
  19.109  virtual machines.
  19.110  
  19.111 -Within domain~0, a process called \emph{xend} runs to manage the
  19.112 -system.  \Xend\ is responsible for managing virtual machines and
  19.113 -providing access to their consoles.  Commands are issued to \xend\ 
  19.114 -over an HTTP interface, either from a command-line tool or from a web
  19.115 -browser.
  19.116 +Within domain~0, a process called \emph{xend} runs to manage the system.
  19.117 +\Xend\ is responsible for managing virtual machines and providing access
  19.118 +to their consoles. Commands are issued to \xend\ over an HTTP interface,
  19.119 +either from a command-line tool or from a web browser.
  19.120  
  19.121  
  19.122  \section{Hardware Support}
  19.123  
  19.124 -Xen currently runs only on the x86 architecture, requiring a `P6' or
  19.125 +Xen currently runs only on the x86 architecture, requiring a ``P6'' or
  19.126  newer processor (e.g.\ Pentium Pro, Celeron, Pentium~II, Pentium~III,
  19.127 -Pentium~IV, Xeon, AMD~Athlon, AMD~Duron).  Multiprocessor machines are
  19.128 -supported, and there is basic support for HyperThreading (SMT),
  19.129 -although this remains a topic for ongoing research. A port
  19.130 -specifically for x86/64 is in progress. Xen already runs on such
  19.131 -systems in 32-bit legacy mode. In addition, a port to the IA64
  19.132 -architecture is approaching completion. We hope to add other
  19.133 -architectures such as PPC and ARM in due course.
  19.134 +Pentium~IV, Xeon, AMD~Athlon, AMD~Duron). Multiprocessor machines are
  19.135 +supported, and there is basic support for HyperThreading (SMT), although
  19.136 +this remains a topic for ongoing research. A port specifically for
  19.137 +x86/64 is in progress. Xen already runs on such systems in 32-bit legacy
  19.138 +mode. In addition, a port to the IA64 architecture is approaching
  19.139 +completion. We hope to add other architectures such as PPC and ARM in
  19.140 +due course.
  19.141  
  19.142 -Xen can currently use up to 4GB of memory.  It is possible for x86
  19.143 -machines to address up to 64GB of physical memory but there are no
  19.144 -plans to support these systems: The x86/64 port is the planned route
  19.145 -to supporting larger memory sizes.
  19.146 +Xen can currently use up to 4GB of memory. It is possible for x86
  19.147 +machines to address up to 64GB of physical memory but there are no plans
  19.148 +to support these systems: The x86/64 port is the planned route to
  19.149 +supporting larger memory sizes.
  19.150  
  19.151 -Xen offloads most of the hardware support issues to the guest OS
  19.152 -running in Domain~0.  Xen itself contains only the code required to
  19.153 -detect and start secondary processors, set up interrupt routing, and
  19.154 -perform PCI bus enumeration.  Device drivers run within a privileged
  19.155 -guest OS rather than within Xen itself. This approach provides
  19.156 -compatibility with the majority of device hardware supported by Linux.
  19.157 -The default XenLinux build contains support for relatively modern
  19.158 -server-class network and disk hardware, but you can add support for
  19.159 -other hardware by configuring your XenLinux kernel in the normal way.
  19.160 +Xen offloads most of the hardware support issues to the guest OS running
  19.161 +in Domain~0. Xen itself contains only the code required to detect and
  19.162 +start secondary processors, set up interrupt routing, and perform PCI
  19.163 +bus enumeration. Device drivers run within a privileged guest OS rather
  19.164 +than within Xen itself. This approach provides compatibility with the
  19.165 +majority of device hardware supported by Linux. The default XenLinux
  19.166 +build contains support for relatively modern server-class network and
  19.167 +disk hardware, but you can add support for other hardware by configuring
  19.168 +your XenLinux kernel in the normal way.
  19.169  
  19.170  
  19.171  \section{History}
  19.172 @@ -119,24 +129,24 @@ distributed computing''. Xen plays a key
  19.173  efficiently partition a single machine to enable multiple independent
  19.174  clients to run their operating systems and applications in an
  19.175  environment. This environment provides protection, resource isolation
  19.176 -and accounting.  The project web page contains further information
  19.177 -along with pointers to papers and technical reports:
  19.178 +and accounting. The project web page contains further information along
  19.179 +with pointers to papers and technical reports:
  19.180  \path{http://www.cl.cam.ac.uk/xeno}
  19.181  
  19.182 -Xen has grown into a fully-fledged project in its own right, enabling
  19.183 -us to investigate interesting research issues regarding the best
  19.184 -techniques for virtualising resources such as the CPU, memory, disk
  19.185 -and network.  The project has been bolstered by support from Intel
  19.186 -Research Cambridge and HP Labs, who are now working closely with us.
  19.187 +Xen has grown into a fully-fledged project in its own right, enabling us
  19.188 +to investigate interesting research issues regarding the best techniques
  19.189 +for virtualizing resources such as the CPU, memory, disk and network.
  19.190 +The project has been bolstered by support from Intel Research Cambridge
  19.191 +and HP Labs, who are now working closely with us.
  19.192  
  19.193  Xen was first described in a paper presented at SOSP in
  19.194  2003\footnote{\tt
  19.195 -  http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the
  19.196 -first public release (1.0) was made that October.  Since then, Xen has
  19.197 +  http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the first
  19.198 +public release (1.0) was made that October. Since then, Xen has
  19.199  significantly matured and is now used in production scenarios on many
  19.200  sites.
  19.201  
  19.202  Xen 3.0 features greatly enhanced hardware support, configuration
  19.203  flexibility, usability and a larger complement of supported operating
  19.204  systems. This latest release takes Xen a step closer to becoming the
  19.205 -definitive open source solution for virtualisation.
  19.206 +definitive open source solution for virtualization.
    20.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    20.2 +++ b/docs/src/user/known_problems.tex	Sat Dec 03 17:52:38 2005 -0700
    20.3 @@ -0,0 +1,3 @@
    20.4 +\chapter{Known Problems}
    20.5 +
    20.6 +Problem One: No Known Problems Chapter.
    21.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    21.2 +++ b/docs/src/user/logfiles.tex	Sat Dec 03 17:52:38 2005 -0700
    21.3 @@ -0,0 +1,3 @@
    21.4 +\chapter{Log Files}
    21.5 +
    21.6 +Placeholder.
    22.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    22.2 +++ b/docs/src/user/memory_management.tex	Sat Dec 03 17:52:38 2005 -0700
    22.3 @@ -0,0 +1,51 @@
    22.4 +\chapter{Memory Management}
    22.5 +
    22.6 +\section{Managing Domain Memory}
    22.7 +
    22.8 +XenLinux domains have the ability to relinquish/reclaim machine
    22.9 +memory at the request of the administrator or the user of the domain.
   22.10 +
   22.11 +\subsection{Setting memory footprints from dom0}
   22.12 +
   22.13 +The machine administrator can request that a domain alter its memory
   22.14 +footprint using the \path{xm mem-set} command.  For instance, we can
   22.15 +request that our example ttylinux domain reduce its memory footprint
   22.16 +to 32 megabytes.
   22.17 +
   22.18 +\begin{verbatim}
   22.19 +# xm mem-set ttylinux 32
   22.20 +\end{verbatim}
   22.21 +
   22.22 +We can now see the result of this in the output of \path{xm list}:
   22.23 +
   22.24 +\begin{verbatim}
   22.25 +# xm list
   22.26 +Name              Id  Mem(MB)  CPU  State  Time(s)  Console
   22.27 +Domain-0           0      251    0  r----    172.2        
   22.28 +ttylinux           5       31    0  -b---      4.3    9605
   22.29 +\end{verbatim}
   22.30 +
   22.31 +The domain has responded to the request by returning memory to Xen. We
   22.32 +can restore the domain to its original size using the command line:
   22.33 +
   22.34 +\begin{verbatim}
   22.35 +# xm mem-set ttylinux 64
   22.36 +\end{verbatim}
   22.37 +
   22.38 +\subsection{Setting memory footprints from within a domain}
   22.39 +
   22.40 +The virtual file \path{/proc/xen/balloon} allows the owner of a domain
   22.41 +to adjust their own memory footprint.  Reading the file (e.g.\
   22.42 +\path{cat /proc/xen/balloon}) prints out the current memory footprint
   22.43 +of the domain.  Writing the file (e.g.\ \path{echo new\_target >
   22.44 +  /proc/xen/balloon}) requests that the kernel adjust the domain's
   22.45 +memory footprint to a new value.
   22.46 +
   22.47 +\subsection{Setting memory limits}
   22.48 +
   22.49 +Xen associates a memory size limit with each domain.  By default, this
   22.50 +is the amount of memory the domain is originally started with,
   22.51 +preventing the domain from ever growing beyond this size.  To permit a
   22.52 +domain to grow beyond its original allocation or to prevent a domain
   22.53 +you've shrunk from reclaiming the memory it relinquished, use the
   22.54 +\path{xm maxmem} command.
    23.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    23.2 +++ b/docs/src/user/migrating_domains.tex	Sat Dec 03 17:52:38 2005 -0700
    23.3 @@ -0,0 +1,70 @@
    23.4 +\chapter{Migrating Domains}
    23.5 +
    23.6 +\section{Domain Save and Restore}
    23.7 +
    23.8 +The administrator of a Xen system may suspend a virtual machine's
    23.9 +current state into a disk file in domain~0, allowing it to be resumed at
   23.10 +a later time.
   23.11 +
   23.12 +The ttylinux domain described earlier can be suspended to disk using the
   23.13 +command:
   23.14 +\begin{verbatim}
   23.15 +# xm save ttylinux ttylinux.xen
   23.16 +\end{verbatim}
   23.17 +
   23.18 +This will stop the domain named ``ttylinux'' and save its current state
   23.19 +into a file called \path{ttylinux.xen}.
   23.20 +
   23.21 +To resume execution of this domain, use the \path{xm restore} command:
   23.22 +\begin{verbatim}
   23.23 +# xm restore ttylinux.xen
   23.24 +\end{verbatim}
   23.25 +
   23.26 +This will restore the state of the domain and restart it. The domain
   23.27 +will carry on as before and the console may be reconnected using the
   23.28 +\path{xm console} command, as above.
   23.29 +
   23.30 +\section{Live Migration}
   23.31 +
   23.32 +Live migration is used to transfer a domain between physical hosts
   23.33 +whilst that domain continues to perform its usual activities --- from
   23.34 +the user's perspective, the migration should be imperceptible.
   23.35 +
   23.36 +To perform a live migration, both hosts must be running Xen / \xend\ and
   23.37 +the destination host must have sufficient resources (e.g.\ memory
   23.38 +capacity) to accommodate the domain after the move. Furthermore we
   23.39 +currently require both source and destination machines to be on the same
   23.40 +L2 subnet.
   23.41 +
   23.42 +Currently, there is no support for providing automatic remote access to
   23.43 +filesystems stored on local disk when a domain is migrated.
   23.44 +Administrators should choose an appropriate storage solution (i.e.\ SAN,
   23.45 +NAS, etc.) to ensure that domain filesystems are also available on their
   23.46 +destination node. GNBD is a good method for exporting a volume from one
   23.47 +machine to another. iSCSI can do a similar job, but is more complex to
   23.48 +set up.
   23.49 +
   23.50 +When a domain migrates, it's MAC and IP address move with it, thus it is
   23.51 +only possible to migrate VMs within the same layer-2 network and IP
   23.52 +subnet. If the destination node is on a different subnet, the
   23.53 +administrator would need to manually configure a suitable etherip or IP
   23.54 +tunnel in the domain~0 of the remote node.
   23.55 +
   23.56 +A domain may be migrated using the \path{xm migrate} command. To live
   23.57 +migrate a domain to another machine, we would use the command:
   23.58 +
   23.59 +\begin{verbatim}
   23.60 +# xm migrate --live mydomain destination.ournetwork.com
   23.61 +\end{verbatim}
   23.62 +
   23.63 +Without the \path{--live} flag, \xend\ simply stops the domain and
   23.64 +copies the memory image over to the new node and restarts it. Since
   23.65 +domains can have large allocations this can be quite time consuming,
   23.66 +even on a Gigabit network. With the \path{--live} flag \xend\ attempts
   23.67 +to keep the domain running while the migration is in progress, resulting
   23.68 +in typical `downtimes' of just 60--300ms.
   23.69 +
   23.70 +For now it will be necessary to reconnect to the domain's console on the
   23.71 +new machine using the \path{xm console} command. If a migrated domain
   23.72 +has any open network connections then they will be preserved, so SSH
   23.73 +connections do not have this limitation.
    24.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    24.2 +++ b/docs/src/user/monitoring_xen.tex	Sat Dec 03 17:52:38 2005 -0700
    24.3 @@ -0,0 +1,3 @@
    24.4 +\chapter{Monitoring Xen}
    24.5 +
    24.6 +Placeholder.
    25.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    25.2 +++ b/docs/src/user/network_management.tex	Sat Dec 03 17:52:38 2005 -0700
    25.3 @@ -0,0 +1,3 @@
    25.4 +\chapter{Network Management}
    25.5 +
    25.6 +Placeholder.
    26.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    26.2 +++ b/docs/src/user/options.tex	Sat Dec 03 17:52:38 2005 -0700
    26.3 @@ -0,0 +1,149 @@
    26.4 +\chapter{Build and Boot Options} 
    26.5 +
    26.6 +This chapter describes the build- and boot-time options which may be
    26.7 +used to tailor your Xen system.
    26.8 +
    26.9 +
   26.10 +\section{Xen Build Options}
   26.11 +
   26.12 +Xen provides a number of build-time options which should be set as
   26.13 +environment variables or passed on make's command-line.
   26.14 +
   26.15 +\begin{description}
   26.16 +\item[verbose=y] Enable debugging messages when Xen detects an
   26.17 +  unexpected condition.  Also enables console output from all domains.
   26.18 +\item[debug=y] Enable debug assertions.  Implies {\bf verbose=y}.
   26.19 +  (Primarily useful for tracing bugs in Xen).
   26.20 +\item[debugger=y] Enable the in-Xen debugger. This can be used to
   26.21 +  debug Xen, guest OSes, and applications.
   26.22 +\item[perfc=y] Enable performance counters for significant events
   26.23 +  within Xen. The counts can be reset or displayed on Xen's console
   26.24 +  via console control keys.
   26.25 +\item[trace=y] Enable per-cpu trace buffers which log a range of
   26.26 +  events within Xen for collection by control software.
   26.27 +\end{description}
   26.28 +
   26.29 +
   26.30 +\section{Xen Boot Options}
   26.31 +\label{s:xboot}
   26.32 +
   26.33 +These options are used to configure Xen's behaviour at runtime.  They
   26.34 +should be appended to Xen's command line, either manually or by
   26.35 +editing \path{grub.conf}.
   26.36 +
   26.37 +\begin{description}
   26.38 +\item [ noreboot ] Don't reboot the machine automatically on errors.
   26.39 +  This is useful to catch debug output if you aren't catching console
   26.40 +  messages via the serial line.
   26.41 +\item [ nosmp ] Disable SMP support.  This option is implied by
   26.42 +  `ignorebiostables'.
   26.43 +\item [ watchdog ] Enable NMI watchdog which can report certain
   26.44 +  failures.
   26.45 +\item [ noirqbalance ] Disable software IRQ balancing and affinity.
   26.46 +  This can be used on systems such as Dell 1850/2850 that have
   26.47 +  workarounds in hardware for IRQ-routing issues.
   26.48 +\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify
   26.49 +  a list of pages not to be allocated for use because they contain bad
   26.50 +  bytes. For example, if your memory tester says that byte 0x12345678
   26.51 +  is bad, you would place `badpage=0x12345' on Xen's command line.
   26.52 +\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$
   26.53 +  com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\
   26.54 +  Xen supports up to two 16550-compatible serial ports.  For example:
   26.55 +  `com1=9600, 8n1, 0x408, 5' maps COM1 to a 9600-baud port, 8 data
   26.56 +  bits, no parity, 1 stop bit, I/O port base 0x408, IRQ 5.  If some
   26.57 +  configuration options are standard (e.g., I/O base and IRQ), then
   26.58 +  only a prefix of the full configuration string need be specified. If
   26.59 +  the baud rate is pre-configured (e.g., by the bootloader) then you
   26.60 +  can specify `auto' in place of a numeric baud rate.
   26.61 +\item [ console=$<$specifier list$>$ ] Specify the destination for Xen
   26.62 +  console I/O.  This is a comma-separated list of, for example:
   26.63 +  \begin{description}
   26.64 +  \item[ vga ] Use VGA console and allow keyboard input.
   26.65 +  \item[ com1 ] Use serial port com1.
   26.66 +  \item[ com2H ] Use serial port com2. Transmitted chars will have the
   26.67 +    MSB set. Received chars must have MSB set.
   26.68 +  \item[ com2L] Use serial port com2. Transmitted chars will have the
   26.69 +    MSB cleared. Received chars must have MSB cleared.
   26.70 +  \end{description}
   26.71 +  The latter two examples allow a single port to be shared by two
   26.72 +  subsystems (e.g.\ console and debugger). Sharing is controlled by
   26.73 +  MSB of each transmitted/received character.  [NB. Default for this
   26.74 +  option is `com1,vga']
   26.75 +\item [ sync\_console ] Force synchronous console output. This is
   26.76 +  useful if you system fails unexpectedly before it has sent all
   26.77 +  available output to the console. In most cases Xen will
   26.78 +  automatically enter synchronous mode when an exceptional event
   26.79 +  occurs, but this option provides a manual fallback.
   26.80 +\item [ conswitch=$<$switch-char$><$auto-switch-char$>$ ] Specify how
   26.81 +  to switch serial-console input between Xen and DOM0. The required
   26.82 +  sequence is CTRL-$<$switch-char$>$ pressed three times. Specifying
   26.83 +  the backtick character disables switching.  The
   26.84 +  $<$auto-switch-char$>$ specifies whether Xen should auto-switch
   26.85 +  input to DOM0 when it boots --- if it is `x' then auto-switching is
   26.86 +  disabled.  Any other value, or omitting the character, enables
   26.87 +  auto-switching.  [NB. Default switch-char is `a'.]
   26.88 +\item [ nmi=xxx ]
   26.89 +  Specify what to do with an NMI parity or I/O error. \\
   26.90 +  `nmi=fatal':  Xen prints a diagnostic and then hangs. \\
   26.91 +  `nmi=dom0':   Inform DOM0 of the NMI. \\
   26.92 +  `nmi=ignore': Ignore the NMI.
   26.93 +\item [ mem=xxx ] Set the physical RAM address limit. Any RAM
   26.94 +  appearing beyond this physical address in the memory map will be
   26.95 +  ignored. This parameter may be specified with a B, K, M or G suffix,
   26.96 +  representing bytes, kilobytes, megabytes and gigabytes respectively.
   26.97 +  The default unit, if no suffix is specified, is kilobytes.
   26.98 +\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to
   26.99 +  domain0. In Xen 3.x the parameter may be specified with a B, K, M or
  26.100 +  G suffix, representing bytes, kilobytes, megabytes and gigabytes
  26.101 +  respectively; if no suffix is specified, the parameter defaults to
  26.102 +  kilobytes. In previous versions of Xen, suffixes were not supported
  26.103 +  and the value is always interpreted as kilobytes.
  26.104 +\item [ tbuf\_size=xxx ] Set the size of the per-cpu trace buffers, in
  26.105 +  pages (default 1).  Note that the trace buffers are only enabled in
  26.106 +  debug builds.  Most users can ignore this feature completely.
  26.107 +\item [ sched=xxx ] Select the CPU scheduler Xen should use.  The
  26.108 +  current possibilities are `bvt' (default), `atropos' and `rrobin'.
  26.109 +  For more information see Section~\ref{s:sched}.
  26.110 +\item [ apic\_verbosity=debug,verbose ] Print more detailed
  26.111 +  information about local APIC and IOAPIC configuration.
  26.112 +\item [ lapic ] Force use of local APIC even when left disabled by
  26.113 +  uniprocessor BIOS.
  26.114 +\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if
  26.115 +  enabled by the BIOS.
  26.116 +\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform.
  26.117 +  This can usually be probed automatically.
  26.118 +\end{description}
  26.119 +
  26.120 +In addition, the following options may be specified on the Xen command
  26.121 +line. Since domain 0 shares responsibility for booting the platform,
  26.122 +Xen will automatically propagate these options to its command line.
  26.123 +These options are taken from Linux's command-line syntax with
  26.124 +unchanged semantics.
  26.125 +
  26.126 +\begin{description}
  26.127 +\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and
  26.128 +  domain 0) parses the BIOS ACPI tables.
  26.129 +\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to
  26.130 +  ignore timer-interrupt override instructions specified by the BIOS
  26.131 +  ACPI tables.
  26.132 +\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs
  26.133 +  that are present in the system, and instead continue to use the
  26.134 +  legacy PIC.
  26.135 +\end{description} 
  26.136 +
  26.137 +
  26.138 +\section{XenLinux Boot Options}
  26.139 +
  26.140 +In addition to the standard Linux kernel boot options, we support:
  26.141 +\begin{description}
  26.142 +\item[ xencons=xxx ] Specify the device node to which the Xen virtual
  26.143 +  console driver is attached. The following options are supported:
  26.144 +  \begin{center}
  26.145 +    \begin{tabular}{l}
  26.146 +      `xencons=off': disable virtual console \\
  26.147 +      `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\
  26.148 +      `xencons=ttyS': attach console to /dev/ttyS0
  26.149 +    \end{tabular}
  26.150 +\end{center}
  26.151 +The default is ttyS for dom0 and tty for all other domains.
  26.152 +\end{description}
    27.1 --- a/docs/src/user/redhat.tex	Sun Dec 04 01:34:25 2005 +0100
    27.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
    27.3 @@ -1,61 +0,0 @@
    27.4 -\chapter{Installing Xen / XenLinux on Red~Hat or Fedora Core}
    27.5 -
    27.6 -When using Xen / XenLinux on a standard Linux distribution there are a
    27.7 -couple of things to watch out for:
    27.8 -
    27.9 -Note that, because domains greater than 0 don't have any privileged
   27.10 -access at all, certain commands in the default boot sequence will fail
   27.11 -e.g.\ attempts to update the hwclock, change the console font, update
   27.12 -the keytable map, start apmd (power management), or gpm (mouse
   27.13 -cursor).  Either ignore the errors (they should be harmless), or
   27.14 -remove them from the startup scripts.  Deleting the following links
   27.15 -are a good start: {\path{S24pcmcia}}, {\path{S09isdn}},
   27.16 -{\path{S17keytable}}, {\path{S26apmd}}, {\path{S85gpm}}.
   27.17 -
   27.18 -If you want to use a single root file system that works cleanly for
   27.19 -both domain~0 and unprivileged domains, a useful trick is to use
   27.20 -different `init' run levels. For example, use run level 3 for
   27.21 -domain~0, and run level 4 for other domains. This enables different
   27.22 -startup scripts to be run in depending on the run level number passed
   27.23 -on the kernel command line.
   27.24 -
   27.25 -If using NFS root files systems mounted either from an external server
   27.26 -or from domain0 there are a couple of other gotchas.  The default
   27.27 -{\path{/etc/sysconfig/iptables}} rules block NFS, so part way through
   27.28 -the boot sequence things will suddenly go dead.
   27.29 -
   27.30 -If you're planning on having a separate NFS {\path{/usr}} partition,
   27.31 -the RH9 boot scripts don't make life easy - they attempt to mount NFS
   27.32 -file systems way to late in the boot process. The easiest way I found
   27.33 -to do this was to have a {\path{/linuxrc}} script run ahead of
   27.34 -{\path{/sbin/init}} that mounts {\path{/usr}}:
   27.35 -
   27.36 -\begin{quote}
   27.37 -  \begin{small}\begin{verbatim}
   27.38 - #!/bin/bash
   27.39 - /sbin/ipconfig lo 127.0.0.1
   27.40 - /sbin/portmap
   27.41 - /bin/mount /usr
   27.42 - exec /sbin/init "$@" <>/dev/console 2>&1
   27.43 -\end{verbatim}\end{small}
   27.44 -\end{quote}
   27.45 -
   27.46 -%% $ XXX SMH: font lock fix :-)
   27.47 -
   27.48 -The one slight complication with the above is that
   27.49 -{\path{/sbin/portmap}} is dynamically linked against
   27.50 -{\path{/usr/lib/libwrap.so.0}} Since this is in {\path{/usr}}, it
   27.51 -won't work. This can be solved by copying the file (and link) below
   27.52 -the {\path{/usr}} mount point, and just let the file be `covered' when
   27.53 -the mount happens.
   27.54 -
   27.55 -In some installations, where a shared read-only {\path{/usr}} is being
   27.56 -used, it may be desirable to move other large directories over into
   27.57 -the read-only {\path{/usr}}. For example, you might replace
   27.58 -{\path{/bin}}, {\path{/lib}} and {\path{/sbin}} with links into
   27.59 -{\path{/usr/root/bin}}, {\path{/usr/root/lib}} and
   27.60 -{\path{/usr/root/sbin}} respectively. This creates other problems for
   27.61 -running the {\path{/linuxrc}} script, requiring bash, portmap, mount,
   27.62 -ifconfig, and a handful of other shared libraries to be copied below
   27.63 -the mount point --- a simple statically-linked C program would solve
   27.64 -this problem.
    28.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    28.2 +++ b/docs/src/user/rhel.tex	Sat Dec 03 17:52:38 2005 -0700
    28.3 @@ -0,0 +1,127 @@
    28.4 +\chapter{Installing Xen on Red Hat Enterprise Linux (RHEL) 4.1}
    28.5 +
    28.6 +RedHat Enterprise Linux is the enterprise-grade, certified version of the Red Hat distribution. This section includes resolving dependencies using yum, installing Xen, and creating an initrd for Xen.
    28.7 +
    28.8 +Stable binary release install
    28.9 +Source install
   28.10 +\section{Stable binary release install}
   28.11 +
   28.12 +\subsection{Setup yum repository}
   28.13 +
   28.14 +Setup your yum repository to Dag's Yum Repository or similar. Dag's is recommended.
   28.15 +
   28.16 +\subsection{Required Packages}
   28.17 +
   28.18 +These packages are required:
   28.19 +
   28.20 +\begin{itemize}
   28.21 +\item bridge-utils
   28.22 +\item curl
   28.23 +\item libidn
   28.24 +\item sysfsutils
   28.25 +\end{itemize}
   28.26 +
   28.27 +Use yum to install these packages.
   28.28 +
   28.29 +\begin{verbatim}
   28.30 +yum install bridge-utils curl libidn sysfsutils
   28.31 +\end{verbatim}
   28.32 +
   28.33 +\subsection{Download Xen}
   28.34 +
   28.35 +\subsection{Download the binary tarball}
   28.36 +Download the Xen 3.0 binary tarball from the XenSource downloads page:
   28.37 +
   28.38 +\begin{quote} {\tt http://www.xensource.com/downloads/}
   28.39 +\end{quote}
   28.40 +
   28.41 +\subsection{Extract and Install}
   28.42 +
   28.43 +\begin{verbatim}
   28.44 +tar zxvf xen-unstable-install-x86\_32.tgz
   28.45 +
   28.46 +cd xen-unstable-install
   28.47 +
   28.48 +./install.sh 
   28.49 +\end{verbatim}
   28.50 +
   28.51 +
   28.52 +\subsection{Disable TLS}
   28.53 +
   28.54 +\begin{verbatim}
   28.55 +mv /lib/tls /lib/tls.disabled
   28.56 +\end{verbatim}
   28.57 +
   28.58 +\subsection{Creating initrd}
   28.59 +
   28.60 +You can use the distro's initrd. The following steps show you how to create one yourself for dom0 and domU. The example uses a Domain0 image, so to adatp it, simply use the appropriate image for DomainU.
   28.61 +
   28.62 +\begin{verbatim}
   28.63 +run depmod 2.x.y-xen0 to re-create modules dependency
   28.64 +
   28.65 +mkinitrd  /boot/initrd-2.x.y-xen0.img  2.x.y-xen0 
   28.66 +\end{verbatim}
   28.67 +
   28.68 +If you get an error
   28.69 +
   28.70 +\begin{verbatim}
   28.71 +   "No module xxx found for kernel 2.x.y-xen0, aborting."
   28.72 +\end{verbatim}
   28.73 +
   28.74 +uncheck xxx in \path{/etc/modprobe.conf} if you don't want support for xxx. If you know that its built into kernel (to check \path{grep -i xxx config-2.6.12-xen0}) you can do
   28.75 +
   28.76 +\begin{verbatim}
   28.77 +mkinitrd  --builtin=aic7xxx  ./2.6.12-xen0.img  2.6.12-xen0
   28.78 +\end{verbatim}
   28.79 +
   28.80 +If another yyy module is reported as "not found,"
   28.81 +
   28.82 +\begin{verbatim}
   28.83 +mkinitrd  --builtin=xxx --builtin=yyy ./2.6.12-xen0.img  2.6.12-xen0
   28.84 +\end{verbatim}
   28.85 +
   28.86 +\subsection{Grub Configuration}
   28.87 +
   28.88 +As usual, you need to make entry in grub configuration file for Xen. Here's a sample grub entry.
   28.89 +
   28.90 +{\small
   28.91 +\begin{verbatim}
   28.92 +title  Xen/RHEL 4.1
   28.93 +       kernel (hd0,5)/boot/xen.gz dom0\_mem=256000
   28.94 +       module (hd0,5)/boot/vmlinuz-2.6.11.12-xen0 root=/dev/hda6
   28.95 +       module (hd0,5)/boot/initrd-2.6.11.12-xen0.img
   28.96 +\end{verbatim}
   28.97 +}
   28.98 +
   28.99 +\section{Source install}
  28.100 +
  28.101 +
  28.102 +\subsection{Download Source Tarball}
  28.103 +
  28.104 +\subsection{Download the binary tarball}
  28.105 +Download the Xen 3.0 binary tarball from the XenSource downloads page:
  28.106 +
  28.107 +\begin{quote} {\tt http://www.xensource.com/downloads/}
  28.108 +\end{quote}
  28.109 +
  28.110 +\subsection{Pre-requisites to build from source}
  28.111 +
  28.112 +Make sure you have all packages. If you had chosen to install Development tools during the distro installation, you should not need to install any extra packages. If not, install the following:
  28.113 +
  28.114 +\begin{itemize}
  28.115 +\item gcc-3.4.3-22.1
  28.116 +\item python-devel-2.3.4-14.1
  28.117 +\item zlib-devel-1.2.1.2-1
  28.118 +\item curl-devel-7.12.1-5.rhel4
  28.119 +\end{itemize}
  28.120 +
  28.121 +\subsection{Install Xen}
  28.122 +
  28.123 +\begin{verbatim}
  28.124 +tar zxvf xen-unstable-src.tgz
  28.125 +cd xen-unstable/
  28.126 +make world
  28.127 +make install
  28.128 +\end{verbatim}
  28.129 +
  28.130 +The rest of the steps follow as with the binary tarball installation.
    29.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    29.2 +++ b/docs/src/user/scheduler_management.tex	Sat Dec 03 17:52:38 2005 -0700
    29.3 @@ -0,0 +1,3 @@
    29.4 +\chapter{Scheduler Management}
    29.5 +
    29.6 +Placeholder.
    30.1 --- a/docs/src/user/start_addl_dom.tex	Sun Dec 04 01:34:25 2005 +0100
    30.2 +++ b/docs/src/user/start_addl_dom.tex	Sat Dec 03 17:52:38 2005 -0700
    30.3 @@ -1,7 +1,7 @@
    30.4  \chapter{Starting Additional Domains}
    30.5  
    30.6  The first step in creating a new domain is to prepare a root
    30.7 -filesystem for it to boot from.  Typically, this might be stored in a
    30.8 +filesystem for it to boot.  Typically, this might be stored in a
    30.9  normal partition, an LVM or other volume manager partition, a disk
   30.10  file or on an NFS server.  A simple way to do this is simply to boot
   30.11  from your standard OS install CD and install the distribution into
   30.12 @@ -12,6 +12,10 @@ To start the \xend\ control daemon, type
   30.13    \verb!# xend start!
   30.14  \end{quote}
   30.15  
   30.16 +%% KMS: If we're going to use '# cmd' syntax we should be consistent
   30.17 +%% about it and have a conventions section noting that '#' == root
   30.18 +%% prompt.
   30.19 +
   30.20  If you wish the daemon to start automatically, see the instructions in
   30.21  Section~\ref{s:xend}. Once the daemon is running, you can use the
   30.22  \path{xm} tool to monitor and maintain the domains running on your
   30.23 @@ -70,11 +74,21 @@ you may wish to edit include:
   30.24  You may also want to edit the {\bf vif} variable in order to choose
   30.25  the MAC address of the virtual ethernet interface yourself.  For
   30.26  example:
   30.27 +%% KMS:  We should indicate "safe" ranges to use.
   30.28  \begin{quote}
   30.29  \verb_vif = ['mac=00:06:AA:F6:BB:B3']_
   30.30  \end{quote}
   30.31  If you do not set this variable, \xend\ will automatically generate a
   30.32 -random MAC address from an unused range.
   30.33 +random MAC address from the range 00:16:3E:xx:xx:xx.  Generated MACs are
   30.34 +not tested for possible collisions, however likelihood of this is low at
   30.35 +\begin{math} 1:2^{48}.\end{math}  XenSource Inc.  gives permission for
   30.36 +anyone to use addresses randomly allocated from this range for use by
   30.37 +their Xen domains.
   30.38 +
   30.39 +
   30.40 +For a list of IEEE
   30.41 +assigned MAC organizationally unique identifiers (OUI), see \newline
   30.42 +{\tt http://standards.ieee.org/regauth/oui/oui.txt}
   30.43  
   30.44  
   30.45  \section{Booting the Domain}
    31.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    31.2 +++ b/docs/src/user/suse.tex	Sat Dec 03 17:52:38 2005 -0700
    31.3 @@ -0,0 +1,3 @@
    31.4 +\chapter{Installing Xen on SuSE or SuSE Linux Enterprise Server (SLES)}
    31.5 +
    31.6 +Placeholder.
    32.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    32.2 +++ b/docs/src/user/testing.tex	Sat Dec 03 17:52:38 2005 -0700
    32.3 @@ -0,0 +1,3 @@
    32.4 +\chapter{Testing Xen}
    32.5 +
    32.6 +Placeholder.
    33.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    33.2 +++ b/docs/src/user/xenstat.tex	Sat Dec 03 17:52:38 2005 -0700
    33.3 @@ -0,0 +1,3 @@
    33.4 +\chapter{xenstat}
    33.5 +
    33.6 +Placeholder.
    34.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    34.2 +++ b/docs/src/user/xentrace.tex	Sat Dec 03 17:52:38 2005 -0700
    34.3 @@ -0,0 +1,3 @@
    34.4 +\chapter{xentrace}
    34.5 +
    34.6 +Placeholder.