Xen devel - Jan 2006 - [PATCH] Add VMX guest quick start in user manual.

Hi all,

With many people''s help, I worked out this patch. This patch is to add
VMX guest quick start into Xen 3.0 user manual.

Signed-off-by: Yongkang You <yongkang.you@intel.com>
Signed-off-by: Alan C. Oehler <alan@xensource.com>
Signed-off-by: John L Villalovos <john.l.villalovos@intel.com>
Signed-off-by: Nitin A Kamble <nitin.a.kamble@intel.com>

Best Regards,
Yongkang (Kangkang) 永康

===============================================--- a/docs/src/user.tex
2006-01-10 09:45:53.567740719 +0800
+++ b/docs/src/user.tex	2006-01-10 09:49:30.070911717 +0800
@@ -1885,6 +1885,220 @@
 
 \appendix
 
+\chapter{Unmodified (VMX) guest domains in Xen with Intel\textregistered
Virtualization Technology (VT)}
+
+Xen supports guest domains running unmodified Guest operating systems using
Virtualization Technology (VT) available on recent Intel Processors. More
information about the Intel Virtualization Technology implementing Virtual
Machine Extensions (VMX) in the processor is available on the Intel website at
\\
+ {\small {\tt http://www.intel.com/technology/computing/vptech}}
+
+\section{Building Xen with VT support}
+
+The following packages need to be installed in order to build Xen with VT
support. Some Linux distributions do not provide these packages by default.
+
+\begin{tabular}{lp{11.0cm}}
+{\bfseries Package} & {\bfseries Description} \\
+
+dev86 & The dev86 package provides an assembler and linker for real mode
80x86 instructions. You need to have this package installed in order to build
the BIOS code which runs in (virtual) real mode.
+
+If the dev86 package is not available on the x86\_64 distribution, you can
install the i386 version of it. The dev86 rpm package for various distributions
can be found at {\scriptsize {\tt
http://www.rpmfind.net/linux/rpm2html/search.php?query=dev86\&submit=Search}}
\\
+
+LibVNCServer & The unmodified guest''s VGA display, keyboard, and
mouse are virtualized using the vncserver library provided by this package. You
can get the sources of libvncserver from {\small {\tt
http://sourceforge.net/projects/libvncserver}}. Build and install the sources on
the build system to get the libvncserver library. The 0.8pre version of
libvncserver is currently working well with Xen.\\
+
+SDL-devel, SDL & Simple DirectMedia Layer (SDL) is another way of
virtualizing the unmodified guest console. It provides an X window for the guest
console.
+
+If the SDL and SDL-devel packages are not installed by default on the build
system, they can be obtained from  {\scriptsize {\tt
http://www.rpmfind.net/linux/rpm2html/search.php?query=SDL\&amp;submit=Search}}
+, {\scriptsize {\tt
http://www.rpmfind.net/linux/rpm2html/search.php?query=SDL-devel\&submit=Search}}
\\
+
+\end{tabular}
+
+\section{Configuration file for unmodified VMX guests}
+
+The Xen installation includes a sample configuration file, {\small {\tt
/etc/xen/xmexample.vmx}}. There are comments describing all the options. In
addition to the common options that are the same as those for paravirtualized
guest configurations, VMX guest configurations have the following settings:
+
+\begin{tabular}{lp{11.0cm}}
+
+{\bfseries Parameter} &	{\bfseries Description} \\
+
+kernel &	The VMX firmware loader, {\small {\tt
/usr/lib/xen/boot/vmxloader}}\\
+
+builder &	The domain build function. The VMX domain uses the vmx builder.\\
+
+acpi & Enable VMX guest ACPI, default=0 (disabled)\\
+
+apic & Enable VMX guest APIC, default=0 (disabled)\\
+
+vif	& Optionally defines MAC address and/or bridge for the network
interfaces. Random MACs are assigned if not given. {\small {\tt type=ioemu}}
means ioemu is used to virtualize the VMX NIC. If no type is specified, vbd is
used, as with paravirtualized guests.\\
+
+disk & Defines the disk devices you want the domain to have access to, and
what you want them accessible as. If using a physical device as the VMX
guest''s disk, each disk entry is of the form
+
+{\small {\tt phy:UNAME,ioemu:DEV,MODE,}}
+
+where UNAME is the device, DEV is the device name the domain will see, and MODE
is r for read-only, w for read-write. ioemu means the disk will use ioemu to
virtualize the VMX disk. If not adding ioemu, it uses vbd like paravirtualized
guests.
+
+If using disk image file, its form should be like 
+
+{\small {\tt file:FILEPATH,ioemu:DEV,MODE}}
+
+If using more than one disk, there should be a comma between each disk entry.
For example:
+
+{\scriptsize {\tt disk =
[''file:/var/images/image1.img,ioemu:hda,w'',
''file:/var/images/image2.img,ioemu:hdb,w'']}}\\
+
+cdrom	& Disk image for CD-ROM. The default is {\small {\tt /dev/cdrom}} for
Domain0. Inside the VMX domain, the CD-ROM will available as device {\small {\tt
/dev/hdc}}. The entry can also point to an ISO file.\\
+
+boot & Boot from floppy (a), hard disk (c) or CD-ROM (d). For example, to
boot from CD-ROM, the entry should be:
+
+boot=''d''\\
+
+device\_model & The device emulation tool for VMX guests. This parameter
should not be changed.\\
+
+sdl &	Enable SDL library for graphics, default = 0 (disabled)\\
+
+vnc &	Enable VNC library for graphics, default = 1 (enabled)\\
+
+vncviewer &	Enable spawning of the vncviewer (only valid when vnc=1),
default = 1 (enabled)
+
+If vnc=1 and vncviewer=0, user can use vncviewer to manually connect VMX from
remote. For example:
+
+{\small {\tt vncviewer domain0\_IP\_address:VMX\_domain\_id}} \\
+
+ne2000 &	Enable ne2000, default = 0 (disabled; use pcnet)\\
+
+serial &	Enable redirection of VMX serial output to pty device\\
+
+localtime &	Set the real time clock to local time [default=0, that is, set
to UTC].\\
+
+enable-audio &	Enable audio support. This is under development.\\
+
+full-screen	& Start in full screen. This is under development.\\
+
+nographic &	Another way to redirect serial output. If enabled, no
''sdl'' or ''vnc'' can work. Not recommended.\\
+
+\end{tabular}
+
+
+\section{Creating virtual disks from scratch}
+\subsection{Using physical disks}
+If you are using a physical disk or physical disk partition, you need to
install a Linux OS on the disk first. Then the boot loader should be installed
in the correct place. For example {\small {\tt dev/sda}} for booting from the
whole disk, or {\small {\tt /dev/sda1}} for booting from partition 1.
+
+\subsection{Using disk image files}
+You need to create a large empty disk image file first; then, you need to
install a Linux OS onto it. There are two methods you can choose. One is
directly installing it using a VMX guest while booting from the OS installation
CD-ROM. The other is copying an installed OS into it. The boot loader will also
need to be installed.
+
+\subsubsection*{To create the image file:}
+The image size should be big enough to accommodate the entire OS. This example
assumes the size is 1G (which is probably too small for most OSes).
+
+{\small {\tt \# dd if=/dev/zero of=hd.img bs=1M count=1 seek=1023}}
+
+\subsubsection*{To directly install Linux OS into an image file using a VMX
guest:}
+
+Install Xen and create VMX with the original image file with booting from
CD-ROM. Then it is just like a normal Linux OS installation. The VMX
configuration file should have these two entries before creating:
+
+{\small {\tt cdrom=''/dev/cdrom''
+boot=''d''}}
+
+If this method does not succeed, you can choose the following method of copying
an installed Linux OS into an image file.
+
+\subsubsection*{To copy a installed OS into an image file:}
+Directly installing is an easier way to make partitions and install an OS in a
disk image file. But if you want to create a specific OS in your disk image,
then you will most likely want to use this method.
+
+\begin{enumerate}
+\item {\bfseries Install a normal Linux OS on the host machine}\\
+You can choose any way to install Linux, such as using yum to install Red Hat
Linux or YAST to install Novell SuSE Linux. The rest of this example assumes the
Linux OS is installed in {\small {\tt /var/guestos/}}.
+
+\item {\bfseries Make the partition table}\\
+The image file will be treated as hard disk, so you should make the partition
table in the image file. For example:
+
+{\scriptsize {\tt \# losetup /dev/loop0 hd.img\\
+\# fdisk -b 512 -C 4096 -H 16 -S 32 /dev/loop0\\
+press ''n'' to add new partition\\
+press ''p'' to choose primary partition\\
+press ''1'' to set partition number\\
+press "Enter" keys to choose default value of "First
Cylinder" parameter.\\
+press "Enter" keys to choose default value of "Last
Cylinder" parameter.\\
+press ''w'' to write partition table and exit\\
+\# losetup -d /dev/loop0}}
+
+\item {\bfseries Make the file system and install grub}\\
+{\scriptsize {\tt \# ln -s /dev/loop0 /dev/loop\\
+\# losetup /dev/loop0 hd.img\\
+\# losetup -o 16384 /dev/loop1 hd.img\\
+\# mkfs.ext3 /dev/loop1\\
+\# mount /dev/loop1 /mnt\\
+\# mkdir -p /mnt/boot/grub\\
+\# cp /boot/grub/stage* /boot/grub/e2fs\_stage1\_5 /mnt/boot/grub\\
+\# umount /mnt\\
+\# grub\\
+grub> device (hd0) /dev/loop\\
+grub> root (hd0,0)\\
+grub> setup (hd0)\\
+grub> quit\\
+\# rm /dev/loop\\
+\# losetup -d /dev/loop0\\
+\# losetup -d /dev/loop1}}
+
+The {\small {\tt losetup}} option {\small {\tt -o 16384}} skips the partition
table in the image file. It is the number of sectors times 512. We need {\small
{\tt /dev/loop}} because grub is expecting a disk device \emph{name}, where
\emph{name} represents the entire disk and \emph{name1} represents the first
partition.
+
+\item {\bfseries Copy the OS files to the image}\\ 
+If you have Xen installed, you can easily use {\small {\tt lomount}} instead of
{\small {\tt losetup}} and {\small {\tt mount}} when coping files to some
partitions. {\small {\tt lomount}} just needs the partition information.
+
+{\scriptsize {\tt \# lomount -t ext3 -diskimage hd.img -partition 1
/mnt/guest\\
+\# cp -ax /var/guestos/\{root,dev,var,etc,usr,bin,sbin,lib\} /mnt/guest\\
+\# mkdir /mnt/guest/\{proc,sys,home,tmp\}}}
+
+\item {\bfseries Edit the {\small {\tt /etc/fstab}} of the guest image}\\
+The fstab should look like this:
+
+{\scriptsize {\tt \# vim /mnt/guest/etc/fstab\\
+/dev/hda1	/		ext3		defaults 1 1\\
+none		/dev/pts	devpts	gid=5,mode=620 0 0\\
+none		/dev/shm	tmpfs		defaults 0 0\\
+none		/proc		proc		defaults 0 0\\
+none		/sys		sysfs		efaults 0 0}}
+
+\item {\bfseries umount the image file}\\
+{\small {\tt \# umount /mnt/guest}}
+\end{enumerate}
+
+Now, the guest OS image {\small {\tt hd.img}} is ready. You can also reference
{\small {\tt http://free.oszoo.org}} for quickstart images. But make sure to
install the boot loader.
+
+\subsection{Install Windows into an Image File using a VMX guest}
+In order to install a Windows OS, you should keep {\small {\tt acpi=0}} in your
VMX configuration file.
+
+\section{VMX Guests}
+\subsection{Editing the Xen VMX config file}
+Make a copy of the example VMX configuration file {\small {\tt
/etc/xen/xmeaxmple.vmx}} and edit the line that reads
+
+{\small {\tt disk = [
''file:/var/images/\emph{guest.img},ioemu:hda,w'' ]}}
+
+replacing \emph{guest.img} with the name of the guest OS image file you just
made.
+
+\subsection{Creating VMX guests}
+Simply follow the usual method of creating the guest, using the -f parameter
and providing the filename of your VMX configuration file:\\
+
+{\small {\tt \# xend start\\
+\# xm create -f /etc/xen/vmxguest.vmx}}
+
+In the default configuration, VNC is on and SDL is off. Therefore VNC windows
will open when VMX guests are created. If you want to use SDL to create VMX
guests, set {\small {\tt sdl=1}} in your VMX configuration file. You can also
turn off VNC by setting {\small {\tt vnc=0}}.
+ 
+\subsection{Destroy VMX guests}
+VMX guests can be destroyed in the same way as can paravirtualized guests. We
recommend that you type the command
+
+{\small {\tt poweroff}} 
+
+in the VMX guest''s console first to prevent data loss. Then execute
the command
+
+{\small {\tt xm destroy \emph{vmx\_guest\_id} }} 
+
+at the Domain0 console.
+
+\subsection{VMX window (X or VNC) Hot Key}
+If you are running in the X environment after creating a VMX guest, an X window
is created. There are several hot keys for control of the VMX guest that can be
used in the window.
+ 
+{\bfseries Ctrl+Alt+2} switches from guest VGA window to the control window.
Typing {\small {\tt help }} shows the control commands help. For example,
''q'' is the command to destroy the VMX guest.\\
+{\bfseries Ctrl+Alt+1} switches back to VMX guest''s VGA.\\
+{\bfseries Ctrl+Alt+3} switches to serial port output. It captures serial
output from the VMX guest. It works only if the VMX guest was configured to use
the serial port. \\
+
+\subsection{Save/Restore and Migration}
+VMX guests currently cannot be saved and restored, nor migrated. These features
are currently under active development.
+
 %% Chapter Glossary of Terms moved to glossary.tex
 \chapter{Glossary of Terms}



_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

"You, Yongkang" <yongkang.you@intel.com> writes:

Shouldn''t you have a warning somewhere early that VMX is still quite
flakey and in development and also that guests won''t perform well due
to poor driver models?
> +{\scriptsize {\tt \# losetup /dev/loop0 hd.img\\
> +\# fdisk -b 512 -C 4096 -H 16 -S 32 /dev/loop0\\
> +press ''n'' to add new partition\\
> +press ''p'' to choose primary partition\\
> +press ''1'' to set partition number\\
> +press "Enter" keys to choose default value of "First
Cylinder" parameter.\\
> +press "Enter" keys to choose default value of "Last
Cylinder" parameter.\\
> +press ''w'' to write partition table and exit\\
> +\# losetup -d /dev/loop0}}
> +
> +\item {\bfseries Make the file system and install grub}\\
> +{\scriptsize {\tt \# ln -s /dev/loop0 /dev/loop\\
> +\# losetup /dev/loop0 hd.img\\
> +\# losetup -o 16384 /dev/loop1 hd.img\\
An easier/cleaner way to handle partitioning on loop is to use kpartx from
multipath-tools. It sets up device mapper in a way that you
can access all the partitions easily.

-Andi

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

> > +\item {\bfseries Make the file system and install grub}\\ 
> > +{\scriptsize {\tt \# ln -s /dev/loop0 /dev/loop\\ \# losetup 
> > +/dev/loop0 hd.img\\ \# losetup -o 16384 /dev/loop1 hd.img\\
> 
> An easier/cleaner way to handle partitioning on loop is to 
> use kpartx from multipath-tools. It sets up device mapper in 
> a way that you can access all the partitions easily.
I''d recommend using lomount, which is in the xen tree (borrowed from
qemu). 

kpartx only works on recent distros, and installing it manually is far
from trivial.

Ian  

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

>-----Original Message-----
>From: Ian Pratt [mailto:m+Ian.Pratt@cl.cam.ac.uk]
>
>> > +\item {\bfseries Make the file system and install grub}\\
>> > +{\scriptsize {\tt \# ln -s /dev/loop0 /dev/loop\\ \# losetup
>> > +/dev/loop0 hd.img\\ \# losetup -o 16384 /dev/loop1 hd.img\\
>>
>> An easier/cleaner way to handle partitioning on loop is to
>> use kpartx from multipath-tools. It sets up device mapper in
>> a way that you can access all the partitions easily.
>
>I''d recommend using lomount, which is in the xen tree (borrowed
from
>qemu).
>
>kpartx only works on recent distros, and installing it manually is far
>from trivial.
>
Hi Ian,

The doc introduces the lomount and uses it when user copy file system
files into the disk image file. It is a very good tool. User need not to
count the offset of partition.

But the lomount is not very fit for the make partitions and make grub,
because mkfs couldn''t run if the target partition is mounted, and when
make grub user need to know which loop device need to use.
>Ian
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel