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 from source and an initial ramdisk file system containing a set of useful
30 tools. We will use a new directory for demonstration; the root directory for the
31 following examples is ``\verb+test/+":
34 [jdoe@newskysaw ~]$ mkdir test/
38 There are a set of tools and sources that are useful for the guest image
39 building procedure. You can obtain these resources from our git repositories.
40 Change to the ``\verb+test/+" directory and clone the resources:
43 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/busybox
44 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/initrd
45 [jdoe@newskysaw test]$ git clone http://hornet.cs.northwestern.edu:9005/linux-2.6.30.y
48 \section{Building the ramdisk filesystem}
49 The guest requires an initial ramdisk filesystem. Jack has made one that you can
50 leverage; it is temporarily located in his home directory. You will need sudo
51 or root access to create the device files when you unpack the archive:
54 [jdoe@newskysaw test]$ cp /home/jarusl/initrd/disks/v3vee_initramfs.tar.gz .
55 [jdoe@newskysaw test]$ sudo tar -C initrd -xzf v3vee_initramfs.tar.gz
59 If you require a custom initial ramdisk filesystem, change to the
60 ``\verb|initrd/initramfs/|" directory and perform the following steps:
63 [jdoe@newskysaw initramfs]$ mkdir -p proc sys var/log
67 Edit the ``\verb|init_task|" script and uncomment these lines:
70 #mknod /dev/tty0 c 4 0
71 #mknod /dev/tty1 c 4 1
72 #mknod /dev/tty2 c 4 2
78 Create the ``\verb|console|" device. If you have sudo or root access it is
79 possible to create this device manually:
82 [jdoe@newskysaw initramfs]$ sudo mknod dev/console c 5 1
83 [jdoe@newskysaw initramfs]$ sudo chmod 0600 dev/console
87 If you do not have sudo or root access it is still possible to create the
88 ``\verb|console|" device indirectly through the kernel build. Change to the
89 ``\verb|initrd/|" directory and create a file called ``\verb|root_files|". Add
93 nod /dev/console 0600 0 0 c 5 1
97 The ``\verb|root_files|" file is used when building the Linux kernel in the
98 section Configuring and building the Linux kernel. Finally, create any
99 additional directories and copy any additional files that you need. Your initial
100 ramdisk filesystem is prepped and ready for installation of the BusyBox tools as
101 described in the section Configuring and installing BusyBox tools.
108 \colfigsize\epsffile{busyboxConf1.eps}
109 \caption{BusyBox configuration}
110 \label{fig:busyboxcf1}
116 \colfigsize\epsffile{busyboxConf2.eps}
118 \caption{BusyBox configuration}
119 \label{fig:busyboxcf2}
122 \section{Configuring and installing BusyBox tools}
124 BusyBox is a software application released as Free software under the GNU GPL
125 that provides many standard Unix tools. BusyBox combines tiny versions of many
126 common UNIX utilities into a single, small executable. For more details on
127 BusyBox visit \url{http://busybox.net}. To configure BusyBox, in the
128 ``\verb+busybox/+" directory, type the following:
131 [jdoe@newskysaw busybox]$ make menuconfig
138 [jdoe@newskysaw busybox]$ make xconfig
142 The BusyBox tools will be installed in the guest's initial ramdisk filesystem;
143 you can add any tools that you need. There are two required configuration
145 ``\verb|BusyBox settings->Build Options|" menu check the
146 ``\verb|Build BusyBox as a static binary (no shared libs)|" option, as shown in
147 figure \ref{fig:busyboxcf1}, and in the
148 ``\verb|BusyBox settings->Installation Options|" menu set the
149 ``\verb|Busybox installation prefix|" to the path of the
150 ``\verb|initrd/initramfs|" directory, as shown in figure \ref{fig:busyboxcf2}.
151 After you finish configuring BusyBox, save your configuration and quit the
152 window. Then, to make the BusyBox tools, type the following:
155 [jdoe@newskysaw busybox]$ make
157 Install the tools to the guest's initial ramdisk filesystem directory:
159 [jdoe@newskysaw busybox]$ make install
164 \colfigsize\epsffile{linuxConf.eps}
166 \caption{Linux Kernel configuration}
171 \section{Configuring and building the Linux kernel}
173 The following procedure demonstrates how to configure and build a 32-bit Linux
174 kernel. Change to the ``\verb|linux-2.6.30.y/|" directory. There is a custom
175 configuration file ``\verb|jrl-default-config|" which is configured with minimal
176 kernel options (all unnecessary options are removed to keep the guest booting
177 process fast). If you are using the custom configuration file type the
181 [jdoe@newskysaw linux-2.6.30.y]$ cp jrl-default-config .config
185 Configure the kernel to meet your requirements. For more on configuring and
186 building Linux kernels, check online. Type the following:
189 [jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386 menuconfig
196 [jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386 xconfig
200 The kernel must be configured with the initial ramdisk file system directory
201 (e.g. ``\verb|initrd/initramfs/|"): in the ``\verb|General setup|" menu under
203 ``\verb|Initial RAM filesystem and RAM disk support|" set the
204 ``\verb|Initramfs source file(s)|" option to the path of the
205 ``\verb|initrd/initramfs/|" directory, as shown in figure \ref{fig:linuxcf}.
206 Additionally, if you are using the ``\verb|root_files|" file to create devices
207 files, add the ``\verb|root_files|" file path, separated by a space, after the
208 initial ramdisk filesystem directory. When you are finished configuring the
209 kernel, save your configuration, and build a bootable ISO image:
212 [jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386 isoimage
216 The ISO image can be found here: ``\verb|arch/x86/boot/image.iso|", and will be
217 used in the section Configuring and building the guest image.
220 \section{Configuring and building the guest image}
222 Checkout the updated Palacios repository to the ``\verb|palacios/|" directory.
223 (You can find instructions for checking out the Palacios repository at
224 \url{http://www.v3vee.org/palacios/}). The guest creator utility is required for
225 building the guest image. Change to the ``\verb|palacios/utils/guest_creator|"
226 directory and build the guest creator utility:
229 [jdoe@newskysaw guest_creator]$ make
233 You will get the ``\verb|build_vm|" utility:
235 [jdoe@newskysaw guest_creator]$ file build_vm
236 build_vm: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked
237 (uses shared libs), for GNU/Linux 2.6.9, not stripped
241 The guest configuration file is written in XML. A sample configuration file is
242 provided: ``\verb|default.xml|". Make a copy of the default configuration file
243 named ``\verb|myconfig.xml|" and edit the configuration elements that you are
244 interested in (if a device is included in the guest configuration file, it
245 must be configured in the section Configuring and building Palacios or the guest
246 will not boot). Of particular importance is the ``\verb|files|" element. Comment
250 <file id="boot-cd" filename="/home/jarusl/image.iso" />
254 Add an attribute that specifies the location of the Linux ISO image:
257 <file id="boot-cd" filename="../../../linux-2.6.30.y/arch/x86/boot/image.iso" />
261 When you are finished editing the guest configuration save the configuration
262 file. The guest image consists of the guest configuration file and the Linux
263 ISO image. Build the guest image with the guest creator utility:
266 [jdoe@newskysaw guest_creator]$ ./build_vm myconfig.xml -o guest.iso
270 The guest image, ``\verb+guest.iso+", is embedded in Kitten's
271 ``\verb|init_task|" in the section Configuring and building Kitten.
277 \colfigsize\epsffile{kittenConf1.eps}
279 \caption{Kitten configuration}
285 \colfigsize\epsffile{kittenConf2.eps}
287 \caption{Kitten configuration}
288 \label{fig:kittencf2}
292 \section{Configuring and building Palacios and Kitten}
293 \subsection*{Configuring and building Palacios}
295 You can find the detailed manual of getting and building Palacios and Kitten
296 from scratch in the Palacios website (\url{http://www.v3vee.org/palacios}). Here
297 we only give the specific requirements related to the procedure of booting the
298 guest. To configure Palacios, change to the ``\verb|test/palacios/|" directory
299 and type the following:
302 [jdoe@newskysaw palacios]$ make menuconfig
309 [jdoe@newskysaw palacios]$ make xconfig
313 Don't forget to include the devices that your guest image requires. When you
314 have configured the components you want to build into Palacios, save the
315 configuration and close the window. To build Palacios type the following:
318 [jdoe@newskysaw palacios]$ make
322 [jdoe@newskysaw palacios]$ make all
326 Once the Palacios static library has been built you can find the library file,
327 ``\verb+libv3vee.a+", in the Palacios root directory.
329 \subsection*{Configuring and building Kitten}
331 Configure Kitten. Change to the ``\verb+test/kitten/+" directory and type the
335 [jdoe@newskysaw kitten]$ make menuconfig
342 [jdoe@newskysaw kitten]$ make xconfig
346 Under the ``\verb|Virtualization|" menu select the
347 ``\verb|Include Palacios virtual machine monitor|" option. Set the
348 ``\verb|Path to pre-built Palacios tree|" option to the Palacios build tree
349 path, ``\verb|..\palacios|", as shown in figure \ref{fig:kittencf}. Set the
350 ``\verb|Path to guest OS ISO image|" option to the guest image path,\\
351 ''\verb|../palacios/utils/guest_creator/guest.iso|'', as shown in figure
352 \ref{fig:kittencf2}. When you have finished configuring Kitten, save the
353 configuration and close the window. To build Kitten type the following:
356 [jdoe@newskysaw kitten]$ make isoimage
360 This builds the bootable ISO image file with guest image, Palacios, and Kitten.
361 The ISO file is located in ``\verb+kitten/arch/x86_64/boot/image.iso+".
365 You have successfully created an ISO image file that can be booted on a machine.
366 You can boot the file on Qemu using the following sample command:
369 [jdoe@newskysaw test]$ /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
372 -serial file:./serial.out \
373 -cdrom kitten/arch/x86_64/boot/image.iso \
378 We have finished the entire procedure for building a guest image and booting it
379 on the Palacios VMM. For more updated details, check the Palacios website
380 \url{http://www.v3vee.org/palacios} and Kitten website
381 \url{https://software.sandia.gov/trac/kitten} regularly.