[[PageOutline]]

= Running apps in VirtualBox virtual machines =

== Introduction ==

BOINC supports applications that run in !VirtualBox virtual machines.
This provides two benefits:
 * You don't need to build app versions for different architectures.
   You develop your app in your environment of choice (say, Scientific Linux),
   and then bundle the resulting executable together with
   a virtual machine image containing the appropriate runtime environment.
   The application can then be run on all platforms
   (Windows, Mac OS X, all versions of Linux)
   with no additional work on your part.
 * Virtual machines provide the strongest available security sandbox;
   a program running in a virtual machine cannot access or modify
   the host system.
   This makes it feasible to deploy untrusted applications.

BOINC's support for VM apps is based on a program called
'''vboxwrapper''' that interfaces between
the BOINC client and the !VirtualBox system.

=== Licensing issues ===

Commercial operating systems like Windows and Mac OS X
have a license with a pay-per-use clause,
so in general you can't use them in the VM image.
Similarly, you can't include pay-per-use software such as Matlab
in the VM image.

=== 32/64 bit issues ===

A VM image is called 32- or 64-bit depending on the operating system it contains.
The BOINC host population includes 32-bit and 64-bit hosts.
64-bit hosts can run 32-bit VMs, but not conversely.
You can choose to provide 32- or 64-bit VM images, or both.

Possible reasons for using 64-bit VM images:
 * The 64-bit version of your app runs significantly faster than the 32-bit version.
 * Your app uses more than 3 GB of virtual address space.

If you provide only 32-bit VM images,
you must still create separate 32- and 64-bit app versions,
using the same VM image but different '''vboxwrapper''' executables.
('''vboxwrapper''' is a C++ program and has different executables
for each platform, include 32- and 64-bit; these are available below.
The 32-bit vboxwrapper will generally not work on a 64-bit machine).

=== Non-Intel and GPU applications ===

!VirtualBox runs only on Intel-compatible processors.
If you want to support other processors,
you'll need to use non-VM-based app versions.

Currently you can't run GPU applications in !VirtualBox VMs.
This may change in the future.

== Creating app versions ==

You must create app versions for each platform you want to support;
the app versions differ in which '''vboxwrapper''' executable they use.
If you use both 32- and 64-bit VMs,
the versions will also differ in the VM image and the application executable.

The application versions for a given platform are of plan class "vbox32"
(for 32-bit machines) or "vbox64" (for 64-bit machines),
and include the following files:

 * The VM image, in !VirtualBox format.
  * Must have the '''copy_file''' attribute.
  * Must have logical name "vm_image.vdi".
 * The application executable to be run in the VM image.
  * This may be a shell script or a binary program.
  * The logical name must be '''shared/boinc_app'''.
 * Other files needed by the application, all with logical names starting with '''shared/'''.
 * An XML '''job description file''' with logical name '''vbox_job.xml''' (see below)
 * '''vboxwrapper''', compiled for the platform (executables are available below).
 * All scripts and executables must have the execute permission set.

Include '''<dont_throttle/>''' in the version.xml file; !VirtualBox does its own CPU throttling.

Typically you can use the same VM image for multiple applications.
This reduces network traffic and client disk usage.

=== The job description file ===

The job description file has logical name '''vbox_job.xml'''
(its physical name should include a version number and other info).
It has following structure:

{{{
<vbox_job>
   <os_name>name</os_name>
   <memory_size_mb>N</memory_size_mb>
   [ <enable_network_access/> ]
   [ <enable_shared_directory/> ]
</vbox_job>
}}}
The elements are:

 '''os_name''':: the name of the guest OS as defined by !VirtualBox,
   e.g. "Linux26", "Linux26_64", "Linux24", etc.
   To see a list of all available OS names, install !VirtualBox on a Linux system,
   and type "vboxmanage list ostypes".

 '''memory_size_mb''':: the amount of physical memory allocated to the VM, in megabytes.

 '''enable_network_access''':: if present, allow the VM to do network access.

 '''enabled_shared_directory''':: if present, create a directory that is shared
   between the host OS and the guest OS.
   Must be set if your application has input or output files.

== Requirements of the VM ==

The VM, when booted, must do the following:

 * If the applications has input or output files, mount the shared directory using

{{{
mount -t vboxsf shared /root/shared
}}}
 where "/root/shared" is the path where the shared directory is to be mounted.
 In this case the VM must contain the !VirtualBox "guest additions".
 Guest additions are required for shared folders to work.

 * Run the application.

 * When the application is finished, shut down the VM
  (e.g., by running '''shutdown''' on Linux).

These steps are typically done by a '''startup script''' in the VM image.
An example startup script is given below.
This script runs the application by doing the following:
 * cd into the shared directory
 * execute '''boinc_app''', and wait for it to exit.

Using this script,
your application executable must have logical name '''share/boinc_app'''.

Doing things this way, the VM image is independent of the application.
You can use the a single VM image for many applications.

== Creating jobs for VM apps ==

The input and output files of a VM app must

 * Have logical names starting with '''shared/'''.
 * Have the '''copy_file''' attribute.

This causes the BOINC client to copy them to and from the '''slot/x/shared/''' directory.

== How it works: example ==

Using the example startup script, the steps in running a vboxwrapper app are:

 1. BOINC client
  * Create slot directory, say slot/0
  * Create '''slot/0/shared''', and copy input files there
  * Execute '''vboxwrapper''' in the slot directory
 1. vboxwrapper
  * Create and run virtual machine
 1. Virtual machine
  * Startup script
   * mounts '''shared''' directory
   * cd into shared directory
   * execute boinc_app
   * when boinc_app exits, shut down virtual machine
 1. vboxwrapper
  * delete virtual machine
  * call boinc_finish()
 1. BOINC client
  * copy output files from slot/0/shared to project directory

== Example startup script ==

The example startup script follows.
You can deploy it by appending to '''/root/.bashrc''' in the VM image.
{{{
echo --- BOINC VM starting
sleep 5
}}}

The "sleep 5" gives you time to break into a console session via CTRL-C
if you need to make changes to the VM in the future.

{{{
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_app
if [ -f /root/shared/boinc_app ]; then
    cd /root/shared
    ./boinc_app
    shutdown -hP 0
else
    echo --- Failed to launch script
    sleep 5
fi
shutdown -hP 0
}}}

== Creating VM images ==

The VM image that you distribute need contain only the
runtime environment for your applications.
In particular, it need not contain:

 * Development tools such as gcc
 * GUI software such as X11, gtk etc.

Reducing the VM image size reduces the network load
on your server and on volunteer hosts, and the disk usage on volunteer hosts.

The easiest way to make a "small" 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].
Such VMs have !VirtualBox and guest additions installed by default.

'''NOTE: 32- and 64-bit VM images created in this way,
and containing all the changes described below,
are available (see links below).
If you use these VM images, you can skip the rest of this section.'''

=== 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,
change the default timeout for grub by modifing /etc/default/grub:
{{{
GRUB_TIMEOUT = 0
}}}

After saving the update run:
{{{
update-grub
}}}

=== Updating Inittab ===

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

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
}}}

== Premade vboxwrapper executables ==

Windows:
x86: [http://boinc.berkeley.edu/dl/vboxwrapper_6.20_windows_intelx86.exe.gz vboxwrapper_6.20_windows_intelx86.exe.gz]

x64: [http://boinc.berkeley.edu/dl/vboxwrapper_6.20_windows_x86_64.exe.gz vboxwrapper_6.20_windows_x86_64.exe.gz]

Mac OS X:

Linux:

== Premade Linux VM Images ==

These VM images were built using the above instructions for creating VM images.
They contain Debian 4.0, without GCC or any build tools installed.
They contain the example startup script.

In most cases, you can use these VM images with no modifications.

x86: [http://boinc.berkeley.edu/dl/vmimage_x86.zip vmimage_x86.zip]

x64: [http://boinc.berkeley.edu/dl/vmimage_x64.zip vmimage_x64.zip]