doc/en/xen-guide.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xen-guide.xml,v 1.9 2011/06/07 09:27:59 nightmorph Exp $ -->

<guide>
<title>Configuring Gentoo with Xen</title>

<author title="Author">
  <mail link="swift@gentoo.org">Sven Vermeulen</mail>
</author>
<author title="Editor">
  <mail link="nightmorph"/>
</author>

<abstract>
This guide describes how to start using Xen on your Gentoo system
</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>6</version>
<date>2011-08-29</date>

<chapter>
<title>Introduction</title>
<section>
<body>

<p>
The <uri link="http://www.xen.org/">Xen</uri> technology allows you to run
multiple operating systems on a single physical system, govern resource
consumption and even migrate domains (which are the virtual environments in
which a guest operating system runs) from one Xen-powered system to another. Xen
requires the host operating system to support Xen (which, in this case, will be
a Linux kernel) but guest operating systems can run unmodified <e>if</e> your
hardware supports Intel Virtualization Technology (VT-x) or AMD Virtualization
Technology (SVM). Otherwise your guest operating systems must also support Xen.
</p>

<p>
This guide will talk you through the configuration steps necessary to get Xen up
and running on Gentoo Linux. We will not discuss Xen itself (the Xen project has
<uri link="http://xen.org/support/documentation.html">decent documentation</uri>
available) nor will we talk about specialized setups that might be very
interesting for Xen setups but are not Xen-related (like exporting Portage
through NFS, booting Linux using PXE, etc.)
</p>

</body>
</section>
</chapter>
<chapter>
<title>Preparing Domain0</title>
<section>
<title>Introduction</title>
<body>

<p>
<e>Domain0</e> is the primary domain under Xen, hosting the host operating
system which governs all other domains. In this chapter we will prepare an
existing Gentoo installation to become the host operating system in this domain
and build the Xen-powered kernel so that Gentoo is ready to host other Xen
domains.
</p>

</body>
</section>
<section>
<title>Rebuilding the Gentoo Installation?</title>
<body>

<p>
A dramatic change that might be necessary is to rebuild the entire Gentoo
installation with a different <c>CFLAGS</c> setting. Guest operating systems
running under Xen might otherwise see major performance degradation. If you,
however, are planning on checking out Xen rather than installing it for
production use and are not terribly fond of rebuilding all programs, you can
skip this step. In this case you will notice performance degradation but you
will still be able to use Xen.
</p>

<impo>
It is advised that, if you change your <c>CFLAGS</c> and build your system with
a gcc lower than version 4, you do not have <c>-Os</c> set as it has been
reported to produce broken code.
</impo>

<pre caption="Editing the CFLAGS and rebuild the Gentoo installation">
~# <i>nano -w /etc/make.conf</i>
<comment>(Add -mno-tls-direct-seg-refs ONLY if you have a 32-bit dom0)</comment>
<comment>(You don't need this flag if you have a 64-bit dom0)</comment>
CFLAGS="-O2 -march=pentium4 -pipe <i>-mno-tls-direct-seg-refs</i>"

~# <i>emerge -e world</i>
</pre>

<p>
If you boot your system using an initial ramdisk (initrd) you need to
rebuild the initrd as well (which is best done by running all steps you would do
when you rebuild your kernel).
</p>

</body>
</section>
<section>
<title>Installing Xen</title>
<body>

<p>
Xen actually contains many components, so you'll need to install a few
packages.
</p>

<pre caption="Installing Xen">
~# <i>emerge xen xen-tools xen-sources</i>
</pre>

</body>
</section>
<section>
<title>Building the Kernel</title>
<body>

<p>
Next we'll build the Linux kernel with Xen support. This kernel, whose sources
are available at <path>/usr/src/linux-2.6.x.z-xen</path>, will be our main
running kernel (i.e. the one running domain 0). In the <c>XEN</c> section you'll
find drivers for all kinds of input/output, each driver having a <e>backend</e>
and <e>frontend</e> implementation available. For the domain 0 kernel you need
to select the <e>backend</e> implementation: these are used by the other
domains (who use the <e>frontend</e> drivers) to communicate directly with
the hardware.
</p>

<p>
Of course, don't forget to select <c>Xen-compatible</c> at <c>Processor type and
features</c>. If you're wondering about networking: each interface in a domain
has a point-to-point link to an interface on domain 0 (called
<path>vifX.Y</path> where X is the domain number and Y the Yth interface of that
domain), so you can configure your network the way you want (bridging, NAT,
etc.)
</p>

<pre caption="Enabling Xen Support for i386 Kernels">
Processor type and features  ---&gt;
      Subarchitecture Type (Xen-compatible)
</pre>

<pre caption="Enabling Xen Support for x86_64 Kernels">
Processor type and features  ---&gt;
      Subarchitecture Type (PC-compatible)
  [*] Enable Xen compatible kernel
  [*] Support for hot-pluggable CPUs
</pre>

<pre caption="Domain-0 Kernel Config">
Bus options (PCI etc.)  ---&gt;
  [*] PCI support
  [ ]   Xen PCI Frontend Debugging

Networking  ---&gt;
  Networking options  ---&gt;
    &lt;*&gt; 802.1d Ethernet Bridging
    <comment>Only required by bridged networking.</comment>

XEN  ---&gt;
  [*] Privileged Guest (domain 0)
  &lt;*&gt; Backend driver support
  &lt;*&gt;   Block-device backend driver
  &lt;*&gt;   Network-device backend driver
  &lt;*&gt;   PCI-device backend driver
           PCI Backend Mode (Virtual PCI) ---&gt;
  [*] Scrub memory before freeing it to Xen
  [*] Disable serial port drivers
      Xen version compatibility (3.0.4 and later)
</pre>

<pre caption="Domain-U Kernel Config">
Bus options (PCI etc.)  ---&gt;
  [ ] PCI support

Device Drivers  ---&gt;
  SCSI device support  ---&gt;
    &lt; &gt; SCSI device support
    <comment>Disabling SCSI support frees up the /dev/sd* device names
    for use as Xen virtual block devices.</comment>

XEN  ---&gt;
  [ ] Privileged Guest (domain 0)
  &lt;*&gt; Block-device frontend driver
  &lt;*&gt; Network-device frontend driver
  [*] Scrub memory before freeing it to Xen
  [*] Disable serial port drivers
      Xen version compatibility (3.0.4 and later)
</pre>

<p>
A nice hint is to have the kernel make process store its intermediate object
files elsewhere so that you can reuse the same kernel tree to build different
configurations:
</p>

<pre caption="Building the Kernel">
~# <i>mkdir -p ~/build/dom0 ~/build/domU</i>
~# <i>make O=~/build/dom0 menuconfig</i>
<comment>(Configure the kernel)</comment>
~# <i>make O=~/build/dom0 &amp;&amp; make O=~/build/dom0 modules_install</i>
</pre>

<p>
Once the kernel is built you'll find the kernel image immediately in the
build directory (not inside <path>arch/</path> or any other directory) called
<path>vmlinuz</path>. Copy it to <path>/boot</path> and then configure your
bootloader to use the Xen hypervisor (one of the components installed
previously) which is stored as <path>/boot/xen.gz</path>. In the bootloader
configuration, add your newly built kernel as the kernel that Xen should
boot. For instance, for GRUB:
</p>

<pre caption="GRUB Configuration for Xen">
title Xen 3.0 / Gentoo Linux 2.6.x.y
root (hd0,0)
kernel /boot/xen.gz
module /boot/kernel-2.6.x.y-xen0 root=/dev/hda3
</pre>

<p>
Now reboot your system into Xen. Once you are booted, you need to load the Xen
daemon:
</p>

<pre caption="Loading the Xen daemon">
~# <i>/etc/init.d/xend start</i>
</pre>

<p>
Now check if you can do whatever you normally do on your system. If this is the
case, you can edit your bootloader configuration to always boot into Xen and add
the Xen deamon to the default runlevel so that it is started automatically
next time you boot.
</p>

<note>
If you wish to start guest domains automatically on boot add <c>xendomains</c>
to the default runlevel as well and create a symlink in
<path>/etc/xen/auto/</path> to the Xen configuration files for the domains
you wish to start.
</note>

</body>
</section>
</chapter>
<chapter>
<title>Creating an Unpriviledged Domain</title>
<section>
<title>Building the Kernel</title>
<body>

<p>
Go to the Xen-powered Linux kernel source and update the configuration. It is
wise to keep as many topics as possible similar to the main kernel except the
<c>XEN</c> settings where drivers should now have their <e>frontend</e>
implementation selected instead of the <e>backend</e>. Then build the kernel
and place the resulting <path>vmlinuz</path> file where you want (we assume this
is <path>/mnt/data/xen/kernel</path>):
</p>

<pre caption="Building the guest kernel">
~# <i>make O=~/build/domU</i>
~# <i>cp ~/build/domU/vmlinuz /mnt/data/xen/kernel/kernel-2.6.x.y-xen</i>
</pre>

<p>
It is also possible to create a single kernel image for both the administrative
domain and the unpriviledged domain. More information about this can be found
in the Xen user manual.
</p>

</body>
</section>
<section>
<title>Creating the Domain Disks</title>
<body>

<p>
For best performance, it is best to dedicate a partition (or logical volume) to
a domain rather than a file based filesystem. However, if you are going to use
Xen primarily for tests using a file based filesystem does have its advantages
(especially regarding maintenance).
</p>

<p>
You can create a file based filesystem using <c>dd</c> and <c>mke2fs</c> (or
any other file system creation tool). For instance, to create a 2Gbyte ext3
filesystem:
</p>

<pre caption="Creating a file based filesystem">
~# <i>dd if=/dev/zero of=/mnt/data/xen/disks/ext3root.img bs=1M count=2048</i>
~# <i>mke2fs -j /mnt/data/xen/disks/ext3root.img</i>
</pre>

</body>
</section>
<section>
<title>Configuring a Domain</title>
<body>

<p>
Next we create a Xen configuration file for a domain. You can store these
configuration files where you want, for instance at
<path>/mnt/data/xen/configs</path>. As an example, we create a configuration
file for a small Gentoo environment which uses the disk image we created
previously:
</p>

<pre caption="Creating a domain configuration file">
~# <i>nano -w /mnt/data/xen/configs/gentoo</i>

kernel = "/mnt/data/xen/kernel/kernel-2.6.x.y-xen"
memory = 512
name   = "gentoo"
<comment>(Map the disk image to the virtual /dev/sda1)</comment>
disk   = ['file:/mnt/data/xen/disks/ext3root.img,sda1,w']
root   = "/dev/sda1 ro"
</pre>

<p>
If you are using a block device (such as an lvm volume or partition) for
the disk use 'phy:' instead of 'file:' and leave off /dev. For example:
</p>

<pre caption="Using a block device">
<comment>(LVM Volume)</comment>
disk = [ 'phy:lvm/xen-guest-root,sda1,w' ]

<comment>(Physical Partition)</comment>
disk = [ 'phy:sdb6,sda1,w' ]
</pre>

<p>
You can find example configuration files in <path>/etc/xen</path>.
</p>

</body>
</section>
<section>
<title>Launching the New Domain</title>
<body>

<p>
Now we're all set and we can launch the new domain. If the disk image contained
an operating system, we could just create and attach the domain using the
<c>xm</c> command (Xen manager):
</p>

<pre caption="Creating and starting a new domain">
~# <i>xm create /mnt/data/xen/configs/gentoo -c</i>
</pre>

<p>
The domain would be booted inside the terminal in which you executed the
command. However, in our case, the disk image is empty so the domain won't boot
up in anything useful. To fix this, you can loop-mount the image and install
Gentoo as you're used to.
</p>

<p>
If you want to disconnect from the domain, press <path>Ctrl+]</path>. You can
always reconnect to the domains' console using <c>xm console gentoo</c>.
However, there is only one console per domain, so only use it when you can't
access the domain otherwise (for instance, through SSH).
</p>

</body>
</section>
</chapter>
<chapter>
<title>Networking on Unpriviledged Domains</title>
<section>
<title>Introduction</title>
<body>

<p>
Xen supports at least two ways of configuring your (virtual) network:
<e>routed</e> and <e>bridged</e>.
</p>

<p>
When selecting the <e>routed</e> approach, the interface inside your
unpriviledged domain is connected to the virtual interface on your
administrative domain. On your administrative domain (domain 0), the virtual
interface is linked together with <path>eth0</path>. The
interface inside your unpriviledged domain should have an IP address on the same
network as the interface on the administrative domain. Any communication to
that IP address can only occur from the administrative domain, unless you set
up specific routing rules.
</p>

<p>
When selecting the <e>bridged</e> approach, your default network interface on
the administrative domain becomes a bridge which accepts connections to the
virtual domains as well as to the IP address your administrative domain has.
</p>

</body>
</section>
<section>
<title>Regular Routed Interfaces</title>
<body>

<p>
Before you set up the interface on your unpriviledged domain, make sure that
Xen's <path>netloop</path> and <path>netbk</path> drivers are loaded. A quick
hint: if you have <path>netloop</path> as a module, load it with
<c>nloopbacks=0</c> so that it doesn't create pointless interfaces to the
loopback device. Then, edit your domain configuration file and add a <c>vif</c>
instruction to it.
</p>

<pre caption="Configuring a virtual interface">
~# <i>nano -w /mnt/data/xen/configs/gentoo</i>

<comment>(Add the vif instruction)</comment>
vif    = [ 'ip=192.168.1.101, vifname=veth1' ]
</pre>

<p>
In the above example, the interface will be created for the unpriviledged domain
(in which it will be called <path>eth0</path>) and Xen will ensure that address
192.168.1.101 will be reachable from the administrative domain through interface
<path>veth1</path>.
</p>

<p>
This doesn't mean that the virtual <path>eth0</path> interface will
automatically have IP 192.168.1.101 assigned to it, but rather that, if you
don't give it that IP, it will not be connected with the administrative domain
and thus cannot be reached.
</p>

<p>
Now edit <path>/etc/xen/xend-config.sxp</path> as follows to select routed
network configuration:
</p>

<pre caption="Editing xend-config.sxp">
~# <i>nano -w /etc/xen/xend-config.sxp</i>

<comment>(Comment out the following lines)</comment>
<i>#</i>(network-script network-bridge)
<i>#</i>(vif-script vif-bridge)

<comment>(Enable the following lines)</comment>
(network-script network-route)
(vif-script vif-route)
</pre>

</body>
</section>
<section>
<title>Bridged Interfaces</title>
<body>

<p>
Unlike the routed interfaces you now need to load the <path>netloop</path>
driver with <c>nloopbacks=1</c> (or higher) as the additional loopback devices
are used to create the bridge. For the other modules you still need the
<path>netbk</path> module as well as briding functionality (<path>bridge</path>
module if build as such).
</p>

<p>
Now edit your virtual domain and add the <c>vif</c> construct:
</p>

<pre caption="Configuring a virtual interface">
~# <i>nano -w /mnt/data/xen/configs/gentoo</i>

<comment>(Add the vif instruction)</comment>
vif    = [ 'ip=192.168.1.101, vifname=veth0' ]
</pre>

<p>
Next edit <path>/etc/xen/xend-config.sxp</path> as follows to select bridged
network configuration:
</p>

<pre caption="Editing xend-config.sxp">
~# <i>nano -w /etc/xen/xend-config.sxp</i>

<comment>(Enable the following lines)</comment>
(network-script network-bridge)
(vif-script vif-bridge)

<comment>(Comment out the following lines if not done already)</comment>
<i>#</i> (network-script network-route)
<i>#</i> (vif-script vif-route)
</pre>

<p>
By default, the bridge will contain whatever interface is configured to be the
default interface (the device that is listed under the default route through
<c>ip route list</c>). If you want to alter this behavior, edit the
<path>xend-config.sxp</path> as follows:
</p>

<pre caption="Editing xend-config.sxp to change bridge configuration">
~# <i>nano -w /etc/xen/xend-config.sxp</i>

<comment>(Edit the network-script line)</comment>
(network-script <i>'</i>network-bridge <i>netdev=eth0 bridge=xenbr0 vifnum=0'</i>)
</pre>

<p>
Once the configuration is done, restart the <c>xend</c> init script to have Xen
build the bridge:
</p>

<pre caption="Restarting the xend daemon">
~# <i>/etc/init.d/xend restart</i>
</pre>

</body>
</section>
</chapter>
<chapter>
<title>Further Resources</title>
<section>
<title>Xen Documentation</title>
<body>

<ul>
  <li>
    <uri link="http://www.xen.org/support/documentation.html">Official Xen
    documentation</uri>
  </li>
  <li>
    <uri link="http://wiki.xen.org/">Xen Wiki</uri>
  </li>
</ul>

</body>
</section>
<section>
<title>Xen Tools</title>
<body>

<ul>
  <li>
    <uri
    link="http://virt-manager.org/">app-emulation/virt-manager</uri>
    is a graphical tool for administering virtual machines
  </li>
</ul>

</body>
</section>
</chapter>
</guide>
1	swift	1.1	<?xml version='1.0' encoding='UTF-8'?>
2			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3	nightmorph	1.10	<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/xen-guide.xml,v 1.9 2011/06/07 09:27:59 nightmorph Exp $ -->
4	swift	1.1
5	nightmorph	1.6	<guide>
6	swift	1.1	<title>Configuring Gentoo with Xen</title>
7
8			<author title="Author">
9			<mail link="swift@gentoo.org">Sven Vermeulen</mail>
10			</author>
11	nightmorph	1.7	<author title="Editor">
12			<mail link="nightmorph"/>
13			</author>
14	swift	1.1
15			<abstract>
16			This guide describes how to start using Xen on your Gentoo system
17			</abstract>
18
19			<!-- The content of this document is licensed under the CC-BY-SA license -->
20			<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21			<license/>
22
23	nightmorph	1.10	<version>6</version>
24			<date>2011-08-29</date>
25	swift	1.1
26			<chapter>
27			<title>Introduction</title>
28			<section>
29			<body>
30
31			<p>
32	nightmorph	1.10	The <uri link="http://www.xen.org/">Xen</uri> technology allows you to run
33	swift	1.1	multiple operating systems on a single physical system, govern resource
34			consumption and even migrate domains (which are the virtual environments in
35			which a guest operating system runs) from one Xen-powered system to another. Xen
36			requires the host operating system to support Xen (which, in this case, will be
37			a Linux kernel) but guest operating systems can run unmodified <e>if</e> your
38			hardware supports Intel Virtualization Technology (VT-x) or AMD Virtualization
39			Technology (SVM). Otherwise your guest operating systems must also support Xen.
40			</p>
41
42			<p>
43			This guide will talk you through the configuration steps necessary to get Xen up
44			and running on Gentoo Linux. We will not discuss Xen itself (the Xen project has
45	nightmorph	1.10	<uri link="http://xen.org/support/documentation.html">decent documentation</uri>
46			available) nor will we talk about specialized setups that might be very
47			interesting for Xen setups but are not Xen-related (like exporting Portage
48			through NFS, booting Linux using PXE, etc.)
49	swift	1.1	</p>
50
51			</body>
52			</section>
53			</chapter>
54			<chapter>
55			<title>Preparing Domain0</title>
56			<section>
57			<title>Introduction</title>
58			<body>
59
60			<p>
61			<e>Domain0</e> is the primary domain under Xen, hosting the host operating
62			system which governs all other domains. In this chapter we will prepare an
63			existing Gentoo installation to become the host operating system in this domain
64			and build the Xen-powered kernel so that Gentoo is ready to host other Xen
65			domains.
66			</p>
67
68			</body>
69			</section>
70			<section>
71	nightmorph	1.7	<title>Rebuilding the Gentoo Installation?</title>
72	swift	1.1	<body>
73
74			<p>
75			A dramatic change that might be necessary is to rebuild the entire Gentoo
76			installation with a different <c>CFLAGS</c> setting. Guest operating systems
77			running under Xen might otherwise see major performance degradation. If you,
78			however, are planning on checking out Xen rather than installing it for
79			production use and are not terribly fond of rebuilding all programs, you can
80			skip this step. In this case you will notice performance degradation but you
81			will still be able to use Xen.
82			</p>
83
84			<impo>
85			It is advised that, if you change your <c>CFLAGS</c> and build your system with
86			a gcc lower than version 4, you do not have <c>-Os</c> set as it has been
87			reported to produce broken code.
88			</impo>
89
90			<pre caption="Editing the CFLAGS and rebuild the Gentoo installation">
91			~# <i>nano -w /etc/make.conf</i>
92	nightmorph	1.7	<comment>(Add -mno-tls-direct-seg-refs ONLY if you have a 32-bit dom0)</comment>
93			<comment>(You don't need this flag if you have a 64-bit dom0)</comment>
94	swift	1.1	CFLAGS="-O2 -march=pentium4 -pipe <i>-mno-tls-direct-seg-refs</i>"
95
96			~# <i>emerge -e world</i>
97			</pre>
98
99			<p>
100			If you boot your system using an initial ramdisk (initrd) you need to
101			rebuild the initrd as well (which is best done by running all steps you would do
102			when you rebuild your kernel).
103			</p>
104
105			</body>
106			</section>
107			<section>
108			<title>Installing Xen</title>
109			<body>
110
111			<p>
112	nightmorph	1.8	Xen actually contains many components, so you'll need to install a few
113			packages.
114	swift	1.1	</p>
115
116	nightmorph	1.8	<pre caption="Installing Xen">
117	swift	1.1	~# <i>emerge xen xen-tools xen-sources</i>
118			</pre>
119
120			</body>
121			</section>
122			<section>
123			<title>Building the Kernel</title>
124			<body>
125
126			<p>
127			Next we'll build the Linux kernel with Xen support. This kernel, whose sources
128			are available at <path>/usr/src/linux-2.6.x.z-xen</path>, will be our main
129			running kernel (i.e. the one running domain 0). In the <c>XEN</c> section you'll
130			find drivers for all kinds of input/output, each driver having a <e>backend</e>
131			and <e>frontend</e> implementation available. For the domain 0 kernel you need
132			to select the <e>backend</e> implementation: these are used by the other
133			domains (who use the <e>frontend</e> drivers) to communicate directly with
134			the hardware.
135			</p>
136
137			<p>
138			Of course, don't forget to select <c>Xen-compatible</c> at <c>Processor type and
139			features</c>. If you're wondering about networking: each interface in a domain
140			has a point-to-point link to an interface on domain 0 (called
141			<path>vifX.Y</path> where X is the domain number and Y the Yth interface of that
142			domain), so you can configure your network the way you want (bridging, NAT,
143			etc.)
144			</p>
145
146			<pre caption="Enabling Xen Support for i386 Kernels">
147			Processor type and features --->
148			Subarchitecture Type (Xen-compatible)
149			</pre>
150
151			<pre caption="Enabling Xen Support for x86_64 Kernels">
152			Processor type and features --->
153			Subarchitecture Type (PC-compatible)
154			[*] Enable Xen compatible kernel
155	nightmorph	1.6	[*] Support for hot-pluggable CPUs
156	swift	1.1	</pre>
157
158			<pre caption="Domain-0 Kernel Config">
159			Bus options (PCI etc.) --->
160			[*] PCI support
161	swift	1.3	[ ] Xen PCI Frontend Debugging
162	swift	1.1
163			Networking --->
164			Networking options --->
165			<*> 802.1d Ethernet Bridging
166			<comment>Only required by bridged networking.</comment>
167
168			XEN --->
169			[*] Privileged Guest (domain 0)
170			<*> Backend driver support
171			<*> Block-device backend driver
172			<*> Network-device backend driver
173	swift	1.3	<*> PCI-device backend driver
174			PCI Backend Mode (Virtual PCI) --->
175	swift	1.1	[*] Scrub memory before freeing it to Xen
176			[*] Disable serial port drivers
177			Xen version compatibility (3.0.4 and later)
178			</pre>
179
180			<pre caption="Domain-U Kernel Config">
181			Bus options (PCI etc.) --->
182			[ ] PCI support
183
184			Device Drivers --->
185			SCSI device support --->
186			< > SCSI device support
187			<comment>Disabling SCSI support frees up the /dev/sd* device names
188			for use as Xen virtual block devices.</comment>
189
190			XEN --->
191			[ ] Privileged Guest (domain 0)
192			<*> Block-device frontend driver
193			<*> Network-device frontend driver
194			[*] Scrub memory before freeing it to Xen
195			[*] Disable serial port drivers
196			Xen version compatibility (3.0.4 and later)
197			</pre>
198
199			<p>
200			A nice hint is to have the kernel make process store its intermediate object
201			files elsewhere so that you can reuse the same kernel tree to build different
202			configurations:
203			</p>
204
205			<pre caption="Building the Kernel">
206			~# <i>mkdir -p ~/build/dom0 ~/build/domU</i>
207			~# <i>make O=~/build/dom0 menuconfig</i>
208			<comment>(Configure the kernel)</comment>
209			~# <i>make O=~/build/dom0 && make O=~/build/dom0 modules_install</i>
210			</pre>
211
212			<p>
213			Once the kernel is built you'll find the kernel image immediately in the
214			build directory (not inside <path>arch/</path> or any other directory) called
215			<path>vmlinuz</path>. Copy it to <path>/boot</path> and then configure your
216			bootloader to use the Xen hypervisor (one of the components installed
217			previously) which is stored as <path>/boot/xen.gz</path>. In the bootloader
218			configuration, add your newly built kernel as the kernel that Xen should
219			boot. For instance, for GRUB:
220			</p>
221
222			<pre caption="GRUB Configuration for Xen">
223			title Xen 3.0 / Gentoo Linux 2.6.x.y
224			root (hd0,0)
225			kernel /boot/xen.gz
226			module /boot/kernel-2.6.x.y-xen0 root=/dev/hda3
227			</pre>
228
229			<p>
230			Now reboot your system into Xen. Once you are booted, you need to load the Xen
231			daemon:
232			</p>
233
234			<pre caption="Loading the Xen daemon">
235			~# <i>/etc/init.d/xend start</i>
236			</pre>
237
238			<p>
239			Now check if you can do whatever you normally do on your system. If this is the
240			case, you can edit your bootloader configuration to always boot into Xen and add
241			the Xen deamon to the default runlevel so that it is started automatically
242			next time you boot.
243			</p>
244
245			<note>
246			If you wish to start guest domains automatically on boot add <c>xendomains</c>
247			to the default runlevel as well and create a symlink in
248			<path>/etc/xen/auto/</path> to the Xen configuration files for the domains
249			you wish to start.
250			</note>
251
252			</body>
253			</section>
254			</chapter>
255			<chapter>
256			<title>Creating an Unpriviledged Domain</title>
257			<section>
258			<title>Building the Kernel</title>
259			<body>
260
261			<p>
262			Go to the Xen-powered Linux kernel source and update the configuration. It is
263			wise to keep as many topics as possible similar to the main kernel except the
264			<c>XEN</c> settings where drivers should now have their <e>frontend</e>
265			implementation selected instead of the <e>backend</e>. Then build the kernel
266			and place the resulting <path>vmlinuz</path> file where you want (we assume this
267			is <path>/mnt/data/xen/kernel</path>):
268			</p>
269
270			<pre caption="Building the guest kernel">
271			~# <i>make O=~/build/domU</i>
272	cam	1.4	~# <i>cp ~/build/domU/vmlinuz /mnt/data/xen/kernel/kernel-2.6.x.y-xen</i>
273	swift	1.1	</pre>
274
275			<p>
276			It is also possible to create a single kernel image for both the administrative
277			domain and the unpriviledged domain. More information about this can be found
278			in the Xen user manual.
279			</p>
280
281			</body>
282			</section>
283			<section>
284			<title>Creating the Domain Disks</title>
285			<body>
286
287			<p>
288			For best performance, it is best to dedicate a partition (or logical volume) to
289			a domain rather than a file based filesystem. However, if you are going to use
290			Xen primarily for tests using a file based filesystem does have its advantages
291			(especially regarding maintenance).
292			</p>
293
294			<p>
295			You can create a file based filesystem using <c>dd</c> and <c>mke2fs</c> (or
296			any other file system creation tool). For instance, to create a 2Gbyte ext3
297			filesystem:
298			</p>
299
300			<pre caption="Creating a file based filesystem">
301			~# <i>dd if=/dev/zero of=/mnt/data/xen/disks/ext3root.img bs=1M count=2048</i>
302			~# <i>mke2fs -j /mnt/data/xen/disks/ext3root.img</i>
303			</pre>
304
305			</body>
306			</section>
307			<section>
308			<title>Configuring a Domain</title>
309			<body>
310
311			<p>
312			Next we create a Xen configuration file for a domain. You can store these
313			configuration files where you want, for instance at
314			<path>/mnt/data/xen/configs</path>. As an example, we create a configuration
315			file for a small Gentoo environment which uses the disk image we created
316			previously:
317			</p>
318
319			<pre caption="Creating a domain configuration file">
320			~# <i>nano -w /mnt/data/xen/configs/gentoo</i>
321
322			kernel = "/mnt/data/xen/kernel/kernel-2.6.x.y-xen"
323			memory = 512
324			name = "gentoo"
325			<comment>(Map the disk image to the virtual /dev/sda1)</comment>
326			disk = ['file:/mnt/data/xen/disks/ext3root.img,sda1,w']
327			root = "/dev/sda1 ro"
328			</pre>
329
330			<p>
331			If you are using a block device (such as an lvm volume or partition) for
332			the disk use 'phy:' instead of 'file:' and leave off /dev. For example:
333			</p>
334
335			<pre caption="Using a block device">
336			<comment>(LVM Volume)</comment>
337			disk = [ 'phy:lvm/xen-guest-root,sda1,w' ]
338
339			<comment>(Physical Partition)</comment>
340			disk = [ 'phy:sdb6,sda1,w' ]
341			</pre>
342
343			<p>
344			You can find example configuration files in <path>/etc/xen</path>.
345			</p>
346
347			</body>
348			</section>
349			<section>
350			<title>Launching the New Domain</title>
351			<body>
352
353			<p>
354			Now we're all set and we can launch the new domain. If the disk image contained
355			an operating system, we could just create and attach the domain using the
356			<c>xm</c> command (Xen manager):
357			</p>
358
359			<pre caption="Creating and starting a new domain">
360			~# <i>xm create /mnt/data/xen/configs/gentoo -c</i>
361			</pre>
362
363			<p>
364			The domain would be booted inside the terminal in which you executed the
365			command. However, in our case, the disk image is empty so the domain won't boot
366			up in anything useful. To fix this, you can loop-mount the image and install
367			Gentoo as you're used to.
368			</p>
369
370			<p>
371			If you want to disconnect from the domain, press <path>Ctrl+]</path>. You can
372			always reconnect to the domains' console using <c>xm console gentoo</c>.
373			However, there is only one console per domain, so only use it when you can't
374			access the domain otherwise (for instance, through SSH).
375			</p>
376
377			</body>
378			</section>
379			</chapter>
380			<chapter>
381			<title>Networking on Unpriviledged Domains</title>
382			<section>
383			<title>Introduction</title>
384			<body>
385
386			<p>
387			Xen supports at least two ways of configuring your (virtual) network:
388			<e>routed</e> and <e>bridged</e>.
389			</p>
390
391			<p>
392			When selecting the <e>routed</e> approach, the interface inside your
393			unpriviledged domain is connected to the virtual interface on your
394			administrative domain. On your administrative domain (domain 0), the virtual
395			interface is linked together with <path>eth0</path>. The
396			interface inside your unpriviledged domain should have an IP address on the same
397			network as the interface on the administrative domain. Any communication to
398			that IP address can only occur from the administrative domain, unless you set
399			up specific routing rules.
400			</p>
401
402			<p>
403			When selecting the <e>bridged</e> approach, your default network interface on
404			the administrative domain becomes a bridge which accepts connections to the
405			virtual domains as well as to the IP address your administrative domain has.
406			</p>
407
408			</body>
409			</section>
410			<section>
411			<title>Regular Routed Interfaces</title>
412			<body>
413
414			<p>
415			Before you set up the interface on your unpriviledged domain, make sure that
416			Xen's <path>netloop</path> and <path>netbk</path> drivers are loaded. A quick
417			hint: if you have <path>netloop</path> as a module, load it with
418			<c>nloopbacks=0</c> so that it doesn't create pointless interfaces to the
419			loopback device. Then, edit your domain configuration file and add a <c>vif</c>
420			instruction to it.
421			</p>
422
423			<pre caption="Configuring a virtual interface">
424			~# <i>nano -w /mnt/data/xen/configs/gentoo</i>
425
426			<comment>(Add the vif instruction)</comment>
427			vif = [ 'ip=192.168.1.101, vifname=veth1' ]
428			</pre>
429
430			<p>
431			In the above example, the interface will be created for the unpriviledged domain
432			(in which it will be called <path>eth0</path>) and Xen will ensure that address
433			192.168.1.101 will be reachable from the administrative domain through interface
434			<path>veth1</path>.
435			</p>
436
437			<p>
438			This doesn't mean that the virtual <path>eth0</path> interface will
439			automatically have IP 192.168.1.101 assigned to it, but rather that, if you
440			don't give it that IP, it will not be connected with the administrative domain
441			and thus cannot be reached.
442			</p>
443
444			<p>
445	swift	1.5	Now edit <path>/etc/xen/xend-config.sxp</path> as follows to select routed
446	swift	1.1	network configuration:
447			</p>
448
449	swift	1.5	<pre caption="Editing xend-config.sxp">
450			~# <i>nano -w /etc/xen/xend-config.sxp</i>
451	swift	1.1
452			<comment>(Comment out the following lines)</comment>
453			<i>#</i>(network-script network-bridge)
454			<i>#</i>(vif-script vif-bridge)
455
456			<comment>(Enable the following lines)</comment>
457			(network-script network-route)
458			(vif-script vif-route)
459			</pre>
460
461			</body>
462			</section>
463			<section>
464			<title>Bridged Interfaces</title>
465			<body>
466
467			<p>
468			Unlike the routed interfaces you now need to load the <path>netloop</path>
469			driver with <c>nloopbacks=1</c> (or higher) as the additional loopback devices
470			are used to create the bridge. For the other modules you still need the
471			<path>netbk</path> module as well as briding functionality (<path>bridge</path>
472			module if build as such).
473			</p>
474
475			<p>
476			Now edit your virtual domain and add the <c>vif</c> construct:
477			</p>
478
479			<pre caption="Configuring a virtual interface">
480			~# <i>nano -w /mnt/data/xen/configs/gentoo</i>
481
482			<comment>(Add the vif instruction)</comment>
483			vif = [ 'ip=192.168.1.101, vifname=veth0' ]
484			</pre>
485
486			<p>
487	swift	1.5	Next edit <path>/etc/xen/xend-config.sxp</path> as follows to select bridged
488	swift	1.1	network configuration:
489			</p>
490
491	swift	1.5	<pre caption="Editing xend-config.sxp">
492			~# <i>nano -w /etc/xen/xend-config.sxp</i>
493	swift	1.1
494			<comment>(Enable the following lines)</comment>
495			(network-script network-bridge)
496			(vif-script vif-bridge)
497
498			<comment>(Comment out the following lines if not done already)</comment>
499			<i>#</i> (network-script network-route)
500			<i>#</i> (vif-script vif-route)
501			</pre>
502
503			<p>
504			By default, the bridge will contain whatever interface is configured to be the
505			default interface (the device that is listed under the default route through
506			<c>ip route list</c>). If you want to alter this behavior, edit the
507	swift	1.5	<path>xend-config.sxp</path> as follows:
508	swift	1.1	</p>
509
510	swift	1.5	<pre caption="Editing xend-config.sxp to change bridge configuration">
511			~# <i>nano -w /etc/xen/xend-config.sxp</i>
512	swift	1.1
513			<comment>(Edit the network-script line)</comment>
514			(network-script <i>'</i>network-bridge <i>netdev=eth0 bridge=xenbr0 vifnum=0'</i>)
515			</pre>
516
517			<p>
518			Once the configuration is done, restart the <c>xend</c> init script to have Xen
519			build the bridge:
520			</p>
521
522			<pre caption="Restarting the xend daemon">
523			~# <i>/etc/init.d/xend restart</i>
524			</pre>
525
526			</body>
527			</section>
528			</chapter>
529	swift	1.2	<chapter>
530			<title>Further Resources</title>
531			<section>
532			<title>Xen Documentation</title>
533			<body>
534
535			<ul>
536			<li>
537	nightmorph	1.10	<uri link="http://www.xen.org/support/documentation.html">Official Xen
538			documentation</uri>
539	swift	1.2	</li>
540			<li>
541	nightmorph	1.10	<uri link="http://wiki.xen.org/">Xen Wiki</uri>
542	swift	1.2	</li>
543			</ul>
544
545			</body>
546			</section>
547			<section>
548			<title>Xen Tools</title>
549			<body>
550
551			<ul>
552			<li>
553			<uri
554	nightmorph	1.10	link="http://virt-manager.org/">app-emulation/virt-manager</uri>
555	swift	1.2	is a graphical tool for administering virtual machines
556			</li>
557			</ul>
558
559			</body>
560			</section>
561			</chapter>
562	swift	1.1	</guide>