BOINC is an awesome piece of software that lets you donate your computer’s processing power to a variety of worthy scientific causes. Unfortunately, if you’re running it on Linux without a graphical interface, the control tool’s documentation is a little lacking.

So here is a miniature howto on getting started with BOINC from the command line. I’m assuming you have a recent version of Debian or Ubuntu and a passing familiarity with how BOINC works (if not, browse the official site).

Step 1: setting up

For starters, you need the BOINC client. If you’ll only be working from the command line, you don’t need the other BOINC packages.

sudo apt-get install boinc-client

This gives you the control utility boinc_cmd and creates the directory /var/lib/boinc-client where your data will be stored.

If you’re running on a 64-bit box, there are two extra steps: first, install the 32-bit version of glibc.

sudo apt-get install ia32-libs

Now edit BOINC’s client config file:

vi /var/lib/boinc-client/client_state.xml

Find the <platform_name> element and change its value to i686-pc-linux-gnu — it should look like this:

<platform_name>i686-pc-linux-gnu</platform_name>

This will tell BOINC to download the 32-bit versions of each project application, rather than asking for 64-bit binaries (which most projects don’t offer).

Step 2a: find your account key

If you’ve already registered a username and password with a BOINC project, you can go to its Web site and hit the “your account” page — you should find a link (such as this one) to have your account key mailed to you.

Step 2b: get a new account key

Alternatively, if you’re starting out with a new project and haven’t registered before, you can use boinc_cmd to register by giving it the create_account option, followed by the project URL, your e-mail address, a password, and your desired username.

boinc_cmd --create_account http://www.malariacontrol.net/ [email protected] hardToGuessPassword myUserName

This command drops you back to the shell having outputted nary a whimper, but if you look in the working directory you’ll find a file called create_account.xml with your account key in the <authenticator>...</authenticator> tags.

less /var/lib/boinc-client/create_account.xml

Step 3: start computing!

Once you’ve signed up for a project, you can attach to it by running boinc_cmd with the --project_attach switch, followed by the project URL and your account key.

boinc_cmd --project_attach http://boinc.bakerlab.org/rosetta a1b2c3d4f5a6b7c8d9e0f

And that’s the hardest part done! Your computer should now be registered with the project and will start downloading numbers to crunch. You can confirm this by looking in the control daemon’s log file, which is also the best place to look if you have trouble:

less /var/lib/boinc-client/stdoutdae.txt

Step 4: what’s happening?

To find out what your system is doing, use the (very verbose) --get_state option.

boinc_cmd --get_state

Step 5: stopping work

Two common tasks (for me at least) are to stop work right now, and to stop after the current unit is finished (i.e. don’t fetch more work). You can do these with the --project option:

boinc_cmd --project http://issofty17.is.noda.tus.ac.jp/ suspend

boinc_cmd --project http://boinc.bio.wzw.tum.de/boincsimap nomorework

The opposites of those commands after the URL are resume and allowmorework respectively. You can also use detach to disconnect your computer from a project completely.

Step 6: for more information …

My recommendations are the official documentation, the unofficial BOINC wiki, the Debian wiki, or any of the various forums. Good luck!