X-Git-Url: http://v3vee.org/palacios/gitweb/gitweb.cgi?p=palacios.git;a=blobdiff_plain;f=manual%2Fguest_build%2FPalacios_Guest_Build.tex;h=d7724969467619c25fb425be41c226f4fe9dbdc6;hp=991a1105c4c38dbf20e7919ea87aee74c62ceb65;hb=f58f4acab7737c6f185d6a4e056280869af22c01;hpb=c69623b464b4e35feb787507121ebdc459faba19
diff --git a/manual/guest_build/Palacios_Guest_Build.tex b/manual/guest_build/Palacios_Guest_Build.tex
index 991a110..d772496 100644
--- a/manual/guest_build/Palacios_Guest_Build.tex
+++ b/manual/guest_build/Palacios_Guest_Build.tex
@@ -5,188 +5,420 @@
\usepackage{verbatim}
\usepackage{epsf}
\usepackage{graphicx}
+\usepackage{hyperref}
\def\colfigsize{\epsfxsize=5in}
-\title{Building guest bootable image for the Palacios and Kitten}
+\pdfpagewidth 8.5in
+\pdfpageheight 11.0in
+
+\setlength\topmargin{0in}
+\setlength\evensidemargin{0in}
+\setlength\oddsidemargin{0in}
+\setlength\textheight{8.0in}
+\setlength\textwidth{6.5in}
+
+\title{Building a bootable guest image for Palacios and Kitten}
\begin{document}
\maketitle
-\section{Getting the stuffs used for building guest image}
+\section{Getting the guest image build tools}
+
+In order to build the bootable guest ISO image, we need to build a Linux kernel
+ from source and an initial ramdisk file system containing a set of useful
+tools. We will use a new directory for demonstration; the root directory for the
+following examples is ``\verb+test/+":
+
+\begin{verbatim}
+[jdoe@newskysaw ~]$ mkdir test/
+\end{verbatim}
+
+\noindent
+There are a set of tools and sources that are useful for the guest image
+building procedure. You can obtain these resources from our git repositories.
+Change to the ``\verb+test/+" directory and clone the resources:
+
+\begin{verbatim}
+[jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/busybox
+[jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/initrd
+[jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/linux-2.6.30.y
+\end{verbatim}
+
+\section{Building the ramdisk filesystem}
+The guest requires an initial ramdisk filesystem. Jack has made one that you can
+leverage; it is temporarily located in his home directory. You will need sudo
+or root access to create the device files when you unpack the archive:
+
+\begin{verbatim}
+[jdoe@newskysaw test]$ cp /home/jarusl/initrd/disks/v3vee_initramfs.tar.gz .
+[jdoe@newskysaw test]$ sudo tar -C initrd -xzf v3vee_initramfs.tar.gz
+\end{verbatim}
+
+\noindent
+If you require a custom initial ramdisk filesystem, change to the
+``\verb|initrd/initramfs/|" directory and perform the following steps:
+
+\begin{verbatim}
+[jdoe@newskysaw initramfs]$ mkdir -p proc sys var/log
+\end{verbatim}
+
+\noindent
+Edit the ``\verb|init_task|" script and uncomment these lines:
+
+\begin{verbatim}
+#mknod /dev/tty0 c 4 0
+#mknod /dev/tty1 c 4 1
+#mknod /dev/tty2 c 4 2
+\end{verbatim}
+
+\pagebreak
+
+\noindent
+Create the ``\verb|console|" device. If you have sudo or root access it is
+possible to create this device manually:
+
+\begin{verbatim}
+[jdoe@newskysaw initramfs]$ sudo mknod dev/console c 5 1
+[jdoe@newskysaw initramfs]$ sudo chmod 0600 dev/console
+\end{verbatim}
+
+\noindent
+If you do not have sudo or root access it is still possible to create the
+``\verb|console|" device indirectly through the kernel build. Change to the
+``\verb|initrd/|" directory and create a file called ``\verb|root_files|". Add
+the following line:
+
+\begin{verbatim}
+nod /dev/console 0600 0 0 c 5 1
+\end{verbatim}
+
+\noindent
+The ``\verb|root_files|" file is used when building the Linux kernel in the
+section Configuring and building the Linux kernel. Finally, create any
+additional directories and copy any additional files that you need. Your initial
+ramdisk filesystem is prepped and ready for installation of the BusyBox tools as
+described in the section Configuring and installing BusyBox tools.
+
+
+
+\pagebreak
+\begin{figure}[ht]
+ \begin{center}
+ \colfigsize\epsffile{busyboxConf1.eps}
+ \caption{BusyBox configuration}
+ \label{fig:busyboxcf1}
+ \end{center}
+\end{figure}
+
+\begin{figure}[ht]
+ \begin{center}
+ \colfigsize\epsffile{busyboxConf2.eps}
+ \end{center}
+ \caption{BusyBox configuration}
+ \label{fig:busyboxcf2}
+\end{figure}
+
+\section{Configuring and installing BusyBox tools}
+
+BusyBox is a software application released as Free software under the GNU GPL
+that provides many standard Unix tools. BusyBox combines tiny versions of many
+common UNIX utilities into a single, small executable. For more details on
+BusyBox visit \url{http://busybox.net}. To configure BusyBox, in the
+``\verb+busybox/+" directory, type the following:
+
+\begin{verbatim}
+[jdoe@newskysaw busybox]$ make menuconfig
+\end{verbatim}
+
+\noindent
+or
+
+\begin{verbatim}
+[jdoe@newskysaw busybox]$ make xconfig
+\end{verbatim}
+
+\noindent
+The BusyBox tools will be installed in the guest's initial ramdisk filesystem;
+you can add any tools that you need. There are two required configuration
+options. In the
+``\verb|BusyBox settings->Build Options|" menu check the
+``\verb|Build BusyBox as a static binary (no shared libs)|" option, as shown in
+figure \ref{fig:busyboxcf1}, and in the
+``\verb|BusyBox settings->Installation Options|" menu set the
+``\verb|Busybox installation prefix|" to the path of the
+``\verb|initrd/initramfs|" directory, as shown in figure \ref{fig:busyboxcf2}.
+After you finish configuring BusyBox, save your configuration and quit the
+window. Then, to make the BusyBox tools, type the following:
+
+\begin{verbatim}
+[jdoe@newskysaw busybox]$ make
+\end{verbatim}
+Install the tools to the guest's initial ramdisk filesystem directory:
+\begin{verbatim}
+[jdoe@newskysaw busybox]$ make install
+\end{verbatim}
+
+\begin{figure}[ht]
+ \begin{center}
+ \colfigsize\epsffile{linuxConf.eps}
+ \end{center}
+ \caption{Linux Kernel configuration}
+ \label{fig:linuxcf}
+\end{figure}
+
-In order to build the bootable guest iso image, we need to build Linux kernel image from its source,
-an initial file system containing a set of useful binary files and other necessary directories and files,
-which will be specified in the following text.
+\section{Configuring and building the Linux kernel}
-We will use a new directory for demonstration,
-the root directory for our following examples are all in the \verb+test/+ as root directory.
+The following procedure demonstrates how to configure and build a 32-bit Linux
+kernel. Change to the ``\verb|linux-2.6.30.y/|" directory. There is a custom
+configuration file ``\verb|jrl-default-config|" which is configured with minimal
+kernel options (all unnecessary options are removed to keep the guest booting
+process fast). If you are using the custom configuration file type the
+following:
\begin{verbatim}
-mkdir test/
-cd test/
+[jdoe@newskysaw linux-2.6.30.y]$ cp jrl-default-config .config
\end{verbatim}
-There are a set of tools and sources that are useful for this building procedure. You can checkout these resources from our git repositories. To checkout them to your local directory, using commands:
+\noindent
+Configure the kernel to meet your requirements. For more on configuring and
+building Linux kernels, check online. Type the following:
\begin{verbatim}
-git clone http://hornet.cs.northwestern.edu:9005/busybox
-git clone http://hornet.cs.northwestern.edu:9005/initrd
-git clone http://hornet.cs.northwestern.edu:9005/linux-2.6.30.y
+[jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386 menuconfig
\end{verbatim}
-\section{Build the ramdisk filesystem}
+\noindent
+or
-Copy needed devices into the \verb+initramfs/dev/+ directory,
-for minimal support, you need console, ram, null, tty.
-(You probably need root privilege to copy and make the device files)
+\begin{verbatim}
+[jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386 xconfig
+\end{verbatim}
-There is an already costumed initial ramdisk system made
-by Jack which you can leverage. The file is temporarily
-in \verb|/home/jarusl/initrd/disks/v3vee_initramfs.tar.gz|
-in newskysaw machine.
+\noindent
+The kernel must be configured with the initial ramdisk file system directory
+(e.g. ``\verb|initrd/initramfs/|"): in the ``\verb|General setup|" menu under
+option
+``\verb|Initial RAM filesystem and RAM disk support|" set the
+``\verb|Initramfs source file(s)|" option to the path of the
+``\verb|initrd/initramfs/|" directory, as shown in figure \ref{fig:linuxcf}.
+Additionally, if you are using the ``\verb|root_files|" file to create devices
+files, add the ``\verb|root_files|" file path, separated by a space, after the
+initial ramdisk filesystem directory. When you are finished configuring the
+kernel, save your configuration, and type the following:
-\section{Configure and Install Busybox tools}
+\begin{verbatim}
+[jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386
+\end{verbatim}
+
+\noindent
+The Linux kernel can be found here: ``\verb|arch/x86/boot/bzImage|". The initial
+ramdisk filesystem can be found here: ``\verb|usr/initramfs_data.cpio|". The
+Linux kernel and initial ramdisk filesystem are used to build the Linux ISO
+image in the section Building the Linux ISO image.
-BusyBox is a software application released as Free software
-under the GNU GPL that provides many standard Unix tools. BusyBox
-combines tiny versions of many common UNIX utilities into a single
-small executable. For more details on Busybox, visiting http://busybox.net.
-To configure BusyBox, in the \verb+busybox/+ directory, type
+\section{Building the Linux ISO image}
+
+The Linux ISO image is a bootable image containing the Linux kernel, initial
+ramdisk filesystem, a boot loader, and a boot loader configuration file. For
+this procedure, we'll use the ``\verb|test/iso/|" directory as the Linux ISO
+build directory:
\begin{verbatim}
-make meunconfig
-make xconfig (X version)
+[jdoe@newskysaw test]$ mkdir iso
\end{verbatim}
-You can add tools as you needed into the guest image. There are
-two specified configurations are required here:
-First, in the "\verb|Build Options|", check the option
-"\verb|Build BusyBox as a static binary (no shared libs)|",
-as shown in figure \ref{fig:busyboxcf1}. Second,
-in the "\verb|Installation Options|", Change
-the "\verb|Busybox installation prefix|" to be the path
-of your "\verb|initramfs|" directory, as shown in figure \ref{fig:busyboxcf2}.
-
-\begin{figure}\begin{center}\colfigsize\epsffile{busyboxConf1.eps}\end{center}\caption{BusyBox configuartion}\label{fig:busyboxcf1}\end{figure}
+\noindent
+Change to the ``\verb|iso/|" directory and copy the required files:
-\begin{figure}\begin{center}\colfigsize\epsffile{busyboxConf2.eps}\end{center}\caption{BusyBox configuartion}\label{fig:busyboxcf2}\end{figure}
-
-After you finish the configuration, save your configuration
-and quit the window. Then, to make the Busybox tools, type
\begin{verbatim}
-make
+[jdoe@newskysaw iso]$ cp ../linux-2.6.30.y/arch/x86/boot/bzImage vmlinuz
+[jdoe@newskysaw iso]$ cp ../linux-2.6.30.y/usr/initramfs_data.cpio initramfs
+[jdoe@newskysaw iso]$ cp /usr/lib/syslinux/isolinux.bin .
\end{verbatim}
-And then install the tools to your inital ramdisk directory
+
+\noindent
+Create a file called ``\verb|isolinux.cfg|" and add the following lines:
\begin{verbatim}
-make install
+default linux
+prompt 0
+
+label linux
+ kernel vmlinuz
+ append initrd=initrd
\end{verbatim}
-\section{Configure and Compile Linux Kernel}
+\noindent
+Change back to the ``\verb|test/|" directory and build the Linux ISO image:
-Go to \verb|linux-2.6.30.y/| directory (or whatever your
-Linux kernel source directory). Type
+\begin{verbatim}
+[jdoe@newskysaw test]$ mkisofs -o linux.iso -b isolinux.bin -no-emul-boot \
+-boot-load-size 4 -boot-info-table -iso-level 2 -input-charset UTF-8 iso/
+\end{verbatim}
+
+\noindent
+The ``\verb|linux.iso|'' file is the Linux ISO image and is used to build the
+guest image in the section Configuring and building the guest image:
\begin{verbatim}
-make menuconfig
-make xconfig (X version)
+[jdoe@newskysaw test]$ file linux.iso
+linux.iso: ISO 9660 CD-ROM filesystem data 'CDROM ' (bootable)
\end{verbatim}
-To configure the kernel as your need.
-There is a customed configuration file "\verb|jrl-default-config|"
-which is configured with minimal kernel options (all of
-unnecessary stuffs are turned off to keep guest booting process faster).
-For more on configuring and compiling Linux kernel image, check online. Here, one
-option for configuring the initial ramdisk file system directory (such
-as \verb|initrd/initramfs|) in the option
-"\verb|initial RAM filesystem and Ram Disk|" is needed,
-as shown in figure \ref{fig:linuxcf}.
+\section{Configuring and building the guest image}
-\begin{figure}\begin{center}\colfigsize\epsffile{linuxConf.eps}\end{center}\caption{Linux Kernel configuartion}\label{fig:linuxcf}\end{figure}
+Checkout the updated Palacios repository to the ``\verb|palacios/|" directory.
+(You can find instructions for checking out the Palacios repository at
+\url{http://www.v3vee.org/palacios/}). The guest creator utility is required for
+building the guest image. Change to the ``\verb|palacios/utils/guest_creator|"
+directory and build the guest creator utility:
-\section{Configure guest devices}
-Checkout the updated Palacios repository to \verb|palacios/|.
-(You can find the instruction of how to get the Palacios and
-Kitten repository in http://www.v3vee.org/palacios/).
+\begin{verbatim}
+[jdoe@newskysaw guest_creator]$ make
+\end{verbatim}
-In the "\verb|palacios/utils/guest_creator|", Type
+\noindent
+You will get the ``\verb|build_vm|" utility:
\begin{verbatim}
-make
+[jdoe@newskysaw guest_creator]$ file build_vm
+build_vm: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked
+(uses shared libs), for GNU/Linux 2.6.9, not stripped
\end{verbatim}
-You will get the guest configuration files creator "\verb|build_vm|".
-The guest configuration file is using XML format. There is a sample configuration file: \verb|default.xml|.
-You can create your own guest configuration, after creating your file, type
+\noindent
+The guest configuration file is written in XML. A sample configuration file is
+provided: ``\verb|default.xml|". Make a copy of the default configuration file
+named ``\verb|myconfig.xml|" and edit the configuration elements that you are
+interested in (if a device is included in the guest configuration file, it
+must be configured in the section Configuring and building Palacios or the guest
+will not boot). Of particular importance is the ``\verb|files|" element. Comment
+out this attribute:
\begin{verbatim}
-./build_vm myconfig.xml -o guest.iso
+
\end{verbatim}
-Where \verb+myconfig.xml+ is your guest configuration file,
-and \verb+guest.iso+ is the output image file that can be
-feed into kitten¡¯s configuration (see next section).
+\noindent
+Add an attribute that specifies the location of the Linux ISO image:
+
+\begin{verbatim}
+
+\end{verbatim}
+
+\noindent
+When you are finished editing the guest configuration save the configuration
+file. The guest image consists of the guest configuration file and the Linux
+ISO image. Build the guest image with the guest creator utility:
+
+\begin{verbatim}
+[jdoe@newskysaw guest_creator]$ ./build_vm myconfig.xml -o guest.iso
+\end{verbatim}
+
+\noindent
+The guest image, ``\verb+guest.iso+", is embedded in Kitten's
+``\verb|init_task|" in the section Configuring and building Kitten.
+
+
+\pagebreak
+\begin{figure}[h]
+ \begin{center}
+ \colfigsize\epsffile{kittenConf1.eps}
+ \end{center}
+ \caption{Kitten configuration}
+ \label{fig:kittencf}
+\end{figure}
+
+\begin{figure}[ht]
+ \begin{center}
+ \colfigsize\epsffile{kittenConf2.eps}
+ \end{center}
+ \caption{Kitten configuration}
+ \label{fig:kittencf2}
+\end{figure}
-\section{Configure and Make Palacios and Kitten}
-\subsection*{Configure and build Palacios}
-You can find the detail manual of getting and building Palacios and Kitten
-from scratch in the Palacios website (http://www.v3vee.org/palacios).
-Here we only give the specific requirements related to the booting guest procedure.
+\section{Configuring and building Palacios and Kitten}
+\subsection*{Configuring and building Palacios}
-To configure Palacios, in Palacios root directory, such as \verb+palacios/+, type
+You can find the detailed manual of getting and building Palacios and Kitten
+from scratch in the Palacios website (\url{http://www.v3vee.org/palacios}). Here
+we only give the specific requirements related to the procedure of booting the
+guest. To configure Palacios, change to the ``\verb|test/palacios/|" directory
+and type the following:
\begin{verbatim}
-make config
+[jdoe@newskysaw palacios]$ make menuconfig
+\end{verbatim}
+
+\noindent
or
-make xconfig
+
+\begin{verbatim}
+[jdoe@newskysaw palacios]$ make xconfig
\end{verbatim}
-To configure the components you want to build into Palacios. And then type
+\noindent
+Don't forget to include the devices that your guest image requires. When you
+have configured the components you want to build into Palacios, save the
+configuration and close the window. To build Palacios type the following:
\begin{verbatim}
-make
+[jdoe@newskysaw palacios]$ make
+\end{verbatim}
or
-make all
+\begin{verbatim}
+[jdoe@newskysaw palacios]$ make all
\end{verbatim}
-To build Palacios static library, after build, you can find the Palacios library file \verb+libv3vee.a+ in root directory.
+\noindent
+Once the Palacios static library has been built you can find the library file,
+``\verb+libv3vee.a+", in the Palacios root directory.
-\subsection*{Configure and build Kitten}
+\subsection*{Configuring and building Kitten}
-To build Kitten, first configure it using the similar way as Palacios, go to \verb+kitten/+, type
+Configure Kitten. Change to the ``\verb+test/kitten/+" directory and type the
+following:
\begin{verbatim}
-make config
-or
-make xconfig
+[jdoe@newskysaw kitten]$ make menuconfig
\end{verbatim}
-Specifically, you have to enable Palacios VMM support in Kitten,
-and configure the root directory of Palacios and the
-path of the guest image file we just built in previous step,
-as show in figure \ref{fig:kittencf} and \ref{fig:kittencf2}.
+\noindent
+or
-\begin{figure}\begin{center}\colfigsize\epsffile{kittenConf1.eps}\end{center}\caption{Kitten configuartion}\label{fig:kittencf}\end{figure}
+\begin{verbatim}
+[jdoe@newskysaw kitten]$ make xconfig
+\end{verbatim}
-\begin{figure}\begin{center}\colfigsize\epsffile{kittenConf2.eps}\end{center}\caption{Kitten configuartion}\label{fig:kittencf2}\end{figure}
-
-After configure, to build the Kitten, type
+\noindent
+Under the ``\verb|Virtualization|" menu select the
+``\verb|Include Palacios virtual machine monitor|" option. Set the
+``\verb|Path to pre-built Palacios tree|" option to the Palacios build tree
+path, ``\verb|..\palacios|", as shown in figure \ref{fig:kittencf}. Set the
+``\verb|Path to guest OS ISO image|" option to the guest image path,\\
+''\verb|../palacios/utils/guest_creator/guest.iso|'', as shown in figure
+\ref{fig:kittencf2}. When you have finished configuring Kitten, save the
+configuration and close the window. To build Kitten type the following:
\begin{verbatim}
-make isoimage
+[jdoe@newskysaw kitten]$ make isoimage
\end{verbatim}
-to make the bootable ISO image file with guest OS, Palacios and Kitten.
-The ISO file is located in \verb+kitten/arch/x86_64/boot/image.iso+.
+\noindent
+This builds the bootable ISO image file with guest image, Palacios, and Kitten.
+The ISO file is located in ``\verb+kitten/arch/x86_64/boot/image.iso+".
-Until here, you have successfully created a guest CD image file that can be
-booted on machine. You can boot the file on Qemu using following sample command
+\pagebreak
+\noindent
+You have successfully created an ISO image file that can be booted on a machine.
+You can boot the file on Qemu using the following sample command:
\begin{verbatim}
-/opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
+[jdoe@newskysaw test]$ /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
-smp 1 \
-m 2047 \
-serial file:./serial.out \
@@ -194,11 +426,10 @@ booted on machine. You can boot the file on Qemu using following sample command
< /dev/null
\end{verbatim}
-Here, we finally finish the entire procedure to
-build costumed guest and boot it on Palacios VMM.
-For more updated details, check Palacios
-website \verb+http://www.v3vee.org/palacios+ and
-Kitten website \verb+https://software.sandia.gov/trac/kitten+ regularly.
-
+\noindent
+We have finished the entire procedure for building a guest image and booting it
+on the Palacios VMM. For more updated details, check the Palacios website
+\url{http://www.v3vee.org/palacios} and Kitten website
+\url{https://software.sandia.gov/trac/kitten} regularly.
\end{document}
\ No newline at end of file