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.6 2010/05/14 21:55:13 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>3</version>
<date>2010-11-14</date>

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

<p>
The <uri link="http://www.xensource.com/">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://www.cl.cam.ac.uk/research/srg/netos/xen/readmes/user">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 couple of
packages. Because it is still <uri
link="/doc/en/handbook/handbook-x86.xml?part=3&amp;chap=3#doc_chap2">~arch
masked</uri> you first need to unmask it by adding the necessary lines to
<path>/etc/portage/package.keywords</path> and then install them.
</p>

<pre caption="Unmasking and Installing Xen">
~# <i>nano -w /etc/portage/package.keywords</i>
app-emulation/xen
app-emulation/xen-tools
sys-kernel/xen-sources

~# <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://tx.downloads.xensource.com/downloads/docs/user/">Xen
    Users' Manual</uri>
  </li>
  <li>
    <uri link="http://xen.xensource.com/documentation.html">Xen Community
    Documentation</uri>
  </li>
  <li>
    <uri link="http://wiki.xensource.com/xenwiki/">Xen Wiki</uri>
  </li>
</ul>

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

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

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