= Running apps in VirtualBox virtual machines =

BOINC's '''vboxwrapper''' program lets you run applications in virtual machines.
This eliminates the need to build app versions for different architectures,
and provides a stronger security sandbox than is otherwise available.

To do this, create an application version of plan class "vbox" containing the following files:

 * The VM image (VirtualBox format).
   Must have the '''copy_file''' attribute.
 * An XML job description file (see below)
 * '''vboxwrapper''', compiled for the platform

== Job description file ==

'''vboxwrapper''' takes an input file '''vbox_job.xml''' with the following structure:

{{{
<vbox_job_desc>
   <os_name>name</os_name>
   <memory_size>N</memory_size>
   <image_filename>name</image_filename>
   [ <enable_network_access/> ]
   [ <enable_shared_directory/> ]
</vbox_job_desc>
}}}

The elements are:

 '''os_name''':: the name of the guest OS, e.g. "Ubuntu" or "Linux 2.6".
   Rom: please check what the choices are, and whether this matters.

 '''memory_size''':: the amount of physical memory allocated to the VM.
 
 '''image_filename''':: the physical name of the VM image file.

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

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

== Input and output files ==

All input and output files

 * Must have logical names of the form '''shared/filename'''.
 * Must have the '''copy_file''' attribute.

== Requirements of the VM ==

The VM image, when booted, must run the application.
This is typically done using a script in /etc.

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

If the applications has input or output files,
the VM must contain the VirtualBox "guest additions",
and it must map the shared directory using

{{{
vboxmap shared path
}}}
where "path" is the path where the shared directory is to be mounted.
Typically it will then cd into that directory
to run the application.