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 [jdoe@newskysaw ~]$ mkdir test/
  36 [jdoe@newskysaw ~]$ 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 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/busybox
  48 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/initrd
  49 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/linux-2.6.30.y
  50 \end{verbatim}
  51
  52 \section{Building the ramdisk filesystem}
  53 The guest requires an initial ramdisk filesystem. Jack has made one that you can
  54 leverage; it is temporarily located in his home directory.  You will need sudo
  55 or root access to create the device files when you unpack the archive:
  56
  57 \begin{verbatim}
  58 [jdoe@newskysaw test]$ cp /home/jarusl/initrd/disks/v3vee_initramfs.tar.gz .
  59 [jdoe@newskysaw test]$ sudo tar -C initrd -xzf v3vee_initramfs.tar.gz
  60 \end{verbatim}
  61
  62 \noindent
  63 If you require a custom initial ramdisk filesystem, in the
  64 ``\verb|initrd/initramfs/|" directory, perform the following steps:
  65
  66 \begin{verbatim}
  67 [jdoe@newskysaw initramfs]$ mkdir -p proc sys var/log
  68 \end{verbatim}
  69
  70 \noindent
  71 Edit the ``\verb|init_task|" script and uncomment these lines:
  72
  73 \begin{verbatim}
  74 #mknod /dev/tty0 c 4 0
  75 #mknod /dev/tty1 c 4 1
  76 #mknod /dev/tty2 c 4 2
  77 \end{verbatim}
  78
  79 \pagebreak
  80
  81 \noindent
  82 Create the \verb|console| device. If you have sudo or root access it is possible
  83 to create this device manually:
  84
  85 \begin{verbatim}
  86 [jdoe@newskysaw initramfs]$ sudo mknod dev/console c 5 1
  87 [jdoe@newskysaw initramfs]$ sudo chmod 0600 dev/console
  88 \end{verbatim}
  89
  90 \noindent
  91 If you do not have sudo or root access it is still possible to create the
  92 \verb|console| device indirectly through the kernel build.  In the
  93 ``\verb|initrd/|" directory create a file called ``\verb|root_files|" and add
  94 the following line:
  95
  96 \begin{verbatim}
  97 nod /dev/console 0600 0 0 c 5 1
  98 \end{verbatim}
  99
 100 \noindent
 101 The ``\verb|root_files|" file will be referenced in the section Configuring and
 102 compiling the Linux kernel. Finally, create any additional directories and copy
 103 any additional files that you need. Your initial ramdisk filesystem is prepped
 104 and ready for installation of the BusyBox tools as described in the section
 105 Configuring and installing BusyBox tools.
 106
 107
 108
 109 \pagebreak
 110 \begin{figure}[ht]
 111   \begin{center}
 112     \colfigsize\epsffile{busyboxConf1.eps}
 113     \caption{BusyBox configuration}
 114     \label{fig:busyboxcf1}
 115   \end{center}
 116 \end{figure}
 117
 118 \begin{figure}[h]
 119   \begin{center}
 120     \colfigsize\epsffile{busyboxConf2.eps}
 121   \end{center}
 122   \caption{BusyBox configuration}
 123   \label{fig:busyboxcf2}
 124 \end{figure}
 125
 126 \section{Configuring and installing BusyBox tools}
 127
 128 BusyBox is a software application released as Free software under the GNU GPL
 129 that provides many standard Unix tools. BusyBox combines tiny versions of many
 130 common UNIX utilities into a single, small executable. For more details on
 131 BusyBox visit \url{http://busybox.net}. To configure BusyBox, in the
 132 ``\verb+busybox/+" directory, type the following:
 133
 134 \begin{verbatim}
 135 [jdoe@newskysaw busybox]$ make menuconfig
 136 \end{verbatim}
 137
 138 \noindent
 139 or
 140
 141 \begin{verbatim}
 142 [jdoe@newskysaw busybox]$ make xconfig (X version)
 143 \end{verbatim}
 144
 145 \noindent
 146 The BusyBox tools will be installed in the guest's initial ramdisk filesystem;
 147 you can add any tools that you need. There are two required configuration
 148 options. In the
 149 ``\verb|BusyBox settings->Build Options|" menu check the
 150 ``\verb|Build BusyBox as a static binary (no shared libs)|" option, as shown in
 151 figure \ref{fig:busyboxcf1}, and in the
 152 ``\verb|BusyBox settings->Installation Options|" menu set the
 153 ``\verb|Busybox installation prefix|" to the path of the
 154 ``\verb|initrd/initramfs|" directory, as shown in figure \ref{fig:busyboxcf2}.
 155 After you finish configuring BusyBox, save your configuration and quit the
 156 window. Then, to make the BusyBox tools, type the following:
 157
 158 \begin{verbatim}
 159 [jdoe@newskysaw busybox]$ make
 160 \end{verbatim}
 161 Install the tools to the guest's initial ramdisk filesystem directory:
 162 \begin{verbatim}
 163 [jdoe@newskysaw busybox]$ make install
 164 \end{verbatim}
 165
 166 \begin{figure}[ht]
 167   \begin{center}
 168     \colfigsize\epsffile{linuxConf.eps}
 169   \end{center}
 170   \caption{Linux Kernel configuration}
 171   \label{fig:linuxcf}
 172 \end{figure}
 173
 174
 175 \section{Configuring and compiling the Linux kernel}
 176
 177 Change to the \verb|linux-2.6.30.y/| directory (or whatever your Linux kernel
 178 source directory is named) and type the following:
 179
 180 \begin{verbatim}
 181 make menuconfig
 182 \end{verbatim}
 183 or
 184 \begin{verbatim}
 185 make xconfig (X version)
 186 \end{verbatim}
 187
 188 \vspace{10pt}
 189 \noindent
 190 Configure the kernel to meet your requirements. There is a custom configuration
 191 file \verb|jrl-default-config| which is configured with minimal kernel options
 192 (all unnecessary options are removed to keep the guest booting process fast).
 193 For more on configuring and compiling Linux kernel images, check online.
 194
 195 \vspace{5pt}
 196 \noindent
 197 The kernel must be configured with the initial ramdisk file system directory
 198 (e.g. \verb|initrd/initramfs|): in the ``\verb|General setup|" menu under
 199 option
 200 ``\verb|Initial RAM filesystem and RAM disk support|" set the
 201 ``\verb|Initramfs source file(s)|" option to the path of your \verb|initramfs|
 202 directory as shown in figure \ref{fig:linuxcf}. When you are finished
 203 configuring the kernel, save your configuration, and type the following:
 204 \begin{verbatim}
 205 make
 206 \end{verbatim}
 207 Some blurb about where the kernel image is...
 208
 209
 210 \section{Configuring guest devices}
 211
 212 Checkout the updated Palacios repository to \verb|palacios/|.  (You can find
 213 instructions for checking out the Palacios and Kitten repositories at
 214 \url{http://www.v3vee.org/palacios/}). To build the guest VM creator tool,
 215 change to the \verb|palacios/utils/guest_creator| directory and type the
 216 following:
 217
 218 \begin{verbatim}
 219 make
 220 \end{verbatim}
 221
 222 \vspace{10pt}
 223 \noindent
 224 You will get the \verb|build_vm| executable. The guest configuration file uses
 225 XML. A sample configuration file is provided: \verb|default.xml|.
 226
 227 \vspace{5pt}
 228 \noindent
 229 ***Various information about how to configure the VM.***
 230
 231 \vspace{5pt}
 232 \noindent
 233 Once you have configured the VM, type the following to build the full guest VM
 234 image:
 235 \begin{verbatim}
 236 ./build_vm myconfig.xml -o guest.iso
 237 \end{verbatim}
 238 where \verb+myconfig.xml+ is your guest configuration file, and \verb+guest.iso+
 239 is the output image file that will be used to configure kitten in the next
 240 section.
 241
 242
 243
 244
 245 \pagebreak
 246 \begin{figure}[h]
 247   \begin{center}
 248     \colfigsize\epsffile{kittenConf1.eps}
 249   \end{center}
 250   \caption{Kitten configuration}
 251   \label{fig:kittencf}
 252 \end{figure}
 253
 254 \begin{figure}[h]
 255   \begin{center}
 256     \colfigsize\epsffile{kittenConf2.eps}
 257   \end{center}
 258   \caption{Kitten configuration}
 259   \label{fig:kittencf2}
 260 \end{figure}
 261
 262
 263 \section{Configuring and building Palacios and Kitten}
 264 \subsection*{Configuring and building Palacios}
 265
 266 You can find the detailed manual of getting and building Palacios and Kitten
 267 from scratch in the Palacios website (\url{http://www.v3vee.org/palacios}). Here
 268 we only give the specific requirements related to the booting guest procedure.
 269 To configure Palacios, in the Palacios root directory (i.e. \verb+palacios/+)
 270 type the following:
 271
 272 \begin{verbatim}
 273 make config
 274 \end{verbatim}
 275 or
 276 \begin{verbatim}
 277 make xconfig
 278 \end{verbatim}
 279
 280 \vspace{10pt}
 281 \noindent
 282 When you have configured the components you want to build into Palacios type
 283 the following:
 284
 285 \begin{verbatim}
 286 make
 287 \end{verbatim}
 288 or
 289 \begin{verbatim}
 290 make all
 291 \end{verbatim}
 292
 293 \vspace{10pt}
 294 \noindent
 295 Once the Palacios static library has been built you can find the library file
 296 \verb+libv3vee.a+ in the Palacios root directory.
 297
 298 \subsection*{Configuring and building Kitten}
 299
 300 To build Kitten, first configure it in as you did Palacios. Change to the
 301 \verb+kitten/+ directory and type the following:
 302
 303 \begin{verbatim}
 304 make config
 305 \end{verbatim}
 306 or
 307 \begin{verbatim}
 308 make xconfig
 309 \end{verbatim}
 310
 311 \vspace{10pt}
 312 \noindent
 313 Under the ``\verb|Virtualization|" menu select the
 314 ``\verb|Include Palacios virtual machine monitor|" option. Set the
 315 ``\verb|Path to pre-built Palacios tree|" option to the path of your Palacios
 316 build, and set the ``\verb|Path to guest ISO image|" option to the path
 317 containing the guest image that was built in the Configuring guest devices
 318 section of this manual.
 319
 320 \vspace{10pt}
 321 \noindent
 322 After configuring Kitten, to build Kitten, type the following:
 323
 324 \begin{verbatim}
 325 make isoimage
 326 \end{verbatim}
 327
 328 \vspace{10pt}
 329 \noindent
 330 This builds the bootable ISO image file with guest OS, Palacios and Kitten.
 331 The ISO file is located in \verb+kitten/arch/x86_64/boot/image.iso+.
 332
 333 \pagebreak
 334 \noindent
 335 You have successfully created a guest CD image file that can be booted on a
 336 machine. You can boot the file on Qemu using the following sample command:
 337
 338 \begin{verbatim}
 339 /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
 340         -smp 1 \
 341         -m 2047 \
 342         -serial file:./serial.out \
 343         -cdrom kitten/arch/x86_64/boot/image.iso \
 344         < /dev/null
 345 \end{verbatim}
 346
 347 \vspace{10pt}
 348 \noindent
 349 We have finished the entire procedure for building a guest image and booting it
 350 on the Palacios VMM. For more updated details, check the Palacios website
 351 \url{http://www.v3vee.org/palacios} and Kitten website
 352 \url{https://software.sandia.gov/trac/kitten} regularly.
 353
 354 \end{document}