diff options
Diffstat (limited to 'docs/src/user/installation.tex')
| -rw-r--r-- | docs/src/user/installation.tex | 465 |
1 files changed, 0 insertions, 465 deletions
diff --git a/docs/src/user/installation.tex b/docs/src/user/installation.tex deleted file mode 100644 index 4e8f519773..0000000000 --- a/docs/src/user/installation.tex +++ /dev/null @@ -1,465 +0,0 @@ -\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~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. -\begin{itemize} -\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) -\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.,\ - 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. - -\section{Installing from Binary Tarball} - -Pre-built tarballs are available for download from the XenSource downloads -page: -\begin{quote} {\tt http://www.xensource.com/downloads/} -\end{quote} - -Once you've downloaded the tarball, simply unpack and install: -\begin{verbatim} -# tar zxvf xen-3.0-install.tgz -# cd xen-3.0-install -# sh ./install.sh -\end{verbatim} - -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. - -\subsection{Obtaining the Source} - -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 \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} - -% \section{The distribution} -% -% The Xen source code repository is structured as follows: -% -% \begin{description} -% \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{patches/}] Experimental patches for Linux. -% \item[\path{docs/}] Various documentation files for users and -% developers. -% \item[\path{extras/}] Bonus extras. -% \end{description} - -\subsection{Building from Source} - -The top-level Xen Makefile includes a target ``world'' that will do the -following: - -\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. -\end{itemize} - -After the build has completed you should have a top-level directory -called \path{dist/} in which all resulting targets will be placed. Of -particular interest are the two XenLinux kernel images, one with a -``-xen0'' extension which contains hardware device drivers and drivers -for Xen's virtual devices, and one with a ``-xenU'' extension that -just contains the virtual ones. These are found in -\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. - -To customize the set of kernels built you need to edit the top-level -Makefile. Look for the line: -\begin{quote} -\begin{verbatim} -KERNELS ?= mk.linux-2.6-xen0 mk.linux-2.6-xenU -\end{verbatim} -\end{quote} - -You can edit this line to include any set of operating system kernels -which have configurations in the top-level \path{buildconfigs/} -directory, for example \path{mk.linux-2.6-xenU} to build a Linux 2.6 -kernel containing only virtual device drivers. - -%% Inspect the Makefile if you want to see what goes on during a -%% build. Building Xen and the tools is straightforward, but XenLinux -%% is more complicated. The makefile needs a `pristine' Linux kernel -%% tree to which it will then add the Xen architecture files. You can -%% tell the makefile the location of the appropriate Linux compressed -%% tar file by -%% setting the LINUX\_SRC environment variable, e.g. \\ -%% \verb!# LINUX_SRC=/tmp/linux-2.6.11.tar.bz2 make world! \\ or by -%% placing the tar file somewhere in the search path of {\tt -%% LINUX\_SRC\_PATH} which defaults to `{\tt .:..}'. If the -%% makefile can't find a suitable kernel tar file it attempts to -%% download it from kernel.org (this won't work if you're behind a -%% firewall). - -%% After untaring the pristine kernel tree, the makefile uses the {\tt -%% mkbuildtree} script to add the Xen patches to the kernel. - -%% \framebox{\parbox{5in}{ -%% {\bf Distro specific:} \\ -%% {\it Gentoo} --- if not using udev (most installations, -%% currently), you'll need to enable devfs and devfs mount at boot -%% time in the xen0 config. }} - -\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. - -If you wish to build a customized XenLinux kernel (e.g.\ to support -additional devices or enable distribution-required features), you can -use the standard Linux configuration mechanisms, specifying that the -architecture being built for is \path{xen}, e.g: -\begin{quote} -\begin{verbatim} -# cd linux-2.6.11-xen0 -# make ARCH=xen xconfig -# cd .. -# make -\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: -\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. - -Note that the only difference between the two types of Linux kernels -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 Generated Binaries} - -The files produced by the build process are stored under the -\path{dist/install/} directory. To install them in their default -locations, do: -\begin{quote} -\begin{verbatim} -# make install -\end{verbatim} -\end{quote} - -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-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 -%% XenLinux kernel -%% \end{itemize} - -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 -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. - -\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: - -%% 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=262144 - module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro console=tty0 -\end{verbatim} -} - -The kernel line tells GRUB where to find Xen itself and what boot -parameters should be passed to it (in this case, setting the domain~0 -memory allocation in kilobytes and the settings for the serial port). -For more details on the various Xen boot parameters see -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. 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:} \\ -%% {\it SuSE} --- Omit the {\tt ro} option from the XenLinux -%% kernel command line, since the partition won't be remounted rw -%% during boot. }} - -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. - -\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} - 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 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 \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. - -We hope that this issue can be resolved by working with Linux -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 -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 by selecting it at the GRUB prompt. |