Running apps in VirtualBox virtual machines

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

NOTE: Do not use software which uses a license that has a pay-per-use clause.

Creating app versions

You must create app versions for each platform you want to support; the app versions differ only in one file.

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. 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.
• All scripts and executables must have the execute permission set. These executables can be downloaded from the BOINC site (see below).

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 bitness of the vboxwrapper and VM image must match the plan class. A 32-bit wrapper cannot use VirtualBox on a 64-bit machine.

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 available os_names, type "vboxmanage list ostypes" at a shell prompt

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 or any special features of the virtualized hardware.

• 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. It may be a compiled program or a script that runs other programs.

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
2. vboxwrapper
   • Create and run virtual machine
3. Virtual machine
   • Startup script
     • mounts shared directory
     • cd into shared directory
     • execute boinc_app
     • when boinc_app exits, shut down virtual machine
4. vboxwrapper
   • delete virtual machine
   • call boinc_finish()
5. 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.

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 easiest way to make a Linux VM is to install the network install of Debian within the VM. You can find the netinst images ​here.

Advantages:

• Small install size
• VirtualBox guest additions installed by default

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

Precompiled vboxwrapper

Windows

x86: vboxwrapper_6.20_windows_intelx86.exe.gz

x64: vboxwrapper_6.20_windows_x86_64.exe.gz

Mac

TBD

Linux

TBD

Premade Linux VM Images

These VM images were built using the instructions for creating vm images and the example startup script.

x86: vmimagex86.vdi.gz

x64: vmimagex64.vdi.gz