Bootstrapping a POVB Guest (version 1.4.x)

Building a POVB guest using the supplied source code for version 1.4.x.

Obtaining the Source Code

The POVB source code can be obtained using subversion. You can check out the source code from SourceForge using the command

svn co https://poolsofvirtualb.svn.sourceforge.net/svnroot/poolsofvirtualb/public poolsofvirtualb 

Important Note: The source code located in trunk is not guaranteed to be stable. If you require a stable release, please use a tagged release. For instance, release 1.4.3 can be checked out using the following command:

svn co https://poolsofvirtualb.svn.sourceforge.net/svnroot/poolsofvirtualb/public/tags/release-1.4.3 poolsofvirtualb 

Prerequisites

1. Bootstrapping for POVB v1.4.x must be performed on either a Mac or Unix-based system. Bootstrapping on a Windows host is not supported in the 1.4 series.
2. VirtualBox version 3.0.x. Bootstrapping with VirtualBox v3.1.x is not supported in the 1.4 series. Versions of VirtualBox from the v2.2 series will provide a working POVB machine without SMP.
3. Software required for mounting floppy disk images.
   1. hdiutil for Macs.
   2. mkdosfs for Unix-based systems.
4. Guest Operating System Installation Media.
   1. DVD images of the selected guest operating system is recommended since bootstrapping can proceed without user intervention when no "cd changes" are required.
   2. The POVB team recommend using the most recent version of CentOS for bootstrapping although other RedHat based operating systems should also work (including Fedora).

Mandatory Changes

Before bootstrapping, POVB requires some mandatory changes to the provided template files. These files contain default values for many options, and are customizable for specific needs.

Kickstart File

The bootstrapping process requires a kickstart file supplying the operating system packages to install as well as the post-installation procedure. These files are specific to the guest operating system chosen for bootstrapping. POVB v1.4.x contains two templates, one for Fedora (fedora-ks.cfg.tmpl) and one for CentOS (centos-ks.cfg.tmpl). These files can be used as the basis for bootstrapping any RedHat based Linux distribution.

The procedure for using the CentOS kickstart file is supplied below. The procedure is largely identical for a Fedora guest (this is left as an exercise for the reader).

1. Rename centos-ks.cfg.tmpl to centos-ks.cfg
2. Modify the root password for the guest machine. The default password is "YouReallyNeedToChangeMe!". To modify the root password, replace the rootpw line inside the kickstart file. It is recommended that you supply an encrypted password. On a Linux system, this can be done using

   grub-md5-crypt
   

Then, the rootpw line can be replaced with

rootpw --iscrypted <generated_encrypted_password>

Personal Configuration File

A template of the personal configuration file is supplied with the POVB v1.4 source code. This file, personal_config.txt.tmpl is located in the condor_status directory of the source code. This file should be renamed personal_config.txt and must be located inside condor_status.

Bootstrapping Script

After updating the template files, some minor modifications must be made to the boostrapping script (bootstrap.sh). You should only need to change information that is in the Variables Declaration section. Confirm the following:

1. OS is defined to be either "CentOS" or "Fedora" based on the chosen guest operating system.
2. DVD points to the location of the guest installation media.
3. KICKSTART_FILE should be set to the name of the customized kickstart file (fedora-ks.cfg or centos-ks.cfg by default). If you have customized the name of the kickstart file, change this value appropriately.

In addition, it may be necessary to change the definitions of GUEST_ADDITIONS based on the location of the VirtualBox installation on your system.

Preparing the Environment

Please be sure that the VirtualBox executable are in the current path. The POVB bootstrapping process requires access to both VBoxManage, VBoxHeadless, and VirtualBox.

Bootstrapping should only be attempted when there are no other virtual machines running. Since the bootstrapping script monitors several VirtualBox processes, the user should confirm that there are no other VMs running while bootstrapping.

Creating the Kickstart Floppy Image

Note: This step only applies if you are bootstrapping on a Linux host. If you are bootstrapping on a Mac host, you can proceed to the next section.

The bootstrapping process requires a floppy image which contains the kickstart file. On a Unix based system, this image must be created as root. It is recommended that the use creates the disk image prior to starting the bootstrapping process. Important Note: Bootstrapping should not be performed as root. On a Unix based host:

sudo ./bootstrap.sh -kickstart

Starting the Bootstrapping Process

The bootstrapping process can be started by running bootstrap.sh without any options. A "silent" bootstrap (in which a VirtualBox window is not displayed to the user) can be performed by appending the -silent flag.

./bootstrap.sh

or

./bootstrap.sh -silent

Bootstrapping Questions

Why did my bootstrap fail?

Bootstrapping can fail for a wide variety of reasons. A list of common reasons is shown below:

1. Incorrect VirtualBox Version: POVB v1.4 supports the VirtualBox v2.2 and v3.0 series. Versions of VirtualBox after v3.0 or before v2.2 should not be used.
2. Failure to modify template files appropriately (see above for detailed explanations).
3. Attempting a bootstrap when
   1. A virtual machine by the same name already exists on the system.
   2. The hard drive files from another bootstrap attempt already exist in the current directory.
4. The required files in the shared directory do not exist. This problem can be remedied by re-checking out the source code.

If you believe that your bootstrapping issues are a problem with the source code, do not hesitate to open a bug ticket.

My bootstrap failed - what do I do now?

You must remove the remnants of a previous bootstrapping attempt before trying again. This can be accomplished by performing the following steps:

1. Remove any virtual machines associated with POVB.
2. Remove any hard drive files associated with POVB (povb_packages_hd.vdi, povb_primary_hd.vdi, povb_condor_hd.vdi). Not only do these files need to removed from the bootstrapping directory, but they must also removed from the VirtualBox Media Manager.
3. Remove any floppy images from the VirtualBox Media Manager.
4. If any VirtualBox processors (VBoxHeadless, VirtualBox, VBoxSVC, etc) are running, these processes should be shutdown.

If there are no other VirtualBox virtual machines for the current user on the system, this process can be expedited as follows.

On a linux system with a standard VirtualBox installation:

rm -rf ~/.VirtualBox

On a MAC with a standard VirtualBox installation:

rm -rf ~/Library/VirtualBox

What user should I bootstrap as?

It is best to perform bootstrapping as a normal user. Besides creating the kickstart floppy image on a Linux system, all portions of the bootstrapping should be performed by a standard user. On a Linux system, it is sometimes necessary to have the bootstrapping user be a member of the "vboxusers" group (see the VirtualBox installation guide for more details).