Rooba
/
boinc
mirror of https://github.com/BOINC/boinc.git
1
0
Fork 0
Code Issues 1 Packages Projects Releases Wiki Activity

docs 

svn path=/trunk/boinc/; revision=809
This commit is contained in:
David Anderson 2003-01-14 19:30:21 +00:00
parent dfd13b720e
commit 833b7bcb2c
7 changed files with 114 additions and 390 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
INSTALL
View File

@ -1,215 +1,5 @@
Installing BOINC
This document describes the generic installation procedure for BOINC
The installation procedure itself is broken into seven steps
1. Downloading the Source
2. Ensuring proper programs are installed
3. Setting environment variables
4. Configuration
5. Building
6. Testing (optional but strongly recommended)
7. Final install (optional)
Please note that BOINC currently only supports the targets all clean install
uninstall tar and client_tar. Currently, BOINC is installed into the
/usr/local/boinc/ directory structure. To install BOINC into a different
directory structure, the macro INSTALL_DIR needs to be edited in all
Makefile.in files.
-------------------------------------------------------------------------------
Downloading the Source
BOINC is distributed via CVS, tarballs compressed with gzip, and Windows
zip files.
The BOINC distribution includes the scheduling servers, both in CGI and FastCGI
versions, the application library, the client, the test scripts, sample
applications, and test scripts.
Unpack the distribution in one directory using the commands
% gunzip boinc.tar.gz
% tar xf boinc.tar
If installing from CVS, download the entire CVS tree.
If installing on Windows, unzip boinc.zip or boinc.tar.gz. Next, unzip
win_build.zip inside the BOINC directory.
If installing on Mac OS X, unzip boinc.zip or boinc.tar.gz. Next, unstuff
mac_build.sit inside the BOINC directory.
-------------------------------------------------------------------------------
Ensuring proper programs are installed
In order for the BOINC server to run, Apache web server and mySQL database
server must both be installed and shared memory must be enabled, with a shared
memory segment size of at least 32 megabytes (more is reccomended).
It is highly reccomended that PHP be installed, as the test scripts and web
administration are written in PHP and will not be usable without PHP installed.
Apache should be configured to allow POST.
-------------------------------------------------------------------------------
Setting environment variables
BOINC depends on several environment variables to compile and run.
BOINC_DOWNLOAD_DIR /usr/local/boinc/download
This directory should be set to be web accessible via Apache. If you plan on
using a different directory, be sure to set the BOINC_DOWNLOAD_DIR properly
so as to point to the correct directory. It is important that this directory
is different from the BOINC_UPLOAD_DIR.
BOINC_UPLOAD_DIR /usr/local/boinc/upload
This directory should be set to be web accessible via Apache. If you plan on
using a different directory, be sure to set the BOINC_UPLOAD_DIR properly
so as to point to the correct directory. It is important that this directory is
different from the BOINC_DOWNLOAD_DIR.
BOINC_PLATFORM_NAME
This is set when configure is run in the client directory. It is used by the
client to determine the name of the BOINC client.
BOINC_EMAIL mgary@ssl.berkeley.edu
This is currently used by one of the test scripts. It is not critical for the
running of BOINC.
BOINC_KEY_DIR /usr/local/boinc/key_dir
This should be set to a directory in which the public and private keys for
BOINC are to be created. If you wish to place this in a different directory,
change the variable appropriately.
BOINC_SHMEM_KEY 0xdadacafe
This should be set to any 32 bit hex value desired. To run multiple instances
of BOINC on one machine, each instance needs to have a different BOINC_SHMEM_KEY
compiled into it.
BOINC_DB_NAME boinc
This should be set to a valid database name for mySQL.
BOINC_USER user
This should be set to the user name of the person running BOINC.
BOINC_UPLOAD_URL http://localhost/cgi-bin/file_upload_handler
This should be set to the url of a valid cgi directory where the BOINC
scheduling server cgi scripts are located.
BOINC_DOWNLOAD_URL http://localhost/download
This should be set to the url of the BOINC_DOWNLOAD_DIR.
BOINC_MASTER_URL http:\\\/\\\/localhost\\\/index.html
This should be set to the master url of your project. The master url is a file
that contains xml tags with information about where scheduling servers can be
found. A sample scheduler tag would be
<scheduler>http://localhost/cgi-bin/cgi</scheduler>
where the url contained within the scheduler tags points to the BOINC
scheduling server cgi scripts.
-------------------------------------------------------------------------------
Configuration
Like most open source software, BOINC must be configured before it can be
built. This document describes the recommended configuration procedure for
both native and cross targets.
We use srcdir to refer to the toplevel source directory for BOINC.
In general, BOINC need not be built into a seperate directory from the source.
Second, when configuring a native system, either cc or gcc must be in your path
or you must set CC in your environment variables before running configure.
Otherwise, the configuration scripts may fail.
To configure BOINC:
% cd srcdir
% ./configure
-------------------------------------------------------------------------------
Building
Now that BOINC is configured, you are ready to build BOINC.
Some commands executed when making BOINC may fail (return a nonzero status) and
be ignored by make.
It is normal to have compiler warnings when compiling certain files. The most
common of these warnings is statement with no effect, due to the use of assert
in the scheduling server, and can be safely ignored.
To make BOINC:
% cd srcdir
% make
-------------------------------------------------------------------------------
Testing
Once BOINC has been built, environment variables are set, and permissions have
been granted, we encourage you to run tests to ensure that BOINC is working
properly before being installed. The tests are located in the srcdir/test/
directory, and are all php scripts.
test_suite.php
This is a script that will run several of the scripts within the test
directory. If there are any file mismatches or errors, there has likely been an
error in setting up BOINC.
test_uc.php
This is a script that runs the uc application. The files should match upon
completion of the script.
test_concat.php
This sript is similar to the test_uc.php script, except that it runs the concat
application.
test_water.php
This script tests some of the water mark funtionality in the BOINC client. If
test_uc.php does not work, this script will also fail.
test_rsc.php
This script tests to ensure that the server will not send unfeasable work units
to a client. Should this script fail, it is either due to your computer having
more than 1 terabyte of available memory and similar amounts of available disk
space or improper configuration of BOINC.
test_api.php
This script should run even if BOINC has been installed improperly. As long as
a build has occurred, this script should work. This script tests the api and
a restartible minimal application without an end-to-end test of BOINC.
test_uc_slow.php
This script is similar to the test_uc.php script, except that it uses the
uc_slow application. The client must be run manually for this script. Currently
there is a bug in BOINC that causes this script to fail.
test_stderr.php
This script uses the uc application to check client error reporting.
-------------------------------------------------------------------------------
Installing
Now that BOINC has been built and tested, you can optionally install it in
/usr/local/boinc.
If the location of any of the CGI elements of the scheduling server are to be
changed, the appropriate environment variables must be updated and the code
must be rebuilt with
$ cd srcdir; make clean; configure; make
You can install BOINC in /usr/local/boinc with
% cd srcdir; make install
You may also want to run the test scripts now that you have installed BOINC to
ensure that all environment variables have been properly set and compiled into
the code.
-------------------------------------------------------------------------------
If you had any issues with BOINC, please let us know. If you come across any
bugs, please post them to our bugtraq or email us.
BOINC documentation is kept online at
http://boinc.berkeley.edu/create_project.html
The documentation is also part of the source tree
(in the doc/ directory).

89
INSTALL_CLIENT
View File

@ -1,89 +0,0 @@
Installing the BOINC client
This document describes the generic installation procedure for the BOINC client
The installation procedure itself is broken into four steps
1. Downloading the Source
2. Configuration
3. Building
4. Running the BOINC client
Please note that BOINC currently only supports the targets all clean install
uninstall tar and zip. Currently, BOINC is installed into the /usr/local/boinc/
directory structure. To install BOINC into a different directory structure,
the macro INSTALL_DIR needs to be edited in the client/Makefile.in file.
-------------------------------------------------------------------------------
Downloading the Source
BOINC is distributed via CVS, tarballs compressed with gzip, and Windows
zip files.
The BOINC client distribution includes the core client and the application
library.
Unpack the distribution in one directory using the commands
% gunzip boinc_client.tar.gz
% tar xf boinc_client.tar
If installing from CVS, the boinc/client, boinc/api, boinc/lib, and
boinc/RSAEuro directories must be downloaded. The boinc/doc directory may be
downloaded if documentation is desired.
If installing on Windows, unzip boinc_client.zip or boinc_client.tar.gz.
Next, unzip win_build.zip inside the BOINC directory.
If installing on Mac OS X, unzip boinc_client.zip or boinc_client.tar.gz.
Next, unstuff mac_build.sit inside the BOINC directory.
-------------------------------------------------------------------------------
Configuration
Like most open source software, BOINC must be configured before it can be
built. This document describes the recommended configuration procedure for
both native and cross targets.
We use srcdir to refer to the toplevel source directory for BOINC.
In general, BOINC need not be built into a seperate directory from the source.
Second, when configuring a native system, either cc or gcc must be in your path
or you must set CC in your environment variables before running configure.
Otherwise, the configuration scripts may fail.
To configure the BOINC client:
% cd srcdir/client
% ./configure
-------------------------------------------------------------------------------
Building
Now that BOINC is configured, you are ready to build BOINC
Some commands executed when making BOINC may fail (return a nonzero status) and
be ignored by make.
It is normal to have compiler warnings when compiling certain files. These
warnings can be safely ignored unless you are a member of the development team.
To make the BOINC client:
% cd srcdir/client
% make
-------------------------------------------------------------------------------
Running the BOINC client
The first time the BOINC client is run, it will prompt the user for some
information, including the master url of the project the user wishes to join
and an authenticator. The file will then attempt to contact the master url
to get information about scheduling servers and attempt to begin
working on the project. After this first time running, the output from the
BOINC client may be redirected to /dev/null. The client can accept two
command line options, -exit_when_idle, which will cause the client to exit
when a scheduling server replies with a no work available message, and the
-exit_after N, which will cause the client to exit after approximately N
seconds. It is recommended that a value of N greater than 100 be given when
using this option.

14
checkin_notes
View File

@ -2938,3 +2938,17 @@ David Jan 13 2003
test/
test.inc
test_loop.php
David Jan 14 2003
- Removed INSTALL_CLIENT and gutted INSTALL
NOTE: all docs should be in HTML
NOTE: spell-check all new documents
INSTALL
INSTALL_CLIENT (removed)
doc/
boinc_dev.html
road_map.html
single_host_server.html
test.html

20
doc/boinc_dev.html
View File

@ -16,9 +16,12 @@ Before sure that you understand exactly how BOINC is intended
to work (for both <a href=participate.html>participants</a>
and <a href=create_project.html>developers</a>)
before getting into the source code.
<p>
<font size=+1><b>
Core client
</b></font>
<ul>
<li> Core client
<ul>
<li> <a href=build.txt>Building the core client</a>
<li> <a href=client_files.html>File structure</a>
<li> <a href=client_fsm.html>FSM structure</a>
<li> <a href=client_data.html>Data structures</a>
@ -26,22 +29,27 @@ before getting into the source code.
<li> <a href=client_debug.html>Debugging</a>
<li> <a href=host_measure.html>Host measurements</a>
</ul>
<li> Scheduling server
<font size=+1><b>
Scheduling server
</b></font>
<ul>
<li> <a href=database.html>The BOINC database</a>
<li> <a href=sched_policy.html>Policy</a>
<li> <a href=sched_impl.html>Implementation</a>
<li> <a href=sched_debug.html>Debugging</a>
</ul>
<li> Protocols
<font size=+1><b>
Protocols
</b></font>
<ul>
<li> <a href=protocol.html>The scheduling server protocol</a>
<li> <a href=rpc_policy.html>Scheduling server timing and retry policies</a>
<li> <a href=upload.html>Data server protocol</a>
<li> <a href=pers_file_xfer.html>Persistent file transfers</a>
</ul>
<li> Miscellaneous
<font size=+1><b>
Miscellaneous
</b></font>
<ul>
<li> <a href=prefs_impl.html>Preferences</a>
</ul>
</ul>

43
doc/road_map.html
View File

@ -2,28 +2,21 @@
<body bgcolor=ffffff>
<h2>Source code road map</h2>
<p>
Unpacking the BOINC source code
creates the following directories:
<pre>
boinc/
RSAEuro/
api/
apps/
client/
win/
mac/
db/
doc/
html_ops/
html_user/
lib/
sched/
sched_fcgi/
test/
tools/
</pre>
BOINC is distributed via CVS, tarballs compressed with gzip, and Windows
zip files.
<ul>
<li>
If installing from CVS, download the entire CVS tree.
<li>
If installing on Windows, unzip boinc.zip or boinc.tar.gz,
and unzip win_build.zip inside the BOINC directory.
<li>
If installing on Mac OS X, unzip boinc.zip or boinc.tar.gz,
and unstuff mac_build.sit inside the BOINC directory.
</ul>
The directory contents are as follows:
<p>
Unpacking the BOINC source code creates the following directories:
<dl>
<dt> RSAEuro/
<dd> A public-domain RSA implementation.
@ -59,3 +52,11 @@ and file upload handler as Fast CGI programs.
<dt> tools/
<dd> Operational utility programs.
</dl>
<p>
On UNIX systems, the BOINC software (both server and client)
can be built by typing
<pre>
configure
make
</pre>
in the top directory.

4
doc/single_host_server.html
View File

@ -19,8 +19,10 @@ Install the following software on the server host:
<ul>
<li> MySQL, version 3.23 or later
<li> PHP, version 4.2.3 or later
<li> Apache, linked with the PHP module
<li> Apache, linked with the PHP module, POST enabled
</ul>
Your operating system must have shared memory enabled, with
a max shared segment size of at least 32 MB.
<h3>Directory structure</h3>

116
doc/test.html
View File

@ -88,61 +88,56 @@ class Project { // represents a project
function add_user($user); // add a User to project's DB
function add_app($app); // add an application
function add_app_version($app_version); // add an app version
function install(optional: $echeduler_file);
//set up directories and DB. If $scheduler_file is provided, then
//there will be installed schedulers at the directories pointed by
//the schedulers
function install(optional: $scheduler_file);
//set up directories and DB. If $scheduler_file is provided, then
//there will be installed schedulers at the directories pointed by
//the schedulers
function start(); // start feeder
function stop(); // stop feeder
function compare_file($out, $correct); // verify that a result file
// matches a known-correct file
function check_results($n, $result); // check that there are n results
// and that they match "result"
// (for all fields that are defined)
function compare_file($out, $correct);
// verify that a result file matches a known-correct file
function check_results($n, $result);
// check that there are n results
// and that they match "result"
// (for all fields that are defined)
//The functions below are used to interrupt or remove certain
//functionalities of the project for a desired time in order to be
//able to test persistance across these failures. All the
//parameters of the functions below are optional. If $time is not
//then action will be taken immediately, otherwise we sleep for
//$time seconds and then take action. $cgi_num,$download_dir_num,
//$handler_num refer to the number of the corresponding parts of
//the system to be disabled temporarily. if they are not
//the default cgi, download, and file_upload_handler respectively.
//multiple cgis can be handles with passing in a file with
//scheduler_urls to project->install. Multiple download URLS are
//handled by adding a numer in between the download_url and the
//file to be downloaded in the wu_template file of the Work class
//for example: <url><DOWNLOAD_URL/>0/<INFILE_0/></url>, in which
//a link from project_dir/download0/ will be added to project_dir/download
//Similiar action can be taken by modifying the result_template file
//of a Work class to handle multiple upload URLs:
//for example: <url><UPLOAD_URL/>0</url>, in which case
//file_upload_handler0 will be added to project_dir/cgi
// The functions below are used to interrupt or remove certain
// functionalities of the project for a desired time in order to be
// able to test persistence across these failures. All the
// parameters of the functions below are optional.
// $cgi_num,$download_dir_num,
// $handler_num refer to the number of the corresponding parts of
// the system to be disabled temporarily. if they are not
// the default cgi, download, and file_upload_handler respectively.
// multiple cgis can be handles with passing in a file with
// scheduler_urls to project->install. Multiple download URLS are
// handled by adding a numer in between the download_url and the
// file to be downloaded in the wu_template file of the Work class
// for example: <url><DOWNLOAD_URL/>0/<INFILE_0/></url>, in which
// a link from project_dir/download0/ will be added to project_dir/download
// Similiar action can be taken by modifying the result_template file
// of a Work class to handle multiple upload URLs:
// for example: <url><UPLOAD_URL/>0</url>, in which case
// file_upload_handler0 will be added to project_dir/cgi
function delete_masterindex($time) //deletes the index.php for
//this project
function reestablish_masterindex($time) //reestablished the master
//index.php
function delete_scheduler($time,$cgi_num)
//deletes project_dir/cgi/cgi$cgi$num
function reinstall_scheduler($time,$cgi_num)
//copies the cgi program into
//project_dir/cgi/cgi$cgi$num
function delete_downloaddir($time,$download_dir_number)
//removes
//project_dir/download$download_dir_num
function reinstall_downloaddir($time,$download_dir_num)
//reestablished
//project_dir/download$download_dir_num
function remove_file_upload_handler($time,$handler_num)
//deletes
//project_dir/cgi/file_upload_handdler$handler_num
function reinstall_file_upload_handler($time, $handler_num)
//reinstalls
//project_dir/cgi/file_upload_handdler$handler_num
function kill_file_upload_hanlder() //blocks until a file_upload_handler is
//running in the system, kills it and returns
function delete_masterindex()
//deletes the index.php for this project
function reestablish_masterindex()
//reestablished the master index.php
function delete_scheduler($cgi_num)
//deletes project_dir/cgi/cgi$cgi$num
function reinstall_scheduler($cgi_num)
//copies the cgi program into project_dir/cgi/cgi$cgi$num
function delete_downloaddir($download_dir_number)
//removes project_dir/download$download_dir_num
function reinstall_downloaddir($download_dir_num)
//reestablished project_dir/download$download_dir_num
function remove_file_upload_handler($handler_num)
//deletes project_dir/cgi/file_upload_handler$handler_num
function reinstall_file_upload_handler($handler_num)
//reinstalls project_dir/cgi/file_upload_handler$handler_num
function kill_file_upload_handler() //blocks until a file_upload_handler is
//running in the system, kills it and returns
}
class User { // represents an account on a project
@ -157,9 +152,9 @@ class Host { // represents a (virtual) host
function install();
//There are two run functions, one that blocks until the client
//being run by this host finishes exection: run() and then there
//being run by this host finishes execution: run() and then there
//run_asynch which spawns a new php process running the client
//and returns to the thread of exection of the parent php process
//and returns to the thread of execution of the parent php process
//the php process_id of the child. This process_id can then be
//used for a call to pcntl_waitpid() to block until the execution
//of the client.
@ -352,18 +347,21 @@ You have to run the client yourself, kill and restart it a few times.
feasible work units.
<li>
<b>test_pers.php</b>: tests the persistent file transfers for
download and upload. It interrupts them in the middle and makes
download and upload.
It interrupts them in the middle and makes
sure that the filesize never decreases along interrupted transfers.
<li>
<b>test_masterurl_failure.php</b>: tests the exponential backoff
mechanism on the client in case of master IURL failures.
This test is not automated. It has to be run, and then client.out
(in the host directory) must be looked at to examine wether everything
This test is not automated.
It has to be run, and then client.out
(in the host directory) must be looked at to examine whether everything
is working correctly.
<li>
<b>test_sched_failure.php</b>:tests the exponential backoff mechanism
on the client in case of scheduling server failures.This test is not
automated. It has to be run, and then client.out (in the host
directory) must be looked at to examine wether everything
on the client in case of scheduling server failures.
This test is not automated.
It has to be run, and then client.out (in the host
directory) must be looked at to examine whether everything
is working correctly.
</ul>