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=7b75bfb464d6614aa772f6b3f64759cd51c55cb4;hp=991a1105c4c38dbf20e7919ea87aee74c62ceb65;hb=e136664c9a3b9346f3cabef154f4e164362a0d82;hpb=c69623b464b4e35feb787507121ebdc459faba19 diff --git a/manual/guest_build/Palacios_Guest_Build.tex b/manual/guest_build/Palacios_Guest_Build.tex index 991a110..7b75bfb 100644 --- a/manual/guest_build/Palacios_Guest_Build.tex +++ b/manual/guest_build/Palacios_Guest_Build.tex @@ -5,185 +5,335 @@ \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 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. +In order to build the bootable guest iso image, we need to build a Linux kernel +image from source and an initial file system containing a set of useful binary +files which will be described in the following text. We will use a new directory +for demonstration; the root directory for the following examples is +``\verb+test/+": -We will use a new directory for demonstration, -the root directory for our following examples are all in the \verb+test/+ as root directory. +\begin{verbatim} +[jdoe@newskysaw ~]$ mkdir test/ +[jdoe@newskysaw ~]$ cd test/ +\end{verbatim} + +\vspace{10pt} +\noindent +There are a set of tools and sources that are useful for the guest image +building procedure. You can checkout these resources from our git repositories; +to check them out to your local ``\verb+test/+" directory use the following +commands: \begin{verbatim} -mkdir test/ -cd test/ +[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} -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: +\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} -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 test]$ cp /home/jarusl/initrd/disks/v3vee_initramfs.tar.gz . +[jdoe@newskysaw test]$ sudo tar -C initrd -xzf v3vee_initramfs.tar.gz \end{verbatim} -\section{Build the ramdisk filesystem} +\noindent +If you require a custom initial ramdisk filesystem, in the +``\verb|initrd/initramfs/|" directory, perform the following steps: -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 initramfs]$ mkdir -p proc sys var/log +\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 +Edit the ``\verb|init_task|" script and uncomment these lines: -\section{Configure and Install Busybox tools} +\begin{verbatim} +#mknod /dev/tty0 c 4 0 +#mknod /dev/tty1 c 4 1 +#mknod /dev/tty2 c 4 2 +\end{verbatim} -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. +\pagebreak -To configure BusyBox, in the \verb+busybox/+ directory, type +\noindent +Create the \verb|console| device. If you have sudo or root access it is possible +to create this device manually: \begin{verbatim} -make meunconfig -make xconfig (X version) +[jdoe@newskysaw initramfs]$ sudo mknod dev/console c 5 1 +[jdoe@newskysaw initramfs]$ sudo chmod 0600 dev/console \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 +If you do not have sudo or root access it is still possible to create the +\verb|console| device indirectly through the kernel build. In the +``\verb|initrd/|" directory create a file called ``\verb|root_files|" and add +the following line: -\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 +nod /dev/console 0600 0 0 c 5 1 +\end{verbatim} + +\noindent +The ``\verb|root_files|" file will be referenced in the section Configuring and +compiling 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}[h] + \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 (X version) \end{verbatim} -And then install the tools to your inital ramdisk directory +\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} -make install +[jdoe@newskysaw busybox]$ make install \end{verbatim} -\section{Configure and Compile Linux Kernel} +\begin{figure}[ht] + \begin{center} + \colfigsize\epsffile{linuxConf.eps} + \end{center} + \caption{Linux Kernel configuration} + \label{fig:linuxcf} +\end{figure} -Go to \verb|linux-2.6.30.y/| directory (or whatever your -Linux kernel source directory). Type + +\section{Configuring and compiling the Linux kernel} + +Change to the \verb|linux-2.6.30.y/| directory (or whatever your Linux kernel +source directory is named) and type the following: \begin{verbatim} -make menuconfig +make menuconfig +\end{verbatim} +or +\begin{verbatim} make xconfig (X version) \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). +\vspace{10pt} +\noindent +Configure the kernel to meet your requirements. 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). +For more on configuring and compiling Linux kernel images, check online. + +\vspace{5pt} +\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 your \verb|initramfs| +directory as shown in figure \ref{fig:linuxcf}. When you are finished +configuring the kernel, save your configuration, and type the following: +\begin{verbatim} +make +\end{verbatim} +Some blurb about where the kernel image is... -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}. -\begin{figure}\begin{center}\colfigsize\epsffile{linuxConf.eps}\end{center}\caption{Linux Kernel configuartion}\label{fig:linuxcf}\end{figure} +\section{Configuring guest devices} -\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/). +Checkout the updated Palacios repository to \verb|palacios/|. (You can find +instructions for checking out the Palacios and Kitten repositories at +\url{http://www.v3vee.org/palacios/}). To build the guest VM creator tool, +change to the \verb|palacios/utils/guest_creator| directory and type the +following: -In the "\verb|palacios/utils/guest_creator|", Type \begin{verbatim} make \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 +\vspace{10pt} +\noindent +You will get the \verb|build_vm| executable. The guest configuration file uses +XML. A sample configuration file is provided: \verb|default.xml|. + +\vspace{5pt} +\noindent +***Various information about how to configure the VM.*** +\vspace{5pt} +\noindent +Once you have configured the VM, type the following to build the full guest VM +image: \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 will be used to configure kitten in the next +section. -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). -\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. -To configure Palacios, in Palacios root directory, such as \verb+palacios/+, type +\pagebreak +\begin{figure}[h] + \begin{center} + \colfigsize\epsffile{kittenConf1.eps} + \end{center} + \caption{Kitten configuration} + \label{fig:kittencf} +\end{figure} + +\begin{figure}[h] + \begin{center} + \colfigsize\epsffile{kittenConf2.eps} + \end{center} + \caption{Kitten configuration} + \label{fig:kittencf2} +\end{figure} + + +\section{Configuring and building Palacios and Kitten} +\subsection*{Configuring and building Palacios} + +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 booting guest procedure. +To configure Palacios, in the Palacios root directory (i.e. \verb+palacios/+) +type the following: \begin{verbatim} make config +\end{verbatim} or +\begin{verbatim} make xconfig \end{verbatim} -To configure the components you want to build into Palacios. And then type +\vspace{10pt} +\noindent +When you have configured the components you want to build into Palacios type +the following: \begin{verbatim} make +\end{verbatim} or +\begin{verbatim} make all \end{verbatim} -To build Palacios static library, after build, you can find the Palacios library file \verb+libv3vee.a+ in root directory. +\vspace{10pt} +\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 +To build Kitten, first configure it in as you did Palacios. Change to the +\verb+kitten/+ directory and type the following: \begin{verbatim} make config +\end{verbatim} or +\begin{verbatim} make xconfig \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}. - -\begin{figure}\begin{center}\colfigsize\epsffile{kittenConf1.eps}\end{center}\caption{Kitten configuartion}\label{fig:kittencf}\end{figure} +\vspace{10pt} +\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 path of your Palacios +build, and set the ``\verb|Path to guest ISO image|" option to the path +containing the guest image that was built in the Configuring guest devices +section of this manual. -\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 +\vspace{10pt} +\noindent +After configuring Kitten, to build Kitten, type the following: \begin{verbatim} make isoimage \end{verbatim} -to make the bootable ISO image file with guest OS, Palacios and Kitten. +\vspace{10pt} +\noindent +This builds 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+. -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 a guest CD 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 \ @@ -194,11 +344,11 @@ 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. - +\vspace{10pt} +\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