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 type the following:
212 [jdoe@newskysaw linux-2.6.30.y]$ make ARCH=i386
216 The Linux kernel can be found here: ``\verb|arch/x86/boot/bzImage|". The initial
217 ramdisk filesystem can be found here: ``\verb|usr/initramfs_data.cpio|". The
218 Linux kernel and initial ramdisk filesystem are used to build the Linux ISO
219 image in the section Building the Linux ISO image.
222 \section{Building the Linux ISO image}
224 The Linux ISO image is a bootable image containing the Linux kernel, initial
225 ramdisk filesystem, a boot loader, and a boot loader configuration file. For
226 this procedure, we'll use the ``\verb|test/iso/|" directory as the Linux ISO
230 [jdoe@newskysaw test]$ mkdir iso
234 Change to the ``\verb|iso/|" directory and copy the required files:
237 [jdoe@newskysaw iso]$ cp ../linux-2.6.30.y/arch/x86/boot/bzImage vmlinuz
238 [jdoe@newskysaw iso]$ cp ../linux-2.6.30.y/usr/initramfs_data.cpio initramfs
239 [jdoe@newskysaw iso]$ cp /usr/lib/syslinux/isolinux.bin .
243 Create a file called ``\verb|isolinux.cfg|" and add the following lines:
255 Change back to the ``\verb|test/|" directory and build the Linux ISO image:
258 [jdoe@newskysaw test]$ mkisofs -o linux.iso -b isolinux.bin -no-emul-boot \
259 -boot-load-size 4 -boot-info-table -iso-level 2 -input-charset UTF-8 iso/
263 The ``\verb|linux.iso|'' file is the Linux ISO image and is used to build the
264 guest image in the section Configuring and building the guest image:
267 [jdoe@newskysaw test]$ file linux.iso
268 linux.iso: ISO 9660 CD-ROM filesystem data 'CDROM ' (bootable)
272 \section{Configuring and building the guest image}
274 Checkout the updated Palacios repository to the ``\verb|palacios/|" directory.
275 (You can find instructions for checking out the Palacios repository at
276 \url{http://www.v3vee.org/palacios/}). The guest creator utility is required for
277 building the guest image. Change to the ``\verb|palacios/utils/guest_creator|"
278 directory and build the guest creator utility:
281 [jdoe@newskysaw guest_creator]$ make
285 You will get the ``\verb|build_vm|" utility:
287 [jdoe@newskysaw guest_creator]$ file build_vm
288 build_vm: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked
289 (uses shared libs), for GNU/Linux 2.6.9, not stripped
293 The guest configuration file is written in XML. A sample configuration file is
294 provided: ``\verb|default.xml|". Make a copy of the default configuration file
295 named ``\verb|myconfig.xml|" and edit the configuration elements that you are
296 interested in (if a device is included in the guest configuration file, it
297 must be configured in the section Configuring and building Palacios or the guest
298 will not boot). Of particular importance is the ``\verb|files|" element. Comment
302 <file id="boot-cd" filename="/home/jarusl/image.iso" />
306 Add an attribute that specifies the location of the Linux ISO image:
309 <file id="boot-cd" filename="../../../linux.iso" />
313 When you are finished editing the guest configuration save the configuration
314 file. The guest image consists of the guest configuration file and the Linux
315 ISO image. Build the guest image with the guest creator utility:
318 [jdoe@newskysaw guest_creator]$ ./build_vm myconfig.xml -o guest.iso
322 The guest image, ``\verb+guest.iso+", is embedded in Kitten's
323 ``\verb|init_task|" in the section Configuring and building Kitten.
329 \colfigsize\epsffile{kittenConf1.eps}
331 \caption{Kitten configuration}
337 \colfigsize\epsffile{kittenConf2.eps}
339 \caption{Kitten configuration}
340 \label{fig:kittencf2}
344 \section{Configuring and building Palacios and Kitten}
345 \subsection*{Configuring and building Palacios}
347 You can find the detailed manual of getting and building Palacios and Kitten
348 from scratch in the Palacios website (\url{http://www.v3vee.org/palacios}). Here
349 we only give the specific requirements related to the procedure of booting the
350 guest. To configure Palacios, change to the ``\verb|test/palacios/|" directory
351 and type the following:
354 [jdoe@newskysaw palacios]$ make menuconfig
361 [jdoe@newskysaw palacios]$ make xconfig
365 Don't forget to include the devices that your guest image requires. When you
366 have configured the components you want to build into Palacios, save the
367 configuration and close the window. To build Palacios type the following:
370 [jdoe@newskysaw palacios]$ make
374 [jdoe@newskysaw palacios]$ make all
378 Once the Palacios static library has been built you can find the library file,
379 ``\verb+libv3vee.a+", in the Palacios root directory.
381 \subsection*{Configuring and building Kitten}
383 Configure Kitten. Change to the ``\verb+test/kitten/+" directory and type the
387 [jdoe@newskysaw kitten]$ make menuconfig
394 [jdoe@newskysaw kitten]$ make xconfig
398 Under the ``\verb|Virtualization|" menu select the
399 ``\verb|Include Palacios virtual machine monitor|" option. Set the
400 ``\verb|Path to pre-built Palacios tree|" option to the Palacios build tree
401 path, ``\verb|..\palacios|", as shown in figure \ref{fig:kittencf}. Set the
402 ``\verb|Path to guest OS ISO image|" option to the guest image path,\\
403 ''\verb|../palacios/utils/guest_creator/guest.iso|'', as shown in figure
404 \ref{fig:kittencf2}. When you have finished configuring Kitten, save the
405 configuration and close the window. To build Kitten type the following:
408 [jdoe@newskysaw kitten]$ make isoimage
412 This builds the bootable ISO image file with guest image, Palacios, and Kitten.
413 The ISO file is located in ``\verb+kitten/arch/x86_64/boot/image.iso+".
417 You have successfully created an ISO image file that can be booted on a machine.
418 You can boot the file on Qemu using the following sample command:
421 [jdoe@newskysaw test]$ /opt/vmm-tools/qemu/bin/qemu-system-x86_64 \
424 -serial file:./serial.out \
425 -cdrom kitten/arch/x86_64/boot/image.iso \
430 We have finished the entire procedure for building a guest image and booting it
431 on the Palacios VMM. For more updated details, check the Palacios website
432 \url{http://www.v3vee.org/palacios} and Kitten website
433 \url{https://software.sandia.gov/trac/kitten} regularly.