xen/docs/src/user/start_addl_dom.tex

\chapter{Starting Additional Domains}

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}

%% 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
\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{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:
%% 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 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}

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.


\section{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
  maintained by Pascal Schmidt. You can download source packages from
  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}


\section{Starting / Stopping Domains Automatically}

It is possible to have certain domains start automatically at boot
time and to have dom0 wait for all running domains to shutdown before
it shuts down the system.

To specify a domain is to start at boot-time, place its configuration
file (or a link to it) under \path{/etc/xen/auto/}.

A Sys-V style init script for Red Hat and LSB-compliant systems is
provided and will be automatically copied to \path{/etc/init.d/}
during install.  You can then enable it in the appropriate way for
your distribution.

For instance, on Red Hat:

\begin{quote}
  \verb_# chkconfig --add xendomains_
\end{quote}

By default, this will start the boot-time domains in runlevels 3, 4
and 5.

You can also use the \path{service} command to run this script
manually, e.g:

\begin{quote}
  \verb_# service xendomains start_

  Starts all the domains with config files under /etc/xen/auto/.
\end{quote}

\begin{quote}
  \verb_# service xendomains stop_

  Shuts down ALL running Xen domains.
\end{quote}