SPY
HILL
Research
Poughkeepsie, New York
SPY
HILL
Research
It is relatively easy to install and run BOINC on Unix. Pre-built packages now exist for the Fedora and Ubuntu distributions of Linux, so installing those packages is probably the easiest way to get up and running quickly. In that case, you don't need to read this page. See instead the article in the BOINC wiki about Installing BOINC.
This page describes how you can install and run the BOINC client on a Unix computer (such as Linux) as a system service (a "daemon").
Last modified: 28 March 2010
If you would like to know more about how BOINC works and how to set up the client on a Unix computer then you can follow the instructions presented here. If you would like to help test BOINC as an "alpha" tester then you'll need to use these instructions to install the BOINC client, since pre-made packages are not available. If you are a package maintainer you might want to use these instructions as a guide for creating your packaged installation. The main steps described below also apply for non-Linux versions of Unix, provided that you build the executables from source and that you make a few appropriate adjustments for your flavor of Unix.
|
You will need to make a few decisions as you go along,
such as whether to run BOINC under a separate
account dedicated to the task (running as a Unix "daemon") or under
your own account (a "personal" installation),
and where to put the working directory.
In any case, the general steps are more or less the same.
If you have already installed BOINC and wish to upgrade, then you can
jump down to
You should also be aware that there is as yet no working screensaver
for BOINC on Linux.
You can view the graphics created by a running application by using
the "Show graphics" button in the BOINC Manager, but don't expect to
see the graphics cover your screen when your computer console is idle.
Since most BOINC volunteers using Linux will have "root" access to
their machine we will just describe the daemon installation here.
If you cannot become "root" on Linux, or don't want to do so just to
try out BOINC, then you can try the
instruction for a personal installation.
In most cases, however, the "daemon" installation is the prefered method.
In the examples given below "#" is used to represent the command
prompt for the root user, while "%" is used to represent the command
prompt for a non-root user. In either case you don't type it, you
only type the command which follows it. In general you should only do
things as root which need to be done as root. Otherwise, use your
personal account or the "boinc" account you will create to run BOINC.
BOINC needs a working directory in which to run.
It creates a number of files and subdirectories in whatever directory
it is run from, so be careful not to run boinc from an
arbitrary directory (such as your home directory).
For a "daemon" installation the recommended working directory is
/var/lib/boinc or /var/lib/boinc-client. The first
is used by Fedora packages while the second is used by Debian/Ubuntu
packages.
You are free to use something else if you want, such
as /home/boinc or /opt/boinc, provided you tell the
init script the directory name (see below).
For a "daemon" installation you should create a separate user account
called "boinc".
The working directory will then be this user's home directory.
How you create a new account can vary between Linux installations, but
on most of the major distributions you should be able to use the
useradd command:
If you don't have useradd on your Linux distribution look for
adduser.
If you don't have that, you'll have to figure out how your version of
Linux is set up to create new user accounts.
The home directory of this new user should be the working directory.
Once you have created this account the home directory will be the
working directory.
If you create the account without specifying a particular directory
like /var/lib/boinc then the default will be /home/boinc.
To be sure, look in the file /etc/passwd for the line for
this new 'boinc' account. It should look something like
As of this writing version 6.10.17 is recommended for Linux.
If you have anything older already installed then you should consider
upgrading.
To get the latest recommended version of BOINC for Linux you should
only have to click on the "Download" link and save the file to disk
somewhere convenient.
If you see a bunch of giberish on the screen then you are viewing the
compressed archive file.
Go back one page and right-click on the link to download the
file.
The file you get from this, boinc_6.10.17_i686-pc-linux-gnu.sh,
is a self-extracting shell script.
This means that you simply run the file through the Bourne
shell, with the command
Since BOINC will be run from the working directory you should move all
the files that were unpacked along with the boinc and
boincmgr executables to that working directory.
Then you copy the executable files boinc and boincmgr
to a directory where you keep executables, preferably one in your
Unix command path.
I recommend installing in /usr/local/bin.
Also, I like to rename boinc to boinc_client to
distinguish it.
The commands to do this are:
Instead of downloading the pre-built client executables, you can also
build the BOINC client from source code.
That is more complicated, but will be necissary on platforms like
PowerPC or FreeBSD where the Linux executables distributed from
Berkeley won't work.
More information about starting BOINC automatically on a wide variety
of platforms can be found at:
For almost any Linux distribution you put the init script in the
file /etc/init.d/boinc (make sure it is executable).
As root, the commands to do this are:
If you want to try this out by hand then you can start the boinc
client as a daemon with the command
If there are problems starting the daemon by hand you may need to make
some adjustments.
You can specify alternative settings for several configuation
variables in a file called boinc in the directory
/etc/sysconfig (for Red Hat/Fedora Linux or
/etc/default (for Ubuntu or other Debian distributions).
This file should just contain variable settings which differ from the
defaults.
If you can start and stop the boinc client daemon by hand then you are
ready to set up automatic startup at boot time.
To do this you need to make links to the init script from the
directories where your system reads startup scripts at boot time.
We will add them to the startup sequence for both run-level 3 (no
window system) and run-level 5 (with window system).
To do so, give the following commands:
The script init.d/boinc contains comments
at the head of the file which allow it to be used by special tools
available in Red Hat and Suse Linux which will create the "S" and "K"
links for you.
But that's a short-cut you can only take on those distros, while the
instructions above apply to almost all Linux distros.
If you are not using Red Hat, Fedora, Debian, Mandrake, or SuSe Linux
then you may need to modify the start/stop script for your
distribution, and you will need to install it to match the startup
proceedure used by your distribution.
But in any case the idea is the same.
Please let me know if you find a small change to my init script which
would allow it to be used on some other Linux distro.
The BOINC client core must be running first.
If you just installed BOINC as described above then you don't need to
reboot to get this to happen.
Simply start the BOINC daemon 'by hand' just this once, by running the
init script, with the command:
Alternatively, you can su to the 'boinc' user, cd to that user's home
directory, and then run the client:
With the client core running in the background, launch the BOINC
Manager, so that you can use it to talk to the client core.
The command is
You can avoid this scary message and enable authentication
automatically (you won't have to enter the password) if you cd to a
directory which contains a copy of the file gui_rpc_auth.cfg
before you run the Manager.
One good way to do this is to put a copy of the
gui_rpc_auth.cfg file in your own home directory, and then
lanuch the Manager from there. (The way the Manager gets this
information is a bit crude and will hopefully be improved in the future.)
Once the Manager starts, if you have not yet attached to any projects,
then the Manager will automatically begin a dialogue to guide you
through the process of attaching to a project.
Once you have attached to one project, you can then attach to more
projects by pressing the "Add Project" button in the Manager's simple
view, or by pulling down "Tools -> Attach to project..." in the
Manager's advanced view.
Note that if you already have attached to BOINC projects on some other
computer then you can also arrange for the new installation to be
attached to the same projects simply by copying the files
account_*.xml to the working directory of the new
installation.
The BOINC core client will then attach to each of these projects when
it is started.
Overview
Here is what has to be done:
The rest of this page simply expands upon these steps.
Background
In what follows it may help to know that there are several components
to BOINC.
First there is the "Core Client", which does the
work of running BOINC applications, communicating to the server,
downloading application and data files and uploading the results.
This is what you run when you are "running BOINC".
Then there is the "BOINC Manager", a separate
program which provides you with a Graphical User Interface to monitor
and control the Client Core.
You do not have to run the BOINC Manager all the time.
Also, you can use the BOINC Manager to monitor boinc clients running
on other computers.
Service ("daemon") installation
In Unix a program running in the background, detached from any
controlling console and providing some kind of system service, is
called a "daemon".
Due to security concerns you do not want BOINC to run as the "root"
user (the superuser), so you will want to create a separate user
account for the BOINC daemon.
You will also want to arrange for this daemon to be started along with
other daemon services at boot time.
Create a boinc account
You should run the BOINC client under its own user account, though
for testing you can run it under your own account just to see if it
works. There is no need to run BOINC as root, and doing so may leave
you vulnerable to attack. (There are no known problems at this time,
but if you don't run as root you won't have to worry about any being
found.)
# useradd -d /var/lib/boinc boinc
(The "#" represents the command prompt for the root user -- you don't
type it, just the command which follows that prompt.)
You will find this command in /usr/sbin if that is not
already in your command PATH for the root account (it should be).
boinc:x:101:101::/var/lib/boinc:/bin/bash
The second to last item in the list (the colons are separators) is
the user's home directory.
This will be the working directory.
(The last item in the list is the user's command shell.)
Obtain and install the BOINC executable(s)
The easiest way to get the BOINC executable files is to download
the pre-built version from the BOINC download page at
If you connect from a Linux computer you will automatically be offered
the latest version for Linux, but there is also an "All Versions" link
on the page which will show you more versions for more platforms,
including versions still in development.
If you are new to BOINC you will want to start with the "recommended"
versions and avoid the development versions.
% sh boinc_6.10.17_i686-pc-linux-gnu.sh
(The "%" represents the non-root command prompt -- you don't type it,
just the command which follows it.)
The script will extract from itself all of the files in the bundle
into a subdirectory called BOINC.
I recommend that you disregard the instructions it gives about running
the client or the manager, and instead follow the instructions that
follow here below:
# cd BOINC
# cp boincmgr /usr/local/bin
# cp boinc /usr/local/bin/boinc_client
You will likely have to be root to copy files to /usr/local/bin.
Set a password for the Manager to contact the Client
To use the BOINC Manager to access and control the running BOINC
Client you should set a password.
This is stored in the file gui_rpc_auth.cfg in the working
directory.
If this file does not already exist, then when you start the BOINC
client it will be created and filled with a 32-character hexadecimal
number.
That's pretty hard to remember, so instead you want to put a simpler
(yet not too simple) password in its place.
The easiest way to do this is to cd to the working directory and echo
into the file.
For example:
% cd ~boinc/
% echo Alohomora > gui_rpc_auth.cfg
This sets the password to "Alohomora".
You should, of course, us something else known only to you.
You will need to give this password whenever you start the BOINC
manager (see below). If you prefer convenience over security you
can use an empty password, by saying just
% echo > gui_rpc_auth.cfg
and then you will not have to give a password when you start the Manager.
Get BOINC to start automatically
You will want to arrange to have BOINC start whenever your computer
starts (for a "daemon" installation) or at least when you log in (for
a "personal" installation).
For a "daemon" installation you need to have a Unix start/stop script
which is invoked when the machine is booted.
I use the following script:
This is known to work on Debian, Ubuntu, Mandrake, Slackware, and SuSe
Linux distributions.
By default it looks for the executable
as /usr/bin/boinc_client.
To change this, add the line
BOINCEXE=/usr/local/bin/boinc_client
to the file /etc/sysconfig/boinc (on Red Hat/Fedora/Mandriva)
or /etc/default/boinc (on Ubuntu or other Debian-derived
Linux distributions). You can use this mechanism to override any of
the other settings in the init script, such as the working directory,
or allowing remote RPC connections, as described later below.
# cp boinc /etc/init.d/boinc
# chmod +x /etc/init.d/boinc
(The 'boinc' file you are copying here is the init script, not the
client executable which I earlier suggested renaming "boinc_client".)
# /etc/init.d/boinc start
and stop the daemon with
# /etc/init.d/boinc stop
If this doesn't produce any errors then it likely worked, but you may
also want to check the log files in the working directory.
If you are a BOINC 'alpha tester' you can use this mechanism to
temporarily use executables you have installed elsewhere for testing
even though you have BOINC installed as a package.
Here is an example, using just the default setttings you would get if this
file didn't exist.
Lines which begin with "#" are comments.
# BOINC daemon configuration settings. The examples below are the defaults
# you'd get if you left them out, so you only need the lines that are different.
#
BOINCUSER=boinc
BOINCDIR=/var/lib/boinc
BUILD_ARCH=i686-pc-linux-gnu
BOINCEXE=/usr/bin/boinc_client
LOGFILE=boinc.log
ERRORLOG=error.log
BOINCOPTS=
LOCKDIR=/var/lock/subsys
To be able to control the BOINC client from another computer you need
to specifically allow remote RPC calls to the client by setting
BOINCOPTS="-allow_remote_gui_rpc"
which is off by default for security.
# ln -s /etc/init.d/boinc /etc/rc0.d/K03boinc
# ln -s /etc/init.d/boinc /etc/rc1.d/K03boinc
# ln -s /etc/init.d/boinc /etc/rc2.d/S98boinc
# ln -s /etc/init.d/boinc /etc/rc3.d/S98boinc
# ln -s /etc/init.d/boinc /etc/rc4.d/S98boinc
# ln -s /etc/init.d/boinc /etc/rc5.d/S98boinc
# ln -s /etc/init.d/boinc /etc/rc6.d/K03boinc
The general way this works is that when the system enters a particular
run level then all of the scripts for that run level which begin with
"K" are invoked, in order, with the single argument "stop" (the "K"
stands for 'kill'), then all of the scripts which begin with "S" are
called, in order, with the single argument "start".
So this causes BOINC to be started late in the boot sequence in run
levels 2-5, but shut down early in the sequence at run level 0
(shutdown), run level 1 (single-user), or run level 6 (reboot).
Attach to a BOINC project
For each project in you wish to participate you need to "attach" the
BOINC client to the project.
For each project you wish to attach to, you need to provide the URL of
the project, a valid e-mail address, and a password.
If you already have an account on the project then the e-mail address
and password must match that account.
If you do not yet have an account on that project then one will be
created for you when you attatch.
# /etc/init.d/boinc start
# su boinc
% cd
% /usr/local/bin/boinc_client &
This assumes that you renamed the executable to boinc_client, as
suggested earlier, and put it in /usr/local/bin.
The "&" lanuches the command in the background, so that
you can give more commands while it is running.
% boincmgr
This will pop of the scary message "Authorization failed connecting to
running client.
Make sure you start this program in the same directory as the client."
Well, that's one way to do it, but this message is not quite accurate.
Click "OK", then pull down "Advance -> Select computer..." and enter
"localhost" for the compuer name, and then the password you set above
as the password.
This will connect the BOINC Manager (in the window which just opened)
with the BOINC client which is running in the background.
Upgrading BOINC
It is fairly straightforward to upgrade your BOINC installation.
You just need to go through a few of the steps above:
Once the client is running, start the manager and take a look at the
messsages. The client should detect the version change and therefore
run new benchmarks. Once they complete, it will continue on with
whatever work you already had. You should still be connected to all
projects with all other settings preserved.
# /etc/init.d/boinc stop
# cd BOINC
# cp boincmgr /usr/local/bin
# cp boinc /usr/local/bin/boinc_client
# /etc/init.d/boinc start
Personal installation
The instruction for a "personal" installation of BOINC on Unix
have been moved to this separate page.
Copyright ©
2010
by Spy Hill Research
http://www.Spy-Hill.net/myers/help/boinc/unix.html
(served by Islay.spy-hill.com)
Last modified:
28 March 2010