Changes between Version 9 and Version 10 of VboxApps

Timestamp:

Sep 29, 2011, 5:14:01 PM (13 years ago)

Author:

davea

Comment:

--

VboxApps

@@ -2 +2 @@
 
 = 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
+
+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.
+
+== 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.
+  If must have a logical name starting with '''shared/'''.
+ * 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.
+  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.
 
-== Job description file ==
-'''vboxwrapper''' takes an input file '''vbox_job.xml''' with the following structure:
+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 which 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:
 
 {{{
@@ -26 +51 @@
 
  '''os_name''':: the name of the guest OS, e.g. "Linux26" or "Linux26_64".
+   WHAT ARE THE OTHER POSSIBILITIES?
 
  '''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.
+ '''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 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(vmbootprocess.png)]]
+
+The VM, when booted, must do the following:
+
+ * If the applications has input or output files, mount the shared directory using
+
+{{{
+mount -t vboxsf share ~/share
+}}}
+ where "~/share" is the path where the shared directory is to be mounted.
+ In this case the VM must contain the VirtualBox "guest additions". EXPLAIN
+
+ * 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.
+
+== 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'''.
+{{{
+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 ~/shared/boinc_app ]; then
+    cd ~/shared
+    bash ./boinc_app
+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 [http://www.debian.org/distrib/netinst 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: [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 ===
+TBD
+=== Linux ===
+TBD
+
+== Premade Linux VM Images ==
+
+SAY SOMETHING ABOUT THESE
+
+x86: [http://boinc.berkeley.edu/dl/vmimagex86.vdi.gz vmimagex86.vdi.gz]
+
+x64: [http://boinc.berkeley.edu/dl/vmimagex64.vdi.gz vmimagex64.vdi.gz]
+