Table of Contents
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.
Usage Scenarios
There are basically two usage scenarios supported by the stock BOINC VboxWrapper:
-
Network-focused VM
-
Task-focused VM
Network-Focused VM
A network- focused VM usually launches its own task agent which downloads work to be processed and eventually shuts down when completed.
Requirements: VboxWrapper, VM job description file, and VM Image.
NOTES: Network communication can be hampered if the host machine is sitting behind a restrictive firewall or proxy server.
Task-Focused VM
A task-focused VM launches a single job downloaded by the BOINC client software and then shuts down.
Requirements: VboxWrapper, VM job description file, and VM Image, startup script, worker application
NOTES: All network communication is disabled for the VM.
Configuring the BOINC Server
Using VirtualBox requires the use of two plan classes:
-
vbox32: Is the application version assigned to 32-bit machines.
-
vbox64: Is the application version assigned to 64-bit machines.
NOTES: The bitness of the VboxWrapper and VM image should match which plan class they are assigned too. A 32-bit wrapper cannot properly detect or use Virtual Box on a 64-bit machine.
A typical installation would look like this:
apps/uppercase/
6.18
windows_intelx86__vbox32
version.xml
...
windows_x86_64__vbox64
version.xml
...
Application Version Record
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>
Configuration options for version.xml can be found here.
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>
Configuration options for VboxWrapper can be found here.
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
NOTES: Make sure the linefeeds conform to the UNIX standard otherwise bash will complain.
Appendix
Premade BOINC VM Wrapper
Windows
x86: vboxwrapper_26202
x64: vboxwrapper_26207
Mac
x64: vboxwrapper_26206
Linux
x64: vboxwrapper_26207
Premade Linux VM Images
x86: vmimage_x86
x64: vmimage_x64
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 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.