| VASSAR COLLEGE |
| Department of Pirates |
|
|
|
|
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
|
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:
) 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.
[an error occurred while processing this directive]
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.
A complete list of software dependencies, including the minimum required
versions, may be found on the BOINC site at:
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.
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.
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.
How to get the source code and a roadmap of the source tree are
provided at
A very quick summary of the process is given by this example:
Here is a quick example:
This creates /usr02/pirates and a number of subdirectories
under it.
The full directory structure is documented at
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.
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.
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).
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.
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.
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
[an error occurred while processing this directive]
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.
% 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.
# cd boinc/tools/
# ./make_project -v --project_root /usr02/pirates pirates Pirates@Home
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.
Except that as of this writing it's not the complicated version.
We should probably show both.
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
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:
# 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.) [an error occurred while processing this directive]
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.)
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
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:
Now, to change the user/group ownership of the entire directory tree
the command (as root) would be something like:
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:
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
[an error occurred while processing this directive]
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
It is also a good idea to create two more database accounts:
You will need to put this database user and password in the project
configuration file, config.xml (see below).
You should verify that these accounts work, with commands like
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:
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.
[an error occurred while processing this directive]
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).
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):
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:
At some point one periodic task you will need to consider is rotation
of your log files.
This is described in more detail here:
[an error occurred while processing this directive]
Clients can obtain the URL of the scheduler from a "link" tag on the
project home page, of the form
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
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).
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.
[an error occurred while processing this directive]
(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:
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.
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.
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.
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.
[an error occurred while processing this directive]
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.
More information about the format and use of this feature may be found
on the BOINC site:
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).
It's easist to modify an existing example.
Here is the
project_files.xml for Pirates@Home
More information about the format and use of this feature may be found
on the BOINC site:
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.
# setenv PROJECT /usr02/pirates
using, of course, your own project root directory. If you prefer bash
then use
# export PROJECT=/usr02/pirates
# $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.)
# 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.
$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.
# 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".)
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.
[an error occurred while processing this directive]
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)
# 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.
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.
# mysql -p -u homestar -h `hostname`
Password:
Try it also without the -h and/or -u flags.
# 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 |
+-----------+-----------------------+----------------------------------+
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.
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>
% $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.
00,05,10,15,20,25,30,35,40,45,50,55 * * * * /usr02/pirates/bin/start --cron >/dev/null
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".
<link rel='boinc_scheduler' href='http://pirates.spy-hill.net/cgi-bin/scheduler'>
<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.
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.
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.
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.
[an error occurred while processing this directive]
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.
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.
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.
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.
(You may need to right-click and download it,
since it is an XML file).
Control Panel
The "control panel" pages are under html/ops. You need
to restrict access to them, as described
here.
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.
(You may need to right-click and download it, since it is an XML file).