manual/guest_build/Palacios_Guest_Build.tex

   1 \documentclass{article}[11pt]
   2
   3 \usepackage{amsmath}
   4 \usepackage{amssymb}
   5 \usepackage{verbatim}
   6 \usepackage{epsf}
   7 \usepackage{graphicx}
   8 \usepackage{hyperref}
   9
  10 \def\colfigsize{\epsfxsize=5in}
  11
  12 \pdfpagewidth 8.5in
  13 \pdfpageheight 11.0in
  14
  15 \setlength\topmargin{0in}
  16 \setlength\evensidemargin{0in}
  17 \setlength\oddsidemargin{0in}
  18 \setlength\textheight{8.0in}
  19 \setlength\textwidth{6.5in}
  20
  21 \title{Building a bootable guest image for Palacios and Kitten}
  22
  23 \begin{document}
  24 \maketitle
  25
  26 \section{Getting the guest image build tools}
  27
  28 In order to build the bootable guest iso image, we need to build a Linux kernel
  29 image from source and an initial file system containing a set of useful binary
  30 files which will be described in the following text. We will use a new directory
  31 for demonstration; the root directory for the following examples is
  32 \verb+test/+:
  33
  34 \begin{verbatim}
  35 mkdir test/
  36 cd test/
  37 \end{verbatim}
  38
  39 \vspace{10pt}
  40 \noindent
  41 There are a set of tools and sources that are useful for the guest image
  42 building procedure. You can checkout these resources from our git repositories;
  43 to check them out to your local \verb+test/+ directory use the following
  44 commands:
  45
  46 \begin{verbatim}
  47 git clone http://hornet.cs.northwestern.edu:9005/busybox
  48 git clone http://hornet.cs.northwestern.edu:9005/initrd
  49 git clone http://hornet.cs.northwestern.edu:9005/linux-2.6.30.y
  50 \end{verbatim}
  51
  52 \section{Building the ramdisk filesystem}
  53
  54 % Introductory text explaining why a ramdisk filesystem is necessary, and a
  55 % small blurb about what it is. Mostly this is necessary because the
  56 % introduction said that the "useful binary files" would be described.
  57
  58 Jack has made an initial ramdisk system that you can leverage. The file is
  59 temporarily in the directory
  60 \verb|/home/jarusl/initrd/disks/v3vee_initramfs.tar.gz| on the
  61 newskysaw machine. If you require a custom initial ramdisk, copy the directories
  62 and files that you require into the \verb+initramfs+/ directory. For minimal
  63 device support, copy theses devices into the \verb+initramfs/dev/+ directory:
  64 console, ram, null, tty (you probably need root privilege to copy and make the
  65 device files).
  66
  67
  68
  69 \pagebreak
  70 \begin{figure}[ht]
  71   \begin{center}
  72     \colfigsize\epsffile{busyboxConf1.eps}
  73     \caption{BusyBox configuration}
  74     \label{fig:busyboxcf1}
  75   \end{center}
  76 \end{figure}
  77
  78 \begin{figure}[h]
  79   \begin{center}
  80     \colfigsize\epsffile{busyboxConf2.eps}
  81   \end{center}
  82   \caption{BusyBox configuration}
  83   \label{fig:busyboxcf2}
  84 \end{figure}
  85
  86 \section{Configuring and installing BusyBox tools}
  87
  88 BusyBox is a software application released as Free software under the GNU GPL
  89 that provides many standard Unix tools. BusyBox combines tiny versions of many
  90 common UNIX utilities into a single small executable. For more details on
  91 BusyBox, visiting \url{http://busybox.net}. To configure BusyBox, in the
  92 \verb+busybox/+ directory, type the following:
  93
  94 \begin{verbatim}
  95 make menuconfig
  96 \end{verbatim}
  97
  98 or
  99
 100 \begin{verbatim}
 101 make xconfig (X version)
 102 \end{verbatim}
 103
 104 \vspace{10pt}
 105 \noindent
 106 You can add the tools you need into the guest image. There are two required
 107 configuration options: in ``\verb|BusyBox settings->Build Options|", check the
 108 ``\verb|Build BusyBox as a static binary|" option, and in
 109 ``\verb|BusyBox settings->Installation Options|", set the
 110 ``\verb|Busybox installation prefix|" to the path of your \verb|initramfs|
 111 directory, as shown in figure \ref{fig:busyboxcf2}. After you finish configuring
 112 BusyBox, save your configuration and quit the window. Then, to make the BusyBox
 113 tools, type the following:
 114
 115 \begin{verbatim}
 116 make
 117 \end{verbatim}
 118 Install the tools to your initial ramdisk directory:
 119 \begin{verbatim}
 120 make install
 121 \end{verbatim}
 122
 123 \begin{figure}[ht]
 124   \begin{center}
 125     \colfigsize\epsffile{linuxConf.eps}
 126   \end{center}
 127   \caption{Linux Kernel configuration}
 128   \label{fig:linuxcf}
 129 \end{figure}
 130
 131
 132 \section{Configuring and compiling the Linux kernel}
 133
 134 Change to the \verb|linux-2.6.30.y/| directory (or whatever your Linux kernel
 135 source directory is named) and type the following:
 136
 137 \begin{verbatim}
 138 make menuconfig
 139 \end{verbatim}
 140 or
 141 \begin{verbatim}
 142 make xconfig (X version)
 143 \end{verbatim}
 144
 145 \vspace{10pt}
 146 \noindent
 147 Configure the kernel to meet your requirements. There is a custom configuration
 148 file \verb|jrl-default-config| which is configured with minimal kernel options
 149 (all unnecessary options are removed to keep the guest booting process fast).
 150 For more on configuring and compiling Linux kernel images, check online.
 151
 152 \vspace{5pt}
 153 \noindent
 154 The kernel must be configured with the initial ramdisk file system directory
 155 (e.g. \verb|initrd/initramfs|): in the ``\verb|General setup|" menu under
 156 option
 157 ``\verb|Initial RAM filesystem and RAM disk support|" set the
 158 ``\verb|Initramfs source file(s)|" option to the path of your \verb|initramfs|
 159 directory as shown in figure \ref{fig:linuxcf}. When you are finished
 160 configuring the kernel, save your configuration, and type the following:
 161 \begin{verbatim}
 162 make
 163 \end{verbatim}
 164 Some blurb about where the kernel image is...
 165
 166
 167 \section{Configuring guest devices}
 168
 169 Checkout the updated Palacios repository to \verb|palacios/|.  (You can find
 170 instructions for checking out the Palacios and Kitten repositories at
 171 \url{http://www.v3vee.org/palacios/}). To build the guest VM creator tool,
 172 change to the \verb|palacios/utils/guest_creator| directory and type the
 173 following:
 174
 175 \begin{verbatim}
 176 make
 177 \end{verbatim}
 178
 179 \vspace{10pt}
 180 \noindent
 181 You will get the \verb|build_vm| executable. The guest configuration file uses
 182 XML. A sample configuration file is provided: \verb|default.xml|.
 183
 184 \vspace{5pt}
 185 \noindent
 186 ***Various information about how to configure the VM.***
 187
 188 \vspace{5pt}
 189 \noindent
 190 Once you have configured the VM, type the following to build the full guest VM
 191 image:
 192 \begin{verbatim}
 193 ./build_vm myconfig.xml -o guest.iso
 194 \end{verbatim}
 195 where \verb+myconfig.xml+ is your guest configuration file, and \verb+guest.iso+
 196 is the output image file that will be used to configure kitten in the next
 197 section.
 198
 199
 200
 201
 202 \pagebreak
 203 \begin{figure}[h]
 204   \begin{center}
 205     \colfigsize\epsffile{kittenConf1.eps}
 206   \end{center}
 207   \caption{Kitten configuration}
 208   \label{fig:kittencf}
 209 \end{figure}
 210
 211 \begin{figure}[h]
 212   \begin{center}
 213     \colfigsize\epsffile{kittenConf2.eps}
 214   \end{center}
 215   \caption{Kitten configuration}
 216   \label{fig:kittencf2}
 217 \end{figure}
 218
 219
 220 \section{Configuring and building Palacios and Kitten}
 221 \subsection*{Configuring and building Palacios}
 222
 223 You can find the detailed manual of getting and building Palacios and Kitten
 224 from scratch in the Palacios website (\url{http://www.v3vee.org/palacios}). Here
 225 we only give the specific requirements related to the booting guest procedure.
 226 To configure Palacios, in the Palacios root directory (i.e. \verb+palacios/+)
 227 type the following:
 228
 229 \begin{verbatim}
 230 make config
 231 \end{verbatim}
 232 or
 233 \begin{verbatim}
 234 make xconfig
 235 \end{verbatim}
 236
 237 \vspace{10pt}
 238 \noindent
 239 When you have configured the components you want to build into Palacios type
 240 the following:
 241
 242 \begin{verbatim}
 243 make
 244 \end{verbatim}
 245 or
 246 \begin{verbatim}
 247 make all
 248 \end{verbatim}
 249
 250 \vspace{10pt}
 251 \noindent
 252 Once the Palacios static library has been built you can find the library file
 253 \verb+libv3vee.a+ in the Palacios root directory.
 254
 255 \subsection*{Configuring and building Kitten}
 256
 257 To build Kitten, first configure it in as you did Palacios. Change to the
 258 \verb+kitten/+ directory and type the following:
 259
 260 \begin{verbatim}
 261 make config
 262 \end{verbatim}
 263 or
 264 \begin{verbatim}
 265 make xconfig
 266 \end{verbatim}
 267
 268 \vspace{10pt}
 269 \noindent
 270 Under the ``\verb|Virtualization|" menu select the
 271 ``\verb|Include Palacios virtual machine monitor|" option. Set the
 272 ``\verb|Path to pre-built Palacios tree|" option to the path of your Palacios
 273 build, and set the ``\verb|Path to guest ISO image|" option to the path
 274 containing the guest image that was built in the Configuring guest devices
 275 section of this manual.
 276
 277 \vspace{10pt}
 278 \noindent
 279 After configuring Kitten, to build Kitten, type the following:
 280
 281 \begin{verbatim}
 282 make isoimage
 283 \end{verbatim}
 284
 285 \vspace{10pt}
 286 \noindent
 287 This builds the bootable ISO image file with guest OS, Palacios and Kitten.
 288 The ISO file is located in \verb+kitten/arch/x86_64/boot/image.iso+.
 289
 290 \pagebreak
 291 \noindent
 292 You have successfully created a guest CD image file that can be booted on a
 293 machine. You can boot the file on Qemu using the following sample command:
 294
 295 \begin{verbatim}
 296 /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
 297         -smp 1 \
 298         -m 2047 \
 299         -serial file:./serial.out \
 300         -cdrom kitten/arch/x86_64/boot/image.iso \
 301         < /dev/null
 302 \end{verbatim}
 303
 304 \vspace{10pt}
 305 \noindent
 306 We have finished the entire procedure for building a guest image and booting it
 307 on the Palacios VMM. For more updated details, check the Palacios website
 308 \url{http://www.v3vee.org/palacios} and Kitten website
 309 \url{https://software.sandia.gov/trac/kitten} regularly.
 310
 311 \end{document}