= Deploying VM Applications =

== Introduction ==
Using virtual machine technology with the BOINC client presents an interesting challenge to projects.  Projects not only have to follow the rules BOINC requires projects to follow but they also have to follow the rules that the virtual machine technology requires as well.  With this document we hope to provide a general outline of how to utilize the VirtualBox virtual machine technology within a BOINC based project.

For the purposes of this document we are going to assume that a task instance only requires the use of a single CPU and no network communication is required during the execution of the task instance.


=== Configuring  Application Version ===
Version.xml:
{{{
<version>
   <file>
      <physical_name>vboxwrapper_6.20_windows_x86_64.exe</physical_name>
      <copy_file/>
      <main_program/>
   </file>
   <file>
      <physical_name>vmimagex64_6_18.vdi</physical_name>
      <logical_name>vm_image.vdi</logical_name>
      <copy_file/>
      <gzip/>
   </file>
   <file>
      <physical_name>vbox_job_6_18_windows_x86_64.xml</physical_name>
      <logical_name>vbox_job.xml</logical_name>
      <copy_file/>
   </file>
   <file>
      <physical_name>boinc_start_6_18_windows_x86_64.sh</physical_name>
      <logical_name>shared/boinc_start.sh</logical_name>
      <copy_file/>
   </file>
   <file>
      <physical_name>uppercase_6.18_i686-pc-linux-gnu</physical_name>
      <logical_name>shared/uppercase_6.18_i686-pc-linux-gnu</logical_name>
      <copy_file/>
   </file>
   <dont_throttle/>
   <file_prefix>shared</file_prefix>
</version>
}}}

=== Configuring Virtual Machine Description ===
vbox_job.xml:
{{{
<vbox_job>
    <os_name>Linux26_64</os_name>
    <memory_size_mb>256</memory_size_mb>
    <enable_shared_directory/>
</vbox_job>
}}}

=== Configuring Startup Script ===
boinc_start.sh:
{{{
#
# Automatically executed by the vmimagex64 at startup.
#
./uppercase_6.18_i686-pc-linux-gnu

#
# Shutdown when complete
#
shutdown -hP 0
}}}

== Appendix ==

=== Premade BOINC VM Wrapper ===

Configuration Options for vboxwrapper can be found [VboxApps here].

==== Windows ====

==== Linux ====


=== Premade Linux Images ===

x86: [http://boinc.berkeley.edu/dl/vmimagex86.vdi.gz vmimagex86.vdi.gz]

x64: [http://boinc.berkeley.edu/dl/vmimagex64.vdi.gz vmimagex64.vdi.gz]

=== Hand-build VM Image ===

The easiest way to begin putting together a Linux VM is to install the network install of Debian within the VM.  You can find the netinst images [http://www.debian.org/distrib/netinst here].

Main advantages:
 * Small install size
 * VirtualBox guest additions installed by default

The VirtualBox guest extensions are required in order to use the shared directory feature to communicate between the guest and host operating systems.

==== Role Selection ====

During install you'll be asked what role should this Linux machine be configured for, make sure all roles are unselected before continuing.

==== Updating Grub ====

If you want to speed up the boot process you should change the default timeout for grub by modifing /etc/default/grub:
{{{
GRUB_TIMEOUT = 0
}}}

After saving the update run:
{{{
root@boinc-vm-image:/etc/default# update-grub
}}}

==== Updating Inittab ====

To configure Linux for automatic login you'll need to install a different terminal handler, mingetty seems to work pretty well for our purposes.

You'll need to install mingetty:
{{{
root@boinc-vm-image:/etc/default# apt-get install mingetty
}}}

Next you'll need to change the terminal handler assigned to the first virtual terminal, change line:
{{{
1:2345:respawn:/sbin/getty 38400 tty1
}}}

To:
{{{
1:2345:respawn:/sbin/mingetty --autologin root --noclear tty1
}}}

==== Updating .bashrc ====

Adding the following to the end of the .bashrc file for root:
{{{
# BOINC VM Initialization
echo BOINC VM Initialization [Sleeping 10 seconds]
sleep 5
}}}

The basic gist here is to give you time to break into a console session via CTRL-C to be able to make changes to the VM in the future.  After executing any job you want the VM to accomplish you'll need to shutdown the VM.  If you encounter an error shutdown the VM so that BOINC can error out the task instance and report the failure.

==== Shared Directory Usage ====

Adding the following to the end of the .bashrc file for root:
{{{
echo -- Mounting shared directory
mount -t vboxsf shared /root/shared
if [ $? -ne 0 ]; then
    echo ---- Failed to mount shared directory
    sleep 5
    shutdown -hP 0
fi

echo -- Launching boinc_start.sh script
if [ -f ~/shared/boinc_start.sh ]; then
    cd ~/shared
    bash ./boinc_start.sh
else
    echo ---- Failed to launch script
    sleep 5
    shutdown -hP 0
fi
}}}

Be sure to create a directory called 'shared' in root's home directory.

The 'boinc_start.sh' script should contain whatever is needed to execute your job from within the VM.