Xen project Mailing List

[Xen-changelog] Merge docs

From: Xen patchbot -unstable <patchbot-unstable@xxxxxxxxxxxxxxxxxxx>

Date: Sun, 04 Dec 2005 05:32:09 +0000

Delivery-date: Sun, 04 Dec 2005 05:32:47 +0000

List-id: BK change log <xen-changelog.lists.xensource.com>

# HG changeset patch # User rread@xxxxxxxxxxxxxxxxxxxxxxxxxxx # Node ID 8098cc1daac47f5ac371947a669b9ba15c6cf3f4 # Parent 757218700a406b69fc0d5108b408f35884ae3cec # Parent bc7567741a4c44b1d6b18b1deca3ce1a7e5721fd Merge docs diff -r 757218700a40 -r 8098cc1daac4 docs/src/user.tex --- a/docs/src/user.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user.tex Sun Dec 4 00:52:38 2005 @@ -1,3 +1,4 @@ +\batchmode \documentclass[11pt,twoside,final,openright]{report} \usepackage{a4,graphicx,html,parskip,setspace,times,xspace} \setstretch{1.15} @@ -29,10 +30,10 @@ \end{center} {\bf DISCLAIMER: This documentation is currently under active - development and as such there may be mistakes and omissions --- - watch out for these and please report any you find to the - developers' mailing list. Contributions of material, suggestions - and corrections are welcome.} + development and as such there may be mistakes and omissions --- watch + out for these and please report any you find to the developers' + mailing list. Contributions of material, suggestions and corrections + are welcome.} \vfill \cleardoublepage @@ -60,102 +61,121 @@ \setstretch{1.1} -\part{Introduction and Tutorial} - %% Chapter Introduction moved to introduction.tex \include{src/user/introduction} -%% Chapter Installation moved to installation.tex + +\part{Installation} + +%% Chapter Basic Installation \include{src/user/installation} -%% Chapter Starting Additional Domains moved to start_addl_dom.tex +%% Chapter Installing Xen on Debian +\include{src/user/debian} + +%% Chapter Installing Xen on Fedora Core +\include{src/user/fedora} + +%% Chapter Installing Xen on Gentoo Linux +\include{src/user/gentoo} + +%% Chapter Installing Xen on SuSE or SuSE SLES +\include{src/user/suse} + +%% Chapter Installing Xen on Red Hat Enterprise Linux (RHEL) +\include{src/user/rhel} + +% Chapter dom0 Installation +\include{src/user/dom0_installation} + +% Chapter domU Installation +\include{src/user/domU_installation} + +% Building Xen +\include{src/user/building_xen} + +% Booting Xen +\include{src/user/booting_xen} + + +\part{Configuration and Management} + +%% Chapter Domain Management Tools and Daemons +\include{src/user/domain_mgmt} + +%% Chapter Starting Additional Domains \include{src/user/start_addl_dom} -%% Chapter Domain Management Tools moved to domain_mgmt.tex -\include{src/user/domain_mgmt} - -%% Chapter Domain Filesystem Storage moved to domain_filesystem.tex +%% Chapter Domain Configuration +\include{src/user/domain_configuration} + +% Chapter Console Management +\include{src/user/console_management} + +% Chapter Network Management +\include{src/user/network_management} + +% Chapter Storage and FileSytem Management \include{src/user/domain_filesystem} - - -\part{User Reference Documentation} - -%% Chapter Control Software moved to control_software.tex -\include{src/user/control_software} - -%% Chapter Domain Configuration moved to domain_configuration.tex -\include{src/user/domain_configuration} +% Chapter Memory Management +\include{src/user/memory_management} + +% Chapter CPU Management +\include{src/user/cpu_management} + +% Chapter Scheduler Management +\include{src/user/scheduler_management} + +% Chapter Migrating Domains +\include{src/user/migrating_domains} %% Chapter Securing Xen \include{src/user/securing_xen} -%% Chapter Build, Boot and Debug Options moved to build.tex -\include{src/user/build} - - -\chapter{Further Support} - -If you have questions that are not answered by this manual, the -sources of information listed below may be of interest to you. Note -that bug reports, suggestions and contributions related to the -software (or the documentation) should be sent to the Xen developers' -mailing list (address below). - - -\section{Other Documentation} - -For developers interested in porting operating systems to Xen, the -\emph{Xen Interface Manual} is distributed in the \path{docs/} -directory of the Xen source distribution. - -% Various HOWTOs are available in \path{docs/HOWTOS} but this content -% is being integrated into this manual. - - -\section{Online References} - -The official Xen web site is found at: -\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/} -\end{quote} - -This contains links to the latest versions of all online -documentation, including the latest version of the FAQ. - - -\section{Mailing Lists} - -There are currently four official Xen mailing lists: - -\begin{description} -\item[xen-devel@xxxxxxxxxxxxxxxxxxx] Used for development - discussions and bug reports. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-devel}} -\item[xen-users@xxxxxxxxxxxxxxxxxxx] Used for installation and usage - discussions and requests for help. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-users}} -\item[xen-announce@xxxxxxxxxxxxxxxxxxx] Used for announcements only. - Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-announce}} -\item[xen-changelog@xxxxxxxxxxxxxxxxxxx] Changelog feed - from the unstable and 2.0 trees - developer oriented. Subscribe at: \\ - {\small {\tt http://lists.xensource.com/xen-changelog}} -\end{description} - - + +\part{Monitoring and Troubleshooting} + +%% Chapter Monitoring Xen +\include{src/user/monitoring_xen} + +% Chapter xenstat +\include{src/user/xenstat} + +% Chapter Log Files +\include{src/user/logfiles} + +%% Chapter Debugging +\include{src/user/debugging} + +% Chapter xentrace +\include{src/user/xentrace} + +%% Chapter Known Problems +\include{src/user/known_problems} + +%% Chapter Testing Xen +\include{src/user/testing} + + +\part{Reference Documentation} + +%% Chapter Control Software +\include{src/user/control_software} + +%% Chapter Build and Boot Options +\include{src/user/options} + +%% Chapter Further Support +\include{src/user/further_support} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix - -%% Chapter Installing Xen / XenLinux on Debian moved to debian.tex -\include{src/user/debian} - -%% Chapter Installing Xen on Red Hat moved to redhat.tex -\include{src/user/redhat} %% Chapter Glossary of Terms moved to glossary.tex \include{src/user/glossary} - - \end{document} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/control_software.tex --- a/docs/src/user/control_software.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/control_software.tex Sun Dec 4 00:52:38 2005 @@ -1,101 +1,10 @@ \chapter{Control Software} - -The Xen control software includes the \xend\ node control daemon -(which must be running), the xm command line tools, and the prototype -xensv web interface. - -\section{\Xend\ (node control daemon)} -\label{s:xend} - -The Xen Daemon (\Xend) performs system management functions related to -virtual machines. It forms a central point of control for a machine -and can be controlled using an HTTP-based protocol. \Xend\ must be -running in order to start and manage virtual machines. - -\Xend\ must be run as root because it needs access to privileged -system management functions. A small set of commands may be issued on -the \xend\ command line: - -\begin{tabular}{ll} - \verb!# xend start! & start \xend, if not already running \\ - \verb!# xend stop! & stop \xend\ if already running \\ - \verb!# xend restart! & restart \xend\ if running, otherwise start it \\ - % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\ - \verb!# xend status! & indicates \xend\ status by its return code -\end{tabular} - -A SysV init script called {\tt xend} is provided to start \xend\ at -boot time. {\tt make install} installs this script in -\path{/etc/init.d}. To enable it, you have to make symbolic links in -the appropriate runlevel directories or use the {\tt chkconfig} tool, -where available. - -Once \xend\ is running, more sophisticated administration can be done -using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv -web interface (see Section~\ref{s:xensv}). - -As \xend\ runs, events will be logged to \path{/var/log/xend.log} and, -if the migration assistant daemon (\path{xfrd}) has been started, -\path{/var/log/xfrd.log}. These may be of use for troubleshooting -problems. - -\section{Xm (command line interface)} -\label{s:xm} - -The xm tool is the primary tool for managing Xen from the console. -The general format of an xm command line is: - -\begin{verbatim} -# xm command [switches] [arguments] [variables] -\end{verbatim} - -The available \emph{switches} and \emph{arguments} are dependent on -the \emph{command} chosen. The \emph{variables} may be set using -declarations of the form {\tt variable=value} and command line -declarations override any of the values in the configuration file -being used, including the standard variables described above and any -custom variables (for instance, the \path{xmdefconfig} file uses a -{\tt vmid} variable). - -The available commands are as follows: - -\begin{description} -\item[mem-set] Request a domain to adjust its memory footprint. -\item[create] Create a new domain. -\item[destroy] Kill a domain immediately. -\item[list] List running domains. -\item[shutdown] Ask a domain to shutdown. -\item[dmesg] Fetch the Xen (not Linux!) boot output. -\item[consoles] Lists the available consoles. -\item[console] Connect to the console for a domain. -\item[help] Get help on xm commands. -\item[save] Suspend a domain to disk. -\item[restore] Restore a domain from disk. -\item[pause] Pause a domain's execution. -\item[unpause] Un-pause a domain. -\item[pincpu] Pin a domain to a CPU. -\item[bvt] Set BVT scheduler parameters for a domain. -\item[bvt\_ctxallow] Set the BVT context switching allowance for the - system. -\item[atropos] Set the atropos parameters for a domain. -\item[rrobin] Set the round robin time slice for the system. -\item[info] Get information about the Xen host. -\item[call] Call a \xend\ HTTP API function directly. -\end{description} - -For a detailed overview of switches, arguments and variables to each -command try -\begin{quote} -\begin{verbatim} -# xm help command -\end{verbatim} -\end{quote} \section{Xensv (web control interface)} \label{s:xensv} Xensv is the experimental web control interface for managing a Xen -machine. It can be used to perform some (but not yet all) of the +machine. It can be used to perform some (but not yet all) of the management tasks that can be done using the xm tool. It can be started using: @@ -107,7 +16,7 @@ \verb_# xensv stop_ \end{quote} -By default, Xensv will serve out the web interface on port 8080. This +By default, Xensv will serve out the web interface on port 8080. This can be changed by editing \path{/usr/lib/python2.3/site-packages/xen/sv/params.py}. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/debian.tex --- a/docs/src/user/debian.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/debian.tex Sun Dec 4 00:52:38 2005 @@ -1,154 +1,173 @@ -\chapter{Installing Xen / XenLinux on Debian} +\chapter{Installing Xen/XenLinux on Debian} -The Debian project provides a tool called \path{debootstrap} which -allows a base Debian system to be installed into a filesystem without -requiring the host system to have any Debian-specific software (such -as \path{apt}). +This appendix describes installing Xen 3.0 on Debian Linux. -Here's some info how to install Debian 3.1 (Sarge) for an unprivileged -Xen domain: +Xen can be installed on Debian GNU/Linux using the following methods: -\begin{enumerate} +\begin{itemize} +\item From a binary tarball +\item From source +\item From debs +\end{itemize} -\item Set up Xen and test that it's working, as described earlier in - this manual. +\section{Installing from a binary tarball} +This section describes the process of installing Xen on Debian Sarge using the stable binary release tarball. -\item Create disk images for rootfs and swap. Alternatively, you might - create dedicated partitions, LVM logical volumes, etc.\ if that - suits your setup. +\subsection{Required Packages} +Install these Debian packages: + +\begin{itemize} +\item bridge-utils +\item libcurl3-dev +\item iproute +\item zlib1g-dev +\item python-dev +\end{itemize} + \begin{verbatim} -dd if=/dev/zero of=/path/diskimage bs=1024k count=size_in_mbytes -dd if=/dev/zero of=/path/swapimage bs=1024k count=size_in_mbytes +apt-get install bridge-utils libcurl3-dev iproute zlib1g-dev python-dev \end{verbatim} - If you're going to use this filesystem / disk image only as a - `template' for other vm disk images, something like 300 MB should be - enough. (of course it depends what kind of packages you are planning - to install to the template) -\item Create the filesystem and initialise the swap image +\subsection{Download the binary tarball} +Download the Xen 3.0 binary tarball from the XenSource downloads +page: + +\begin{quote} {\tt http://www.xensource.com/downloads/} +\end{quote} + +\subsection{Extract and Install} \begin{verbatim} -mkfs.ext3 /path/diskimage -mkswap /path/swapimage +# tar zxvf +xen-2.0.7-install-x86_32.tgz +# cd xen-2.0.7-install-x86_32.tgz +# ./install.sh \end{verbatim} -\item Mount the disk image for installation +If everything goes well, you should something like + \begin{verbatim} -mount -o loop /path/diskimage /mnt/disk +Installing Xen from +'./install' to '/'... + All done. + Checking to see whether prerequisite tools are installed... + All done. \end{verbatim} -\item Install \path{debootstrap}. Make sure you have debootstrap - installed on the host. If you are running Debian Sarge (3.1 / - testing) or unstable you can install it by running \path{apt-get - install debootstrap}. Otherwise, it can be downloaded from the - Debian project website. -\item Install Debian base to the disk image: +\subsection{Configure grub} +Make an entry in your grub configuration like below. + +{\small \begin{verbatim} -debootstrap --arch i386 sarge /mnt/disk \ - http://ftp.<countrycode>.debian.org/debian +title Xen on Debian +kernel (hd0,5)/boot/xen.gz dom0_mem=131000 +module (hd0,5)/boot/vmlinuz-2.6-xen0 root=/dex/hda6 ro console=tty0 +\end{verbatim} +} + +You can now boot into Xen by by choosing the right option from grub menu. + +\section{Installing from source} +\subsection{Required Packages} +Besides packages mentioned under binary tarball install, you will need: + +\begin{itemize} +\item gcc v3.2.x or v3.3.x +\item binutils +\item GNU make +\end{itemize} + + +\subsection{Download the source tree} +The Xen source tree is available as either a compressed source tarball +or as a clone of our master Mercurial repository. + +\begin{description} +\item[Obtaining the Source Tarball]\mbox{} \\ + Stable versions and daily snapshots of the Xen source tree are + available from the Xen download page: + \begin{quote} {\tt http://www.xensource.com/downloads/} + \end{quote} +\item[Obtaining the source via Mercurial]\mbox{} \\ + The source tree may also be obtained via the public Mercurial + repository hosted at: + \begin{quote}{\tt http://xenbits.xensource.com}. + \end{quote} See the instructions and the Getting Started Guide + referenced at: + \begin{quote} + {\tt http://www.xensource.com/downloads/}. + \end{quote} +\end{description} + +\subsection{Extract, build and install} + +\begin{verbatim} +# tar zxvf xen-3.0.0-src.tgz +# cd xen-3.0 +# make dist +#./install.sh \end{verbatim} - You can use any other Debian http/ftp mirror you want. +\section{Installing from debs} +This section describes the process of installing Xen on Debian Sarge using debs created by Edward Despard. -\item When debootstrap completes successfully, modify settings: +\subsection{Edward's announcement to xen-user list} +"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." + +\subsection{Adding apt source} +Add the following lines to \path{/etc/apt/sources.list}: + +\begin{quote} +{\small \begin{verbatim} -chroot /mnt/disk /bin/bash +deb http://tinyurl.com/8tpup +\end{verbatim} +} +\end{quote} + +Note: On Ubuntu, simple replace debian with ubuntu in the above. Replace xen-unstable with with xen-stable for a stable version. + +Now run \path{aptitude update} or \path{apt-get update}. Doing \path{apt-cache search xen}, you should see following packages in the output. + +\begin{itemize} +\item kernel-image-2.6.12-xen0 - Xen 2.6 kernel image +\item kernel-image-2.6.12-xenu - Xen 2.6 kernel image +\item kernel-patch-xen-2.6.12 - patch to kernel to support xen +\item libxen3.0 - control libraries for Xen +\item libxen-dev - development libraries for Xen +\item xen-doc - documentation for Xen +\item xen-hypervisor - Xen hypervisor kernel +\item xen-kernels - Xen kernels +\item xen - Package to install all of Xen +\item xen-tools - Tools for managing xen domains +\end{itemize} + +\subsection{Installing Xen} +You can now install xen using \path{apt-get}, \path{aptitude}, \path{synaptic}, etc. + +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. + +\begin{verbatim} +# apt-cache +depends xen + xen + Depends: xen-doc + Depends: xen-kernels + Depends: xen-hypervisor + Depends: xen-tools \end{verbatim} -Edit the following files using vi or nano and make needed changes: + +\subsection{xenkernels.conf} +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 + \begin{verbatim} -/etc/hostname -/etc/hosts -/etc/resolv.conf -/etc/network/interfaces -/etc/networks +label=Xen(3.0-unstable082205)/Linux(2.6.12)-- + xen=/boot/xen-3.0-unstable082205.gz + kernel=/boot/xen/dom0/vmlinuz-2.6.12-xen0 + mem=256000 + root=/dev/hda4 \end{verbatim} -Set up access to the services, edit: -\begin{verbatim} -/etc/hosts.deny -/etc/hosts.allow -/etc/inetd.conf -\end{verbatim} - -Add Debian mirror to: -\begin{verbatim} -/etc/apt/sources.list -\end{verbatim} - -Create fstab like this: -\begin{verbatim} -/dev/sda1 / ext3 errors=remount-ro 0 1 -/dev/sda2 none swap sw 0 0 -proc /proc proc defaults 0 0 -\end{verbatim} - -Logout - -\item Unmount the disk image -\begin{verbatim} -umount /mnt/disk -\end{verbatim} - -\item Create Xen 2.0 configuration file for the new domain. You can - use the example-configurations coming with Xen as a template. - - Make sure you have the following set up: -\begin{verbatim} -disk = [ 'file:/path/diskimage,sda1,w', 'file:/path/swapimage,sda2,w' ] -root = "/dev/sda1 ro" -\end{verbatim} - -\item Start the new domain -\begin{verbatim} -xm create -f domain_config_file -\end{verbatim} - -Check that the new domain is running: -\begin{verbatim} -xm list -\end{verbatim} - -\item Attach to the console of the new domain. You should see - something like this when starting the new domain: - -\begin{verbatim} -Started domain testdomain2, console on port 9626 -\end{verbatim} - - There you can see the ID of the console: 26. You can also list the - consoles with \path{xm consoles} (ID is the last two digits of the - port number.) - - Attach to the console: - -\begin{verbatim} -xm console 26 -\end{verbatim} - - or by telnetting to the port 9626 of localhost (the xm console - program works better). - -\item Log in and run base-config - - As a default there's no password for the root. - - Check that everything looks OK, and the system started without - errors. Check that the swap is active, and the network settings are - correct. - - Run \path{/usr/sbin/base-config} to set up the Debian settings. - - Set up the password for root using passwd. - -\item Done. You can exit the console by pressing {\path{Ctrl + ]}} - -\end{enumerate} - - -If you need to create new domains, you can just copy the contents of -the `template'-image to the new disk images, either by mounting the -template and the new image, and using \path{cp -a} or \path{tar} or by -simply copying the image file. Once this is done, modify the -image-specific settings (hostname, network settings, etc). +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. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/domain_filesystem.tex --- a/docs/src/user/domain_filesystem.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/domain_filesystem.tex Sun Dec 4 00:52:38 2005 @@ -1,9 +1,17 @@ -\chapter{Domain Filesystem Storage} - -It is possible to directly export any Linux block device in dom0 to -another domain, or to export filesystems / devices to virtual machines -using standard network protocols (e.g.\ NBD, iSCSI, NFS, etc.). This -chapter covers some of the possibilities. +\chapter{Storage and File System Management} + +Storage can be made available to virtual machines in a number of +different ways. This chapter covers some possible configurations. + +The most straightforward method is to export a physical block device (a +hard drive or partition) from dom0 directly to the guest domain as a +virtual block device (VBD). + +Storage may also be exported from a filesystem image or a partitioned +filesystem image as a \emph{file-backed VBD}. + +Finally, standard network storage protocols such as NBD, iSCSI, NFS, +etc., can be used to provide storage to virtual machines. \section{Exporting Physical Devices as VBDs} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/domain_mgmt.tex --- a/docs/src/user/domain_mgmt.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/domain_mgmt.tex Sun Dec 4 00:52:38 2005 @@ -1,20 +1,98 @@ \chapter{Domain Management Tools} -The previous chapter described a simple example of how to configure -and start a domain. This chapter summarises the tools available to -manage running domains. +This chapter summarises the tools available to manage running domains. -\section{Command-line Management} +\section{\Xend\ } +\label{s:xend} + +The Xen Daemon (\Xend) (node control daemon) performs system management +functions related to virtual machines. It forms a central point of +control for a machine and can be controlled using an HTTP-based +protocol. \Xend\ must be running in order to start and manage virtual +machines. + +\Xend\ must be run as root because it needs access to privileged system +management functions. A small set of commands may be issued on the +\xend\ command line: + +\begin{tabular}{ll} + \verb!# xend start! & start \xend, if not already running \\ + \verb!# xend stop! & stop \xend\ if already running \\ + \verb!# xend restart! & restart \xend\ if running, otherwise start it \\ + % \verb!# xend trace_start! & start \xend, with very detailed debug logging \\ + \verb!# xend status! & indicates \xend\ status by its return code +\end{tabular} + +A SysV init script called {\tt xend} is provided to start \xend\ at boot +time. {\tt make install} installs this script in \path{/etc/init.d}. To +enable it, you have to make symbolic links in the appropriate runlevel +directories or use the {\tt chkconfig} tool, where available. + +Once \xend\ is running, more sophisticated administration can be done +using the xm tool (see Section~\ref{s:xm}) and the experimental Xensv +web interface (see Section~\ref{s:xensv}). + +As \xend\ runs, events will be logged to \path{/var/log/xend.log} and, +if the migration assistant daemon (\path{xfrd}) has been started, +\path{/var/log/xfrd.log}. These may be of use for troubleshooting +problems. + +\section{Xm} +\label{s:xm} Command line management tasks are also performed using the \path{xm} -tool. For online help for the commands available, type: +tool. For online help for the commands available, type: + \begin{quote} - \verb_# xm help_ +\begin{verbatim} +# xm help +\end{verbatim} \end{quote} -You can also type \path{xm help $<$command$>$} for more information on -a given command. +You can also type \path{xm help $<$command$>$} for more information on a +given command. + +The xm tool is the primary tool for managing Xen from the console. The +general format of an xm command line is: + +\begin{verbatim} +# xm command [switches] [arguments] [variables] +\end{verbatim} + +The available \emph{switches} and \emph{arguments} are dependent on the +\emph{command} chosen. The \emph{variables} may be set using +declarations of the form {\tt variable=value} and command line +declarations override any of the values in the configuration file being +used, including the standard variables described above and any custom +variables (for instance, the \path{xmdefconfig} file uses a {\tt vmid} +variable). + +The available commands are as follows: + +\begin{description} +\item[mem-set] Request a domain to adjust its memory footprint. +\item[create] Create a new domain. +\item[destroy] Kill a domain immediately. +\item[list] List running domains. +\item[shutdown] Ask a domain to shutdown. +\item[dmesg] Fetch the Xen (not Linux!) boot output. +\item[consoles] Lists the available consoles. +\item[console] Connect to the console for a domain. +\item[help] Get help on xm commands. +\item[save] Suspend a domain to disk. +\item[restore] Restore a domain from disk. +\item[pause] Pause a domain's execution. +\item[unpause] Un-pause a domain. +\item[pincpu] Pin a domain to a CPU. +\item[bvt] Set BVT scheduler parameters for a domain. +\item[bvt\_ctxallow] Set the BVT context switching allowance for the + system. +\item[atropos] Set the atropos parameters for a domain. +\item[rrobin] Set the round robin time slice for the system. +\item[info] Get information about the Xen host. +\item[call] Call a \xend\ HTTP API function directly. +\end{description} \subsection{Basic Management Commands} @@ -82,122 +160,6 @@ # xencons localhost 9605 \end{verbatim} -\section{Domain Save and Restore} +\section{xenstored} -The administrator of a Xen system may suspend a virtual machine's -current state into a disk file in domain~0, allowing it to be resumed -at a later time. - -The ttylinux domain described earlier can be suspended to disk using -the command: -\begin{verbatim} -# xm save ttylinux ttylinux.xen -\end{verbatim} - -This will stop the domain named `ttylinux' and save its current state -into a file called \path{ttylinux.xen}. - -To resume execution of this domain, use the \path{xm restore} command: -\begin{verbatim} -# xm restore ttylinux.xen -\end{verbatim} - -This will restore the state of the domain and restart it. The domain -will carry on as before and the console may be reconnected using the -\path{xm console} command, as above. - -\section{Live Migration} - -Live migration is used to transfer a domain between physical hosts -whilst that domain continues to perform its usual activities --- from -the user's perspective, the migration should be imperceptible. - -To perform a live migration, both hosts must be running Xen / \xend\ -and the destination host must have sufficient resources (e.g.\ memory -capacity) to accommodate the domain after the move. Furthermore we -currently require both source and destination machines to be on the -same L2 subnet. - -Currently, there is no support for providing automatic remote access -to filesystems stored on local disk when a domain is migrated. -Administrators should choose an appropriate storage solution (i.e.\ -SAN, NAS, etc.) to ensure that domain filesystems are also available -on their destination node. GNBD is a good method for exporting a -volume from one machine to another. iSCSI can do a similar job, but is -more complex to set up. - -When a domain migrates, it's MAC and IP address move with it, thus it -is only possible to migrate VMs within the same layer-2 network and IP -subnet. If the destination node is on a different subnet, the -administrator would need to manually configure a suitable etherip or -IP tunnel in the domain~0 of the remote node. - -A domain may be migrated using the \path{xm migrate} command. To live -migrate a domain to another machine, we would use the command: - -\begin{verbatim} -# xm migrate --live mydomain destination.ournetwork.com -\end{verbatim} - -Without the \path{--live} flag, \xend\ simply stops the domain and -copies the memory image over to the new node and restarts it. Since -domains can have large allocations this can be quite time consuming, -even on a Gigabit network. With the \path{--live} flag \xend\ attempts -to keep the domain running while the migration is in progress, -resulting in typical `downtimes' of just 60--300ms. - -For now it will be necessary to reconnect to the domain's console on -the new machine using the \path{xm console} command. If a migrated -domain has any open network connections then they will be preserved, -so SSH connections do not have this limitation. - - -\section{Managing Domain Memory} - -XenLinux domains have the ability to relinquish / reclaim machine -memory at the request of the administrator or the user of the domain. - -\subsection{Setting memory footprints from dom0} - -The machine administrator can request that a domain alter its memory -footprint using the \path{xm mem-set} command. For instance, we can -request that our example ttylinux domain reduce its memory footprint -to 32 megabytes. - -\begin{verbatim} -# xm mem-set ttylinux 32 -\end{verbatim} - -We can now see the result of this in the output of \path{xm list}: - -\begin{verbatim} -# xm list -Name Id Mem(MB) CPU State Time(s) Console -Domain-0 0 251 0 r---- 172.2 -ttylinux 5 31 0 -b--- 4.3 9605 -\end{verbatim} - -The domain has responded to the request by returning memory to Xen. We -can restore the domain to its original size using the command line: - -\begin{verbatim} -# xm mem-set ttylinux 64 -\end{verbatim} - -\subsection{Setting memory footprints from within a domain} - -The virtual file \path{/proc/xen/balloon} allows the owner of a domain -to adjust their own memory footprint. Reading the file (e.g.\ -\path{cat /proc/xen/balloon}) prints out the current memory footprint -of the domain. Writing the file (e.g.\ \path{echo new\_target > - /proc/xen/balloon}) requests that the kernel adjust the domain's -memory footprint to a new value. - -\subsection{Setting memory limits} - -Xen associates a memory size limit with each domain. By default, this -is the amount of memory the domain is originally started with, -preventing the domain from ever growing beyond this size. To permit a -domain to grow beyond its original allocation or to prevent a domain -you've shrunk from reclaiming the memory it relinquished, use the -\path{xm maxmem} command. +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/glossary.tex --- a/docs/src/user/glossary.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/glossary.tex Sun Dec 4 00:52:38 2005 @@ -57,14 +57,19 @@ \item[Shadow pagetables] A technique for hiding the layout of machine memory from a virtual machine's operating system. Used in some {\bf - VMMs} to provide the illusion of contiguous physical memory, in + VMMs} to provide the illusion of contiguous physical memory, in Xen this is used during {\bf live migration}. + +\item[Virtual Block Device] Persistant storage available to a virtual + machine, providing the abstraction of an actual block storage device. + {\bf VBD}s may be actual block devices, filesystem images, or + remote/network storage. \item[Virtual Machine] The environment in which a hosted operating system runs, providing the abstraction of a dedicated machine. A virtual machine may be identical to the underlying hardware (as in {\bf full virtualisation}, or it may differ, as in {\bf - paravirtualisation}). + paravirtualisation}). \item[VMM] Virtual Machine Monitor - the software that allows multiple virtual machines to be multiplexed on a single physical machine. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/installation.tex --- a/docs/src/user/installation.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/installation.tex Sun Dec 4 00:52:38 2005 @@ -1,45 +1,43 @@ -\chapter{Installation} +\chapter{Basic Installation} The Xen distribution includes three main components: Xen itself, ports -of Linux and NetBSD to run on Xen, and the userspace -tools required to manage a Xen-based system. This chapter describes -how to install the Xen~2.0 distribution from source. Alternatively, -there may be pre-built packages available as part of your operating -system distribution. +of Linux and NetBSD to run on Xen, and the userspace tools required to +manage a Xen-based system. This chapter describes how to install the +Xen~3.0 distribution from source. Alternatively, there may be pre-built +packages available as part of your operating system distribution. \section{Prerequisites} \label{sec:prerequisites} -The following is a full list of prerequisites. Items marked `$\dag$' -are required by the \xend\ control tools, and hence required if you -want to run more than one virtual machine; items marked `$*$' are only -required if you wish to build from source. +The following is a full list of prerequisites. Items marked `$\dag$' are +required by the \xend\ control tools, and hence required if you want to +run more than one virtual machine; items marked `$*$' are only required +if you wish to build from source. \begin{itemize} -\item A working Linux distribution using the GRUB bootloader and - running on a P6-class or newer CPU\@. +\item A working Linux distribution using the GRUB bootloader and running + on a P6-class or newer CPU\@. \item [$\dag$] The \path{iproute2} package. \item [$\dag$] The Linux bridge-utils\footnote{Available from {\tt http://bridge.sourceforge.net}} (e.g., \path{/sbin/brctl}) \item [$\dag$] The Linux hotplug system\footnote{Available from {\tt - http://linux-hotplug.sourceforge.net/}} (e.g., \path{/sbin/hotplug} - and related scripts) + http://linux-hotplug.sourceforge.net/}} (e.g., + \path{/sbin/hotplug} and related scripts) \item [$*$] Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make). \item [$*$] Development installation of libcurl (e.g.,\ libcurl-devel). \item [$*$] Development installation of zlib (e.g.,\ zlib-dev). -\item [$*$] Development installation of Python v2.2 or later (e.g.,\ +\item [$*$] Development installation of Python v2.2 or later (e.g.,\ python-dev). \item [$*$] \LaTeX\ and transfig are required to build the documentation. \end{itemize} -Once you have satisfied these prerequisites, you can now install -either a binary or source distribution of Xen. - +Once you have satisfied these prerequisites, you can now install either +a binary or source distribution of Xen. \section{Installing from Binary Tarball} -Pre-built tarballs are available for download from the Xen download +Pre-built tarballs are available for download from the XenSource downloads page: \begin{quote} {\tt http://www.xensource.com/downloads/} \end{quote} @@ -51,14 +49,28 @@ # sh ./install.sh \end{verbatim} -Once you've installed the binaries you need to configure your system -as described in Section~\ref{s:configure}. - - +Once you've installed the binaries you need to configure your system as +described in Section~\ref{s:configure}. + +\section{Installing from RPMs} +Pre-built RPMs are available for download from the XenSource downloads +page: +\begin{quote} {\tt http://www.xensource.com/downloads/} +\end{quote} + +Once you've downloaded the RPMs, you typically install them via the RPM commands: +\begin{verbatim} +# rpm -ivh \emph{rpmname} +\end{verbatim} + +See the instructions and the Release Notes for each RPM set referenced at: + \begin{quote} + {\tt http://www.xensource.com/downloads/}. + \end{quote} + \section{Installing from Source} -This section describes how to obtain, build and install Xen from -source. +This section describes how to obtain, build and install Xen from source. \subsection{Obtaining the Source} @@ -90,9 +102,9 @@ % \item[\path{tools/}] Xen node controller daemon (Xend), command line % tools, control libraries % \item[\path{xen/}] The Xen VMM. +% \item[\path{buildconfigs/}] Build configuration files % \item[\path{linux-*-xen-sparse/}] Xen support for Linux. -% \item[\path{linux-*-patches/}] Experimental patches for Linux. -% \item[\path{netbsd-*-xen-sparse/}] Xen support for NetBSD. +% \item[\path{patches/}] Experimental patches for Linux. % \item[\path{docs/}] Various documentation files for users and % developers. % \item[\path{extras/}] Bonus extras. @@ -106,11 +118,11 @@ \begin{itemize} \item Build Xen. \item Build the control tools, including \xend. -\item Download (if necessary) and unpack the Linux 2.6 source code, - and patch it for use with Xen. -\item Build a Linux kernel to use in domain~0 and a smaller - unprivileged kernel, which can optionally be used for unprivileged - virtual machines. +\item Download (if necessary) and unpack the Linux 2.6 source code, and + patch it for use with Xen. +\item Build a Linux kernel to use in domain~0 and a smaller unprivileged + kernel, which can optionally be used for unprivileged virtual + machines. \end{itemize} After the build has completed you should have a top-level directory @@ -122,16 +134,16 @@ \path{dist/install/boot/} along with the image for Xen itself and the configuration files used during the build. -The NetBSD port can be built using: -\begin{quote} -\begin{verbatim} -# make netbsd20 -\end{verbatim}\end{quote} -NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch. -The snapshot is downloaded as part of the build process if it is not -yet present in the \path{NETBSD\_SRC\_PATH} search path. The build -process also downloads a toolchain which includes all of the tools -necessary to build the NetBSD kernel under Linux. +%The NetBSD port can be built using: +%\begin{quote} +%\begin{verbatim} +%# make netbsd20 +%\end{verbatim}\end{quote} +%NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch. +%The snapshot is downloaded as part of the build process if it is not +%yet present in the \path{NETBSD\_SRC\_PATH} search path. The build +%process also downloads a toolchain which includes all of the tools +%necessary to build the NetBSD kernel under Linux. To customize the set of kernels built you need to edit the top-level Makefile. Look for the line: @@ -169,7 +181,7 @@ %% currently), you'll need to enable devfs and devfs mount at boot %% time in the xen0 config. }} -\subsection{Custom XenLinux Builds} +\subsection{Custom Kernels} % If you have an SMP machine you may wish to give the {\tt '-j4'} % argument to make to get a parallel build. @@ -187,26 +199,26 @@ \end{verbatim} \end{quote} -You can also copy an existing Linux configuration (\path{.config}) -into e.g.\ \path{linux-2.6.11-xen0} and execute: +You can also copy an existing Linux configuration (\path{.config}) into +e.g.\ \path{linux-2.6.11-xen0} and execute: \begin{quote} \begin{verbatim} # make ARCH=xen oldconfig \end{verbatim} \end{quote} -You may be prompted with some Xen-specific options. We advise -accepting the defaults for these options. +You may be prompted with some Xen-specific options. We advise accepting +the defaults for these options. Note that the only difference between the two types of Linux kernels -that are built is the configuration file used for each. The ``U'' +that are built is the configuration file used for each. The ``U'' suffixed (unprivileged) versions don't contain any of the physical -hardware device drivers, leading to a 30\% reduction in size; hence -you may prefer these for your non-privileged domains. The ``0'' -suffixed privileged versions can be used to boot the system, as well -as in driver domains and unprivileged domains. - -\subsection{Installing the Binaries} +hardware device drivers, leading to a 30\% reduction in size; hence you +may prefer these for your non-privileged domains. The ``0'' suffixed +privileged versions can be used to boot the system, as well as in driver +domains and unprivileged domains. + +\subsection{Installing Generated Binaries} The files produced by the build process are stored under the \path{dist/install/} directory. To install them in their default @@ -217,13 +229,13 @@ \end{verbatim} \end{quote} -Alternatively, users with special installation requirements may wish -to install them manually by copying the files to their appropriate +Alternatively, users with special installation requirements may wish to +install them manually by copying the files to their appropriate destinations. %% Files in \path{install/boot/} include: %% \begin{itemize} -%% \item \path{install/boot/xen-2.0.gz} Link to the Xen 'kernel' +%% \item \path{install/boot/xen-3.0.gz} Link to the Xen 'kernel' %% \item \path{install/boot/vmlinuz-2.6-xen0} Link to domain 0 %% XenLinux kernel %% \item \path{install/boot/vmlinuz-2.6-xenU} Link to unprivileged @@ -233,28 +245,30 @@ The \path{dist/install/boot} directory will also contain the config files used for building the XenLinux kernels, and also versions of Xen and XenLinux kernels that contain debug symbols such as -(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which -are essential for interpreting crash dumps. Retain these files as the +(\path{xen-syms-2.0.6} and \path{vmlinux-syms-2.6.11.11-xen0}) which are +essential for interpreting crash dumps. Retain these files as the developers may wish to see them if you post on the mailing list. \section{Configuration} \label{s:configure} -Once you have built and installed the Xen distribution, it is simple -to prepare the machine for booting and running Xen. +Once you have built and installed the Xen distribution, it is simple to +prepare the machine for booting and running Xen. \subsection{GRUB Configuration} An entry should be added to \path{grub.conf} (often found under \path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot. This file is sometimes called \path{menu.lst}, depending on your -distribution. The entry should look something like the following: - +distribution. The entry should look something like the following: + +%% KMSelf Thu Dec 1 19:06:13 PST 2005 262144 is useful for RHEL/RH and +%% related Dom0s. {\small \begin{verbatim} title Xen 3.0 / XenLinux 2.6 - kernel /boot/xen-3.0.gz dom0_mem=131072 + kernel /boot/xen-3.0.gz dom0_mem=262144 module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro console=tty0 \end{verbatim} } @@ -266,11 +280,11 @@ Section~\ref{s:xboot}. The module line of the configuration describes the location of the -XenLinux kernel that Xen should start and the parameters that should -be passed to it. Tthese are standard Linux parameters, identifying the -root device and specifying it be initially mounted read only and -instructing that console output be sent to the screen. Some -distributions such as SuSE do not require the \path{ro} parameter. +XenLinux kernel that Xen should start and the parameters that should be +passed to it. These are standard Linux parameters, identifying the root +device and specifying it be initially mounted read only and instructing +that console output be sent to the screen. Some distributions such as +SuSE do not require the \path{ro} parameter. %% \framebox{\parbox{5in}{ %% {\bf Distro specific:} \\ @@ -278,85 +292,174 @@ %% kernel command line, since the partition won't be remounted rw %% during boot. }} - -If you want to use an initrd, just add another \path{module} line to -the configuration, like: -{\small +To use an initrd, add another \path{module} line to the configuration, +like: {\small \begin{verbatim} module /boot/my_initrd.gz \end{verbatim} } +%% KMSelf Thu Dec 1 19:05:30 PST 2005 Other configs as an appendix? + When installing a new kernel, it is recommended that you do not delete -existing menu options from \path{menu.lst}, as you may wish to boot -your old Linux kernel in future, particularly if you have problems. +existing menu options from \path{menu.lst}, as you may wish to boot your +old Linux kernel in future, particularly if you have problems. \subsection{Serial Console (optional)} + +Serial console access allows you to manage, monitor, and interact with +your system over a serial console. This can allow access from another +nearby system via a null-modem ("LapLink") cable, remotely via a serial +concentrator, or for debugging an emulator such as Qemu. + +You system's BIOS, bootloader (GRUB), Xen, Linux, and login access must +each be individually configured for serial console access. It is +\emph{not} strictly necessary to have each component fully functional, +but it can be quite useful. + +For general information on serial console configuration under Linux, +refer to the ``Remote Serial Console HOWTO'' at The Linux Documentation +Project: {\tt http://www.tldp.org}. + +\subsubsection{Serial Console BIOS configuration} + +Enabling system serial console output neither enables nor disables +serial capabilities in GRUB, Xen, or Linux, but may make remote +management of your system more convenient by displaying POST and other +boot messages over serial port and allowing remote BIOS configuration. + +Refer to your hardware vendor's documentation for capabilities and +procedures to enable BIOS serial redirection. + + +\subsubsection{Serial Console GRUB configuration} + +Placeholder + +Enabling GRUB serial console output neither enables nor disables Xen or +Linux serial capabilities, but may made remote management of your system +more convenient by displaying GRUB prompts, menus, and actions over +serial port and allowing remote GRUB management. + +Adding the following two lines to your GRUB configuration file, +typically \path{/boot/grub/menu.lst} or \path{/boot/grub/grub.conf} +depending on your distro, will enable GRUB serial output. + +\begin{quote} {\small \begin{verbatim} + serial --unit=0 --speed=115200 --word=8 --parity=no --stop=1 + terminal --timeout=10 serial console +\end{verbatim}} +\end{quote} + +Note that when both the serial port and the local monitor and keyboard +are enabled, the text "Press any key to continue." will appear at both. +Pressing a key on one device will cause GRUB to display to that device. +The other device will see no output. If no key is pressed before the +timeout period expires, the system will boot to the default GRUB boot +entry. + +Please refer to the GRUB info documentation for further information. + + +\subsubsection{Serial Console Xen configuration} + +Enabling Xen serial console output neither enables nor disables Linux +kernel output or logging in to Linux over serial port. It does however +allow you to monitor and log the Xen boot process via serial console and +can be very useful in debugging. %% kernel /boot/xen-2.0.gz dom0_mem=131072 com1=115200,8n1 %% module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro -In order to configure Xen serial console output, it is necessary to -add an boot option to your GRUB config; e.g.\ replace the above kernel -line with: -\begin{quote} -{\small -\begin{verbatim} +In order to configure Xen serial console output, it is necessary to add +an boot option to your GRUB config; e.g.\ replace the above kernel line +with: +\begin{quote} {\small \begin{verbatim} kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1 \end{verbatim}} \end{quote} This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1 -stop bit and no parity. Modify these parameters for your set up. - -One can also configure XenLinux to share the serial console; to -achieve this append ``\path{console=ttyS0}'' to your module line. - -If you wish to be able to log in over the XenLinux serial console it -is necessary to add a line into \path{/etc/inittab}. Add the line: -\begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty ttyS0}} -\end{quote} - -and you should be able to log in. To successfully log in as root over -the serial line will require adding \path{ttyS0} to -\path{/etc/securetty} if it is not already there. +stop bit and no parity. Modify these parameters for your environment. + +One can also configure XenLinux to share the serial console; to achieve +this append ``\path{console=ttyS0}'' to your module line. + + +\subsubsection{Serial Console Linux configuration} + +Enabling Linux serial console output at boot neither enables nor +disables logging in to Linux over serial port. It does however allow +you to monitor and log the Linux boot process via serial console and can be +very useful in debugging. + +To enable Linux output at boot time, add the parameter +\path{console=ttyS0} (or ttyS1, ttyS2, etc.) to your kernel GRUB line. +Under Xen, this might be: +\begin{quote} {\small \begin{verbatim} + module /vmlinuz-2.6-xen0 ro root=/dev/VolGroup00/LogVol00 console=ttyS0, 115200 +\end{verbatim}} +\end{quote} +to enable output over ttyS0 at 115200 baud. + + + +\subsubsection{Serial Console Login configuration} + +Logging in to Linux via serial console, under Xen or otherwise, requires +specifying a login prompt be started on the serial port. To permit root +logins over serial console, the serial port must be added to +\path{/etc/securetty}. + +To automatically start a login prompt over serial port, +Add the line: \begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty +ttyS0}} \end{quote} to \path{/etc/inittab}. Run \path{init q} to force +a reload of your inttab and start getty. + +To enable root logins, add \path{ttyS0} to \path{/etc/securetty} if not +already present. + +Your distribution may use an alternate getty, options include getty, +mgetty, agetty, and others. Consult your distribution's documentation +for further information. + \subsection{TLS Libraries} Users of the XenLinux 2.6 kernel should disable Thread Local Storage (TLS) (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before -attempting to boot a XenLinux kernel\footnote{If you boot without - first disabling TLS, you will get a warning message during the boot - process. In this case, simply perform the rename after the machine - is up and then run \texttt{/sbin/ldconfig} to make it take effect.}. -You can always reenable TLS by restoring the directory to its original -location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}). +attempting to boot a XenLinux kernel\footnote{If you boot without first + disabling TLS, you will get a warning message during the boot process. + In this case, simply perform the rename after the machine is up and + then run \path{/sbin/ldconfig} to make it take effect.}. You can +always reenable TLS by restoring the directory to its original location +(i.e.\ \path{mv /lib/tls.disabled /lib/tls}). The reason for this is that the current TLS implementation uses -segmentation in a way that is not permissible under Xen. If TLS is -not disabled, an emulation mode is used within Xen which reduces -performance substantially. +segmentation in a way that is not permissible under Xen. If TLS is not +disabled, an emulation mode is used within Xen which reduces performance +substantially. We hope that this issue can be resolved by working with Linux -distributions to implement a minor backward-compatible change -to the TLS library. +distributions to implement a minor backward-compatible change to the TLS +library. \section{Booting Xen} -It should now be possible to restart the system and use Xen. Reboot -and choose the new Xen option when the Grub screen appears. - -What follows should look much like a conventional Linux boot. The -first portion of the output comes from Xen itself, supplying low level -information about itself and the underlying hardware. The last -portion of the output comes from XenLinux. - -You may see some errors during the XenLinux boot. These are not +It should now be possible to restart the system and use Xen. Reboot and +choose the new Xen option when the Grub screen appears. + +What follows should look much like a conventional Linux boot. The first +portion of the output comes from Xen itself, supplying low level +information about itself and the underlying hardware. The last portion +of the output comes from XenLinux. + +You may see some errors during the XenLinux boot. These are not necessarily anything to worry about --- they may result from kernel configuration differences between your XenLinux kernel and the one you usually use. When the boot completes, you should be able to log into your system as -usual. If you are unable to log in, you should still be able to -reboot with your normal Linux kernel. +usual. If you are unable to log in, you should still be able to reboot +with your normal Linux kernel by selecting it at the GRUB prompt. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/introduction.tex --- a/docs/src/user/introduction.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/introduction.tex Sun Dec 4 00:52:38 2005 @@ -1,45 +1,56 @@ \chapter{Introduction} -Xen is a \emph{paravirtualising} virtual machine monitor (VMM), or -``hypervisor'', for the x86 processor architecture. Xen can securely +Xen is a \emph{para-virtualizing} virtual machine monitor (VMM), or +``hypervisor'', for the x86 processor architecture. Xen can securely execute multiple virtual machines on a single physical system with -close-to-native performance. The virtual machine technology -facilitates enterprise-grade functionality, including: +close-to-native performance. The virtual machine technology facilitates +enterprise-grade functionality, including: \begin{itemize} -\item Virtual machines with performance close to native hardware. -\item Live migration of running virtual machines between physical - hosts. +\item Virtual machines with performance typically 94-98\% of native hardware. +\item Live migration of running virtual machines between physical hosts. \item Excellent hardware support. Supports most Linux device drivers. -\item Sandboxed, re-startable device drivers. +\item Sand-boxed, re-startable device drivers. \end{itemize} -Paravirtualisation permits very high performance virtualisation, even +Para-virtualization permits very high performance virtualization, even on architectures like x86 that are traditionally very hard to -virtualise. +virtualize. The drawback of this approach is that it requires operating systems to -be \emph{ported} to run on Xen. Porting an OS to run on Xen is -similar to supporting a new hardware platform, however the process is -simplified because the paravirtual machine architecture is very -similar to the underlying native hardware. Even though operating -system kernels must explicitly support Xen, a key feature is that user -space applications and libraries \emph{do not} require modification. +be \emph{ported} to run on Xen. Porting an OS to run on Xen is similar +to supporting a new hardware platform, however the process is simplified +because the para-virtual machine architecture is very similar to the +underlying native hardware. Even though operating system kernels must +explicitly support Xen, a key feature is that user space applications +and libraries \emph{do not} require modification. + +With hardware CPU virtualization as provided by Intel VT and AMD +Pacifica technology, the ability to run an unmodified guest OS kernel is +available. No porting of the OS is required; however some additional +driver support is necessary within Xen itself. Unlike traditional full +virtualization hypervisors, which suffer a tremendous performance +overhead, the combination of Xen and VT or Xen and Pacifica technology +complement one another to offer superb performance for para-virtualized +guest operating systems and full support for unmodified guests, which +run natively on the processor without need for emulation, under VT. +Full support for VT and Pacifica chipsets will appear in early 2006. Xen support is available for increasingly many operating systems: -right now, Linux and NetBSD are available for Xen 3.0. -A FreeBSD port is undergoing testing and will be incorporated into the -release soon. Other OS ports, including Plan 9, are in progress. We -hope that that arch-xen patches will be incorporated into the -mainstream releases of these operating systems in due course (as has -already happened for NetBSD). +currently, Linux and NetBSD are available for Xen 3.0. A FreeBSD port is +undergoing testing and will be incorporated into the release soon. Other +OS ports, including Plan 9, are in progress. We hope that that arch-xen +patches will be incorporated into the mainstream releases of these +operating systems in due course (as has already happened for NetBSD). + +%% KMSelf Thu Dec 1 14:59:02 PST 2005 PPC port status? Possible usage scenarios for Xen include: \begin{description} \item [Kernel development.] Test and debug kernel modifications in a - sandboxed virtual machine --- no need for a separate test machine. + sand-boxed virtual machine --- no need for a separate test machine. \item [Multiple OS configurations.] Run multiple operating systems simultaneously, for instance for compatibility or QA purposes. \item [Server consolidation.] Move multiple servers onto a single @@ -50,7 +61,7 @@ control and isolation than single-system image solutions, particularly by using live migration for load balancing. \item [Hardware support for custom OSes.] Allow development of new - OSes while benefitting from the wide-ranging hardware support of + OSes while benefiting from the wide-ranging hardware support of existing OSes such as Linux. \end{description} @@ -62,10 +73,10 @@ Xen may host multiple \emph{guest} operating systems, each of which is executed within a secure virtual machine. In Xen terminology, a -\emph{domain}. Domains are scheduled by Xen to make effective use of -the available physical CPUs. Each guest OS manages its own -applications. This management includes the responsibility of -scheduling each application within the time allotted to the VM by Xen. +\emph{domain}. Domains are scheduled by Xen to make effective use of the +available physical CPUs. Each guest OS manages its own applications. +This management includes the responsibility of scheduling each +application within the time allotted to the VM by Xen. The first domain, \emph{domain~0}, is created automatically when the system boots and has special management privileges. Domain~0 builds @@ -73,39 +84,38 @@ administrative tasks such as suspending, resuming and migrating other virtual machines. -Within domain~0, a process called \emph{xend} runs to manage the -system. \Xend\ is responsible for managing virtual machines and -providing access to their consoles. Commands are issued to \xend\ -over an HTTP interface, either from a command-line tool or from a web -browser. +Within domain~0, a process called \emph{xend} runs to manage the system. +\Xend\ is responsible for managing virtual machines and providing access +to their consoles. Commands are issued to \xend\ over an HTTP interface, +either from a command-line tool or from a web browser. \section{Hardware Support} -Xen currently runs only on the x86 architecture, requiring a `P6' or +Xen currently runs only on the x86 architecture, requiring a ``P6'' or newer processor (e.g.\ Pentium Pro, Celeron, Pentium~II, Pentium~III, -Pentium~IV, Xeon, AMD~Athlon, AMD~Duron). Multiprocessor machines are -supported, and there is basic support for HyperThreading (SMT), -although this remains a topic for ongoing research. A port -specifically for x86/64 is in progress. Xen already runs on such -systems in 32-bit legacy mode. In addition, a port to the IA64 -architecture is approaching completion. We hope to add other -architectures such as PPC and ARM in due course. +Pentium~IV, Xeon, AMD~Athlon, AMD~Duron). Multiprocessor machines are +supported, and there is basic support for HyperThreading (SMT), although +this remains a topic for ongoing research. A port specifically for +x86/64 is in progress. Xen already runs on such systems in 32-bit legacy +mode. In addition, a port to the IA64 architecture is approaching +completion. We hope to add other architectures such as PPC and ARM in +due course. -Xen can currently use up to 4GB of memory. It is possible for x86 -machines to address up to 64GB of physical memory but there are no -plans to support these systems: The x86/64 port is the planned route -to supporting larger memory sizes. +Xen can currently use up to 4GB of memory. It is possible for x86 +machines to address up to 64GB of physical memory but there are no plans +to support these systems: The x86/64 port is the planned route to +supporting larger memory sizes. -Xen offloads most of the hardware support issues to the guest OS -running in Domain~0. Xen itself contains only the code required to -detect and start secondary processors, set up interrupt routing, and -perform PCI bus enumeration. Device drivers run within a privileged -guest OS rather than within Xen itself. This approach provides -compatibility with the majority of device hardware supported by Linux. -The default XenLinux build contains support for relatively modern -server-class network and disk hardware, but you can add support for -other hardware by configuring your XenLinux kernel in the normal way. +Xen offloads most of the hardware support issues to the guest OS running +in Domain~0. Xen itself contains only the code required to detect and +start secondary processors, set up interrupt routing, and perform PCI +bus enumeration. Device drivers run within a privileged guest OS rather +than within Xen itself. This approach provides compatibility with the +majority of device hardware supported by Linux. The default XenLinux +build contains support for relatively modern server-class network and +disk hardware, but you can add support for other hardware by configuring +your XenLinux kernel in the normal way. \section{History} @@ -119,24 +129,24 @@ efficiently partition a single machine to enable multiple independent clients to run their operating systems and applications in an environment. This environment provides protection, resource isolation -and accounting. The project web page contains further information -along with pointers to papers and technical reports: +and accounting. The project web page contains further information along +with pointers to papers and technical reports: \path{http://www.cl.cam.ac.uk/xeno} -Xen has grown into a fully-fledged project in its own right, enabling -us to investigate interesting research issues regarding the best -techniques for virtualising resources such as the CPU, memory, disk -and network. The project has been bolstered by support from Intel -Research Cambridge and HP Labs, who are now working closely with us. +Xen has grown into a fully-fledged project in its own right, enabling us +to investigate interesting research issues regarding the best techniques +for virtualizing resources such as the CPU, memory, disk and network. +The project has been bolstered by support from Intel Research Cambridge +and HP Labs, who are now working closely with us. Xen was first described in a paper presented at SOSP in 2003\footnote{\tt - http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the -first public release (1.0) was made that October. Since then, Xen has + http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}, and the first +public release (1.0) was made that October. Since then, Xen has significantly matured and is now used in production scenarios on many sites. Xen 3.0 features greatly enhanced hardware support, configuration flexibility, usability and a larger complement of supported operating systems. This latest release takes Xen a step closer to becoming the -definitive open source solution for virtualisation. +definitive open source solution for virtualization. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/start_addl_dom.tex --- a/docs/src/user/start_addl_dom.tex Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/start_addl_dom.tex Sun Dec 4 00:52:38 2005 @@ -1,7 +1,7 @@ \chapter{Starting Additional Domains} The first step in creating a new domain is to prepare a root -filesystem for it to boot from. Typically, this might be stored in a +filesystem for it to boot. Typically, this might be stored in a normal partition, an LVM or other volume manager partition, a disk file or on an NFS server. A simple way to do this is simply to boot from your standard OS install CD and install the distribution into @@ -11,6 +11,10 @@ \begin{quote} \verb!# xend start! \end{quote} + +%% KMS: If we're going to use '# cmd' syntax we should be consistent +%% about it and have a conventions section noting that '#' == root +%% prompt. If you wish the daemon to start automatically, see the instructions in Section~\ref{s:xend}. Once the daemon is running, you can use the @@ -70,11 +74,21 @@ You may also want to edit the {\bf vif} variable in order to choose the MAC address of the virtual ethernet interface yourself. For example: +%% KMS: We should indicate "safe" ranges to use. \begin{quote} \verb_vif = ['mac=00:06:AA:F6:BB:B3']_ \end{quote} If you do not set this variable, \xend\ will automatically generate a -random MAC address from an unused range. +random MAC address from the range 00:16:3E:xx:xx:xx. Generated MACs are +not tested for possible collisions, however likelihood of this is low at +\begin{math} 1:2^{48}.\end{math} XenSource Inc. gives permission for +anyone to use addresses randomly allocated from this range for use by +their Xen domains. + + +For a list of IEEE +assigned MAC organizationally unique identifiers (OUI), see \newline +{\tt http://standards.ieee.org/regauth/oui/oui.txt} \section{Booting the Domain} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/booting_xen.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/booting_xen.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,170 @@ +\chapter{Booting Xen} + +Once Xen is installed and configured as described in the preceding chapter, it +should now be possible to restart the system and use Xen. + +Booting the system into Xen will bring you up into the privileged management d +omain, Domain0. At that point you are ready to create guest domains and "boot" t +hem using the xm create command. + +\section{Booting Domain0} + +After installation and configuration is complete, reboot the system and and ch +oose the new Xen option when the Grub screen appears. + +What follows should look much like a conventional Linux boot. The +first portion of the output comes from Xen itself, supplying low level +information about itself and the underlying hardware. The last +portion of the output comes from XenLinux. + +You may see some errors during the XenLinux boot. These are not +necessarily anything to worry about --- they may result from kernel +configuration differences between your XenLinux kernel and the one you +usually use. + +%% KMSelf Wed Nov 30 18:09:37 PST 2005: We should specify what these are. + +When the boot completes, you should be able to log into your system as +usual. If you are unable to log in, you should still be able to +reboot with your normal Linux kernel by selecting it at the GRUB prompt. + +The first step in creating a new domain is to prepare a root +filesystem for it to boot. Typically, this might be stored in a normal +partition, an LVM or other volume manager partition, a disk file or on +an NFS server. A simple way to do this is simply to boot from your +standard OS install CD and install the distribution into another +partition on your hard drive. + +To start the \xend\ control daemon, type +\begin{quote} + \verb!# xend start! +\end{quote} + +If you wish the daemon to start automatically, see the instructions in +Section~\ref{s:xend}. Once the daemon is running, you can use the +\path{xm} tool to monitor and maintain the domains running on your +system. This chapter provides only a brief tutorial. We provide full +details of the \path{xm} tool in the next chapter. + +% \section{From the web interface} +% +% Boot the Xen machine and start Xensv (see Chapter~\ref{cha:xensv} +% for more details) using the command: \\ +% \verb_# xensv start_ \\ +% This will also start Xend (see Chapter~\ref{cha:xend} for more +% information). +% +% The domain management interface will then be available at {\tt +% http://your\_machine:8080/}. This provides a user friendly wizard +% for starting domains and functions for managing running domains. +% +% \section{From the command line} +\section{Booting Guest Domains} + +\subsection{Creating a Domain Configuration File} + +Before you can start an additional domain, you must create a +configuration file. We provide two example files which you can use as +a starting point: +\begin{itemize} +\item \path{/etc/xen/xmexample1} is a simple template configuration + file for describing a single VM\@. +\item \path{/etc/xen/xmexample2} file is a template description that + is intended to be reused for multiple virtual machines. Setting the + value of the \path{vmid} variable on the \path{xm} command line + fills in parts of this template. +\end{itemize} + +Copy one of these files and edit it as appropriate. Typical values +you may wish to edit include: + +\begin{quote} +\begin{description} +\item[kernel] Set this to the path of the kernel you compiled for use + with Xen (e.g.\ \path{kernel = ``/boot/vmlinuz-2.6-xenU''}) +\item[memory] Set this to the size of the domain's memory in megabytes + (e.g.\ \path{memory = 64}) +\item[disk] Set the first entry in this list to calculate the offset + of the domain's root partition, based on the domain ID\@. Set the + second to the location of \path{/usr} if you are sharing it between + domains (e.g.\ \path{disk = ['phy:your\_hard\_drive\%d,sda1,w' \% + (base\_partition\_number + vmid), + 'phy:your\_usr\_partition,sda6,r' ]} +\item[dhcp] Uncomment the dhcp variable, so that the domain will + receive its IP address from a DHCP server (e.g.\ \path{dhcp=``dhcp''}) +\end{description} +\end{quote} + +You may also want to edit the {\bf vif} variable in order to choose +the MAC address of the virtual ethernet interface yourself. For +example: + +\begin{quote} +\verb_vif = ['mac=00:16:3E:F6:BB:B3']_ +\end{quote} +If you do not set this variable, \xend\ will automatically generate a +random MAC address from the range 00:16:3E:xx:xx:xx, assigned by IEEE to +XenSource as an OUI (organizationally unique identifier). XenSource +Inc. gives permission for anyone to use addresses randomly allocated +from this range for use by their Xen domains. + +For a list of IEEE OUI assignments, see \newline +{\tt http://standards.ieee.org/regauth/oui/oui.txt}. + + +\subsection{Booting the Guest Domain} + +The \path{xm} tool provides a variety of commands for managing +domains. Use the \path{create} command to start new domains. Assuming +you've created a configuration file \path{myvmconf} based around +\path{/etc/xen/xmexample2}, to start a domain with virtual machine +ID~1 you should type: + +\begin{quote} +\begin{verbatim} +# xm create -c myvmconf vmid=1 +\end{verbatim} +\end{quote} + +The \path{-c} switch causes \path{xm} to turn into the domain's +console after creation. The \path{vmid=1} sets the \path{vmid} +variable used in the \path{myvmconf} file. + +You should see the console boot messages from the new domain appearing +in the terminal in which you typed the command, culminating in a login +prompt. + +\subsection{Example: ttylinux} + +Ttylinux is a very small Linux distribution, designed to require very +few resources. We will use it as a concrete example of how to start a +Xen domain. Most users will probably want to install a full-featured +distribution once they have mastered the basics\footnote{ttylinux is + the distribution's home page: {\tt + http://www.minimalinux.org/ttylinux/}}. + +\begin{enumerate} +\item Download and extract the ttylinux disk image from the Files + section of the project's SourceForge site (see + \path{http://sf.net/projects/xen/}). +\item Create a configuration file like the following: + \begin{quote} +\begin{verbatim} +kernel = "/boot/vmlinuz-2.6-xenU" +memory = 64 +name = "ttylinux" +nics = 1 +ip = "1.2.3.4" +disk = ['file:/path/to/ttylinux/rootfs,sda1,w'] +root = "/dev/sda1 ro" +\end{verbatim} + \end{quote} +\item Now start the domain and connect to its console: + \begin{quote} +\begin{verbatim} +xm create configfile -c +\end{verbatim} + \end{quote} +\item Login as root, password root. +\end{enumerate} + diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/building_xen.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/building_xen.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Building Xen} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/console_management.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/console_management.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Console Management} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/cpu_management.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/cpu_management.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,44 @@ +\chapter{CPU Management} + +Placeholder. +%% KMS Something sage about CPU / processor management. + +Xen allows a domain's virtual CPU(s) to be associated with one or more +host CPUs. This can be used to allocate real resources among one or +more guests, or to make optimal use of processor resources when +utilizing dual-core, hyperthreading, or other advanced CPU technologies. + +Xen enumerates physical CPUs in a `depth first' fashion. For a system +with both hyperthreading and multiple cores, this would be all the +hyperthreads on a given core, then all the cores on a given socket, +and then all sockets. I.e. if you had a two socket, dual core, +hyperthreaded Xeon the CPU order would be: + + +\begin{center} +\begin{tabular}{|l|l|l|l|l|l|l|r|} +\multicolumn{4}{c|}{socket0} & \multicolumn{4}{c|}{socket1} \\ \hline +\multicolumn{2}{c|}{core0} & \multicolumn{2}{c|}{core1} & +\multicolumn{2}{c|}{core0} & \multicolumn{2}{c|}{core1} \\ \hline +ht0 & ht1 & ht0 & ht1 & ht0 & ht1 & ht0 & ht1 \\ +\#0 & \#1 & \#2 & \#3 & \#4 & \#5 & \#6 & \#7 \\ +\end{tabular} +\end{center} + + +Having multiple vcpus belonging to the same domain mapped to the same +physical CPU is very likely to lead to poor performance. It's better to +use `vcpus-set' to hot-unplug one of the vcpus and ensure the others are +pinned on different CPUs. + +If you are running IO intensive tasks, its typically better to dedicate +either a hyperthread or whole core to running domain 0, and hence pin +other domains so that they can't use CPU 0. If your workload is mostly +compute intensive, you may want to pin vcpus such that all physical CPU +threads are available for guest domains. + + +\section{Setting CPU Pinning} + +FIXME: To specify a domain's CPU pinning use the XXX command/syntax in +XXX. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/debugging.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/debugging.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,18 @@ +\chapter{Debugging} + +Xen has a set of debugging features that can be useful to try and figure +out what's going on. Hit ``h'' on the serial line (if you specified a baud +rate on the Xen command line) or ScrollLock-h on the keyboard to get a +list of supported commands. + +If you have a crash you'll likely get a crash dump containing an EIP +(PC) which, along with an \path{objdump -d image}, can be useful in +figuring out what's happened. Debug a Xenlinux image just as you would +any other Linux kernel. + +%% We supply a handy debug terminal program which you can find in +%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should +%% be built and executed on another machine that is connected via a +%% null modem cable. Documentation is included. Alternatively, if the +%% Xen machine is connected to a serial-port server then we supply a +%% dumb TCP terminal client, {\tt xencons}. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/dom0_installation.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/dom0_installation.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{dom0 Installation} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/domU_installation.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/domU_installation.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{domU Installation} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/fedora.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/fedora.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,102 @@ +\chapter{Installing Xen on Fedora~Core 4} + +This section will help you in installing Xen 3 on Fedora Core 4 using various methods. + +\section{Installing Xen from Source Package and binary package} + +\subsection{Required Packages} +bridge\_utils + + +\subsection{Installing} + +Download the source or binary tarballs available at \begin{quote} {\tt http://www.xensource.com/downloads } \end{quote}. + +Extract the archive using following command: + +\begin{verbatim} +tar -zxvf xen-*****-***.tgz +\end{verbatim} + +cd into the xen directory. + +To compile and install the source do + +\begin{verbatim} + make dist + make install +\end{verbatim} + + +To install the binary tarball, all you need to do is run the \path{install.sh} script. + +\begin{verbatim} + #./install.sh +\end{verbatim} + +\subsection{Installing Xen using yum} + +To install xen, type the command + +\begin{verbatim} +#yum install xen +\end{verbatim} + +This will download the following rpms and install them: + +\begin{itemize} +\item xen +\item bridge-utils +\item sysfsutils +\end{itemize} + +Next we need to install kernel-xen0 and kernel-xenU. Type the command: + +\begin{verbatim} + yum install kernel-xen0 kernel-xenU +\end{verbatim} + +Note: This installs xen0 and xenU kernels and adds an entry in the grub configuration. +Getting Xen up and running + +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 + +Note: Installation using yum doesn't require the configuration of grub as mentioned below. + +An example grub entry would be like: + +{\small +\begin{verbatim} +title Xen Unstable(From Fedora Core 4) + root (hd0,0) + kernel /fedora/xen.gz dom0\_mem=230000 console=vga + module /fedora/vmlinuz-2.6-xen0 root=/dev/Vol1/LV3 ro console=tty0 + module /fedora/initrd-2.6.11-1.1369\_FC4smp.img +\end{verbatim} +} + +Also make sure that \path{/var/run/xenstored} and \path{/var/lib/xenstored} directories have been created. If they are not, manually create them. + +Now reboot and select the xen0 option from the GRUB menu. + +To check whether you are running the xen0 kernel, type \path{uname -r} + +Now start the xend process: + +\begin{verbatim} +xend start +\end{verbatim} + +To check whether xend process is running or not, type the following command which lists the running domains. + +\begin{verbatim} +#xm list + Name Id Mem(MB) CPU VCPU(s) State Time(s) + Domain-0 0 219 0 1 r----- 28.9 +\end{verbatim} + +Since you haven't created any guest domains yet, you would see only Domain0. + +Further Help and documentations + +Besides the usual resources, see the Fedora Quickstart Guide \begin{quote} {\tt http://www.fedoraproject.org/wiki/FedoraXenQuickstart } \end{quote} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/further_support.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/further_support.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,52 @@ +\chapter{Further Support} + +If you have questions that are not answered by this manual, the +sources of information listed below may be of interest to you. Note +that bug reports, suggestions and contributions related to the +software (or the documentation) should be sent to the Xen developers' +mailing list (address below). + + +\section{Other Documentation} + +For developers interested in porting operating systems to Xen, the +\emph{Xen Interface Manual} is distributed in the \path{docs/} +directory of the Xen source distribution. + + +\section{Online References} + +The official Xen web site is found at: +\begin{quote} {\tt http://www.cl.cam.ac.uk/netos/xen/} +\end{quote} + +This contains links to the latest versions of all online +documentation, including the latest version of the FAQ. + +Information regarding Xen is also available at the Xen Wiki at +\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote} +The Xen project uses Bugzilla as its bug tracking system. You'll find +the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/. + + +\section{Mailing Lists} + +There are several mailing lists that are used to discuss Xen related +topics. The most widely relevant are listed below. An official page of +mailing lists and subscription information can be found at \begin{quote} + {\tt http://lists.xensource.com/} \end{quote} + +\begin{description} +\item[xen-devel@xxxxxxxxxxxxxxxxxxx] Used for development + discussions and bug reports. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-devel}} +\item[xen-users@xxxxxxxxxxxxxxxxxxx] Used for installation and usage + discussions and requests for help. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-users}} +\item[xen-announce@xxxxxxxxxxxxxxxxxxx] Used for announcements only. + Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-announce}} +\item[xen-changelog@xxxxxxxxxxxxxxxxxxx] Changelog feed + from the unstable and 2.0 trees - developer oriented. Subscribe at: \\ + {\small {\tt http://lists.xensource.com/xen-changelog}} +\end{description} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/gentoo.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/gentoo.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Installing Xen on Gentoo Linux} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/known_problems.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/known_problems.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Known Problems} + +Problem One: No Known Problems Chapter. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/logfiles.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/logfiles.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Log Files} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/memory_management.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/memory_management.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,51 @@ +\chapter{Memory Management} + +\section{Managing Domain Memory} + +XenLinux domains have the ability to relinquish/reclaim machine +memory at the request of the administrator or the user of the domain. + +\subsection{Setting memory footprints from dom0} + +The machine administrator can request that a domain alter its memory +footprint using the \path{xm mem-set} command. For instance, we can +request that our example ttylinux domain reduce its memory footprint +to 32 megabytes. + +\begin{verbatim} +# xm mem-set ttylinux 32 +\end{verbatim} + +We can now see the result of this in the output of \path{xm list}: + +\begin{verbatim} +# xm list +Name Id Mem(MB) CPU State Time(s) Console +Domain-0 0 251 0 r---- 172.2 +ttylinux 5 31 0 -b--- 4.3 9605 +\end{verbatim} + +The domain has responded to the request by returning memory to Xen. We +can restore the domain to its original size using the command line: + +\begin{verbatim} +# xm mem-set ttylinux 64 +\end{verbatim} + +\subsection{Setting memory footprints from within a domain} + +The virtual file \path{/proc/xen/balloon} allows the owner of a domain +to adjust their own memory footprint. Reading the file (e.g.\ +\path{cat /proc/xen/balloon}) prints out the current memory footprint +of the domain. Writing the file (e.g.\ \path{echo new\_target > + /proc/xen/balloon}) requests that the kernel adjust the domain's +memory footprint to a new value. + +\subsection{Setting memory limits} + +Xen associates a memory size limit with each domain. By default, this +is the amount of memory the domain is originally started with, +preventing the domain from ever growing beyond this size. To permit a +domain to grow beyond its original allocation or to prevent a domain +you've shrunk from reclaiming the memory it relinquished, use the +\path{xm maxmem} command. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/migrating_domains.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/migrating_domains.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,70 @@ +\chapter{Migrating Domains} + +\section{Domain Save and Restore} + +The administrator of a Xen system may suspend a virtual machine's +current state into a disk file in domain~0, allowing it to be resumed at +a later time. + +The ttylinux domain described earlier can be suspended to disk using the +command: +\begin{verbatim} +# xm save ttylinux ttylinux.xen +\end{verbatim} + +This will stop the domain named ``ttylinux'' and save its current state +into a file called \path{ttylinux.xen}. + +To resume execution of this domain, use the \path{xm restore} command: +\begin{verbatim} +# xm restore ttylinux.xen +\end{verbatim} + +This will restore the state of the domain and restart it. The domain +will carry on as before and the console may be reconnected using the +\path{xm console} command, as above. + +\section{Live Migration} + +Live migration is used to transfer a domain between physical hosts +whilst that domain continues to perform its usual activities --- from +the user's perspective, the migration should be imperceptible. + +To perform a live migration, both hosts must be running Xen / \xend\ and +the destination host must have sufficient resources (e.g.\ memory +capacity) to accommodate the domain after the move. Furthermore we +currently require both source and destination machines to be on the same +L2 subnet. + +Currently, there is no support for providing automatic remote access to +filesystems stored on local disk when a domain is migrated. +Administrators should choose an appropriate storage solution (i.e.\ SAN, +NAS, etc.) to ensure that domain filesystems are also available on their +destination node. GNBD is a good method for exporting a volume from one +machine to another. iSCSI can do a similar job, but is more complex to +set up. + +When a domain migrates, it's MAC and IP address move with it, thus it is +only possible to migrate VMs within the same layer-2 network and IP +subnet. If the destination node is on a different subnet, the +administrator would need to manually configure a suitable etherip or IP +tunnel in the domain~0 of the remote node. + +A domain may be migrated using the \path{xm migrate} command. To live +migrate a domain to another machine, we would use the command: + +\begin{verbatim} +# xm migrate --live mydomain destination.ournetwork.com +\end{verbatim} + +Without the \path{--live} flag, \xend\ simply stops the domain and +copies the memory image over to the new node and restarts it. Since +domains can have large allocations this can be quite time consuming, +even on a Gigabit network. With the \path{--live} flag \xend\ attempts +to keep the domain running while the migration is in progress, resulting +in typical `downtimes' of just 60--300ms. + +For now it will be necessary to reconnect to the domain's console on the +new machine using the \path{xm console} command. If a migrated domain +has any open network connections then they will be preserved, so SSH +connections do not have this limitation. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/monitoring_xen.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/monitoring_xen.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Monitoring Xen} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/network_management.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/network_management.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Network Management} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/options.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/options.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,149 @@ +\chapter{Build and Boot Options} + +This chapter describes the build- and boot-time options which may be +used to tailor your Xen system. + + +\section{Xen Build Options} + +Xen provides a number of build-time options which should be set as +environment variables or passed on make's command-line. + +\begin{description} +\item[verbose=y] Enable debugging messages when Xen detects an + unexpected condition. Also enables console output from all domains. +\item[debug=y] Enable debug assertions. Implies {\bf verbose=y}. + (Primarily useful for tracing bugs in Xen). +\item[debugger=y] Enable the in-Xen debugger. This can be used to + debug Xen, guest OSes, and applications. +\item[perfc=y] Enable performance counters for significant events + within Xen. The counts can be reset or displayed on Xen's console + via console control keys. +\item[trace=y] Enable per-cpu trace buffers which log a range of + events within Xen for collection by control software. +\end{description} + + +\section{Xen Boot Options} +\label{s:xboot} + +These options are used to configure Xen's behaviour at runtime. They +should be appended to Xen's command line, either manually or by +editing \path{grub.conf}. + +\begin{description} +\item [ noreboot ] Don't reboot the machine automatically on errors. + This is useful to catch debug output if you aren't catching console + messages via the serial line. +\item [ nosmp ] Disable SMP support. This option is implied by + `ignorebiostables'. +\item [ watchdog ] Enable NMI watchdog which can report certain + failures. +\item [ noirqbalance ] Disable software IRQ balancing and affinity. + This can be used on systems such as Dell 1850/2850 that have + workarounds in hardware for IRQ-routing issues. +\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify + a list of pages not to be allocated for use because they contain bad + bytes. For example, if your memory tester says that byte 0x12345678 + is bad, you would place `badpage=0x12345' on Xen's command line. +\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ + com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\ + Xen supports up to two 16550-compatible serial ports. For example: + `com1=9600, 8n1, 0x408, 5' maps COM1 to a 9600-baud port, 8 data + bits, no parity, 1 stop bit, I/O port base 0x408, IRQ 5. If some + configuration options are standard (e.g., I/O base and IRQ), then + only a prefix of the full configuration string need be specified. If + the baud rate is pre-configured (e.g., by the bootloader) then you + can specify `auto' in place of a numeric baud rate. +\item [ console=$<$specifier list$>$ ] Specify the destination for Xen + console I/O. This is a comma-separated list of, for example: + \begin{description} + \item[ vga ] Use VGA console and allow keyboard input. + \item[ com1 ] Use serial port com1. + \item[ com2H ] Use serial port com2. Transmitted chars will have the + MSB set. Received chars must have MSB set. + \item[ com2L] Use serial port com2. Transmitted chars will have the + MSB cleared. Received chars must have MSB cleared. + \end{description} + The latter two examples allow a single port to be shared by two + subsystems (e.g.\ console and debugger). Sharing is controlled by + MSB of each transmitted/received character. [NB. Default for this + option is `com1,vga'] +\item [ sync\_console ] Force synchronous console output. This is + useful if you system fails unexpectedly before it has sent all + available output to the console. In most cases Xen will + automatically enter synchronous mode when an exceptional event + occurs, but this option provides a manual fallback. +\item [ conswitch=$<$switch-char$><$auto-switch-char$>$ ] Specify how + to switch serial-console input between Xen and DOM0. The required + sequence is CTRL-$<$switch-char$>$ pressed three times. Specifying + the backtick character disables switching. The + $<$auto-switch-char$>$ specifies whether Xen should auto-switch + input to DOM0 when it boots --- if it is `x' then auto-switching is + disabled. Any other value, or omitting the character, enables + auto-switching. [NB. Default switch-char is `a'.] +\item [ nmi=xxx ] + Specify what to do with an NMI parity or I/O error. \\ + `nmi=fatal': Xen prints a diagnostic and then hangs. \\ + `nmi=dom0': Inform DOM0 of the NMI. \\ + `nmi=ignore': Ignore the NMI. +\item [ mem=xxx ] Set the physical RAM address limit. Any RAM + appearing beyond this physical address in the memory map will be + ignored. This parameter may be specified with a B, K, M or G suffix, + representing bytes, kilobytes, megabytes and gigabytes respectively. + The default unit, if no suffix is specified, is kilobytes. +\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to + domain0. In Xen 3.x the parameter may be specified with a B, K, M or + G suffix, representing bytes, kilobytes, megabytes and gigabytes + respectively; if no suffix is specified, the parameter defaults to + kilobytes. In previous versions of Xen, suffixes were not supported + and the value is always interpreted as kilobytes. +\item [ tbuf\_size=xxx ] Set the size of the per-cpu trace buffers, in + pages (default 1). Note that the trace buffers are only enabled in + debug builds. Most users can ignore this feature completely. +\item [ sched=xxx ] Select the CPU scheduler Xen should use. The + current possibilities are `bvt' (default), `atropos' and `rrobin'. + For more information see Section~\ref{s:sched}. +\item [ apic\_verbosity=debug,verbose ] Print more detailed + information about local APIC and IOAPIC configuration. +\item [ lapic ] Force use of local APIC even when left disabled by + uniprocessor BIOS. +\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if + enabled by the BIOS. +\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform. + This can usually be probed automatically. +\end{description} + +In addition, the following options may be specified on the Xen command +line. Since domain 0 shares responsibility for booting the platform, +Xen will automatically propagate these options to its command line. +These options are taken from Linux's command-line syntax with +unchanged semantics. + +\begin{description} +\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and + domain 0) parses the BIOS ACPI tables. +\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to + ignore timer-interrupt override instructions specified by the BIOS + ACPI tables. +\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs + that are present in the system, and instead continue to use the + legacy PIC. +\end{description} + + +\section{XenLinux Boot Options} + +In addition to the standard Linux kernel boot options, we support: +\begin{description} +\item[ xencons=xxx ] Specify the device node to which the Xen virtual + console driver is attached. The following options are supported: + \begin{center} + \begin{tabular}{l} + `xencons=off': disable virtual console \\ + `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\ + `xencons=ttyS': attach console to /dev/ttyS0 + \end{tabular} +\end{center} +The default is ttyS for dom0 and tty for all other domains. +\end{description} diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/rhel.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/rhel.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,127 @@ +\chapter{Installing Xen on Red Hat Enterprise Linux (RHEL) 4.1} + +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. + +Stable binary release install +Source install +\section{Stable binary release install} + +\subsection{Setup yum repository} + +Setup your yum repository to Dag's Yum Repository or similar. Dag's is recommended. + +\subsection{Required Packages} + +These packages are required: + +\begin{itemize} +\item bridge-utils +\item curl +\item libidn +\item sysfsutils +\end{itemize} + +Use yum to install these packages. + +\begin{verbatim} +yum install bridge-utils curl libidn sysfsutils +\end{verbatim} + +\subsection{Download Xen} + +\subsection{Download the binary tarball} +Download the Xen 3.0 binary tarball from the XenSource downloads page: + +\begin{quote} {\tt http://www.xensource.com/downloads/} +\end{quote} + +\subsection{Extract and Install} + +\begin{verbatim} +tar zxvf xen-unstable-install-x86\_32.tgz + +cd xen-unstable-install + +./install.sh +\end{verbatim} + + +\subsection{Disable TLS} + +\begin{verbatim} +mv /lib/tls /lib/tls.disabled +\end{verbatim} + +\subsection{Creating initrd} + +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. + +\begin{verbatim} +run depmod 2.x.y-xen0 to re-create modules dependency + +mkinitrd /boot/initrd-2.x.y-xen0.img 2.x.y-xen0 +\end{verbatim} + +If you get an error + +\begin{verbatim} + "No module xxx found for kernel 2.x.y-xen0, aborting." +\end{verbatim} + +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 + +\begin{verbatim} +mkinitrd --builtin=aic7xxx ./2.6.12-xen0.img 2.6.12-xen0 +\end{verbatim} + +If another yyy module is reported as "not found," + +\begin{verbatim} +mkinitrd --builtin=xxx --builtin=yyy ./2.6.12-xen0.img 2.6.12-xen0 +\end{verbatim} + +\subsection{Grub Configuration} + +As usual, you need to make entry in grub configuration file for Xen. Here's a sample grub entry. + +{\small +\begin{verbatim} +title Xen/RHEL 4.1 + kernel (hd0,5)/boot/xen.gz dom0\_mem=256000 + module (hd0,5)/boot/vmlinuz-2.6.11.12-xen0 root=/dev/hda6 + module (hd0,5)/boot/initrd-2.6.11.12-xen0.img +\end{verbatim} +} + +\section{Source install} + + +\subsection{Download Source Tarball} + +\subsection{Download the binary tarball} +Download the Xen 3.0 binary tarball from the XenSource downloads page: + +\begin{quote} {\tt http://www.xensource.com/downloads/} +\end{quote} + +\subsection{Pre-requisites to build from source} + +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: + +\begin{itemize} +\item gcc-3.4.3-22.1 +\item python-devel-2.3.4-14.1 +\item zlib-devel-1.2.1.2-1 +\item curl-devel-7.12.1-5.rhel4 +\end{itemize} + +\subsection{Install Xen} + +\begin{verbatim} +tar zxvf xen-unstable-src.tgz +cd xen-unstable/ +make world +make install +\end{verbatim} + +The rest of the steps follow as with the binary tarball installation. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/scheduler_management.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/scheduler_management.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Scheduler Management} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/suse.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/suse.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Installing Xen on SuSE or SuSE Linux Enterprise Server (SLES)} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/testing.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/testing.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{Testing Xen} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/xenstat.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/xenstat.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{xenstat} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/xentrace.tex --- /dev/null Sun Dec 4 00:34:25 2005 +++ b/docs/src/user/xentrace.tex Sun Dec 4 00:52:38 2005 @@ -0,0 +1,3 @@ +\chapter{xentrace} + +Placeholder. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/build.tex --- a/docs/src/user/build.tex Sun Dec 4 00:34:25 2005 +++ /dev/null Sun Dec 4 00:52:38 2005 @@ -1,170 +0,0 @@ -\chapter{Build, Boot and Debug Options} - -This chapter describes the build- and boot-time options which may be -used to tailor your Xen system. - - -\section{Xen Build Options} - -Xen provides a number of build-time options which should be set as -environment variables or passed on make's command-line. - -\begin{description} -\item[verbose=y] Enable debugging messages when Xen detects an - unexpected condition. Also enables console output from all domains. -\item[debug=y] Enable debug assertions. Implies {\bf verbose=y}. - (Primarily useful for tracing bugs in Xen). -\item[debugger=y] Enable the in-Xen debugger. This can be used to - debug Xen, guest OSes, and applications. -\item[perfc=y] Enable performance counters for significant events - within Xen. The counts can be reset or displayed on Xen's console - via console control keys. -\item[trace=y] Enable per-cpu trace buffers which log a range of - events within Xen for collection by control software. -\end{description} - - -\section{Xen Boot Options} -\label{s:xboot} - -These options are used to configure Xen's behaviour at runtime. They -should be appended to Xen's command line, either manually or by -editing \path{grub.conf}. - -\begin{description} -\item [ noreboot ] Don't reboot the machine automatically on errors. - This is useful to catch debug output if you aren't catching console - messages via the serial line. -\item [ nosmp ] Disable SMP support. This option is implied by - `ignorebiostables'. -\item [ watchdog ] Enable NMI watchdog which can report certain - failures. -\item [ noirqbalance ] Disable software IRQ balancing and affinity. - This can be used on systems such as Dell 1850/2850 that have - workarounds in hardware for IRQ-routing issues. -\item [ badpage=$<$page number$>$,$<$page number$>$, \ldots ] Specify - a list of pages not to be allocated for use because they contain bad - bytes. For example, if your memory tester says that byte 0x12345678 - is bad, you would place `badpage=0x12345' on Xen's command line. -\item [ com1=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ - com2=$<$baud$>$,DPS,$<$io\_base$>$,$<$irq$>$ ] \mbox{}\\ - Xen supports up to two 16550-compatible serial ports. For example: - `com1=9600, 8n1, 0x408, 5' maps COM1 to a 9600-baud port, 8 data - bits, no parity, 1 stop bit, I/O port base 0x408, IRQ 5. If some - configuration options are standard (e.g., I/O base and IRQ), then - only a prefix of the full configuration string need be specified. If - the baud rate is pre-configured (e.g., by the bootloader) then you - can specify `auto' in place of a numeric baud rate. -\item [ console=$<$specifier list$>$ ] Specify the destination for Xen - console I/O. This is a comma-separated list of, for example: - \begin{description} - \item[ vga ] Use VGA console and allow keyboard input. - \item[ com1 ] Use serial port com1. - \item[ com2H ] Use serial port com2. Transmitted chars will have the - MSB set. Received chars must have MSB set. - \item[ com2L] Use serial port com2. Transmitted chars will have the - MSB cleared. Received chars must have MSB cleared. - \end{description} - The latter two examples allow a single port to be shared by two - subsystems (e.g.\ console and debugger). Sharing is controlled by - MSB of each transmitted/received character. [NB. Default for this - option is `com1,vga'] -\item [ sync\_console ] Force synchronous console output. This is - useful if you system fails unexpectedly before it has sent all - available output to the console. In most cases Xen will - automatically enter synchronous mode when an exceptional event - occurs, but this option provides a manual fallback. -\item [ conswitch=$<$switch-char$><$auto-switch-char$>$ ] Specify how - to switch serial-console input between Xen and DOM0. The required - sequence is CTRL-$<$switch-char$>$ pressed three times. Specifying - the backtick character disables switching. The - $<$auto-switch-char$>$ specifies whether Xen should auto-switch - input to DOM0 when it boots --- if it is `x' then auto-switching is - disabled. Any other value, or omitting the character, enables - auto-switching. [NB. Default switch-char is `a'.] -\item [ nmi=xxx ] - Specify what to do with an NMI parity or I/O error. \\ - `nmi=fatal': Xen prints a diagnostic and then hangs. \\ - `nmi=dom0': Inform DOM0 of the NMI. \\ - `nmi=ignore': Ignore the NMI. -\item [ mem=xxx ] Set the physical RAM address limit. Any RAM - appearing beyond this physical address in the memory map will be - ignored. This parameter may be specified with a B, K, M or G suffix, - representing bytes, kilobytes, megabytes and gigabytes respectively. - The default unit, if no suffix is specified, is kilobytes. -\item [ dom0\_mem=xxx ] Set the amount of memory to be allocated to - domain0. In Xen 3.x the parameter may be specified with a B, K, M or - G suffix, representing bytes, kilobytes, megabytes and gigabytes - respectively; if no suffix is specified, the parameter defaults to - kilobytes. In previous versions of Xen, suffixes were not supported - and the value is always interpreted as kilobytes. -\item [ tbuf\_size=xxx ] Set the size of the per-cpu trace buffers, in - pages (default 1). Note that the trace buffers are only enabled in - debug builds. Most users can ignore this feature completely. -\item [ sched=xxx ] Select the CPU scheduler Xen should use. The - current possibilities are `bvt' (default), `atropos' and `rrobin'. - For more information see Section~\ref{s:sched}. -\item [ apic\_verbosity=debug,verbose ] Print more detailed - information about local APIC and IOAPIC configuration. -\item [ lapic ] Force use of local APIC even when left disabled by - uniprocessor BIOS. -\item [ nolapic ] Ignore local APIC in a uniprocessor system, even if - enabled by the BIOS. -\item [ apic=bigsmp,default,es7000,summit ] Specify NUMA platform. - This can usually be probed automatically. -\end{description} - -In addition, the following options may be specified on the Xen command -line. Since domain 0 shares responsibility for booting the platform, -Xen will automatically propagate these options to its command line. -These options are taken from Linux's command-line syntax with -unchanged semantics. - -\begin{description} -\item [ acpi=off,force,strict,ht,noirq,\ldots ] Modify how Xen (and - domain 0) parses the BIOS ACPI tables. -\item [ acpi\_skip\_timer\_override ] Instruct Xen (and domain~0) to - ignore timer-interrupt override instructions specified by the BIOS - ACPI tables. -\item [ noapic ] Instruct Xen (and domain~0) to ignore any IOAPICs - that are present in the system, and instead continue to use the - legacy PIC. -\end{description} - - -\section{XenLinux Boot Options} - -In addition to the standard Linux kernel boot options, we support: -\begin{description} -\item[ xencons=xxx ] Specify the device node to which the Xen virtual - console driver is attached. The following options are supported: - \begin{center} - \begin{tabular}{l} - `xencons=off': disable virtual console \\ - `xencons=tty': attach console to /dev/tty1 (tty0 at boot-time) \\ - `xencons=ttyS': attach console to /dev/ttyS0 - \end{tabular} -\end{center} -The default is ttyS for dom0 and tty for all other domains. -\end{description} - - -\section{Debugging} -\label{s:keys} - -Xen has a set of debugging features that can be useful to try and -figure out what's going on. Hit `h' on the serial line (if you -specified a baud rate on the Xen command line) or ScrollLock-h on the -keyboard to get a list of supported commands. - -If you have a crash you'll likely get a crash dump containing an EIP -(PC) which, along with an \path{objdump -d image}, can be useful in -figuring out what's happened. Debug a Xenlinux image just as you -would any other Linux kernel. - -%% We supply a handy debug terminal program which you can find in -%% \path{/usr/local/src/xen-2.0.bk/tools/misc/miniterm/} This should -%% be built and executed on another machine that is connected via a -%% null modem cable. Documentation is included. Alternatively, if the -%% Xen machine is connected to a serial-port server then we supply a -%% dumb TCP terminal client, {\tt xencons}. diff -r 757218700a40 -r 8098cc1daac4 docs/src/user/redhat.tex --- a/docs/src/user/redhat.tex Sun Dec 4 00:34:25 2005 +++ /dev/null Sun Dec 4 00:52:38 2005 @@ -1,61 +0,0 @@ -\chapter{Installing Xen / XenLinux on Red~Hat or Fedora Core} - -When using Xen / XenLinux on a standard Linux distribution there are a -couple of things to watch out for: - -Note that, because domains greater than 0 don't have any privileged -access at all, certain commands in the default boot sequence will fail -e.g.\ attempts to update the hwclock, change the console font, update -the keytable map, start apmd (power management), or gpm (mouse -cursor). Either ignore the errors (they should be harmless), or -remove them from the startup scripts. Deleting the following links -are a good start: {\path{S24pcmcia}}, {\path{S09isdn}}, -{\path{S17keytable}}, {\path{S26apmd}}, {\path{S85gpm}}. - -If you want to use a single root file system that works cleanly for -both domain~0 and unprivileged domains, a useful trick is to use -different `init' run levels. For example, use run level 3 for -domain~0, and run level 4 for other domains. This enables different -startup scripts to be run in depending on the run level number passed -on the kernel command line. - -If using NFS root files systems mounted either from an external server -or from domain0 there are a couple of other gotchas. The default -{\path{/etc/sysconfig/iptables}} rules block NFS, so part way through -the boot sequence things will suddenly go dead. - -If you're planning on having a separate NFS {\path{/usr}} partition, -the RH9 boot scripts don't make life easy - they attempt to mount NFS -file systems way to late in the boot process. The easiest way I found -to do this was to have a {\path{/linuxrc}} script run ahead of -{\path{/sbin/init}} that mounts {\path{/usr}}: - -\begin{quote} - \begin{small}\begin{verbatim} - #!/bin/bash - /sbin/ipconfig lo 127.0.0.1 - /sbin/portmap - /bin/mount /usr - exec /sbin/init "$@" <>/dev/console 2>&1 -\end{verbatim}\end{small} -\end{quote} - -%% $ XXX SMH: font lock fix :-) - -The one slight complication with the above is that -{\path{/sbin/portmap}} is dynamically linked against -{\path{/usr/lib/libwrap.so.0}} Since this is in {\path{/usr}}, it -won't work. This can be solved by copying the file (and link) below -the {\path{/usr}} mount point, and just let the file be `covered' when -the mount happens. - -In some installations, where a shared read-only {\path{/usr}} is being -used, it may be desirable to move other large directories over into -the read-only {\path{/usr}}. For example, you might replace -{\path{/bin}}, {\path{/lib}} and {\path{/sbin}} with links into -{\path{/usr/root/bin}}, {\path{/usr/root/lib}} and -{\path{/usr/root/sbin}} respectively. This creates other problems for -running the {\path{/linuxrc}} script, requiring bash, portmap, mount, -ifconfig, and a handful of other shared libraries to be copied below -the mount point --- a simple statically-linked C program would solve -this problem. _______________________________________________ Xen-changelog mailing list Xen-changelog@xxxxxxxxxxxxxxxxxxx http://lists.xensource.com/xen-changelog

©2013 Xen Project, A Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation.
Xen Project is a trademark of The Linux Foundation.