path: root/docs/src/user/installation.tex

\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.