This page is about deploying a wrapper application with BOINC on Debian or Ubuntu. It extends the page BOINC/ServerGuide/AppDeployment.

1. Wrapper Application

BOINC provides a wrapper app to use normal binaries in a BOINC environment. Its source code ships with the regular BOINC tree. In Debian, it is provided by the boinc-app-examples package.

In short, the wrapper system works like this:

1.1. Deployment

Upstream is currently in a transition to a new arrangement for multifile projects, see http://boinc.berkeley.edu/trac/wiki/AppVersionNew. With the latest stable version of BOINC, the fairly recent 6.12.33 that is in Debian testing, the here described procedure is still the way to go.

The wrapper deployment is explained here as a selection of templates. Select the one closest to your requirements. The documents here are a follow up from BOINC/ServerGuide/AppDeployment. It assumes you to be already familiar with the there described deployment of BOINC-savvy applications.

1.1.1. Obtain the binaries

Use the fetch_example_applications script provided with the boinc-server-maker package to obtain the binaries for the wrapper applications, copy them to the app folder of the project root. Since this is a multifile project, the directory hierarchies are important. The binaries should be arranged as shown in the following structure.

In multifile applications, the files are put in a sub-directory of name appname_version_fullplatformname.

You are invited to use the script provided by the boinc-server-maker package

/usr/share/doc/boinc-server-maker/examples/fetch_example_applications.sh

which when executed directly will create a folder as follows:

apps/
`-- wrapper
    |-- wrapper_6.12_i686-pc-linux-gnu
    |   |-- wrapper_6.12_i686-pc-linux-gnu
    |   `-- wrapper_6.12_i686-pc-linux-gnu.sig
    |-- wrapper_6.12_ia64-linux-gnu
    |   |-- wrapper_6.12_ia64-linux-gnu
    |   `-- wrapper_6.12_ia64-linux-gnu.sig
    |-- wrapper_6.12_mips-linux-gnu
    |   |-- wrapper_6.12_mips-linux-gnu
    |   `-- wrapper_6.12_mips-linux-gnu.sig
    `-- wrapper_6.12_x86-64-pc-linux-gnu
        |-- wrapper_6.12_x86_64-pc-linux-gnu
        `-- wrapper_6.12_x86_64-pc-linux-gnu.sig

1.1.2. Configuring the wrapper

The wrapper binary upon invocation checks for a job description file named job.xml, which is used to inform the wrapper about the actual binary to execute and its command line arguments to pass. This file has to be present in the same directory where wrapper binary is, i.e. for single file projects in the $installroot/$fileprojectname/apps/appname/ or for multi-arch ones at $installroot/$fileprojectname/apps/appname/appname_ver_platform/

Here the basic skeleton of a job.xml file. We'll amend it throughout these instructions to suit our varying demands.

<job_desc>
    <task>
        <application>binary_name_to_call</application>
        <command_line>arguments_to_pass</command_line>
        <stdin_filename>stdin_file</stdin_filename>
        <stdout_filename>stdout_file</stdout_filename>
        <stderr_filename>stderr_file</stderr_filename> 
    </task>
</job_desc>

1.2. Walk through: simple script with no input

The example script used in this section counts from 0 to a number specified as command line argument, and outputs as out:

cat <<EOSCRIPT > count 
#!/bin/bash
seq $1 > out
EOSCRIPT

The script will be executed directly, so it better becomes executable:

chmod +x count

1.2.1. Create directory structures

The job description file for this script will look like this:

cat <<EOJOB > job.xml
<job_desc>
    <task>
        <application>count</application>
        <command_line>1000</command_line>
    </task>
</job_desc>
EOJOB

As mentioned above, the payload binary/script has to be copied to the sub-directory for each platform. Since the script can be the same for every platform (it is just text), we do plain copies:

cd $installroot/$fileprojectnme && \
for p in apps/wrapper/*/
do
  cp path/to/count path/to/count.sig path/to/job.xml path/to/job.xml.sig $p
done

Now, the app directory should look like ... except for the .sig files, which are added only later by the automated signing by bin/update_versions:

apps/
`-- wrapper
    |-- wrapper_6.12_i686-pc-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- job.xml
    |   |-- job.xml.sig
    |   |-- wrapper_6.12_i686-pc-linux-gnu
    |   `-- wrapper_6.12_i686-pc-linux-gnu.sig
    |-- wrapper_6.12_ia64-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- job.xml
    |   |-- job.xml.sig
    |   |-- wrapper_6.12_ia64-linux-gnu
    |   `-- wrapper_6.12_ia64-linux-gnu.sig
    |-- wrapper_6.12_mips-linux-gnu
    |   |-- count
    |   |-- count.sig
    |   |-- job.xml
    |   |-- job.xml.sig
    |   |-- wrapper_6.12_mips-linux-gnu
    |   `-- wrapper_6.12_mips-linux-gnu.sig
    `-- wrapper_6.12_x86-64-pc-linux-gnu
        |-- count
        |-- count.sig
        |-- job.xml
        |-- job.xml.sig
        |-- wrapper_6.12_x86_64-pc-linux-gnu
        `-- wrapper_6.12_x86_64-pc-linux-gnu.sig

Please not that every file that ends with .sig extention, contains the signature of the respective file. They (signature files) are generated by

$projectroot/bin/sign_executable /path/to/file/ /path/to/code_sign_private >> filename.sig

the code_sign_private is the private key file of the project, and for a production level real world project, it is advised you store it in a separate isolated computer and perform signing from there.

Use bin/xadd and bin/update_versions to put the app to database:

<app>
   <name>wrapper</name>
   <user_friendly_name>Wrapper Test</user_friendly_name>
</app>

1.2.2. Workunit

1.2.2.1. Template files

The application does not have an input, and dos a trivial small computation. A sample workunit template for the script, say wrapper_wu should look like

$ cat <<WUCONF > $installroot/$fileprojectname/templates/wrapper_wu
<workunit>
    <rsc_fpops_bound>1e12</rsc_fpops_bound>
    <rsc_fpops_est>1e14</rsc_fpops_est>
</workunit>
WUCONF

The rsc_fpop directives are used to define computational size parameters, expressed as number of FLOPS needed by the program. Our count produces a file named out as output, which should be transported back, the result template will be (call it wrapper_result)

$ cat <<WRECONF > $installroot/$fileprojectname/templates/wrapper_result
<file_info>
    <name><OUTFILE_0/></name>
    <generated_locally/>
    <upload_when_present/>
    <max_nbytes>5000000</max_nbytes>
    <url><UPLOAD_URL/></url>
</file_info>
<result>
    <file_ref>
        <file_name><OUTFILE_0/></file_name>
        <open_name>out</open_name>
        <copy_file/>
    </file_ref>
</result>
WRECONF

The commands below expect both templates in the folder $installroot/$fileprojectname/templates/.

1.2.2.2. Work units added to system

Finally create work,

cd $installroot/$fileprojectname && \
./bin/create_work --appname wrapper \
                  --wu_name wrapper_test \
                  --wu_template $installroot/$fileprojectname/templates/wrapper_wu \
                  --result_template $installroot/$fileprojectname/templates/wrapper_result 

This effort has now added a single job to the system. For adding multiple jobs with different input files, check next section.

1.2.3. Some complex Extensions

1.2.3.1. Multiple Tasks

Wrapper allows us to compute multiple tasks (binaries). The binaries have to be specified using the <task> tag.

<job_desc>
    <task>
        <application>binary_1</application>
        ... other tags
        <weight>X</weight>
    </task>
    <task>
        <application>binary_2</application>
        ... other tags
        <weight>Y</weight>
    </task>
</job_desc>

The <weight> tag specifies the contribution of each app towards the total computation. If binary_1 uses 10% and binary_2 rest, then X and Y are 10 and 90 respectively.

1.2.3.2. Status of Computation

The <fraction_done_filename> tag can be used to specify a file to check completion. Wrapper checks for a number between 0 and 1, inside the file, and sets the percentage of completion.

1.2.3.3. Multiple Input Files

Same as a normal BOINC application. See BOINC/ServerGuide/AppDeployment#Multiple_Input.2BAC8-Output_Files

1.3. Footnote

Currently we experiance some glitch in the wrapperapp, the problems are noted in BOINC/Debugging#WrapperApp

1.4. See Also

Back to BOINC/ServerGuide/AppDeployment, ?BOINC/ServerGuide/