4 | | 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. |
5 | | |
6 | | To do this, create an application version of plan class "vbox" containing the following files: |
7 | | |
8 | | * The VM image (VirtualBox format). Must have the '''copy_file''' attribute. Must have logical name "vm_image.vdi". |
9 | | * An XML job description file (see below) |
10 | | * '''vboxwrapper''', compiled for the platform |
| 4 | |
| 5 | BOINC's '''vboxwrapper''' program lets you run applications in VirtualBox virtual machines. |
| 6 | This eliminates the need to build app versions for different architectures, |
| 7 | and provides a stronger security sandbox than is otherwise available. |
| 8 | |
| 9 | == Creating app versions == |
| 10 | |
| 11 | You must create app versions for each platform you want to support; |
| 12 | the app versions differ only in one file. |
| 13 | |
| 14 | The application versions for a given platform are of plan class "vbox32" |
| 15 | (for 32-bit machines) or "vbox64" (for 64-bit machines), |
| 16 | and include the following files: |
| 17 | |
| 18 | * The VM image, in VirtualBox format. |
| 19 | * Must have the '''copy_file''' attribute. |
| 20 | * Must have logical name "vm_image.vdi". |
| 21 | * The application executable to be run in the VM image. |
| 22 | If must have a logical name starting with '''shared/'''. |
| 23 | * Other files needed by the application, all with logical names starting with '''shared/'''. |
| 24 | * An XML job description file with logical name '''vbox_job.xml''' (see below) |
| 25 | * '''vboxwrapper''', compiled for the platform. |
| 26 | These executables can be downloaded from the BOINC site (see below). |
36 | | The VM image, when booted, must run the application. This is typically done using a script in /etc. |
37 | | |
38 | | When the application is finished, it must shut down the VM (e.g., by running '''shutdown''' on Linux). |
39 | | |
40 | | If the applications has input or output files, the VM must contain the VirtualBox "guest additions", and it must mount the shared directory using |
41 | | |
42 | | {{{ |
43 | | mount -t vboxsf share ~/host |
44 | | }}} |
45 | | 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. |
46 | | |
47 | | [[Image(vmbootprocess.png)]] |
| 64 | |
| 65 | The VM, when booted, must do the following: |
| 66 | |
| 67 | * If the applications has input or output files, mount the shared directory using |
| 68 | |
| 69 | {{{ |
| 70 | mount -t vboxsf share ~/share |
| 71 | }}} |
| 72 | where "~/share" is the path where the shared directory is to be mounted. |
| 73 | In this case the VM must contain the VirtualBox "guest additions". EXPLAIN |
| 74 | |
| 75 | * Run the application. |
| 76 | |
| 77 | * When the application is finished, shut down the VM |
| 78 | (e.g., by running '''shutdown''' on Linux). |
| 79 | |
| 80 | These steps are typically done by a '''startup script''' in the VM image. |
| 81 | An example startup script is given below. |
| 82 | This script runs the application by doing the following: |
| 83 | * cd into the shared directory |
| 84 | * execute '''boinc_app''', and wait for it to exit. |
| 85 | |
| 86 | Using this script, |
| 87 | your application executable must have logical name '''share/boinc_app'''. |
| 88 | It may be a compiled program or a script that runs other programs. |
| 89 | |
| 90 | == Creating jobs for VM apps == |
| 91 | |
| 92 | The input and output files of a VM app must |
| 93 | |
| 94 | * Have logical names starting with '''shared/'''. |
| 95 | * Have the '''copy_file''' attribute |
| 96 | |
| 97 | This causes the BOINC client to copy them to and from the '''slot/x/shared/''' directory. |
| 98 | |
| 99 | == How it works: example == |
| 100 | |
| 101 | Using the example startup script, the steps in running a vboxwrapper app are: |
| 102 | |
| 103 | 1. BOINC client |
| 104 | * Create slot directory, say slot/0 |
| 105 | * Create '''slot/0/shared''', and copy input files there |
| 106 | * Execute '''vboxwrapper''' in the slot directory |
| 107 | 1. vboxwrapper |
| 108 | * Create and run virtual machine |
| 109 | 1. Virtual machine |
| 110 | * Startup script |
| 111 | * mounts '''shared''' directory |
| 112 | * cd into shared directory |
| 113 | * execute boinc_app |
| 114 | * when boinc_app exits, shut down virtual machine |
| 115 | 1. vboxwrapper |
| 116 | * delete virtual machine |
| 117 | * call boinc_finish() |
| 118 | 1. BOINC client |
| 119 | * copy output files from slot/0/shared to project directory |
| 120 | |
| 121 | == Example startup script == |
| 122 | |
| 123 | The example startup script follows. |
| 124 | You can deploy it by appending to '''~root/.bashrc'''. |
| 125 | {{{ |
| 126 | echo --- BOINC VM starting |
| 127 | sleep 5 |
| 128 | }}} |
| 129 | |
| 130 | The "sleep 5" gives you time to break into a console session via CTRL-C |
| 131 | if you need to make changes to the VM in the future. |
| 132 | |
| 133 | {{{ |
| 134 | echo --- Mounting shared directory |
| 135 | mount -t vboxsf shared /root/shared |
| 136 | if [ $? -ne 0 ]; then |
| 137 | echo --- Failed to mount shared directory |
| 138 | sleep 5 |
| 139 | shutdown -hP 0 |
| 140 | fi |
| 141 | |
| 142 | echo -- Launching boinc_app |
| 143 | if [ -f ~/shared/boinc_app ]; then |
| 144 | cd ~/shared |
| 145 | bash ./boinc_app |
| 146 | else |
| 147 | echo --- Failed to launch script |
| 148 | sleep 5 |
| 149 | fi |
| 150 | shutdown -hP 0 |
| 151 | }}} |
| 152 | |
| 153 | == Creating VM images == |
| 154 | |
| 155 | The easiest way to make a Linux VM is to install the network install of Debian within the VM. |
| 156 | You can find the netinst images [http://www.debian.org/distrib/netinst here]. |
| 157 | |
| 158 | Advantages: |
| 159 | * Small install size |
| 160 | * !VirtualBox guest additions installed by default |
| 161 | |
| 162 | === Role Selection === |
| 163 | |
| 164 | During install you'll be asked what role should this Linux machine be configured for. |
| 165 | Make sure all roles are unselected before continuing. |
| 166 | |
| 167 | === Updating Grub === |
| 168 | |
| 169 | If you want to speed up the boot process, |
| 170 | change the default timeout for grub by modifing /etc/default/grub: |
| 171 | {{{ |
| 172 | GRUB_TIMEOUT = 0 |
| 173 | }}} |
| 174 | |
| 175 | After saving the update run: |
| 176 | {{{ |
| 177 | update-grub |
| 178 | }}} |
| 179 | |
| 180 | === Updating Inittab === |
| 181 | |
| 182 | To configure Linux for automatic login you'll need to install |
| 183 | a different terminal handler. |
| 184 | mingetty works well for our purposes. |
| 185 | |
| 186 | To install mingetty: |
| 187 | {{{ |
| 188 | root@boinc-vm-image:/etc/default# apt-get install mingetty |
| 189 | }}} |
| 190 | |
| 191 | Next you'll need to change the terminal handler assigned to the first virtual terminal. |
| 192 | Change line: |
| 193 | {{{ |
| 194 | 1:2345:respawn:/sbin/getty 38400 tty1 |
| 195 | }}} |
| 196 | |
| 197 | To: |
| 198 | {{{ |
| 199 | 1:2345:respawn:/sbin/mingetty --autologin root --noclear tty1 |
| 200 | }}} |
| 201 | |
| 202 | == Precompiled vboxwrapper == |
| 203 | === Windows === |
| 204 | x86: [http://boinc.berkeley.edu/dl/vboxwrapper_6.20_windows_intelx86.exe.gz vboxwrapper_6.20_windows_intelx86.exe.gz] |
| 205 | |
| 206 | x64: [http://boinc.berkeley.edu/dl/vboxwrapper_6.20_windows_x86_64.exe.gz vboxwrapper_6.20_windows_x86_64.exe.gz] |
| 207 | |
| 208 | === Mac === |
| 209 | TBD |
| 210 | === Linux === |
| 211 | TBD |
| 212 | |
| 213 | == Premade Linux VM Images == |
| 214 | |
| 215 | SAY SOMETHING ABOUT THESE |
| 216 | |
| 217 | x86: [http://boinc.berkeley.edu/dl/vmimagex86.vdi.gz vmimagex86.vdi.gz] |
| 218 | |
| 219 | x64: [http://boinc.berkeley.edu/dl/vmimagex64.vdi.gz vmimagex64.vdi.gz] |
| 220 | |