[[PageOutline]]

= 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. Must have logical name "vm_image.vdi".
 * An XML job description file (see below)
 * '''vboxwrapper''', compiled for the platform

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

== Job description file ==
'''vboxwrapper''' takes an input file '''vbox_job.xml''' with the 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, e.g. "Linux26" or "Linux26_64".

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

 '''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.

== 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 mount the shared directory using

{{{
mount -t vboxsf share ~/host
}}}
where "~/host" is the path where the shared directory is to be mounted. Typically it will then cd into that directory to run the application.

[[Image(vmprocess.png)]]