SPY HILL Research Spy-Hill.net


Poughkeepsie, New York [DIR] [UP]

Installing and Running the BOINC client on Unix


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
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.

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.
Service ('daemon') installation
  • Create 'boinc'account
  • Obtain BOINC
  • Password
  • Starting the daemon
  • Attach to projects
  • Topics
    Overview
    Background
    Upgrading

    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.

    Overview

    Here is what has to be done:
    1. Create a "boinc" user account and working area (directory)
    2. Obtain and install the executable files
    3. Set a password for the Manager to contact the Client
    4. Arrange for BOINC to start automatically
    5. Start BOINC, and attach to a project (or several)
    The rest of this page simply expands upon these steps.
    RUN BOINC ONLY ON AUTHORIZED COMPUTERS
    You should run BOINC only on computers which you own, or for which you have obtained the owner's permission. Some companies and schools have policies that prohibit using their computers for BOINC projects or similar uses.

    If you have already installed BOINC and wish to upgrade, then you can jump down to

    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.

    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.


    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.)

    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:

    # 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).

    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

    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.

    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

    % 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:

    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:

    # 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.

    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.

    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.

    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:

    # 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".)

    If you want to try this out by hand then you can start the boinc client as a daemon with the command

    # /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 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 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.

    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:

    # 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).

    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.

    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.

    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:

    # /etc/init.d/boinc start

    Alternatively, you can su to the 'boinc' user, cd to that user's home directory, and then run the client:

    # 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.

    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

    % 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.

    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.

    Upgrading BOINC

    It is fairly straightforward to upgrade your BOINC installation. You just need to go through a few of the steps above:
    1. Stop the running client (if it's running):
      # /etc/init.d/boinc stop
    2. Download the latest version of the client for your platform. (as described above), unpack it, and copy the client and manager executables to /usr/local/bin:
      # cd BOINC # cp boincmgr /usr/local/bin # cp boinc /usr/local/bin/boinc_client
    3. Start the client:
      # /etc/init.d/boinc start
    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.


    Personal installation

    The instruction for a "personal" installation of BOINC on Unix have been moved to
    this separate page.


    Last modified: 28 March 2010 Copyright © 2010 by Spy Hill Research http://www.spy-hill.net /help/boinc/unix.html