1. BOINC - Berkeley Open Infrastructure for Network Computing

?TableOfContents(3)

Separate pages were created for:

?Anchor(Introduction)

1.1. Introduction

This page accompanies an ["Alioth"] [http://alioth.debian.org/projects/pkg-boinc/ project of the same name] on the creation of respective ["DebianPackage"]s. A detailed introduction to [http://boinc.berkeley.edu/ BOINC] itself is available on the wiki pages of [http://boinc-doc.net/boinc-wiki/index.php?title=BOINC_FAQ:_Introduction_To_BOINC boinc-doc.net] and [http://en.wikipedia.org/wiki/BOINC en.wikipedia.org]. In short, BOINC provides an infrastructure for distributed computing that is currently applied for various scientific problems. Hence, everybody can do something beneficial to the world at large while one's computer is not in use.

1.1.1. Benefits of Debian for BOINC

The main criticism of the BOINC project is that it would be difficult to install. Well, to install packages in ["Debian"] is not difficult. The motivation to create packages for this worthwhile cause requires no further explanation, maybe except for the following hint: Debian is special for its support of many different architectures, which is only sustainable because of an automated compilation of novel packages. Thus, the provision of BOINC on Debian significantly contributes to the acceptance of the project in all these non-mainstream architectures.

Another peculiarity of Debian is the option to create dedicated chroot environments, which may be essential for security sensitive administrators. Debian's ["debootstrap"] tool creates such easily, also in subdirectories of other Linux distributions. Together with the dynamic package management, this renders Debian a prime candidate for the creation of virtual hosts arbitrary Linux distributions or - maybe more interestingly - on Windows machines running ["Xen"], ["coLinux"] or ["VMware"]. http://packages.debian.org/boinc-client Furthermore, the frequently distributed ["LiveCD"]s of Debian may bring functional BOINC installations to the masses.

1.1.2. Once you decide to prepare your very own BOINC project...

... you demand too much from this effort that is aiming merely at packaging existing packages for Debian. The upstream official [http://boinc.berkeley.edu/create_project.php documentation to create a BOINC project] should be a first read and the BOINC [http://boinc.berkeley.edu/email_lists.php mailing lists] and [http://boinc.berkeley.edu/dev/ message boards] will come to your assistance.

A boinc-server package is available in the experimental branch of the svn server and there are also plans to upload it to Debian's experimental section. The package however can use some more help to further ease the entry level for creating one's own Debian-based BOINC project. Please consider to contact and join the [http://lists.alioth.debian.org/pipermail/pkg-boinc-devel/ BOINC developers mailing list] with respect to the server package and follow the ["BOINC/Server"]-dedicated page on this Wiki.

1.2. Technical overview

From the user's perspective, BOINC has three parts:

  1. The server that the data flow to which, after registration to the project(s), is no longer of interest.
  2. The BOINC core client that is commonly wrapped by the BOINC Manager (boincmgr) and the only program that is actually started by the user.

  3. The project-specific application (e.g. setiathome) that is started by the BOINC core client.

The speed of the processor is measured by the BOINC core client. One gets the more credits, the faster the BOINC core client says the individual machine is. Hence, it makes perfect sense to have a very much optimized binary of the BOINC core client, if one is interested in the stats. However, the project specific application, which does the real work, does not profit from an optimisation of the merely communicating BOINC client. It is the application's code where the real interest is in. Hence, the ultimate goal is to have locally optimised Debian packages for the scientific applications, too. These however are mostly distributed as binaries only, though, which renders this process difficult.

?Anchor(Installation)

1.3. Installation

1.3.1. Installation of binary packages

The BOINC packages are part of the Debian main archive since DebianEtch (see: [http://packages.debian.org/boinc-client boinc-client], [http://packages.debian.org/boinc-dev boinc-dev], [http://packages.debian.org/boinc-manager boinc-manager]). ["Backports"] of these packages for DebianSarge are on http://backports.org. To install BOINC on your computer update your package index files and install the boinc-client and boinc-manager packages:

apt-get update
apt-get install boinc-client boinc-manager

Finally, run the graphical user interface boincmgr and follow the instructions to attach a new project to your BOINC core client. A non-graphical alternative to boincmgr is the boinc_cmd program, which is included in the boinc-client package.

1.3.1.1. On 64bit Systems

At the time of writing, none of the projects provide 64bit binaries. From a programmer's view this is reasonable since most projects will not or only minimally profit from 64 bits and most of today's 64 bits processors can efficiently run 32 bit applications, too. However, for that a set of libraries is needed that may not be installed and thus extra complexity is added that apparently kept the projects' developers away from directly supporting the 64 bit platforms.

Debian however offers a 64 bit package for the Open Source SETI client itself. Just apt-get install boinc-app-seti and use the boincmgr application as outlined above.

1.3.2. Package repository on Alioth

For testing purposes some of our packages are first uploaded to our own repository on [http://pkg-boinc.alioth.debian.org Alioth]. To point package management tools to this repository follow these instructions:

If you are running DebianUnstable you should add the following lines to your /etc/apt/sources.list file:

# BOINC packages for Debian "sid" (unstable)
deb     http://pkg-boinc.alioth.debian.org/debian unstable main
deb-src http://pkg-boinc.alioth.debian.org/debian unstable main

If you are running DebianSarge with ["Backports"] you should add the following lines to your /etc/apt/sources.list file:

# BOINC packages for Debian "sarge" (stable) with packages from backports.org
deb     http://pkg-boinc.alioth.debian.org/debian sarge-backports main
deb-src http://pkg-boinc.alioth.debian.org/debian sarge-backports main

1.3.3. Installation from source

To install the BOINC packages from source, a deb-src line pointing to Debian's main archive must be present in your /etc/apt/sources.list file. Also make sure that you have the build-essential and fakeroot packages installed on your system. Curiosity is a good motivation to inspect and compile the source. Whenever you feel more serious to improve or to port the code to a novel platform please check out the aforementioned [http://pkg-boinc.alioth.debian.org Alioth project] that offers a [http://svn.debian.org/wsvn/pkg-boinc Subversion repository] with the latest source and a technically easier way to communicate your changes back to us.

  1. Prepare a source directory and download the BOINC source package and it's build dependencies:

    mkdir -p ~/src/boinc
    cd !$
    apt-get build-dep boinc
    apt-get source boinc
  2. Change to the BOINC directory and build the sources. Before running dpkg-buildpackage you can apply patches to the BOINC source or set compiler flags to optimize the BOINC core client. Information on how to do this is given at the BOINC/ClientBenchmarks page.

    cd boinc-X.Y.Z/
    dpkg-buildpackage -rfakeroot -us -uc
  3. After dpkg-buildpackage successfully finishes the build you can install your custom built packages:

    cd ~/src/boinc
    dpkg -i boinc-client_X.Y.Z-R_ARCH.deb boinc-manager_X.Y.Z-R_ARCH.deb

If dpkg-buildpackage fails to build the BOINC packages this probably indicates a bug in our sources and it is worth reporting it to the pkg-boinc-devel mailing list pkg-boinc-devel@lists.alioth.debian.org.

?Anchor(Troubleshooting)

1.4. Troubleshooting

1.4.1. Bug tracking

1.4.1.1. Everything works fine but some submissions get evaluated as erroneous

If this is fewer than 10 in 100 times then this may be some physiological behaviour. The submitted results are not all 100% identical when run on different machines.

1.4.1.2. Where to find status reports on clients

The boinc-client installed by the Debian package does not perform the actual computation. That is performed by the binary downloaded dynamically by that client. The web site of the project features entries for each result which may be indicative of one problem or the other.

1.4.2. Graphics

Graphics are supported, but they won't show up by default. The X display needs to be accessible to the BOINC graphics processes in order to see the interesting graphics for, e.g., Einstein@Home, and it isn't by default.

Your X display can be made accessible to all local UNIX socket connections, including the ones from BOINC, by running

xhost +local:

This is generally safe on single-user machines, though not ideal. It is a bad idea on multi-user machines, so don't do it there.

Then, the "Show graphics" button in boincmgr, or the --result ... graphics_window option to boinc_cmd, will actually work. Unfortunately, when it doesn't work because of failed X authorization, it does not report the error back to boinc_cmd or boinc_mgr, and the only trace of the error is in some log file in the result directory /var/lib/boinc-client/slots/<whatever>.

1.4.3. Command Line Only

Successfully running BOINC from the command line may take a little work. The package installs boinc_client as a daemon service running under user boinc. When working from the command line only, this means using boinc_cmd to communicate with the boinc_client service.

boinc_cmd can be a little frustration to work with, the man page needs a volunteer to step up and the feedback from the command is minimalistic. By default, the output from boinc_client is piped to log files in /var/lib/boinc-client/ (stdoutdae.txt and stderrdae.txt). These will need to be consulted when troubleshooting.

The first command you should use should be

boinc_cmd --get_state

Why not try it! When it works, you'll see lots of information about the projects you are (or are not) running but it's likely not to work just yet.

1.4.3.1. Authorization

The first stumbling block is that (for security reasons) boinc_cmd should not be authorized to connect to the daemon initially. boinc_client will have invented a random password (to protect the connection to the boinc_client daemon and is nothing at all to do with project passwords) and put it into /var/lib/boinc-client/gui_rpc_auth.cfg. You'll probably want to edit this file so that it contains the password you want to use.

boinc_client will need to be restarted for this change to take effect. This can be done thus:

/etc/init.d/boinc-client restart

Now try

boinc_cmd --host localhost --passwd <YOUR PASSWORD> --get_state

Hopefully it should work now.

1.4.3.2. Signing Up

When using the command line, you'll need to sign up using a form on the project website. In return, you will receive an email containing important information looking something like:

Welcome to SETI@home.

This email confirms your account with SETI@home:
    Project URL:         http://setiathome.berkeley.edu
    Account Key:         xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

    User name:           Your User Name
    E-mail:              email@example.com


For further information and assistance with SETI@home go to http://setiathome.berkeley.edu

You now need to ask boinc_client to attach each project you want to run. Use

boinc_cmd --host localhost --passwd <YOUR PASSWORD>  --project_attach http://setiathome.berkeley.edu xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

where xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx is the account key contained in the email.

To attach the boinc_client to your SETI-account use

boinc_cmd --host localhost --passwd <YOUR PASSWORD>  --lookup_account http://setiathome.berkeley.edu YourEmail YourSetiPassword

To check that this has been successful, use:

boinc_cmd --host localhost --passwd <YOUR PASSWORD> --get_state

You should now see your projects listed under Projects, a little like

...
======= Projects =======
1) -----------
   name: SETI@home
   master URL: http://setiathome.berkeley.edu/
...

and a lot of other information as well.

If this doesn't work for you, start by consulting the logs in the /var/lib/boinc-client directory.

1.4.3.3. Installing and configuring BOINC without boincmgr on Debian Etch

This is how I installed and configured BOINC on an underused Debian Etch server. It seems to work fine.

# apt-get install boinc-client
# boinc_cmd --project_attach http://www.worldcommunitygrid.org 00000000000000000000000000000000
# boinc_cmd --project http://www.worldcommunitygrid.org update
# boinc_cmd --set_run_mode always
# boinc_cmd --set_network_mode always
# boinc_cmd --project http://www.worldcommunitygrid.org resume

You can monitor your installation with:

# boinc_cmd --get_state
# boinc_cmd --get_messages 0

1.4.4. Going back to older version

Once you have agglomerated evidence that something is wrong with the current version of the boinc client, it may be worth to consider a downgrade to the previous version. Not all problems may occur with all clients, with an increasing number of clients you may indeed be the first to experience a particular issue.

Debian has a snapshot functionality. The link below please reset to the date you feel that everything last worked: http://snapshot.debian.net/archive/2006/05/10/debian/pool/main/b/boinc/ Download the respective boinc-client and boinc-manager .deb packages and run dpkg -i on the boinc-*.deb.

http://boinc.berkeley.edu/logo/logo_small.png

1.5. Contact

Please contact the maintainers of the BOINC packages and the community of Debian BOINC developers via the [http://lists.alioth.debian.org/pipermail/pkg-boinc-devel/ Alioth mailing list].