1 \documentclass{article}[11pt]
10 \def\colfigsize{\epsfxsize=5in}
15 \setlength\topmargin{0in}
16 \setlength\evensidemargin{0in}
17 \setlength\oddsidemargin{0in}
18 \setlength\textheight{8.0in}
19 \setlength\textwidth{6.5in}
21 \title{Building a bootable guest image for Palacios and Kitten}
26 \section{Getting the guest image build tools}
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
35 [jdoe@newskysaw ~]$ mkdir test/
36 [jdoe@newskysaw ~]$ cd test/
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
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
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:
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
63 If you require a custom initial ramdisk filesystem, in the
64 ``\verb|initrd/initramfs/|" directory, perform the following steps:
67 [jdoe@newskysaw initramfs]$ mkdir -p proc sys var/log
71 Edit the ``\verb|init_task|" script and uncomment these lines:
74 #mknod /dev/tty0 c 4 0
75 #mknod /dev/tty1 c 4 1
76 #mknod /dev/tty2 c 4 2
82 Create the \verb|console| device. If you have sudo or root access it is possible
83 to create this device manually:
86 [jdoe@newskysaw initramfs]$ sudo mknod dev/console c 5 1
87 [jdoe@newskysaw initramfs]$ sudo chmod 0600 dev/console
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
97 nod /dev/console 0600 0 0 c 5 1
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.
112 \colfigsize\epsffile{busyboxConf1.eps}
113 \caption{BusyBox configuration}
114 \label{fig:busyboxcf1}
120 \colfigsize\epsffile{busyboxConf2.eps}
122 \caption{BusyBox configuration}
123 \label{fig:busyboxcf2}
126 \section{Configuring and installing BusyBox tools}
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:
135 [jdoe@newskysaw busybox]$ make menuconfig
142 [jdoe@newskysaw busybox]$ make xconfig (X version)
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
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:
159 [jdoe@newskysaw busybox]$ make
161 Install the tools to the guest's initial ramdisk filesystem directory:
163 [jdoe@newskysaw busybox]$ make install
168 \colfigsize\epsffile{linuxConf.eps}
170 \caption{Linux Kernel configuration}
175 \section{Configuring and compiling the Linux kernel}
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:
185 make xconfig (X version)
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.
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
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:
207 Some blurb about where the kernel image is...
210 \section{Configuring guest devices}
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
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|.
229 ***Various information about how to configure the VM.***
233 Once you have configured the VM, type the following to build the full guest VM
236 ./build_vm myconfig.xml -o guest.iso
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
248 \colfigsize\epsffile{kittenConf1.eps}
250 \caption{Kitten configuration}
256 \colfigsize\epsffile{kittenConf2.eps}
258 \caption{Kitten configuration}
259 \label{fig:kittencf2}
263 \section{Configuring and building Palacios and Kitten}
264 \subsection*{Configuring and building Palacios}
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/+)
282 When you have configured the components you want to build into Palacios type
295 Once the Palacios static library has been built you can find the library file
296 \verb+libv3vee.a+ in the Palacios root directory.
298 \subsection*{Configuring and building Kitten}
300 To build Kitten, first configure it in as you did Palacios. Change to the
301 \verb+kitten/+ directory and type the following:
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.
322 After configuring Kitten, to build Kitten, type the following:
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+.
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:
339 /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
342 -serial file:./serial.out \
343 -cdrom kitten/arch/x86_64/boot/image.iso \
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.