SPY HILL Research Spy-Hill.net


Poughkeepsie, New York [DIR] [UP]

Creating and Configuring a BOINC Project


This document describes the basic steps required to set up a BOINC project. These include configuring and running a MySQL database server, configuring and running the Apache web server, and building and deploying the BOINC daemons.

Last modified: 1 January 2012
Topics
Overview
Software
Database
Building BOINC
make_project script
Web Server
Configuration:
  • File Permissions
  • Database passwords
  • config.xml
  • Daemon tasks
  • Scheduler
  • Feeder
  • Applications
    Customization
    Overview

    Setting up a BOINC project (the server and the applications it distributes) involves a number of steps, all of which are straightforward, but the overall task can be a bit daunting to those new to BOINC. Here is an outline of the process:

    1. Choose a server (Unix)
    2. Obtain required Software
    3. Set up database server (MySQL)
    4. Build the BOINC server software
    5. Run the make_project script
    6. Set up the web server (Apache)
    7. Adjust and check the configuration
    8. Create and deploy your application
    9. Customize your site
    Useful information about creating a BOINC project can also be found on the BOINC site at: as well as these In the examples which follow, "#" indicates the prompt for Unix commands issued by the 'root' user, while "%" is the prompt for commands issued from your normal (non-root) Unix account. The BOINC icon () indicates a link to the main BOINC documentation from Berkeley, or the BOINC wiki. These should open in a new window.

    Once you have your project set up, or even before it's all working, you should seriously consider joining the boinc_projects mailing list. You can ask questions here of others who are also running projects, or read the answers for questions you didn't even think to ask. Please do not post questions about running a project to the boinc_dev mailing list, which is only for software development.

    Choosing a Server

    BOINC applications can run on Windows, MacOS X, and Unix (generally Linux, but also Solaris and HPUX), but the server must be a Unix computer, generally running Linux. Just about any Linux distribution will work, so long as it has the necessary software, as described in the next section.

    There are three ways you can approach the task of making sure that your server is set up correctly to host a BOINC project. The first is to use a Linux distribution which automatically (or very easily) includes all the requisite software. The second is to specifically download, build and install the necessary software (or download and install binaries or packages). The third is to download and run a Linux Virtual Machine for BOINC using the VMware Player. The choice is up to you. I personally don't recommend the VM approach, because then you don't learn anything about how BOINC is set up, and you spend more time sorting out problems with the VM.

    I have had good results using the Red Hat/Fedora Core distributions. Pirates@Home was initially set up on a Red Hat 7.3 machine, then updated to Fedora Core 3, and now runs on Fedora Core 4. This does not mean that you must use one of these distributions, only that it's likely to work for you with minimal difficulty.

    As of Spring 2007 you cannot set up a project on FC3 without installing additional software (such as MySQL) 'by hand', but FC4 and FC5 are fine 'out of the box' (except that you do need to install at least one package which is not installed by default -- see below). If you are setting up a new machine you may want to use the latest Fedora release, or the latest minus one if the latest is really new.

    BOINC continues to be a work in progress, and as it evolves the software requirements change. What might have been an acceptable server configuration a few months ago may not work now because some component needs to be updated. Again, you can try to update your software through the package/software update system which is a part of your particular distribution, or you can download, build and install the latest version of a particular piece of software to bring your machine up to the required version. Choose the path that is easiest for you.

    If you choose to install software yourself rather than through your distribution's package manager (eg. saying `./configure; make; make install`) then you must insure that this software is up to date, even as other components are automatically updated. In the past I've sometimes built OpenSSL or libcurl myself to get the latest versions, only to later find that those versions were now out of date compared to newer version installed as updated packages.

    If you are going to create BOINC applications to run on Windows then you will also need a separate Windows machine on which to develop that code. That is separate from the project server.

    BOINC Unix group

    To make server management easier, especially if the duties might be shared between multiple Unix user accounts, it can be very useful to create a Unix group called "boinc" and add your own account to the group.

    Required Software

    The basic components of a BOINC server are: So basically you need to build the BOINC code for the daemons, and then install and configure all these components. There is also some supporting software you need, such as Python (a scripting language used for the initial configuration of the server), PHP (for server side web scripting), OpenSSL (encryption software) and libcurl (for web transfer functions).

    A complete list of software dependencies, including the minimum required versions, may be found on the BOINC site at:

    This is the software required to set up a server. You do not need to build the Core Client or BOINC Manager (the folks at Berkeley will do that). Thus you do not need wxWidgets. You will eventually need the software required to build a BOINC application, but the only thing you'll need beyond what is required for the server is the proper graphics libraries, assuming you build an application which includes graphics (which is not a requirement). If you are going to build applications to run on Windows then you will need a separate build machine for that.

    The process of obtaining and building the BOINC software is dealt with later below. For now, it may help to know that BOINC has recently changed over from using CVS for source code version control to using Subversion (SVN), so you will need a working Subversion client in order to be able to check out the source code.

    Database Server

    It is possible to run the database server on the same machine which serves as your web server and runs the BOINC daemons, or you may make this a separate server. You can start out with everything on one machine, and then move the database server to another machine once your project grows to where this is necessary.

    You do not need to worry too much about the database filling up as time goes on. BOINC will remove Results and Workunits from the database after they have completed (you can configure the expiration time). The database is only used to manage active work (along with keeping track of all participating users and machines).

    If you have everything on one machine, you may want to put the database on a separate disk partition. The default for MySQL is to use /var/lib, and I have found that the /var partition is often too small for this. In the example below I have my database on the separate partition called /usr02.

    MySQL Unix Accounts

    It is a good idea to create a separate Unix account and group just for MySQL, and run the server daemon under that account and group rather than as the superuser ('root'). Then if there are any security problems which allow an attacker to break in via the database system, he can only do what the database user can do, but will not have full 'root' powers.

    This is done for you if you install via .rpm file, as on Fedora/Red Hat Linux. If you are not installing this way then you may need to create the user 'mysql' and group 'mysql' yourself, either by editing the appropriate files or by running the useradd and groupadd commands.

    Later, when you configure your installation, you will want to create or adjust several different database accounts. But that comes later.

    Configuration File

    The MySQL database configuration is controlled by the file /etc/my.cnf. As an example, the version used on my server for Pirates@Home can be found
    here. As you can see, the key elements which you need to change are the datadir, basedir, and log and pid files. I have almost everything under /usr02/lib/mysqld

    Initialization

    The first time you start the database server the startup script /etc/rc.d/init.d/mysqld will run the database initialization command mysql_install_db. (This is on Fedora/Red Hat. If your distribution does not do this then you can run this script yourself.) This will create some initial database tables and the master database account. The user name on the master account is 'root', and it is not password protected.
    As the script will instruct you, you should run the mysqladmin command to give the master database account a password. However, you should save this until later, after you have run the make_project script (see below).

    Automatic Startup

    You will likely wish to configure the database daemon to start automatically when your system is booted. The commands to do that on Red Hat/Fedora (which must be run as 'root') are:
    # chkconfig mysqld on # service mysqld restart

    Building BOINC on Unix

    Obtaining and building the BOINC software is fairly well documented. BOINC has recently changed over from using CVS for source code version control to using Subversion (SVN), so you will need a working Subversion client.

    How to get the source code and a roadmap of the source tree are provided at

    More detailed instructions (perhaps too much detail, perhaps some of it is old) can be found at:

    A very quick summary of the process is given by this example:

    % cd work_dir % svn co http://boinc.berkeley.edu/svn/trunk/boinc % cd boinc % svn update -r 12677 # optional - sets a particular revision % _autosetup Bootstrapping configure script and makefiles: Checking version of 'make' >= 3.79... succeeded. (3.80) Checking version of 'm4' >= 1.4... succeeded. (1.4) Checking version of 'pkg-config' >= 0.15... succeeded. (0.20) Checking version of 'autoconf' >= 2.58... succeeded. (2.59) Checking version of 'automake' >= 1.8... succeeded. (1.9) aclocal -I m4 && autoheader && automake && autoconf Done, now run ./configure % ./configure --prefix=/usr/local/boinc --- Configuring BOINC 5.9.11 (Release) --- --- Build Components: (server & client) --- checking build system type... i686-pc-linux-gnu checking host system type... i686-pc-linux-gnu checking target system type... % make make all-recursive make[1]: Entering directory ...
    The make command may complain about not finding certain components required to build the client, but at this stage you don't care, since you only want to build the server software.

    Run the make_project script

    Once the 'make' command finishes successfully you will want to run the make_project script, which is in the tools subdirectory of the source distribution. You must specify the name of your project on the command line, and you can optionally specify the project root directory and many other options. The complete documentation for this script may be found at:
    It's best to run this script as the Unix 'root' user, if you can, because then there will be no problem creating the proper directories or accessing the database. If you cannot do this then you may need to add command line arguments for the database user and password. If you make a mistake you can easily start over, but you need to include command line flags to delete the previous installation or database.

    Here is a quick example:

    # cd boinc/tools/ # ./make_project -v --project_root /usr02/pirates pirates Pirates@Home

    This creates /usr02/pirates and a number of subdirectories under it. The full directory structure is documented at

    It also creates a database called 'pirates' (or the name you used here for the "short" name for your project).

    Web Server

    BOINC uses the Apache web server both to communicate with users, though the web pages, and to communicate with the clients for scheduling, downloading files, and uploading results.

    Configuration

    Details about how to set up the web server configuration can be found at
    The make_project script will create a template configuration file for the web server in the project root directory. That way you can simply edit it to match your server configuration, which is much easier than creating it from scratch.

    You may also find it useful to have a working example. Here is the configuration file for Pirates@Home. It is a bit more complicated than the one produced by make_project, in part because it creates a separate "virtual host" on the server, and it also supports some extra features which are being tested on Pirates@Home.

    Except that as of this writing it's not the complicated version. We should probably show both.

    PHP - server side scripting

    Most of the web pages you view on BOINC, especially those which contain information about your account or preferences, are generated dynamically on the server using PHP. Some configuration and management functions are also performed by running PHP scripts from the command line. You will therefore need to have a fairly recent version of PHP installed, and configure your web server to use it. The latest version of Apache httpd has PHP turned on by default (in /etc/httpd/conf.d/php.conf), but you may also want to review the configuration file in /etc/php.ini.

    In particular, to improve security of your server you should verify that "register_globals" is turned off. This is the default for new installations, but might be turned on if you are copying a file from another project or site.

    You should also review and adjust the settings in this file for error reporting. You can turn on a variety of error reporting functions which can help you debug your site, but you will likely want to turn these off once you are in production. Errors may be displayed on the web pages, and/or logged to the web server error log. You can adjust the error reporting level so that you receive "notices" of minor things such as uninitialized variables, or only major errors, or something in between. If you are not actively working on developing BOINC code then you likely do not want to see the "notice" level errors. In that case set

    error_reporting = E_ALL & ~E_NOTICE

    GD - dynamical graphical image manipulation library

    The BOINC server use the 'gd' suite of image processing functions to create re-sized versions of profile and avatar images. PHP works very well with GD, but I encountered problems when I moved to a Fedora Core machine. The clearest symptom of the problem was an error message saying something like:
    PHP Fatal error: Call to undefined function gd_info() in /usr02/pirates/html/inc/image.inc on line 6,...

    It turns out that Fedora Core 4 (and 5) does not include GD with PHP by default. It is easily added by installing the 'php-gd' RPM, either from the install CD, or more easily using yum with the command:

    # yum install php-gd

    More information about GD can be found at:

    Automatic Startup

    You will likely wish to configure the web server to start automatically when your system is booted. The commands to do that on Red Hat/Fedora (which must be run as 'root') are:
    # chkconfig httpd on # service httpd configtest Syntax OK. # service mysqld restart
    (How you do this on your Linux distro may be different, but the idea is the same.)

    Configuration

    This section describes the steps necessary to configure the site to serve out Workunits to client machines. You will need to verify or adjust some file permissions, add database passwords, and edit the config.xml file. Further customization to make your web site more functional and attractive are described in a later section.

    When it comes time to upgrade your project software (as described here) you will want to go through these steps again to verify that everything is still configured properly. (The 'upgrade' script can change file permissions.)

    File Permissions

    The make_project script may not get all of the file permissions set correct for your project directories, depending on how you are configuring your user and group permissions. If you ran the make_project script as 'root', which is the easiest way to do it when you are getting started, then the files will all be owned by 'root', which is not very useful. Most of the files should be owned by an unprivileged account which will be used to manage the project. That can be your personal Unix account, or a separate account created for this purpose (such as 'boincadm'). It is also useful to create a Unix group called 'boinc' for managing the project, especially if several people may be involved in such management.

    It will be convenient in what follows to define the PROJECT environment variable to be the top directory for the project. Using csh this is done with something like

    # setenv PROJECT /usr02/pirates
    using, of course, your own project root directory. If you prefer bash then use
    # export PROJECT=/usr02/pirates

    Some subdirectories are not created until the project is "started". An easy way to deal with this is to run the 'status' script once, which will create those directories but not actually "start" the project. The command is:

    # $PROJECT/bin/status
    Then the changes describe below will also apply to the subdirectories this creates. At this point don't worry about the output from this command. (You may still need to go back later and change some file ownerships and permissions for subdirectories which have not yet been created.)

    Now, to change the user/group ownership of the entire directory tree the command (as root) would be something like:

    # chown -R boincadm:boinc $PROJECT
    The "-R" flag makes the command recursively descend all subdirectories. Here "boincadm" is the name of the account you have set up to manage the project. If you are not using a separate account then use your own login account name.

    Certain directories and files need to be writable by the web server daemon, which should be running as a non-root user. The web server user and group names are often "apache" (on Fedora/Red Hat based systems) or "www-data" (on Debian systems). The easiest way to do this is through group permissions, and there are two ways to do it: You can add the "apache" (or "www-data") user to the "boinc" group, or you can change particular files or directories to be writeable by the "apache" (or "www-data") group. In either case you then make the files and directories group writeable, and then the web server daemon can write to them. The first way may be easier, but it also has a potential security vulnerability: All files which are writeable by the "boinc" group can then be modified by the web server daemon. The second approach is more explicit and slightly more secure, so that is what I use in what follows (even though the BOINC documentation suggests the opposite here. I disagree, but in normal operation both methods give the same result.)

    The following directories (and files and directories inside them) need to be writeable by the web server daemon:

      $PROJECT/upload
      $PROJECT/log_*
      $PROJECT/html/cache 
      $PROJECT/html/user_profile
      $PROJECT/html/languages
    
    As an example, for the last in the list, one would say
    # chgrp -R apache $PROJECT/html/languages # chmod -R g+w $PROJECT/html/languages
    Recall that the "-R" flag applies the comamnd recursively to subdirectories.

    One complication you may encounter is that some subdirectories of these, which are created by the web server later, may then not be readable by your account. You may need to adjust the permissions accordingly later. If you add your own Unix account to the apache or www-data group then you will automatically be able to read any file or directory created by the web server. If you set the "sgid" bit on a directory then any subdirectory created in it will inherit the group, which can prevent these kinds of problems.

    (When I last did an installation I also found that to get the web site working I had to say

    # chmod o+rx $PROJECT/html/inc
    but this is unusual. This directory needs to be readable by the web server, but should not be writeable.)

    download directory

    Another important permission to get right is for the download directory and it's subdirectories. These need to be readable by the apache web server so that the files in the download area can be served to clients. Rather than just making everything world readable, you can make the download directory group "apache", and the same for any fanout subdirectories by saying
    % chgrp apache $PROJECT/download % chmod g+rxs $PROJECT/download
    Here the "+s" on a directory rather than an executable file makes the group ownership of subdirectories inheritable from the parent when they are created.

    feeder daemon

    One of the most important file permission you need to get right is for the feeder daemon. Here's why: An instance of the scheduler CGI script is started each time a client contacts the scheduler via the web server. To avoid the cost of starting up a database connection each time, the feeder runs continuously with a connection to the database, and then transfers information between the scheduler and database via shared memory. Thus the scheduler, run by the web server, and the feeder, running under your own Unix account, need to be able to connect via shared memory. If the apache server is not in the "boinc" group then the feeder can be made to run under the "apache" group by saying
    % chgrp apache $PROJECT/bin/feeder % chmod g+xs $PROJECT/bin/feeder
    The "+s" causes the feeder to run with group "apache", which allows the scheduler CGI which is also running under group "apache" to connect to the shared memory segment set up by the feeder. (On Debian systems use the group "www-data" rather than "apache".)

    If you don't get the permissions right on the feeder then you may find in the scheduler log file (cgi.log) the error message

    Can't attach shmem: -146 (feeder not running?)
    Even though the feeder may be running, it cannot communicate with the scheduler through shared memory if the permissions are not set correctly.

    Database Password and Accounts

    Earlier, when the database server was initialized, a master database account was created with the name 'root' and no password. Now you should add a password to the account. The command to do this is:
    # mysqladmin -u root password (whatever) # mysqladmin -u root -h `hostname` password (whatever)

    It is also a good idea to create two more database accounts:

    1. One database account is for use by the web server and BOINC daemons. It should only have the permissions required to perform daily work, it should not be able to alter the database structure or get information beyond this particular database. This is created by first connecting to the database server as the 'root' user, and then issuing a GRANT command to create a new account with the correct permissions, like so:
      # mysql -p -u root Password: mysql> use pirates; mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON * TO 'homestar' IDENTIFIED BY 'beleted';
      (You can type this all in lower case (except that the password is case-sensitive). I am just in the habit of typing SQL in upper case.) Don't forget the final semi-colon, which ends the SQL command.

      You will need to put this database user and password in the project configuration file, config.xml (see below).

    2. It can be useful to create another database user, with the same name as the Unix login you will use to manage the project, which has greater powers than the daemon account just created, but lesser powers than 'root'. That way you can use this Unix account to more easily modify the database, either for troubleshooting or when the BOINC software is updated. Here is how to do this:
      use pirates; mysql> GRANT ALL * TO 'boincadm' IDENTIFIED BY 'password'; mysql> GRANT ALL * TO 'boincadm'@'localhost' IDENTIFIED BY 'password'; mysql> quit
      The reason for two entries is that when you try to connect to the database from a shell on the machine which is running the server you end up connecting from 'localhost', which is different from any other hostname, so an additional entry is needed.
    Do not use this database account for day to day operation of your project. Be sure to use the more restricted account (eg. 'homestar') for that. Then if by chance some is able to crack into the project and issue commands to the database server they can only do limited damage. (They cannot, for example, drop an entire table, as demonstrated by this well known xkcd comic.) Use the 'boincadm' database account only to update the database schema or fix problems which can't be dealt with by using the restricted account. Keep this in mind when you upgrade your project, because you will need to use this more powerful database account to perform a database upgrade. Any upgrade changes to the database schema will (and should) fail with the more limited database account.

    You should verify that these accounts work, with commands like

    # mysql -p -u homestar -h `hostname` Password:
    Try it also without the -h and/or -u flags.

    The initial configuration of MySQL on Unix includes two "anonymous" accounts with no password. These only have access to "test" databases, but to really secure your server you may want to assign passwords to these accounts, or delete them altogether. To delete them:

    # mysql -u root mysql> DELETE FROM mysql.user WHERE User = '';
    When the dust settles, you can list all the database user accounts and verify that they all have passwords with:
    # mysql -u root mysql> SELECT User,Host,Password FROM mysql.user; +-----------+-----------------------+----------------------------------+ | User | Host | Password | +-----------+-----------------------+----------------------------------+ | root | localhost | *60A192DDF7927A05D1C1285381A6DE9 | | root | % | *60A192DDF7927A05D1C1285381A6DE9 | | homestar | % | *B35D43E87F6799FD62A19CCC96BD1D8 | | boincadm | % | *DBDC09C1ADAEBEEEF6658A21FCD21CF | | boincadm | localhost | *DBDC09C1ADAEBEEEF6658A21FCD21CF | +-----------+-----------------------+----------------------------------+

    Detailed instructions for securing the initial MySQL configuration can be found in the MySQL 5.0 Reference Manual, Sect 2.10.3

    Much more detailed information about managing a MySQL database, including user accounts, may be found in "Managing and Using MySQL" by George Reese, Randy Jay Yarker, and Tim King, with Hugh E. Williams, (O'Reilly, 2002) or any of the many other references on MySQL.

    Main project configuration - config.xml

    The main configuration of your BOINC project is controlled by a file called $PROJECT/config.xml. Running the make_project script creates this file, but you will need to edit it a bit to get your project started.

    In particular, you will need to add the database username and password for the 'daemon' database account created above.

    You may also find it useful to group items which affect similar things together, even though the default order does not do this.

    It can be useful to have a working example of this file to use as a reference. The configuration file for Pirates@Home (with some sensitive information altered) may be found here. (You may need to right-click and download the file if your browser won't view XML properly.)

    Complete documentation for the project configuration file can be found on the BOINC website and the BOINC wiki:

    One thing to keep in mind when you are starting out. Make sure that all the URL's in config.xml will work from the point of view of your client machines. Don't use a host name which may be in /etc/hosts on your server, but not in DNS or otherwise available to your clients. If you are working behind a firewall you may need to be careful about using internal -vs- external IP addresses, etc. The same comments apply to the URL of the scheduler, configured later (below).

    Daemon tasks

    A section of the config.xml file controls the operation of "daemon" tasks which run continuously to keep the project operating. At a minimum you need to run the transitioner and feeder. The transitioner controls changes of state for Results and Workunits as they make their way through the system. The feeder communicates database information to the scheduler CGI via shared memory. There is also a file deleter daemon, which deletes files that are no longer needed after a Workunit has finished. This is likely on by default in config.xml, but I recommend disabling it at first, so that you can more easily see that everything is functioning well. To do so, add the following to the <daemon> block for the file deleter:
    <disabled> 1 </disabled>

    Two other daemons need to be running to process returning Workunits: the "validator" and the "assimilator". When your project is running with the application you have written then you will likely also need to use custom-built versions of these daemons. But to get the project started you can use the sample versions. The name of the application needs to appear on the command line. The easiest way to get started is to copy from the configuration file for Pirates@Home.

    The Pirates@Home configuration file also shows an example of how to run the make_work program as a daemon, which is useful for testing your project. You will eventually have to write your own code to create work appropriate for your project's application. This is disabled in the example by default.

    Once you have the daemon tasks configured you can "start" the project with the command (run under your own Unix account or the one you set up to run the project, not root):

    % $PROJECT/bin/start
    Remember, you'll have to do this "by hand" when you reboot the machine.

    Periodic tasks

    Some tasks need to be performed periodically to keep the project functioning smoothly. These can include rotating logs, recording statistics, purging the database, updating user profile pages, and choosing the "User of the Day". These are all specified in a <tasks> block in the file config.xml. For example, the task which records run statistics every 12 hours is specified by:
    <task> <host>alvarez</host> <cmd>db_dump -d 1 -dump_spec ../db_dump.xml</cmd> <period> 12 hr </period> <output>db_dump.log</output> </task>
    The parameters used in creating the summary output are all in the file db_dump.xml in the main project directory.

    To see what other tasks might be performed this way, take a look at the Pirates@Home configuration file.

    These tasks are actually performed by running the command $PROJECT/bin/start --cron periodically from a cron job. So you need to edit your personal crontab (or the system crontab) and add the line similar to this:

    00,05,10,15,20,25,30,35,40,45,50,55 * * * * /usr02/pirates/bin/start --cron >/dev/null

    At some point one periodic task you will need to consider is rotation of your log files. This is described in more detail here:

    Scheduler configuration

    Clients connect to the project to get work via the "scheduler" in the cgi-bin directory. This has been named just "cgi" for historical reasons. I find it useful to make a copy in the same directory called scheduler, but you will find references to this in the BOINC literature as just "cgi".

    Clients can obtain the URL of the scheduler from a "link" tag on the project home page, of the form

    <link rel='boinc_scheduler' href='http://pirates.spy-hill.net/cgi-bin/scheduler'>

    Clients can also obtain the URL of scheduler(s) from a block of XML imbeded in a comment in the project home page. In the sample code provided by BOINC this is included in the home page from the file schedulers.txt . The file just contains a line like

    <scheduler>http://pirates.spy-hill.net/cgi-bin/cgi</scheduler>
    You should of course edit this to point to your own scheduler. You need to be sure that there are no trailing spaces between the URL and the closing tag. Apparently such spaces are not properly removed by some versions of the core client.

    The "link" tag, while prefered, is relatively new and only supported by newer BOINC clients (5.8.8 and onward). The "scheduler" tags are the "traditional" way the scheduler URL has been distributed, and this is the only way that older clients will find your scheduler. At present you are best advised to use both, while expecting that the "scheduler" tags will go away someday (but not anytime soon).

    Feeder configuration

    The scheduler needs to be able to communicate with the "feeder" daemon via shared memory. This will fail if the file permissions of both do not match. I recommend setting the feeder to run under group "apache" or "www-data". See the section above on File Permissions for details.

    Attach and Create an Account

    The easiest way to test your configuration is to attach to the project and create an account using the BOINC client. From some other machine, using the BOINC Manager window, pull down "Tools -> Attach to Project" and follow the dialog. If all goes well you will be attached to your new project and have created your first user account.

    If it doesn't work at first, this is a good time to debug the connection. You will find error messages in the messages area of the BOINC Manager on the client, in the log directory of your project, and in the web server logs on the server. You can verify with a browser that you can connect to the project main page, the download area, and the scheduler. (If the scheduler is working it will probably say something about your viewing the page with a broswer, which it's not set up to do, but that confirms that it is being run.) You might also put a test script in the cgi-bin to verify that you can connect to it and that CGI scripts are being run.

    Applications and Platforms

    While your server runs on a Unix system, your applications can be built for a variety of platforms (Windows, Mac, Linux, or others). Building BOINC applications is the subject of another long set of notes, which you will find here: Before you write your own application, it may be useful to start by building and running some simpler examples. The simplest is the Hello, World! program for BOINC. After that, you can work through the sequence of example applications: yello, cube, lalanne, and so on, which demonstrate successively more complicated aspects of writing BOINC applications.

    (If you are impatient to test your project server, and you are trusting of pirates, you can download the executable for the "hello" application from http://pirates.spy-hill.net/download.)

    For each application, once you have built the executable, you will need to add or update the application on the project site. Instructions for doing this can be found here:

    Briefly, to add a new application to the project you need to add it to the file project.xml and then run the xadd program. This file also controls which platforms your project supports (Windows, Mac, Linux, etc...).

    To run the application you will also need to put Workunit and Result template files in $PROJECT/templates. See the examples that come with the hello app and the other example apps.

    Site Customization

    When you first set up your BOINC project you need to do a few things customize the web pages and get everything working. Many project specific settings are set in the directory html/project. You need to create this directory. The easiest thing to do is to rename the directory html/project.sample (which comes with BOINC) to become html/project.

    Project Configuration

    A large number of parameters that control the web pages are in the file project.inc in the html/project directory. Edit these to match your requirments. In the same file you will find a number of functions you should customize. In particular, the function project_banner() controls the banner which is put at the top of every displayed web page.

    I have found it easiest to put all the new, separate functions I've created for my project in a separate file html/project/extras.php (you could name it anything you want) and then include that file from /html/project/project.inc. You could just as well put any project specific code in project.inc, but I think it's slightly easier to have a separation between the BOINC distributed code, even if it needs to be customized, and other code.

    The reason that you must rename certain sample files and directories is so that they will not be overwritten when you run the script to upgrade your project. That script will copy new versions of all files in the BOINC distribution, which would replace the custom versions if there were files in the distribution with the same names.

    Project Home Page

    The home page for your project is the file index.php in the html/user directory. A template file sample_index.php is provided in the BOINC distribution, but you need to customize it for your project. This page will also provide the URL of the scheduler (or schedulers) for your project, as already described previously.

    The sample provided with the BOINC code should only be considered a rudimentary outline. It does not provide very good navigation links or organization. If your project depends on volunteers then you will want to put some effort into making the home page functional, practical, attractive, and easy to use, or else you will find that you are not attracting as many volunteers as you might.

    Discussion Forums

    BOINC comes with software to support discusison forums so that participants can 'talk' with each other. When you set up a project you need to do two things to get the discussion forums started. You need to run a PHP script which creates the Categories for discussion and the Forums themselves under each Category. You also need to create the main index page for the discussion forums.

    The create_forums.php script in the html/ops directory contains functions to create forum Categories and Forums. It is not an easy file to read or edit, but you only have to do this once. One argument you give to create a catagory or forum is an ordering parameter; the categories are displayed in increasing Order number, and then the Forums in each Category are also displayed in increasing order based on this parameter. If you ever need to change the display order, the easiest way to do so right now is 'by-hand' via the command line using mySQL (sorry).

    These example files might make the task easier:

    The main index page for the discussion forums is a file called forum_index.php in the html/user directory. You can edit the template file forum_sample_index.php to provide a custom look for your project and to select the searching options you wish to provide.

    Front Page and RSS News

    The front page news (and an RSS feed) is currently set in the file project_news.inc in the html/project directory. The format is fairly simple and there are examples in the file. Edit this file whenever you want to add a news item to the RSS feed and front page news. (A nicer interactive RSS news management system is in the works, but it is not working yet. The news file will be in html/cache and will normally not need to be edited by hand.)

    Server Status Page

    There is a web page which shows an overview of server status, at html/user/server_status.php. It is not linked from the default project home page, so you may want to make a link to it from an appropriate place, so that both you and your project participants can see what the server is doing.

    Client Web Links

    Edit the file gui_urls.xml to provide links to your project directly from the BOINC Manager on client machines. Buttons appear on the left side of the manager when your project is selected under the "Projects" tab, and pressing one of the buttons starts a web browser which displays a paraticular web page.

    In addition to a link to the main project page, you can have links to the user's account or a page specific to the computer in use. Just don't over-do it.

    It's easist to modify an existing example. Here is the gui_urls.xml file for Pirates@Home.
    (You may need to right-click and download it, since it is an XML file).

    More information about the format and use of this feature may be found on the BOINC site:

    Control Panel

    The "control panel" pages are under html/ops. You need to restrict access to them, as described here.

    Note that it is also possible to use the same mechanism to restrict who you give work to, which can be useful while you are getting your project started. (In that case you put the .htaccess file in the cgi-bin directory, not html/ops).

    BSG Icons

    The newest BOINC Manager has a mode called the "BOINC Simple GUI" (BSG). You can define icon images which are shown in the BSG to represent both your project and your applications. You do this by editing the file project_files.xml in the main project directory.

    It's easist to modify an existing example. Here is the project_files.xml for Pirates@Home
    (You may need to right-click and download it, since it is an XML file).

    More information about the format and use of this feature may be found on the BOINC site:


    Please send corrections or suggestions for improvement to
    myers@spy-hill.net


    Last modified: 01 January 2012 Copyright © 2012 by Spy Hill Research http://www.spy-hill.net /~myers/help/boinc/Create_Project.html