Intro

The idea behind this project is to use virtual machines with boinc clients. Virtual Machines lets you use your software with a pre-built setup. We will use a Virtual Machine to run scientific software.

One of the problems that you could have with scientific software is that only works in one platform, for example GNU/Linux. The other problem that you could face is the dependencies that you have to satisfy for running that software. These problems could be very difficult to solve it if your environment work have different platforms and versions of the Operating Systems. If you want to avoid these problems you could try to use a Virtual Machine (VM). The VM lets you to setup the platform that you want (GNU/Linux, BSD, Windows, ...) and install there the libraries and dependencies that are necessary. After that you will only need to use the VM in any platform you want, because you will have a controlled environment that could work as you have decide.

We can afford that approach with the well known Boinc technology.

Requirements

To run this infrastructure you will need to setup a BoincServer and add some work. Obviously we will need to use a Virtual Machine. In our case we run some different tests and we decided to use VMware Player, a free VM. As you can see in this link VMware is the application that has a better performance.

So we will need the next software:

• Boinc Server
• Virtual Machine (VMware)
• Boinc Wrapper for running the VMware

Boinc Server

You can find a howto in the next link: BoincServer.

Virtual Machine (VMware)

We will use these VM in two platforms: MS Windows and GNU/Linux. So you have to download this application and install it in all the clients that will use it. Note that you will need in both cases a root access to install it. You can download the software from here.

Now you will need an image for that VM. We are going to use a GNU/Linux image. The people of VMware provides some prebuilt images with different distributions in this web page. You can download the OS system that you want from there, or if you prefer you can purchase the VMware software and use it for creating new images.

You can try to build an image with Qemu, but we haven't tried it.

Once you have installed your VMware software in one client for debugging you can go to the next step.

Boinc Wrapper for running the VMware

Now that you have the server installed and you have some clients to test, we have to build some applications that executes the VM. We are going to use a little program called "Wrapper" that lets you run legacy applications. This software is provided by the Boinc team, so you will only need to download the boinc_samples folder from their CVS.

Building the Wrapper

In GNU/Linux

You will only need to download the boinc_samples in the same father folder for the Boinc server. So if you have all your software source in /usr/local/src/ you will need to follow these steps:

cvs -d :pserver:anonymous:@alien.ssl.berkeley.edu:/home/cvs/cvsroot checkout boinc_samples
cd boinc_samples

You will download all the example applications that they have developed. You will only need the wrapper software, but it will be interesting to build the other examples and try to run some tests to understand perfectly well how all works.

As you can see, you will have a folder called win_build. In that folder you will find all the solution projects that MS Visual Studio 2003 needs for build it.

Compile the code

First of all you have to be sure that you have installed the boinc libraries. Now you will only need to access the folder of the wrapper source code, and run the instructions that you will find in the README file if exists or in the Make file.

cd /usr/local/src/boinc_samples/wrapper
ln -s `g++ -print-file-name=libstdc++.a`
make

After this you will a have a binary for the GNU/Linux platform. From this point you will be able to run this binary in all the GNU/Linux that have the same libc6, so if you are building the software in a very new GNU/Linux distribution you have to consider this as a little problem. The solution is to use and old version of GNU/Linux and an old gcc.

In MS Windows

For building the applications you will need all the boinc source code and the MS Visual Studio 2003. You will need a CVS client version for Windows, for example Tortoise CVS. Once you have installed a CVS client you will be ready to download all the code.

As in the GNU/Linux case you will need to have the boinc and boinc_samples folder in the same father folder. In each folder you will have a folder called win_build. In that folder you will have all the solution files that MS Visual Studio 2003 will need. There are a solution for build all the necessary Boinc libraries and all the the Boinc samples. Obviously you don't have to build each examples, but as before it will be useful if you build it for testing purposes.

Building the libraries

You will need to download another libraries for building the Boinc libraries. That libraries are necessary for building the graphical client. You can download the libraries from here.

These steps are necessary because the wrapper will need a recent version of the client. Once you have download and unpack it you have to build it. As with the Boinc code, you will have to open the file wx.dsw in the folder build\msw. You have all the explanations here. After that you will be able to build the Boinc libraries.

Now you have to open the file boinc_2003.sln from the win_build folder and build it. After that you will have all the code compiled and now you can follow with the boinc_samples.

Building the boinc_samples

As before you will have a folder called win_build. There you will have a solution file for each application, and one that could compile all of them. I recommend to compile all of them, so you have to open samples_2003.sln and build it. Now you will be able to run the applications with the boinc client.

How works the wrapper

The wrapper is an application that lets you execute in a Boinc client legacy applications. In our case it will be the VMware player. For testing purposes they give you a legacy application. In the boinc_samples folder you will have an application called worker. That application has to be compiled, but it doesn't use any Boinc library. The worker only opens a file called in reads it and writes it to a file called out plus a "Done!" string. You can build that example in Windows and in GNU/Linux.

The legacy applications should be downloaded with the Boinc client, but in our case we couldn't do that with the VMware binary, because it has a lot of dependencies. So we will need to write an script or a binary that will execute the wrapper for running the VMware Player.

The wrapper will need a file called job.xml. This file specifies which is the legacy application that have to be started, and which are the input , output files and the command line arguments. The structure of that file is this:

<job_desc>
    <task>
        <application>worker_5.10_windows_intelx86.exe</application>
        <stdin_filename>stdin</stdin_filename>
        <stdout_filename>stdout</stdout_filename>
        <command_line>10</command_line>
    </task>
</job_desc>

Here you have to write the exact name of the Legacy application file. If the application uses an input file you have to write here the name of it. If the application will create an output file you have to write here the name of it. ==If the application will need some arguments that are passed via command line you have to write it here.

Once you have the binary of the wrapper, the legacy application and this file, you will have to move it to the folder of the application in the Boinc Project, for example: /opt/BoincProjects/vmathome/apps/wrapper/wrapper_1.0_i686-linux-pc-gnu/. The job.xml must use the next name: job.xml\=job_0.xml. The 0 is the version. Probably you will need to use a different version number if you are going to use two or more platforms. The reason is that if you write the same name of the file in each platform the last one will overwrite the before platforms job.xml. If the file is equal in all the platforms you will not need to take care of this.

After that you will only need to run the command bin/xadd and bin/update_versions for adding the applications to the database. If you have some doubts you should follow the BoincServer howto.

Another important thing is to be sure that all the permissions are well defined for the binaries. If they are executable they must be executable. Once you have run the commands you will have a copy of the files in the download project folder. You, at least, will have the wrapper binary, the legacy application and the job_n.xml file for each platform.

Work Units

Now its time for adding the work units. You have an official explanation in this link. A work unit is a template where you define which are the files that your Boinc application will need and which are the results that have to be uploaded after the work has been done. You will have two small examples in your project folder under templates. In that folder you will find two files: uc_result (for the result files that will be generated) and uc_wu (for the input files that will be needed by the Boinc application).

uc_wu

Here you define the all the files that must be downloaded because the application will needed them. All the files that will be needed must be declared here, and after that copy it to the download project folder. The template has the next items:

<file_info>
    <number>0</number>
    [ <sticky/>, other attributes]
</file_info>
[ ... ]
<workunit>
    <file_ref>
        <file_number>0</file_number>
        <open_name>NAME</open_name>
        <copy_file/>
    </file_ref>
    [ ... ]
    [ <command_line>-flags xyz</command_line> ]
    [ <rsc_fpops_est>x</rsc_fpops_est> ]
    [ <rsc_fpops_bound>x</rsc_fpops_bound> ]
    [ <rsc_memory_bound>x</rsc_memory_bound> ]
    [ <rsc_disk_bound>x</rsc_disk_bound> ]
    [ <delay_bound>x</delay_bound> ]
    [ <min_quorum>x</min_quorum> ]
    [ <target_nresults>x</target_nresults> ]
    [ <max_error_results>x</max_error_results> ]
    [ <max_total_results>x</max_total_results> ]
    [ <max_success_results>x</max_success_results> ]
</workunit>

is used to enumerate the files. If your application will need 20 files you will have 20 instances starting in zero with that this tag. is used to define the work unit. Here you name the file_info files, I mean we add the logical names of that 20 instances. After that you will setup the work unit with some parameters. is used to name the instances that you have declared before in file_info. The name is fixed with the tags . An important option that this tag has is . You will use it when the file is used by a legacy application.

As we are building the work unit for the VMware application, we have to copy all the image files in the download project folder. After that you will have to know how many files are and the names of them. Here you have an example for the Debian image:

<file_info>
    <number>0</number>
</file_info>
<file_info>
    <number>1</number>
</file_info>
<file_info>
    <number>2</number>
</file_info>
<file_info>
    <number>3</number>
</file_info>
<file_info>
    <number>4</number>
</file_info>
<file_info>
    <number>5</number>
</file_info>
<file_info>
    <number>6</number>
</file_info>
<file_info>
    <number>7</number>
</file_info>
<workunit>
    <file_ref>
        <file_number>0</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6.nvram</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>1</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6-s001.vmdk</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>2</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6-s002.vmdk</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>3</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6-s003.vmdk</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>4</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6.vmdk</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>5</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6.vmsd</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>6</file_number>
        <open_name>debian-31r0a-i386-netinst-kernel2.6.vmx</open_name>
        <copy_file/>
    </file_ref>
    <file_ref>
        <file_number>7</file_number>
        <open_name>image</open_name>
        <copy_file/>
    </file_ref>
    <rsc_disk_bound>1000000000.000000</rsc_disk_bound>
</workunit>

We have added an option for the work unit. for assure that we will not have problems with the disk space in the client. You can avoid that option if you want.

NOTE: you must know how much space will need your VM, because if your image grows the Boinc client will abort the execution. So it's very important to know moreless how much space will use your VM image.

uc_result

This template is used for uploading the files that your Boinc application has created. The template will be like this:

<file_info>
    <name><OUTFILE_0/></name>
    <generated_locally/>
    <upload_when_present/>
    <max_nbytes>32768</max_nbytes>
    <url><UPLOAD_URL/></url>
</file_info>
<result>
    <file_ref>
        <file_name><OUTFILE_0/></file_name>
        <open_name>result</open_name>
    </file_ref>
</result>

as before is used to declare the files that will be upload. as before is used for naming the files. is used to specify that this file is used by a legacy application.

This result template should be modified for you needings.

Adding the work unit

Now you will need to run a command for adding the work unit to the database. After that you will be able to start the server and run the tests. The command is:

bin/create_work -appname wrapper -wu_name HHH -wu_template templates/uc_wu -result_template templates/uc_result debian-31r0a-i386-netinst-kernel2.6.nvram debian-31r0a-i386-netinst-kernel2.6-s001.vmdk debian-31r0a-i386-netinst-kernel2.6-s002.vmdk debian-31r0a-i386-netinst-kernel2.6-s003.vmdk debian-31r0a-i386-netinst-kernel2.6.vmdk debian-31r0a-i386-netinst-kernel2.6.vmsd debian-31r0a-i386-netinst-kernel2.6.vmx

-appname the name of the Boinc application. -wu_name the name of the work unit. You can write what you want. -wu_template the work unit template. -result_template the result template.

After that you have to add the files in the order that you had written in the wu_template

That's all. Now you can run the server.

Special Notes

The wrapper has two issues:

• GNU/Linux version doesn't finish in the right way
• Windows version cannot execute bat files, you get an error in the client

GNU/Linux

I have encounter a problem with this version. When your legacy application ends its execution the wrapper needs to know that, and exit calling a method: boinc_finish(0). The client says that your application has finished with a zero, but it doesn't find the file boinc_finished_called. I have try to fix it in the original code, but I couldn't. The solution was to build a new sub-wrapper called starter. The original wrapper will start the starter sub-wrapper and this one the legacy application. It does moreless the same work but with this new application we can get the results uploaded.

The sub-wrapper only executes a program called worker. You can change that in the source code if you want.

You can download the code from here

For running the VMware Player I have created a script called worker. The code is quite simple:

#!/bin/bash

cd ../../projects/pcedg008.cern.ch_vmware/
vmplayer debian-31r0a-i386-netinst-kernel2.6.vmx

The *.vmx file is the name of the image. You must check that the executable permissions are enabled. This file must be in the application folder.

Windows

The original wrapper has a problem running bat files. When you try that you get an error in the client. The solution I have adopted was to build a new sub-wrapper called starter.d.exe. The original wrapper will call the sub-wrapper and this one what you want. We need this because the legacy application could not be run alone in our boin client. The sub-wrapper starts the legacy application that we want, in our case the VMware Player.

You can found the code here.

The sub-wrapper is made for running only the VMware Player, but it's very easy to modify it for your needs.

This application needs a file called image where you define which is the image that the VMware Player has to start with. This file must be placed in the download project folder and added in the work unit template.

Windows Client

I have created a Windows Client and we want to test in all Windows PC that want to join this project. You can download the client from here.

The server url is: http://pcedg008.cern.ch/vmware/

Thanks to all, and thanks for join the community.

LHC@VMware

If you want to try a real application you can join this project: LHC@VMware. The server url is: http://pcedg008.cern.ch/lhcatvmware/.

This project will use one VMware image for running the lhc@home project. This project is more or less the same as the VMware project but with some scientific software inside. For starting the lhc@home project I have created a script called start-boinc.sh that could be downloaded here. The idea behind this script is to unpack the boinc client and after that run it.

-- Daniel Lombraña González - 19 Dec 2006

• starter.tar.bz2: GNU/Linux sub-wrapper

• starter.d.tar.bz2: Windows sub-wrapper

• boinc-client.zip: Boinc Client for Windows

• start-boinc.sh: Script for starting the boinc client inside VMware images