ia64/xen-unstable

view docs/src/user/installation.tex @ 7727:d7bcc7bbf981

Fix region0 virtual accesses
Signed-off by: Dan Magenheimer <dan.magenheimer@hp.com>
author djm@kirby.fc.hp.com
date Fri Nov 11 12:51:08 2005 -0600 (2005-11-11)
parents 4e0c94871be2
children 79e8991af6b4
line source
1 \chapter{Installation}
3 The Xen distribution includes three main components: Xen itself, ports
4 of Linux and NetBSD to run on Xen, and the userspace
5 tools required to manage a Xen-based system. This chapter describes
6 how to install the Xen~2.0 distribution from source. Alternatively,
7 there may be pre-built packages available as part of your operating
8 system distribution.
11 \section{Prerequisites}
12 \label{sec:prerequisites}
14 The following is a full list of prerequisites. Items marked `$\dag$'
15 are required by the \xend\ control tools, and hence required if you
16 want to run more than one virtual machine; items marked `$*$' are only
17 required if you wish to build from source.
18 \begin{itemize}
19 \item A working Linux distribution using the GRUB bootloader and
20 running on a P6-class (or newer) CPU.
21 \item [$\dag$] The \path{iproute2} package.
22 \item [$\dag$] The Linux bridge-utils\footnote{Available from {\tt
23 http://bridge.sourceforge.net}} (e.g., \path{/sbin/brctl})
24 \item [$\dag$] The Linux hotplug system\footnote{Available from {\tt
25 http://linux-hotplug.sourceforge.net/}} (e.g., \path{/sbin/hotplug}
26 and related scripts)
27 \item [$\dag$] An installation of Twisted~v1.3 or
28 above\footnote{Available from {\tt http://www.twistedmatrix.com}}.
29 There may be a binary package available for your distribution;
30 alternatively it can be installed by running `{\sl make
31 install-twisted}' in the root of the Xen source tree.
32 \item [$*$] Build tools (gcc v3.2.x or v3.3.x, binutils, GNU make).
33 \item [$*$] Development installation of libcurl (e.g., libcurl-devel)
34 \item [$*$] Development installation of zlib (e.g., zlib-dev).
35 \item [$*$] Development installation of Python v2.2 or later (e.g.,
36 python-dev).
37 \item [$*$] \LaTeX\ and transfig are required to build the
38 documentation.
39 \end{itemize}
41 Once you have satisfied the relevant prerequisites, you can now
42 install either a binary or source distribution of Xen.
45 \section{Installing from Binary Tarball}
47 Pre-built tarballs are available for download from the Xen download
48 page
49 \begin{quote} {\tt http://xen.sf.net}
50 \end{quote}
52 Once you've downloaded the tarball, simply unpack and install:
53 \begin{verbatim}
54 # tar zxvf xen-2.0-install.tgz
55 # cd xen-2.0-install
56 # sh ./install.sh
57 \end{verbatim}
59 Once you've installed the binaries you need to configure your system
60 as described in Section~\ref{s:configure}.
63 \section{Installing from Source}
65 This section describes how to obtain, build, and install Xen from
66 source.
68 \subsection{Obtaining the Source}
70 The Xen source tree is available as either a compressed source tar
71 ball or as a clone of our master BitKeeper repository.
73 \begin{description}
74 \item[Obtaining the Source Tarball]\mbox{} \\
75 Stable versions (and daily snapshots) of the Xen source tree are
76 available as compressed tarballs from the Xen download page
77 \begin{quote} {\tt http://xen.sf.net}
78 \end{quote}
80 \item[Using BitKeeper]\mbox{} \\
81 If you wish to install Xen from a clone of our latest BitKeeper
82 repository then you will need to install the BitKeeper tools.
83 Download instructions for BitKeeper can be obtained by filling out
84 the form at:
85 \begin{quote} {\tt http://www.bitmover.com/cgi-bin/download.cgi}
86 \end{quote}
87 The public master BK repository for the 2.0 release lives at:
88 \begin{quote} {\tt bk://xen.bkbits.net/xen-2.0.bk}
89 \end{quote}
90 You can use BitKeeper to download it and keep it updated with the
91 latest features and fixes.
93 Change to the directory in which you want to put the source code, then
94 run:
95 \begin{verbatim}
96 # bk clone bk://xen.bkbits.net/xen-2.0.bk
97 \end{verbatim}
99 Under your current directory, a new directory named \path{xen-2.0.bk}
100 has been created, which contains all the source code for Xen, the OS
101 ports, and the control tools. You can update your repository with the
102 latest changes at any time by running:
103 \begin{verbatim}
104 # cd xen-2.0.bk # to change into the local repository
105 # bk pull # to update the repository
106 \end{verbatim}
107 \end{description}
109 % \section{The distribution}
110 %
111 % The Xen source code repository is structured as follows:
112 %
113 % \begin{description}
114 % \item[\path{tools/}] Xen node controller daemon (Xend), command line
115 % tools, control libraries
116 % \item[\path{xen/}] The Xen VMM.
117 % \item[\path{linux-*-xen-sparse/}] Xen support for Linux.
118 % \item[\path{linux-*-patches/}] Experimental patches for Linux.
119 % \item[\path{netbsd-*-xen-sparse/}] Xen support for NetBSD.
120 % \item[\path{docs/}] Various documentation files for users and
121 % developers.
122 % \item[\path{extras/}] Bonus extras.
123 % \end{description}
125 \subsection{Building from Source}
127 The top-level Xen Makefile includes a target `world' that will do the
128 following:
130 \begin{itemize}
131 \item Build Xen.
132 \item Build the control tools, including \xend.
133 \item Download (if necessary) and unpack the Linux 2.6 source code,
134 and patch it for use with Xen.
135 \item Build a Linux kernel to use in domain 0 and a smaller
136 unprivileged kernel, which can optionally be used for unprivileged
137 virtual machines.
138 \end{itemize}
140 After the build has completed you should have a top-level directory
141 called \path{dist/} in which all resulting targets will be placed; of
142 particular interest are the two kernels XenLinux kernel images, one
143 with a `-xen0' extension which contains hardware device drivers and
144 drivers for Xen's virtual devices, and one with a `-xenU' extension
145 that just contains the virtual ones. These are found in
146 \path{dist/install/boot/} along with the image for Xen itself and the
147 configuration files used during the build.
149 The NetBSD port can be built using:
150 \begin{quote}
151 \begin{verbatim}
152 # make netbsd20
153 \end{verbatim}
154 \end{quote}
155 NetBSD port is built using a snapshot of the netbsd-2-0 cvs branch.
156 The snapshot is downloaded as part of the build process, if it is not
157 yet present in the \path{NETBSD\_SRC\_PATH} search path. The build
158 process also downloads a toolchain which includes all the tools
159 necessary to build the NetBSD kernel under Linux.
161 To customize further the set of kernels built you need to edit the
162 top-level Makefile. Look for the line:
164 \begin{quote}
165 \begin{verbatim}
166 KERNELS ?= mk.linux-2.6-xen0 mk.linux-2.6-xenU
167 \end{verbatim}
168 \end{quote}
170 You can edit this line to include any set of operating system kernels
171 which have configurations in the top-level \path{buildconfigs/}
172 directory, for example \path{mk.linux-2.6-xenU} to build a Linux 2.6
173 kernel containing only virtual device drivers.
175 %% Inspect the Makefile if you want to see what goes on during a
176 %% build. Building Xen and the tools is straightforward, but XenLinux
177 %% is more complicated. The makefile needs a `pristine' Linux kernel
178 %% tree to which it will then add the Xen architecture files. You can
179 %% tell the makefile the location of the appropriate Linux compressed
180 %% tar file by
181 %% setting the LINUX\_SRC environment variable, e.g. \\
182 %% \verb!# LINUX_SRC=/tmp/linux-2.6.11.tar.bz2 make world! \\ or by
183 %% placing the tar file somewhere in the search path of {\tt
184 %% LINUX\_SRC\_PATH} which defaults to `{\tt .:..}'. If the
185 %% makefile can't find a suitable kernel tar file it attempts to
186 %% download it from kernel.org (this won't work if you're behind a
187 %% firewall).
189 %% After untaring the pristine kernel tree, the makefile uses the {\tt
190 %% mkbuildtree} script to add the Xen patches to the kernel.
193 %% \framebox{\parbox{5in}{
194 %% {\bf Distro specific:} \\
195 %% {\it Gentoo} --- if not using udev (most installations,
196 %% currently), you'll need to enable devfs and devfs mount at boot
197 %% time in the xen0 config. }}
199 \subsection{Custom XenLinux Builds}
201 % If you have an SMP machine you may wish to give the {\tt '-j4'}
202 % argument to make to get a parallel build.
204 If you wish to build a customized XenLinux kernel (e.g. to support
205 additional devices or enable distribution-required features), you can
206 use the standard Linux configuration mechanisms, specifying that the
207 architecture being built for is \path{xen}, e.g:
208 \begin{quote}
209 \begin{verbatim}
210 # cd linux-2.6.11-xen0
211 # make ARCH=xen xconfig
212 # cd ..
213 # make
214 \end{verbatim}
215 \end{quote}
217 You can also copy an existing Linux configuration (\path{.config})
218 into \path{linux-2.6.11-xen0} and execute:
219 \begin{quote}
220 \begin{verbatim}
221 # make ARCH=xen oldconfig
222 \end{verbatim}
223 \end{quote}
225 You may be prompted with some Xen-specific options; we advise
226 accepting the defaults for these options.
228 Note that the only difference between the two types of Linux kernel
229 that are built is the configuration file used for each. The `U'
230 suffixed (unprivileged) versions don't contain any of the physical
231 hardware device drivers, leading to a 30\% reduction in size; hence
232 you may prefer these for your non-privileged domains. The `0'
233 suffixed privileged versions can be used to boot the system, as well
234 as in driver domains and unprivileged domains.
236 \subsection{Installing the Binaries}
238 The files produced by the build process are stored under the
239 \path{dist/install/} directory. To install them in their default
240 locations, do:
241 \begin{quote}
242 \begin{verbatim}
243 # make install
244 \end{verbatim}
245 \end{quote}
247 Alternatively, users with special installation requirements may wish
248 to install them manually by copying the files to their appropriate
249 destinations.
251 %% Files in \path{install/boot/} include:
252 %% \begin{itemize}
253 %% \item \path{install/boot/xen-2.0.gz} Link to the Xen 'kernel'
254 %% \item \path{install/boot/vmlinuz-2.6-xen0} Link to domain 0
255 %% XenLinux kernel
256 %% \item \path{install/boot/vmlinuz-2.6-xenU} Link to unprivileged
257 %% XenLinux kernel
258 %% \end{itemize}
260 The \path{dist/install/boot} directory will also contain the config
261 files used for building the XenLinux kernels, and also versions of Xen
262 and XenLinux kernels that contain debug symbols (\path{xen-syms-2.0.6}
263 and \path{vmlinux-syms-2.6.11.11-xen0}) which are essential for
264 interpreting crash dumps. Retain these files as the developers may
265 wish to see them if you post on the mailing list.
268 \section{Configuration}
269 \label{s:configure}
271 Once you have built and installed the Xen distribution, it is simple
272 to prepare the machine for booting and running Xen.
274 \subsection{GRUB Configuration}
276 An entry should be added to \path{grub.conf} (often found under
277 \path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot.
278 This file is sometimes called \path{menu.lst}, depending on your
279 distribution. The entry should look something like the following:
281 {\small
282 \begin{verbatim}
283 title Xen 2.0 / XenLinux 2.6
284 kernel /boot/xen-2.0.gz dom0_mem=131072
285 module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro console=tty0
286 \end{verbatim}
287 }
289 The kernel line tells GRUB where to find Xen itself and what boot
290 parameters should be passed to it (in this case, setting domain 0's
291 memory allocation in kilobytes and the settings for the serial port).
292 For more details on the various Xen boot parameters see
293 Section~\ref{s:xboot}.
295 The module line of the configuration describes the location of the
296 XenLinux kernel that Xen should start and the parameters that should
297 be passed to it (these are standard Linux parameters, identifying the
298 root device and specifying it be initially mounted read only and
299 instructing that console output be sent to the screen). Some
300 distributions such as SuSE do not require the \path{ro} parameter.
302 %% \framebox{\parbox{5in}{
303 %% {\bf Distro specific:} \\
304 %% {\it SuSE} --- Omit the {\tt ro} option from the XenLinux
305 %% kernel command line, since the partition won't be remounted rw
306 %% during boot. }}
309 If you want to use an initrd, just add another \path{module} line to
310 the configuration, as usual:
312 {\small
313 \begin{verbatim}
314 module /boot/my_initrd.gz
315 \end{verbatim}
316 }
318 As always when installing a new kernel, it is recommended that you do
319 not delete existing menu options from \path{menu.lst} --- you may want
320 to boot your old Linux kernel in future, particularly if you have
321 problems.
323 \subsection{Serial Console (optional)}
325 %% kernel /boot/xen-2.0.gz dom0_mem=131072 com1=115200,8n1
326 %% module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro
329 In order to configure Xen serial console output, it is necessary to
330 add an boot option to your GRUB config; e.g.\ replace the above kernel
331 line with:
332 \begin{quote}
333 {\small
334 \begin{verbatim}
335 kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
336 \end{verbatim}}
337 \end{quote}
339 This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1
340 stop bit and no parity. Modify these parameters for your set up.
342 One can also configure XenLinux to share the serial console; to
343 achieve this append ``\path{console=ttyS0}'' to your module line.
345 If you wish to be able to log in over the XenLinux serial console it
346 is necessary to add a line into \path{/etc/inittab}, just as per
347 regular Linux. Simply add the line:
348 \begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty ttyS0}}
349 \end{quote}
351 and you should be able to log in. Note that to successfully log in as
352 root over the serial line will require adding \path{ttyS0} to
353 \path{/etc/securetty} in most modern distributions.
355 \subsection{TLS Libraries}
357 Users of the XenLinux 2.6 kernel should disable Thread Local Storage
358 (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before
359 attempting to run with a XenLinux kernel\footnote{If you boot without
360 first disabling TLS, you will get a warning message during the boot
361 process. In this case, simply perform the rename after the machine
362 is up and then run \texttt{/sbin/ldconfig} to make it take effect.}.
363 You can always reenable it by restoring the directory to its original
364 location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
366 The reason for this is that the current TLS implementation uses
367 segmentation in a way that is not permissible under Xen. If TLS is
368 not disabled, an emulation mode is used within Xen which reduces
369 performance substantially.
371 We hope that this issue can be resolved by working with Linux
372 distribution vendors to implement a minor backward-compatible change
373 to the TLS library.
376 \section{Booting Xen}
378 It should now be possible to restart the system and use Xen. Reboot
379 as usual but choose the new Xen option when the Grub screen appears.
381 What follows should look much like a conventional Linux boot. The
382 first portion of the output comes from Xen itself, supplying low level
383 information about itself and the machine it is running on. The
384 following portion of the output comes from XenLinux.
386 You may see some errors during the XenLinux boot. These are not
387 necessarily anything to worry about --- they may result from kernel
388 configuration differences between your XenLinux kernel and the one you
389 usually use.
391 When the boot completes, you should be able to log into your system as
392 usual. If you are unable to log in to your system running Xen, you
393 should still be able to reboot with your normal Linux kernel.