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