ia64/xen-unstable

view docs/src/user/installation.tex @ 7053:b2928ee8ddcd

Update User's Guide installation section to mention hotplug.

Now that hotplug seems to be necessary to boot new domains (at least, to
get disk access in those domains), add a note to the installation guide
mentioning this dependency.

Signed-off-by: Michael Vrable <mvrable@cs.ucsd.edu>
author kaf24@firebug.cl.cam.ac.uk
date Fri Sep 23 20:10:32 2005 +0100 (2005-09-23)
parents 06d84bf87159
children a2d613c125a5
line source
1 \chapter{Installation}
3 The Xen distribution includes three main components: Xen itself, ports
4 of Linux 2.4 and 2.6 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.4-xenU} to build a Linux 2.4
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 %% The procedure is similar to build the Linux 2.4 port: \\
194 %% \verb!# LINUX_SRC=/path/to/linux2.4/source make linux24!
197 %% \framebox{\parbox{5in}{
198 %% {\bf Distro specific:} \\
199 %% {\it Gentoo} --- if not using udev (most installations,
200 %% currently), you'll need to enable devfs and devfs mount at boot
201 %% time in the xen0 config. }}
203 \subsection{Custom XenLinux Builds}
205 % If you have an SMP machine you may wish to give the {\tt '-j4'}
206 % argument to make to get a parallel build.
208 If you wish to build a customized XenLinux kernel (e.g. to support
209 additional devices or enable distribution-required features), you can
210 use the standard Linux configuration mechanisms, specifying that the
211 architecture being built for is \path{xen}, e.g:
212 \begin{quote}
213 \begin{verbatim}
214 # cd linux-2.6.11-xen0
215 # make ARCH=xen xconfig
216 # cd ..
217 # make
218 \end{verbatim}
219 \end{quote}
221 You can also copy an existing Linux configuration (\path{.config})
222 into \path{linux-2.6.11-xen0} and execute:
223 \begin{quote}
224 \begin{verbatim}
225 # make ARCH=xen oldconfig
226 \end{verbatim}
227 \end{quote}
229 You may be prompted with some Xen-specific options; we advise
230 accepting the defaults for these options.
232 Note that the only difference between the two types of Linux kernel
233 that are built is the configuration file used for each. The `U'
234 suffixed (unprivileged) versions don't contain any of the physical
235 hardware device drivers, leading to a 30\% reduction in size; hence
236 you may prefer these for your non-privileged domains. The `0'
237 suffixed privileged versions can be used to boot the system, as well
238 as in driver domains and unprivileged domains.
240 \subsection{Installing the Binaries}
242 The files produced by the build process are stored under the
243 \path{dist/install/} directory. To install them in their default
244 locations, do:
245 \begin{quote}
246 \begin{verbatim}
247 # make install
248 \end{verbatim}
249 \end{quote}
251 Alternatively, users with special installation requirements may wish
252 to install them manually by copying the files to their appropriate
253 destinations.
255 %% Files in \path{install/boot/} include:
256 %% \begin{itemize}
257 %% \item \path{install/boot/xen-2.0.gz} Link to the Xen 'kernel'
258 %% \item \path{install/boot/vmlinuz-2.6-xen0} Link to domain 0
259 %% XenLinux kernel
260 %% \item \path{install/boot/vmlinuz-2.6-xenU} Link to unprivileged
261 %% XenLinux kernel
262 %% \end{itemize}
264 The \path{dist/install/boot} directory will also contain the config
265 files used for building the XenLinux kernels, and also versions of Xen
266 and XenLinux kernels that contain debug symbols (\path{xen-syms-2.0.6}
267 and \path{vmlinux-syms-2.6.11.11-xen0}) which are essential for
268 interpreting crash dumps. Retain these files as the developers may
269 wish to see them if you post on the mailing list.
272 \section{Configuration}
273 \label{s:configure}
275 Once you have built and installed the Xen distribution, it is simple
276 to prepare the machine for booting and running Xen.
278 \subsection{GRUB Configuration}
280 An entry should be added to \path{grub.conf} (often found under
281 \path{/boot/} or \path{/boot/grub/}) to allow Xen / XenLinux to boot.
282 This file is sometimes called \path{menu.lst}, depending on your
283 distribution. The entry should look something like the following:
285 {\small
286 \begin{verbatim}
287 title Xen 2.0 / XenLinux 2.6
288 kernel /boot/xen-2.0.gz dom0_mem=131072
289 module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro console=tty0
290 \end{verbatim}
291 }
293 The kernel line tells GRUB where to find Xen itself and what boot
294 parameters should be passed to it (in this case, setting domain 0's
295 memory allocation in kilobytes and the settings for the serial port).
296 For more details on the various Xen boot parameters see
297 Section~\ref{s:xboot}.
299 The module line of the configuration describes the location of the
300 XenLinux kernel that Xen should start and the parameters that should
301 be passed to it (these are standard Linux parameters, identifying the
302 root device and specifying it be initially mounted read only and
303 instructing that console output be sent to the screen). Some
304 distributions such as SuSE do not require the \path{ro} parameter.
306 %% \framebox{\parbox{5in}{
307 %% {\bf Distro specific:} \\
308 %% {\it SuSE} --- Omit the {\tt ro} option from the XenLinux
309 %% kernel command line, since the partition won't be remounted rw
310 %% during boot. }}
313 If you want to use an initrd, just add another \path{module} line to
314 the configuration, as usual:
316 {\small
317 \begin{verbatim}
318 module /boot/my_initrd.gz
319 \end{verbatim}
320 }
322 As always when installing a new kernel, it is recommended that you do
323 not delete existing menu options from \path{menu.lst} --- you may want
324 to boot your old Linux kernel in future, particularly if you have
325 problems.
327 \subsection{Serial Console (optional)}
329 %% kernel /boot/xen-2.0.gz dom0_mem=131072 com1=115200,8n1
330 %% module /boot/vmlinuz-2.6-xen0 root=/dev/sda4 ro
333 In order to configure Xen serial console output, it is necessary to
334 add an boot option to your GRUB config; e.g.\ replace the above kernel
335 line with:
336 \begin{quote}
337 {\small
338 \begin{verbatim}
339 kernel /boot/xen.gz dom0_mem=131072 com1=115200,8n1
340 \end{verbatim}}
341 \end{quote}
343 This configures Xen to output on COM1 at 115,200 baud, 8 data bits, 1
344 stop bit and no parity. Modify these parameters for your set up.
346 One can also configure XenLinux to share the serial console; to
347 achieve this append ``\path{console=ttyS0}'' to your module line.
349 If you wish to be able to log in over the XenLinux serial console it
350 is necessary to add a line into \path{/etc/inittab}, just as per
351 regular Linux. Simply add the line:
352 \begin{quote} {\small {\tt c:2345:respawn:/sbin/mingetty ttyS0}}
353 \end{quote}
355 and you should be able to log in. Note that to successfully log in as
356 root over the serial line will require adding \path{ttyS0} to
357 \path{/etc/securetty} in most modern distributions.
359 \subsection{TLS Libraries}
361 Users of the XenLinux 2.6 kernel should disable Thread Local Storage
362 (e.g.\ by doing a \path{mv /lib/tls /lib/tls.disabled}) before
363 attempting to run with a XenLinux kernel\footnote{If you boot without
364 first disabling TLS, you will get a warning message during the boot
365 process. In this case, simply perform the rename after the machine
366 is up and then run \texttt{/sbin/ldconfig} to make it take effect.}.
367 You can always reenable it by restoring the directory to its original
368 location (i.e.\ \path{mv /lib/tls.disabled /lib/tls}).
370 The reason for this is that the current TLS implementation uses
371 segmentation in a way that is not permissible under Xen. If TLS is
372 not disabled, an emulation mode is used within Xen which reduces
373 performance substantially.
375 We hope that this issue can be resolved by working with Linux
376 distribution vendors to implement a minor backward-compatible change
377 to the TLS library.
380 \section{Booting Xen}
382 It should now be possible to restart the system and use Xen. Reboot
383 as usual but choose the new Xen option when the Grub screen appears.
385 What follows should look much like a conventional Linux boot. The
386 first portion of the output comes from Xen itself, supplying low level
387 information about itself and the machine it is running on. The
388 following portion of the output comes from XenLinux.
390 You may see some errors during the XenLinux boot. These are not
391 necessarily anything to worry about --- they may result from kernel
392 configuration differences between your XenLinux kernel and the one you
393 usually use.
395 When the boot completes, you should be able to log into your system as
396 usual. If you are unable to log in to your system running Xen, you
397 should still be able to reboot with your normal Linux kernel.