The Generic BOINC Application Client (GBAC) is a virtualization enabled wrapper application. Beyond its name GBAC also represents a generic framework providing virtualized environments for various distributed computing infrastructures (DCIs). GBAC was implemented using the DC-API Meta API and does not rely on any middleware specific functionalities, thus it is possible to use it on any DCIs that are supported by DC-API, currently BOINC, Condor and XtremWeb. In this manual we detail the BOINC related aspects such as (i) deployment, (ii) configuration, (iii) usage and (iv) known limitations and workarounds.
This document will not detail the server side (BOINC project) related requirements, as they are no different than for any other BOINC application. On the client side GBAC has the following requirements:
<WRAP important> Notes for BOINC Client on Windows: GBAC application running under the BOINC Client needs to have access to the VirtualBox command line management interface (VBoxManage command). If the client is installed in a restricted account (Protected application execution option is selected during the client install), then GBAC (or any other application running under BOINC) will not have the required privileges to run the VBoxManage command. There is a workaround, which we detail in Section BOINC Client on Windows: sandboxed and service installation. </WRAP>
The following components are available for download in the downloads section at http://gbac.sourceforge.net
An overview of GBAC can be found at the Components - GBAC page.
In the following sections we detail the components of GBAC.
<WRAP box center>
<WRAP centeralign>The components of GBAC</WRAP>
</WRAP>
The GBAC wrapper is a BOINC application handling the communication with the BOINC client and managing VirtualBox and the data transfer between host and guest. It is based on the VBoxWrapper of BOINC1).
The wrapper first creates a shared directory for file transfers between the host and the virtual machine. It copies all legacy application input files in this directory. GBAC does not separate the binaries of the legacy application and its input files. This means that all legacy application binaries and their input files are normal input files for GBAC and are not part of the GBAC BOINC application. As a next step the virtual machine is started using VirtualBox. GBAC does not contain and does not deploy VirtualBox; it is a prerequisite and every host must have VirtualBox preinstalled before GBAC can be used. Next, the legacy application is executed in the virtual machine by the GBAC guest extensions and the outputs are copied to the shared directory. Once the application finished the GBAC guest extensions shut down the virtual machine. Once the virtual machine terminates GBAC copies the results from the shared directory to the work directory of the BOINC client and terminates itself. The behavior of GBAC is configured via its configuration file, which we detail next.
GBAC requires the configuration file to have the BOINC logical name of vbox_job.xml (see Section Deployment for more details). As its name suggests it uses an XML-like sytax, below is shown an example. All parameters of the file must use the <foo>value</foo> or <bar/> syntax and the file must begin with <vbox_job_desc> and end with </vbox_job_desc>. The following parameters can be used:
VBoxManage list ostypes command. Usually set here Linux26, Debian for 32bit Linux and Linux26_64 or Debian_64 for 64bit Linux installed in the virtual appliance.<vbox_job_desc> <os_name>Linux26</os_name> <memory_size_mb>512</memory_size_mb> <image_filename>gbac-debian-x86.vdi.gz</image_filename> <enable_shared_directory/> <enable_network/> </vbox_job_desc>
Instead of listing legacy application binaries separately as input files they can be bundled in an archive and only the archive needs to be specified. The following rules should be used when creating an application bundle:
<EXECUTABLE NAME> is the filename of the main executable in the bundle and <EXTENSION> is the extension depending on the archiver used, e.g., if the main executable is my_executable and ZIP is used then the bundle must be named my_executable.app.zip.
The essence of GBAC is a virtual appliance which contains an operating system, the VirtualBox guest extensions and the GBAC guest extensions. It is used by VirtualBox to boot a virtual machine which in turn is used to execute legacy applications, see Section Custom virtual appliances for more details on the contents of the VA.
The filesystem of the virtual machine is reseted to its original state for each work unit (it uses the immutable option of VirtualBox). Thus no work unit can do any permanent harm to it. The virtual appliance is part of the GBAC application (and not of the legacy application) and it is downloaded by any client only once.
We provide a Debian Linux 6.0 32bit virtual appliance which is able to execute most applications and also can be used as basis for custom virtual appliances. The console login information for the virtual appliance is the following:
rootabc123. <wrap important>Note: the period at the end is part of the password</wrap>The virtual appliance for GBAC contains several additions and modifications compared to a standard Linux installation:
/etc/init.d/gbac/root/runme.sh/mnt/shared/ which is mounted during boot time.The GBAC guest extensions are responsible for (a) mounting the guest-host shared directory, (b) copying the legacy application files to the sandbox or extracting the legacy application bundle (see Section Legacy application bundle) to the sandbox and ( c) executing the legacy application.
The functionality of GBAC is detailed at the Components - GBAC page.
In the following subsections we detail (i) the required steps to deploy GBAC on the server and (ii) configuration for the clients: we are going to deploy GBAC in a BOINC project, configure a BOINC Client and submit and execute an example GBAC job.
We assume the following:
gbacsample./project/ directory).
In the next sections we describe two methods for deploying GBAC. First (in section Deployment with boinc_appmgr) we show how to do the deployment via the boinc_appmgr tool provided by the SZDG package, and in section Manual deployment we describe how to deploy GBAC manually on the server.
<WRAP important>NOTE: You must download the virtual appliance for the GBAC binary package(s) separately from the virtual_appliance folder on SourceForge (gbac-debian-x86_vdi-rXXXX.gz) and rename it to gbac-debian-x86.vdi.gz or else the installation will fail (Required file 'gbac-debian-x86.vdi.gz' is missing). You don't need to uncompress the .gz, GBAC will uncompress it when started on a client resource.</WRAP>
Easiest way to deploy GBAC is with the boinc_appmgr tool. There are three .xml files present in the GBAC binary bundle as shown in the next listing with the <PLATFORM> part replaced by the current application bundle platform name (e.g., i686-pc-linux-gnu or windows_intelx86):
gbac-<PLATFORM>-client-debug.xml gbac-<PLATFORM>-client.xml gbac-master.xml
These files are passed as parameters (detailed later in this section) for boinc_appmgr, and are for the following:
gbac-<PLATFORM>-client-debug.xml - Deploy the GBAC BOINC application with debugging enabled (see section sec:debug for more details on debugging).gbac-<PLATFORM>-client.xml - Deploy the GBAC BOINC application without debugging enabled.gbac-master.xml - Deploy GBAC server side components, i.e. the validator (sample_trivial_validator).
From these .xml files you need one client file (either gbac-<PLATFORM>-client.xml or gbac-client-debug.xml) and the server file. To deploy GBAC perform the following steps and execute the following commands as the project administrator user:
boinc_appmgr --add --client gbac-<PLATFORM>-client.xml
boinc_appmgr --add --client gbac-<PLATFORM>-client-debug.xml
boinc_appmgr --add --master gbac-master.xml
<WRAP important>NOTE: You must download the virtual appliance for the GBAC binary package(s) separately from the virtual_appliance folder on SourceForge (gbac-debian-x86_vdi-rXXXX.gz) and rename it to gbac-debian-x86.vdi.gz or else the installation will fail (Required file 'gbac-debian-x86.vdi.gz' is missing). You don't need to uncompress the .gz, GBAC will uncompress it when started on a client resource.</WRAP>
In the following we will deploy GBAC for Linux 64bit. GBAC is a BOINC application so the procedure contains no different steps than for any other BOINC application, but still there are some specific requirements which we want to detail here.
project.xml of the project and add the following contents to the contents, right before the closing </boinc>: <app>
<name>gbac</name>
<user_friendly_name>GBAC</user_friendly_name>
</app>
It should look like this afterwards:
[...]
<app>
<name>gbac</name>
<user_friendly_name>GBAC</user_friendly_name>
</app>
</boinc>
gbac/gbac_1.80_x86_64-pc-linux-gnu inside /apps/ for GBAC. The first part (gbac/) is for the application and the second part inside the first one (gbac_1.80_x86_64-pc-linux-gnu) is for the current version (1.80) of the Linux 64 bit application (x86_64-pc-linux-gnu).gbac_1.80_x86_64-pc-linux-gnu gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz.file_ref_info gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info
gbac_1.80_x86_64-pc-linux-gnu.gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz.gbac_1.80_x86_64-pc-linux-gnu-debian60-x86.vdi.gz.file_ref_info with the following contents:<copy_file> <open_name>gbac-debian-x86.vdi.gz</open_name>
gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml with the following contents:<vbox_job_desc> <os_name>Linux26</os_name> <memory_size_mb>512</memory_size_mb> <image_filename>debian60-x86.vdi</image_filename> <enable_shared_directory/> </vbox_job_desc>
gbac_1.80_x86_64-pc-linux-gnu-vbox_job.xml.file_ref_info with the following contents: <copy_file> <open_name>vbox_job.xml</open_name>
xadd and update_versions commands.sample_trivial_validator supplied by BOINC should be used:config.xml and add the following contents to the daemons section of the file:<daemon> <cmd>sample_trivial_validator -d 3 -app gbac</cmd> </daemon>
stop and start commands after each other.
The wsclient utilility of 3G Bridge will be used for task submission in Section sec:usecase., but first 3G Bridge has to be configured for GBAC. We assume that it is already deployed and configured for the BOINC project through the DC-API-Single plug in and only the GBAC related configuration is missing. See the 3g-bridge manual for more information and examples how to deploy 3G Bridge on a BOINC project. The following steps should be performed for GBAC:
/master/3g-bridge/dc-api.conf and add the following contents to the end of the file:[Client-gbac] MaxOutputSize = 210485760 MaxDiskUsage = 2048000000 MaxMemUsage = 768MiB EnableSuspend = false MinQuorum = 1 TargetNResults = 1 MaxErrorResults = 2 MaxTotalResults = 5 MaxSuccessResults = 5 MaxFPOps = 1.0e+16
The options set here are detailed in the DC-API manual3) in section 'Per-client configuration'. The parameter MaxFPOps determines maximum floating-point operations and thus the run time limit for workunits. Increase this (and restart the project) when GBAC is terminated by the BOINC Client because it reached this limit. Same applies for MaxOutputSize, MaxDiskUsage and MaxMemUsage.</p>
cg_algqueue table of 3G Bridge database by executing the following commands as the BOINC project user: mysql boinc_gbacsample
Here gbacsample is the short name of the BOINC project.
insert into cg_algqueue (grid, alg, batchsize, statistics) \
values ('DG', 'gbac', 1, NULL);
Here we assume that the BOINC project (and the DC-API-Single plug in) is configured as DG grid in 3G Bridge.
stop and start commands after each other.GBAC requires the BOINC Client and VirtualBox to be installed on all resources. Installing VirtualBox is a straightforward procedure which we don't detail here. Installing and configuring BOINC for GBAC is also simple, but there are some specific steps required which we detail here.
<WRAP centeralign>BOINC install dialog on Windows</WRAP></WRAP>
<WRAP box center>
<WRAP centeralign>Advanced view mode of the BOINC Manager with Run always option selected in the Activity menu</WRAP>
</WRAP>
<WRAP box center>
<WRAP centeralign>BOINC simple view</WRAP>
</WRAP>
<WRAP box center>
<WRAP centeralign>BOINC advanced view</WRAP>
</WRAP>
In this example the wsclient command line utility will be used to (a) submit a legacy application to BOINC for the GBAC application, (b) monitor the status of the execution and © retrieve outputs once finished. We assume the following:
ws-submitter component of 3G Bridge is configured and running on http://example.com:9001/ . See the 3g-bridge manual for more information and examples how to set up ws-submitter for 3G Bridge./tmp/emmil/ directory.The following steps need to be performed:
FILESDIR=/tmp/emmil/
wsclient -repeat 1 -m add -e http://example.com:9001 \
-g DG -a wu_script.sh -n gbac \
-i JobInputReal.txt=$FILESDIR/JobInputReal.txt \
-i emmil_i686-pc-linux-gnu.app.tar.gz=$FILESDIR/emmil_i686-pc-linux-gnu.app.tar.gz
-o LPSolvOutput.txt
wsclient command will print an UUID for the submitted task:b82ca283-e9c1-49bf-98be-335adc4b4252
wsclientare explained in the wsclient manual page of the wsclient Debian package (man wsclient). wsclient: wsclient -m status -e 'http://example.com:9001' \
-j b82ca283-e9c1-49bf-98be-335adc4b4252
b82ca283-e9c1-49bf-98be-335adc4b4252 Running
wget:wsclient -m output -e 'http://example.com:9001' \
-j b82ca283-e9c1-49bf-98be-335adc4b4252
Output files for job 'b82ca283-e9c1-49bf-98be-335adc4b4252': LPSolvOutput.txt http://example.com/3g-bridge-gbacsample/b8/b82ca283-e9c1-49bf-98be-335adc4b4252/LPSolvOutput.txt
GBAC allows to pass environment variables to the job/ application executed in the VM. For the job a separate environment will be set up and the variables will be exported there. GBAC has a gbac_job.xml configuration file that that serves two purposes:
<MAIN_EXE>.app.tar.gz app bundle format
The format of gbac_job.xml is as follows:
<gbac_job> <setenv>FOO="foo"</setenv> <setenv>BAR="bar"</setenv> <main_executable>emmil_i686-pc-linux-gnu</main_executable> </gbac_job>
<setenv>VARIABLE=“VALUE”</setenv> statements where the VARIABLE with value VALUE will be exported for the application in the VM. <main_executable><MAIN_EXE></main_executable> line defining the main executable (MAIN_EXE) of the application.*.app.tar.gz) can not contain the gbac_job.xml, it must be separate input file for the job.It is possible to create custom virtual appliances for GBAC containing custom operating systems, libraries and 3rd party tools, but the following should be considered:
In the following section we detail the steps for deploying GBAC Guest Tools in the CernVM VA, that is a Scientific Linux (Red Hat) based image.
The following steps needed to deploy GBAC Guest Tools in the CernVM VA:
adduser vmsandbox
usermod -a -G wheel vmsandbox
mkdir -p /mnt/shared
mkdir -p /home/vmsandbox/logs
$>id vmsandbox uid=500(vmsandbox) gid=501(vmsandbox) groups=10(wheel),501(vmsandbox)
The number after uid= is the user id (500 in this case), and the number after gid= is the group id (501 in this case).
shared /mnt/shared vboxsf gid=501,uid=500 0 0
cp /mnt/shared/gbac /etc/init.d/ cp /mnt/shared/guest-tools.sh /home/vmsandbox
chkconfig --add gbac
chkconfig —level 2 gbac off chkconfig —level 3 gbac on
Defaults:vmsandbox !requiretty vmsandbox ALL = (root) NOPASSWD: /sbin/shutdown -h now
GBAC provides several features that ease application and virtual appliance development and debugging. In the following we detail these.
In this section we detail the debug configuration file of GBAC and its parameters. GBAC requires the configuration file to have the BOINC logical name of vbox_debug.xml. As the name suggests it uses an XML-like sytax, The next code block shows an example. All parameters of the file must use the <foo>value</foo> or <bar/> syntax and the file must begin with <vbox_debug> and end with </vbox_debug>.
<vbox_debug> <display_gui/> <log_vboxmanage/> <not_standalone/> </vbox_debug>
The following parameters can be used:
'display_gui': Switch between headless and GUI modes (default: headless): by default the virtual machine is run in the background without any display window. When this parameter is set a window is used as the display of the virtual machine.'log_vboxmanage': Log vboxmanage commands and their results to stderr as well (default: no).'not_standalone': For vm name generation debugging, assume false where standalone mode is checked in the wrapper code.
<WRAP box center>
<WRAP centeralign>GBAC with <display_gui/> set in the debug config file</WRAP>
</WRAP>
The virtual machine started by GBAC will shutdown automatically when the task finished (or if no task can be started). For debugging purposes it is possible to disable this behavior: if a file named no_shutdown is present in the guest-host shared directory the virtual machine will keep running and can be shut down only by hand (either from the console or from the VirtualBox menu).
To run the GBAC VA as a “standalone” virtual machine do the following steps:
shared with Full access to the virtual machine. <wrap important>Make sure that the automount option is not selected!</wrap>no_shutdown into this shared folder.
Place a file named display_gui in the working directory of GBAC before the VM is started to start VirtualBox in windowed mode (same as the display_gui option of vbox_debug.xml).
There are no networking related components (i.e., ifconfig, dhclient) in the default VA. To install additional components via network the following steps must be performed:
shared and put a file named no_shutdown in it. This will make the VM run endlessly (else the guest components would shut down the machine after the - failed - execution of the non existent application). Configure network for the VM in VirtualBox./mnt/shared), this will install all packages: dpkg -i *.deb
dmesg | grep eth
this should print something similar (instead of eth2 can be anything):
[...] e1000: eth0 [...] [...] renamed network interface eth0 to eth2
eth2 the equivalent you saw in the previous query): ifconfig eth2 up
eth2 the equivalent you saw in the previous query) and you should have networking: dhclient eth2
apt-get install … to install additional packages.GBAC provides 3 log files when requested:
gbac-app.stdout), gbac-app.stderr) and gbac-exec.log)
These files should be specified as output files e.g., with wsclient (see code below) and will be automatically generated by GBAC.
<WRAP box center>
wsclient \ [...] -o gbac-app.stdout \ -o gbac-app.stderr \ -o gbac-exec.log
<WRAP centeralign>A GBAC log example with wsclient</WRAP>
</WRAP>
In the following subsections we detail the known limitations of GBAC and the proposed workarounds and resolutions. The limitations are marked with (L) and the resolutions with (R).
(L) The running VirtualBox VM is a separate process that BOINC does not consider its own. This means that if the client has a setting that it should suspend computation if the non-BOINC CPU load goes above a threshold, it will constantly suspend-resume the virtual machine.
(R) Currently the only workaround is to set BOINC to always run in the BOINC Manager. We'll fix this in an upcoming release…
(L) We found that BOINC has sometimes trouble detecting VirtualBox (registry virtualization), thus GBAC is also not able to detect it and will permanently fail.
(R) We are investigating this issue, and still don't have any workaround for it.
(L) On Windows if the BOINC Client is installed and run under a restricted account (when installed with Protected application execution option) it won't have privileges to start a virtual machine via VirtualBox.
(R) To fix this the following modifications have to be done (as administrator):
boinc_admin (or boinc_master) and boinc_project.boinc_project account needs to have full control on the following two directories (adjust path if not installed on the C drive or in the default location):C:\Program Files\Oracle\VirtualBox\C:\WINDOWS\system32\config\systemprofile\.VirtualBox\ – If this directory does not exist, create it and grant the privileges.boinc_project account also needs to have Launch and Activation, Access and Configuration Permissions on the VirtualBox DCOM service.(L) Currently it is not possible to cache the legacy binaries on clients and hence they will be downloaded for each time for every work unit.
(R) We are aware of this problem and working on it for a near future release.
(L) Only generic validators (e.g., sample trivial validator) can be used with GBAC.
(R) GBAC is a generic framework for executing legacy applications, thus it is not possible to use application specific validators.
Please report bugs and provide feedback via email to desktopgrid AT lpds DOT sztaki DOT hu.
