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

cleaned up docs 

svn path=/trunk/boinc/; revision=351
This commit is contained in:
David Anderson 2002-08-19 18:43:10 +00:00
parent b635209bc6
commit 3eb85774bf
38 changed files with 702 additions and 1415 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
client/client_state.C
View File

@ -385,7 +385,7 @@ int CLIENT_STATE::exit_tasks() {
//
int CLIENT_STATE::write_state_file() {
unsigned int i, j;
FILE* f = fopen(STATE_FILE_TEMP, "wb");
FILE* f = fopen(STATE_FILE_TEMP, "w");
int retval;
if (log_flags.state_debug) {

26
doc/app.html
View File

@ -1,21 +1,14 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Platforms, Applications, and Versions</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Platforms, Applications, and Versions</title>
<h2>Platforms, Applications, and Versions</h2>
<p>
A <b>platform</b> is a compilation target (Windows/Intel,
A <b>platform</b> is a compilation target (Windows/Intel,
Linux/Intel, MacOS/PPC, etc.).
Platforms are maintained in the <b>platform</b> table in the BOINC
DB, and can be created using the <a href="tools.html">add</a>
utility program.
<p>
An <b>application</b> is a computational task; in concrete terms it
An <b>application</b> is a computational task; in concrete terms it
consists of an executable program (perhaps in versions for various
platforms) and a set of input files to be processed by the program.
A project can operate many applications.
@ -24,15 +17,15 @@ BOINC DB, and can be created using the <a href="tools.html">add</a>
utility.
<p>
An application program may go through a sequence of <a
href="version.html">versions</a>.
An application program may go through a sequence of
<ahref="version.html">versions</a>.
A particular version, compiled for a particular platform, is
called an <b>application version</b>.
An application version can consist of multiple files: for example, a
controller script, pre- and post-processing programs, and a primary.
<p>
Each application version has an integer <b>version number</b>.
Each application version has an integer <b>version number</b>.
Projects can assign version numbers however they like; for example,
version 304 might represent major version 3 and minor version 4.
Version numbers should be used consistently across platforms;
@ -40,13 +33,13 @@ Windows version 304 should be computationally identical to
Mac version 304.
<p>
Each application has a <b>minimum version</b>.
Each application has a <b>minimum version</b>.
When a client is sent work for an application, it is also sent
the latest application version for its platform.
It is sent work only if this version is the minimum or greater.
<p>
Application version are maintained in the <b>app_version</b> table
Application version are maintained in the <b>app_version</b> table
in the BOINC DB, Each entry includes an XML document describing the
files that make up the application version:
<pre>
@ -67,6 +60,3 @@ files that make up the application version:
&lt;/app_version&gt;
</pre> The <a href="tools.html">add</a> utility program provides a
simplified interface for creating application versions.
</body>
</html>

41
doc/back_end.html
View File

@ -1,46 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Back End Examples</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Back End Examples</title>
<h2>Back End Examples</h2>
<p>
Here are some examples of the "back ends" that could be used by
Here are some examples of the "back ends" that could be used by
various types of project.
</p>
<p>
<b>SETI@home with local data servers</b>
</p>
<b>SETI@home with local data servers</b>
<ul>
<li>
A <b>splitter program</b> generates data files. For each data
<li> A <b>splitter program</b> generates data files. For each data
file, calls the BOINC server library to create a workunit record and
several result records, and stores the data file on disk of a data
server.
</li>
<li>
A <b>garbage collector</b> program deletes data files for which
enough results have been returned. Generates new result records as
needed.
</li>
<li>
A <b>result handler</b> program checks for new results. Parses
<li> A <b>garbage collector</b> program deletes data files for which
enough results have been returned.
Generates new result records as needed.
<li> A <b>result handler</b> program checks for new results. Parses
result files, and transfers contents to a separate "science database".
Does redundancy checking, and marks result records as valid or invalid.
</li>
</ul>
<p>
</p>
<b>SETI@home with remote data servers</b>
<p>
As above, but the splitter program writes data files to DLT tape.
As above, but the splitter program writes data files to DLT tape.
The result records are generated, using the URL of a selected data
server. The tape is mailed to the data server. An operator at the data
server.
The tape is mailed to the data server.
An operator at the data
server transfers the files to disk, than uses a web control panel to
mark the batch as ready, which marks the result records as ready.
</p>
</body>
</html>

21
doc/batch.html
View File

@ -1,21 +1,10 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Batches</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Batches</title>
<h2>Batches</h2>
<p>
Workunits and results can be grouped together into <b>batches</b>.
Each batch is represented by an integer. Results must belong to the same
batch as their workunit.
</p>
Workunits and results can be grouped together into <b>batches</b>.
Each batch is represented by an integer.
Results must belong to the same batch as their workunit.
<p>
BOINC provides tools for manipulating workunits and results by
BOINC provides tools for manipulating workunits and results by
batch: e.g., for changing the status of all results in a batch from
"inactive" to "unsent".
</p>
</body>
</html>

24
doc/client_data.html
View File

@ -1,18 +1,9 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Data Structures</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: Data Structures</title>
<h2>Core Client: Data Structures</h2>
<p>
The key data structures in the core client are as follows.
</p>
The key data structures in the core client are as follows.
<p>
Basic types:
</p>
Basic types:
<pre>
PROJECT
APP
@ -21,16 +12,13 @@ APP_VERSION
IO_FILE_DESC
WORKUNIT
RESULT
</pre> <pre>ACCOUNTS</pre> Contains a vector of PROJECTs, summarizing
</pre>
<pre>ACCOUNTS</pre> Contains a vector of PROJECTs, summarizing
the accounts file.
<p>
</p>
<pre>CLIENT_STATE</pre>
<p>
Contains vectors of all the basic types. These are crossed-linked
Contains vectors of all the basic types. These are crossed-linked
with pointers; for example, APP_VERSION has a pointer to FILE_INFO. Also
contains FSM sets for network connections, HTTP operations, file
transfers, and active tasks.
</p>
</body>
</html>

125
doc/client_debug.html
View File

@ -1,102 +1,55 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Debugging</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<h2>Core Client: Debugging</h2> <h3>Core client logging and error
output</h3>
<title>Core Client: Debugging</title>
<h2>Core Client: Debugging</h2> <h3>Core client logging and error output</h3>
<p>
The core client writes error messages to stderr. This mechanism is
reserved for serious problems, i.e. those that reflect bugs in the core
The core client writes error messages to stderr.
This mechanism is reserved for serious problems,
i.e. those that reflect bugs in the core
client program or conditions that require user intervention.
Specifically, The client verifies that arguments to functions have valid
values, and will print a message to stderr on an invalid argument. These
error messages are formatted as <tt>error: CLASS_NAME.function:
error_statement argument</tt>. Common errors of this type include
unexpected NULL pointer arguments and negative lengths. Error numbers
values, and will print a message to stderr on an invalid argument.
These error messages are formatted as <tt>error: CLASS_NAME.function:
error_statement argument</tt>.
Common errors of this type include
unexpected NULL pointer arguments and negative lengths.
Error numbers
are defined in <b>lib/error_numbers.h</b>.
</p>
<p>
In addition, the core client can write a variety of "logging"
information to stdout. The logging options are read from a file
<b>log_flags.xml</b>. This file has the following format:
</p>
In addition, the core client can write a variety of "logging"
information to stdout.
The logging options are read from a file
<b>log_flags.xml</b>.
This file has the following format:
<pre>
&lt;log_flags&gt;
[ flags ]
&lt;/log_flags&gt;
</pre> The flags are as follows:
</pre>
The flags are as follows:
<dl>
<dt>
&lt;task/&gt;
</dt>
<dd>
Log the start, restart and completion of computational tasks.
</dd>
<dt>
&lt;file_xfer/&gt;
</dt>
<dd>
Log the start, restart and completion of file transfers.
</dd>
<dt>
&lt;sched_ops/&gt;
</dt>
<dd>
Log connections with scheduling servers.
</dd>
<dt>
&lt;state_debug/&gt;
</dt>
<dd>
Log changes to the "client state" data structures.
</dd>
<dt>
&lt;task_debug/&gt;
</dt>
<dd>
Log debugging information about task execution.
</dd>
<dt>
&lt;file_xfer_debug/&gt;
</dt>
<dd>
Log debugging information about file transfers.
</dd>
<dt>
&lt;sched_op_debug/&gt;
</dt>
<dd>
Log the request and reply messages of exchanges with scheduling
<dt> &lt;task/&gt;
<dd> Log the start, restart and completion of computational tasks.
<dt> &lt;file_xfer/&gt;
<dd> Log the start, restart and completion of file transfers.
<dt> &lt;sched_ops/&gt;
<dd> Log connections with scheduling servers.
<dt> &lt;state_debug/&gt;
<dd> Log changes to the "client state" data structures.
<dt> &lt;task_debug/&gt;
<dd> Log debugging information about task execution.
<dt> &lt;file_xfer_debug/&gt;
<dd> Log debugging information about file transfers.
<dt> &lt;sched_op_debug/&gt;
<dd> Log the request and reply messages of exchanges with scheduling
servers.
</dd>
<dt>
&lt;http_debug/&gt;
</dt>
<dd>
Log debugging information about HTTP operations.
</dd>
<dt>
&lt;time_debug/&gt;
</dt>
<dd>
Log the passage of time.
</dd>
<dt>
&lt;net_xfer_debug/&gt;
</dt>
<dd>
Log debugging information about network communication.
</dd>
<dt> &lt;http_debug/&gt;
<dd> Log debugging information about HTTP operations.
<dt> &lt;time_debug/&gt;
<dd> Log the passage of time.
<dt> &lt;net_xfer_debug/&gt;
<dd> Log debugging information about network communication.
</dl>
<h3>Application error output</h3>
<p>
The stderr of applications is automatically directed to a file. The
The stderr of applications is automatically directed to a file. The
contents of this file are returned to the scheduling server and stored
in the database.
</p>
</body>
</html>

38
doc/client_files.html
View File

@ -1,41 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: File Structure</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: File Structure</title>
<h2>Core Client: File Structure</h2>
<p>
The core client runs in a BOINC home directory. An account file
(accounts.xml) must be present in this directory. The core client
The core client runs in a BOINC home directory.
An account file (accounts.xml) must be present in this directory.
The core client
creates and uses the following files and directories within the BOINC
home directory:
</p>
<ul>
<li>
<b>client_state.xml</b>: this is an description of the files,
<li>
<b>client_state.xml</b>: this is an description of the files,
application, workunits and results present on this client.
</li>
<li>
Each project has a <b>project subdirectory</b> whose name is the
project's base URL. This subdirectory contains all files (inputs,
<li>
Each project has a <b>project subdirectory</b> whose name is the
project's base URL.
This subdirectory contains all files (inputs,
outputs, executables) related to the project.
</li>
<li>
<b>slots</b>: this directory contains one subdirectory for each
<li>
<b>slots</b>: this directory contains one subdirectory for each
CPU "slot" (normally there are as many slots as the host has CPUs). The
subdirectories are named 0, 1, ... N-1.
</li>
</ul>
<p>
Each result executes in particular slot. The core client creates
Each result executes in particular slot. The core client creates
symbolic links (UNIX) or .lnk files (Windows) in the slot directory,
linking the input, output and executable files to the appropriate files
in the project directory. On UNIX, the core client uses chroot() so that
the application sees the slot directory as the root of its filesystem,
and cannot create or access files outside of it.
</p>
</body>
</html>

73
doc/client_fsm.html
View File

@ -1,72 +1,45 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Finite-State Machine (FSM) Structure</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: Finite-State Machine (FSM) Structure</title>
<h2>Core Client: Finite-State Machine (FSM) Structure</h2>
<p>
The core client can perform many activities (file transfers,
computations, RPCs to scheduling servers) in parallel. To manage this
parallelism, the core client is structures as a number of
<b>finite-state machines</b> (FSM). For example, an HTTP transaction is
The core client can perform many activities (file transfers,
computations, RPCs to scheduling servers) in parallel.
To manage this parallelism, the core client is structures as a number of
<b>finite-state machines</b> (FSM).
For example, an HTTP transaction is
represented by an FSM whose states might include:
</p>
<ul>
<li>
Waiting for connection establishment.
</li>
<li>
Waiting to send request header.
</li>
<li>
Waiting to send send request body.
</li>
<li>
Waiting for reply header.
</li>
<li>
Waiting for reply body.
</li>
<li>
Finished.
</li>
<li> Waiting for connection establishment.
<li> Waiting to send request header.
<li> Waiting to send send request body.
<li> Waiting for reply header.
<li> Waiting for reply body.
<li> Finished.
</ul>
<p>
FSMs of a particular type are managed by an <b>FSM container</b>.
FSMs of a particular type are managed by an <b>FSM container</b>.
Each FSM container manages a set of FSMs, and provides a <b>poll()</b>
function for detecting and performing state transitions. These functions
are nonblocking.
</p>
<p>
The core client uses the following FSM types:
</p>
The core client uses the following FSM types:
<ul>
<li>
<b>NET_XFER</b> (container: <b>NET_XFER_SET</b>). Each instance
<li>
<b>NET_XFER</b> (container: <b>NET_XFER_SET</b>). Each instance
represents a network connection, for which data is being transferred
to/from memory or a disk file. The <b>poll()</b> function uses
<b>select()</b> to manage the FSM without blocking.
</li>
<li>
<b>HTTP_OP</b> (container: <b>HTTP_OP_SET</b>). Each instance
<li>
<b>HTTP_OP</b> (container: <b>HTTP_OP_SET</b>). Each instance
represents an HTTP operation (GET, PUT or POST).
</li>
<li>
<b>FILE_XFER</b> (container: <b>FILE_XFER_SET</b>). Each
<li>
<b>FILE_XFER</b> (container: <b>FILE_XFER_SET</b>). Each
instance represents a file transfer (upload or download) in progress.
</li>
<li>
<b>ACTIVE_TASK</b> (container: <b>ACTIVE_TASK_SET</b>). Each
<li>
<b>ACTIVE_TASK</b> (container: <b>ACTIVE_TASK_SET</b>). Each
instance represents a running application.
</li>
</ul>
<p>
An FSM may be implemented using other FSMs; for example, FILE_XFER
An FSM may be implemented using other FSMs; for example, FILE_XFER
is implemented using HTTP_OP, which in turn is implemented using
NET_XFER.
</p>
</body>
</html>

12
doc/client_logic.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Logic</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: Logic</title>
<h2>Core Client: Logic</h2>
<p>
</p>
</body>
</html>

12
doc/client_network.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Network Scheduling and Retry Policy</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: Network Scheduling and Retry Policy</title>
<h2>Core Client: Network Scheduling and Retry Policy</h2>
<p>
</p>
</body>
</html>

12
doc/comp_examples.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Examples</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Compute Model: Examples</title>
<h2>Compute Model: Examples</h2>
<p>
</p>
</body>
</html>

92
doc/database.html
View File

@ -1,82 +1,40 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>The BOINC Database</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>The BOINC Database</title>
<h2>The BOINC Database</h2>
<p>
BOINC uses a relational database to keep track of participants, work
and result. The reference implementation uses MySQL, but any SQL
database can be used.
</p>
BOINC uses a relational database to keep track of participants, work
and result.
The reference implementation uses MySQL, but any SQL database can be used.
<p>
In boinc/html_user/ there is a file called db_name containing only the
name of the database for that project. Each BOINC project will have a different database
name. This allows for access to different databases through the webpages of projects.
In boinc/html_user/ there is a file called db_name containing only the
name of the database for that project.
Each BOINC project will have a different database name.
This allows for access to different databases through the webpages of projects.
<p>
The database tables are as follows:
</p>
The database tables are as follows:
<dl>
<dt>
platform
</dt>
<dd>
Compilation targets of the core client and/or applications.
</dd>
<dt>
app
</dt>
<dd>
Applications. The core client is treated as an application; its
<dt> platform
<dd> Compilation targets of the core client and/or applications.
<dt> app
<dd> Applications. The core client is treated as an application; its
name is "core_client".
</dd>
<dt>
app_version
</dt>
<dd>
Versions of applications. Each record includes a URL for
<dt> app_version
<dd> Versions of applications. Each record includes a URL for
downloading the executable, and the MD5 checksum of the executable.
</dd>
<dt>
user
</dt>
<dd>
Describes users, including their email address, name, web
<dt> user
<dd> Describes users, including their email address, name, web
password, and authenticator.
</dd>
<dt>
preferences
</dt>
<dd>
Describes preferences. The actual preference information is
<dt> preferences
<dd> Describes preferences. The actual preference information is
stored in an XML document in a "blob" field of this table.
</dd>
<dt>
host
</dt>
<dd>
Describes hosts.
</dd>
<dt>
workunit
</dt>
<dd>
Describes workunits. The input file descriptions are stored in
<dt> host
<dd> Describes hosts.
<dt> workunit
<dd> Describes workunits. The input file descriptions are stored in
an XML document in a blob field. Includes counts of the number of
results linked to this workunit, and the numbers that have been sent,
that have succeeded, and that have failed.
</dd>
<dt>
result
</dt>
<dd>
Describes results. Includes a "state" (whether the result has
<dt> result
<dd> Describes results. Includes a "state" (whether the result has
been dispatched). Stores a number of items relevant only after the
result has been returned: CPU time, exit status, and validation status.
</dd>
</dl>
</body>
</html>

12
doc/dev.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Application Development</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Application Development</title>
<h2>Application Development</h2>
<p>
</p>
</body>
</html>

28
doc/file_access.html
View File

@ -1,26 +1,18 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Remote File Access</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Compute Model: Remote File Access</title>
<h2>Compute Model: Remote File Access</h2>
<p>
Output files can be designated as sticky but not
upload-when-present. Sometimes this is done because the file will be
Output files can be designated as sticky but not
upload-when-present.
Sometimes this is done because the file will be
used as an input for a later workunit; it may also be done to spread
large output data across participant disks, in cases where the data may
be too large to store on the project back-end.
</p>
<p>
To access such a file, the back end inserts a <b>file access
request</b> in the database. This specifies a file and a data-server
URL. When a host storing the file contacts the scheduling server (which
To access such a file, the back end inserts a <b>file access
request</b> in the database.
This specifies a file and a data-server URL.
When a host storing the file contacts the scheduling server (which
may not happen for a while) the scheduling server forwards the file
access request. The host confirms the file transfer when it is
access request.
The host confirms the file transfer when it is
completed; the back-end must poll for this event.
</p>
</body>
</html>

12
doc/file_xfer_policy.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Core Client: Network Scheduling and Retry Policy</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Core Client: Network Scheduling and Retry Policy</title>
<h2>Core Client: Network Scheduling and Retry Policy</h2>
<p>
</p>
</body>
</html>

102
doc/files.html
View File

@ -1,19 +1,12 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Storage</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<h2>Compute Model: Storage</h2> <h3>Files</h3>
<title>Compute Model: Storage</title>
<h2>Compute Model: Storage</h2>
<h3>Files</h3>
<p>
The BOINC storage model is based on <b>files</b>. The inputs and
The BOINC storage model is based on <b>files</b>.
The inputs and
outputs of applications, and the applications executables, are files.
</p>
<p>
A file is described by an XML element of the form
</p>
A file is described by an XML element of the form
<pre>
&lt;file_info&gt;
&lt;name&gt;foobar&lt;/name&gt;
@ -27,56 +20,39 @@ outputs of applications, and the applications executables, are files.
[ &lt;upload_when_present/&gt; ]
[ &lt;sticky/&gt; ]
&lt;/file_info&gt;
</pre> The components are as follows:
</pre>
The components are as follows:
<ul>
<li>
The <b>&lt;name&gt;</b> element gives the file's name, which
<li> The <b>&lt;name&gt;</b> element gives the file's name, which
must be unique within the project.
</li>
<li>
Each <b>&lt;url&gt;</b> element gives a URL where the file is
<li> Each <b>&lt;url&gt;</b> element gives a URL where the file is
(or will be) located on a data server.
</li>
<li>
The <b>&lt;md5_cksum&gt;</b> element is the MD5 checksum of the
<li> The <b>&lt;md5_cksum&gt;</b> element is the MD5 checksum of the
file, providing protection against corruption and spoofing.
</li>
<li>
The <b>&lt;nbytes&gt;</b> element is the size of the file in
<li> The <b>&lt;nbytes&gt;</b> element is the size of the file in
bytes (may be greater than 2^32).
</li>
<li>
The <b>&lt;max_nbytes&gt;</b> element is the maximum allowable
size of the file in bytes (may be greater than 2^32). This is used to
prevent flooding data servers with bogus data.
</li>
<li>
The <b>&lt;sticky&gt;</b> element, if present, indicates that
<li> The <b>&lt;max_nbytes&gt;</b> element is the maximum allowable
size of the file in bytes (may be greater than 2^32).
This is used to prevent flooding data servers with bogus data.
<li> The <b>&lt;sticky&gt;</b> element, if present, indicates that
the file should be retained on the client after its initial use.
</li>
<li>
The <b>&lt;upload_when_present&gt;</b> element, if present,
<li> The <b>&lt;upload_when_present&gt;</b> element, if present,
indicates that the file should be uploaded after it is created.
</li>
<li>
The <b>&lt;executable&gt;</b> element, if present, indicates
<li> The <b>&lt;executable&gt;</b> element, if present, indicates
that the file protections should be set to allow execution.
</li>
</ul>
These attributes allow the specification of various types of files: for
example, input or output files that are retained for use as input to
later computations.
<p>
Once a file is created (on a data server or a participant host) it
Once a file is created (on a data server or a participant host) it
is immutable.
</p>
<h3>File references</h3>
<p>
Files may be associated with <a href="work.html">workunits</a>, <a
href="result.html">results</a> and <a href="app.html">application
versions</a>. Each such association is represented by an XML element of
the form
</p>
Files may be associated with <a href="work.html">workunits</a>,
<a href="result.html">results</a> and
<a href="app.html">application versions</a>.
Each such association is represented by an XML element of the form
<pre>
&lt;file_ref&gt;
&lt;file_name&gt;foobar&lt;/file_name&gt;
@ -84,28 +60,20 @@ the form
[ &lt;fd&gt;2&lt;/fd&gt; ]
[ &lt;main_program/&gt; ]
&lt;/file_ref&gt;
</pre> The components are as follows:
</pre>
The components are as follows:
<ul>
<li>
The <b>&lt;file_name&gt;</b> element specifies a file.
</li>
<li>
The <b>&lt;open_name&gt;</b> element, if present, is the name by
<li> The <b>&lt;file_name&gt;</b> element specifies a file.
<li> The <b>&lt;open_name&gt;</b> element, if present, is the name by
which the application will refer to the file (in a call to
<b>fopen()</b>, for example). Note that this file will usually be a
<b>fopen()</b>, for example).
Note that this file will usually be a
BOINC soft link rather than the actual file.
</li>
<li>
The <b>&lt;fd&gt;</b> element, if present, indicates the file
descriptor number by which the application will access the file. This
file descriptor will only be set up if the application calls the API
<li> The <b>&lt;fd&gt;</b> element, if present, indicates the file
descriptor number by which the application will access the file.
This file descriptor will only be set up if the application calls the API
function <tt>boinc_init</tt>.
</li>
<li>
The <b>&lt;main_program&gt;</b> element is used for files
associated with application versions. It indicates that this file is the
application's main program.
</li>
<li> The <b>&lt;main_program&gt;</b> element is used for files
associated with application versions.
It indicates that this file is the application's main program.
</ul>
</body>
</html>

42
doc/flow.html
View File

@ -1,41 +1,29 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Work Distribution</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Compute Model: Work Distribution</title>
<h2>Compute Model: Work Distribution</h2>
<p>
Results are not necessarily dispatched one at a time. Instead, each
participant host maintains an estimate of the amount of work remaining
(i.e. the time until one of its processors will be idle). Each host also
Results are not necessarily dispatched one at a time.
Instead, each participant host
maintains an estimate of the amount of work remaining
(i.e. the time until one of its processors will be idle).
Each host also
has two scheduling parameters, the <b>high-water mark</b> and the
<b>low-water mark</b> (these are part of the host's "preferences",
discussed later).
</p>
<p>
Normally the work remaining is between the high- and low-water
marks. When the work remaining reaches the low-water mark, the core
Normally the work remaining is between the high- and low-water marks.
When the work remaining reaches the low-water mark, the core
client contacts one or more scheduling servers, and attempts to get
enough work to exceed the high-water mark. The scheduling server sends a
maximum of four weeks of work. If a work unit is not feasible for a host
enough work to exceed the high-water mark.
The scheduling server sends a maximum of four weeks of work.
If a work unit is not feasible for a host
because it consumes too many system resources, the scheduling server
will not send that work unit.
</p>
<p>
The amount of work (measured in FP/int ops) sent in a single
scheduling RPC can be limited by the project, on a per-application
basis.
</p>
The amount of work (measured in FP/int ops) sent in a single
scheduling RPC can be limited by the project, on a per-application basis.
<p>
This scheme allows hosts that are sporadically connected (because
This scheme allows hosts that are sporadically connected (because
they're portable or have modem-based connections) to avoid becoming idle
due to lack of work.
</p>
<p>
<b>To do</b>: per-workunit flag saying to return the result ASAP?
</p>
</body>
</html>
<b>To do</b>: per-workunit flag saying to return the result ASAP?

86
doc/host_measure.html
View File

@ -1,86 +1,58 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Measuring and Distinguishing Hosts</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Measuring and Distinguishing Hosts</title>
<h2>Measuring and Distinguishing Hosts</h2>
<p>
The core client measures the following aspects of each host:
</p>
The core client measures the following aspects of each host:
<ul>
<li>
<b>CPU performance</b>: integer ops/sec, double-precision
<li> <b>CPU performance</b>: integer ops/sec, double-precision
floating-point ops/sec, and memory bandwidth are measured separately.
They are measured by a process executing at the same priority as BOINC
applications, so the results will be affected by other processes. These
measurements are taken when the client starts for the first time, and
once every month aftewards.
</li>
<li>
<b>Number of CPUs</b>: By default, the number of simultaneous
<li> <b>Number of CPUs</b>: By default, the number of simultaneous
slot directories will be set to this number unless otherwise indicated
by user preferences.
</li>
<li>
<b>Vendor and model of CPU</b>
</li>
<li>
<b>Disk space</b>: free space and total space on the drive which
<li> <b>Vendor and model of CPU</b>
<li> <b>Disk space</b>: free space and total space on the drive which
BOINC is installed on. These numbers will be used to ensure BOINC does
not use more space than set in the user preferences.
</li>
<li>
<b>Memory</b>: total RAM, CPU cache, and swap space. These
<li> <b>Memory</b>: total RAM, CPU cache, and swap space. These
numbers can be used by the scheduling server to decide whether or not to
assign work to a client. This also provides a means for assignment of
differing work based on host abilities.
</li>
<li>
<b>Timezone</b>:
</li>
<li>
<b>Last IP address</b> and count of consecutive same addresses.
</li>
<li>
<b>Number of RPCs and time of last RPC</b>.
</li>
<li>
<b>Fractions of time</b> that core client runs on host, host is
connected, and user is active. These are computed as
<li> <b>Timezone</b>:
<li> <b>Last IP address</b> and count of consecutive same addresses.
<li> <b>Number of RPCs and time of last RPC</b>.
<li> <b>Fractions of time</b> that core client runs on host, host is
connected, and user is active.
These are computed as
exponentially-weighted averages; see the class TIME_STATS.
</li>
<li>
<b>Operating system name and version</b>.
</li>
<li>
<b>Average up- and downstream network bandwidth</b>. These are
computed
as exponentially-weighted averages; see the class NET_STATS.
</li>
<li> <b>Operating system name and version</b>.
<li> <b>Average up- and downstream network bandwidth</b>.
These are computed as exponentially-weighted averages; see the class NET_STATS.
</ul>
These quantities are reported in every scheduling RPC, and their latest
values are stored in the BOINC database. <h3>Distinguishing hosts</h3>
values are stored in the BOINC database.
<h3>Distinguishing hosts</h3>
<p>
Not all systems have an application-readable globally unique ID, so
we don't take this approach. When a host first contacts the scheduling
Not all systems have an application-readable globally unique ID, so
we don't take this approach.
When a host first contacts the scheduling
server it is assigned a host ID, which it stores in its
<tt>client_state.xml</tt> file.
</p>
<p>
The BOINC database maintains the RPC sequence number for each host,
The BOINC database maintains the RPC sequence number for each host,
and the host maintains the sequence number in its
<tt>client_state.xml</tt> file.
</p>
<p>
To install the BOINC client on a large number of computers, users
To install the BOINC client on a large number of computers, users
are instructed to copy only the executable and the <tt>prefs.xml</tt>
file. If the user copies the <tt>client_state.xml</tt> file as well, the
file.
If the user copies the <tt>client_state.xml</tt> file as well, the
first RPCs from the other hosts will have a repeat sequence number; in
this case the scheduling server creates a new host record and returns
its ID.
</p>
</body>
</html>

3
doc/index.html
View File

@ -2,7 +2,8 @@
<body bgcolor="#FFFFFF">
<h2>Berkeley Open Infrastructure for Network Computing (BOINC)</h2>
Berkeley Open Infrastructure for Network Computing (BOINC) is a software platform for public-participation distributed computing projects like
Berkeley Open Infrastructure for Network Computing (BOINC)
is a software platform for distributed computing projects like
distributed.net and SETI@home.
<ul>

38
doc/master_url.html
View File

@ -1,35 +1,23 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>The Master URL</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>The Master URL</title>
<h2>The Master URL</h2>
<p>
Each project is identified by a <b>master URL</b>. This URL is used
to publicize the project. The <b>master page</b> at this URL has two
functions.
</p>
Each project is identified by a <b>master URL</b>.
This URL is used to publicize the project.
The <b>master page</b> at this URL has two functions.
<ul>
<li>
It is the home page of the project; when viewed in a browser it
<li> It is the home page of the project; when viewed in a browser it
describes the project and contains links for registering and for
downloading the core client.
</li>
<li>
It contains XML tags of the form <pre>
<li> It contains XML tags of the form <pre>
&lt;scheduler&gt;http://host.domain.edu/cgi/scheduler&lt;scheduler&gt;
&lt;scheduler&gt;http://host2.domain.edu/cgi/scheduler&lt;scheduler&gt;
</pre> that give the URLs of the project's scheduling servers. These
tags can be embedded within HTML comments. The BOINC core client reads
and parses the master page to find scheduler servers. If it is unable to
connect to any scheduler server for a project, it rereads the master
page.
</li>
</pre>
that give the URLs of the project's scheduling servers.
These tags can be embedded within HTML comments.
The BOINC core client reads
and parses the master page to find scheduler servers.
If it is unable to
connect to any scheduler server for a project, it rereads the master page.
</ul>
This mechanism lets a project change the locations of its scheduling
servers, or add new servers.
</body>
</html>

112
doc/prefs.html
View File

@ -1,108 +1,64 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Preferences</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Preferences</title>
<h2>Preferences</h2>
<p>
Participants can specify <b>preferences</b> determining and limiting
Participants can specify <b>preferences</b> determining and limiting
how BOINC uses their computers. Preferences are divided into three
groups:
</p>
<ul>
<li>
<b>Work preferences</b>
</li>
<li> <b>Work preferences</b>
<ul>
<li>
Whether work (computation and network transfer) should be done
<li> Whether work (computation and network transfer) should be done
while the host is being used (i.e. during keyboard and mouse input).
</li>
<li>
Whether work should be done while the computer is being powered
<li> Whether work should be done while the computer is being powered
by batteries.
</li>
<li>
Whether to wait for user confirmation before making network
connections.
</li>
<li>
Minimum and maximum amounts of work to maintain on disk. These
values are expressed as time values. The client will try to ensure it
<li> Whether to wait for user confirmation before making network connections.
<li> Minimum and maximum amounts of work to maintain on disk.
These values are expressed as time values.
The client will try to ensure it
has at least enough work to keep it busy for x days, and at most y days.
If the host is frequently disconnected from the Internet, the minimum
level should be at least as long as the typical period of disconnection.
The larger the difference between minimum and maximum, the less often
BOINC will connect to the Internet.
</li>
</ul>
<li>
<b>Disk preferences</b>
</li>
<li> <b>Disk preferences</b>
BOINC's usage of disk space can be limited in one or more of the
following ways:
<ul>
<li>
Maximum disk space used by BOINC.
</li>
<li>
Maximum disk percentage used by BOINC.
</li>
<li>
Minimum disk space to keep free.
</li>
<li> Maximum disk space used by BOINC.
<li> Maximum disk percentage used by BOINC.
<li> Minimum disk space to keep free.
</ul>
<li>
<b>Project preferences</b> (one set for each project)
</li>
<li> <b>Project preferences</b> (one set for each project)
<ul>
<li> Master URL of project
<li> Email address
<li> Authenticator
<li>
Master URL of project
</li>
<li>
Email address
</li>
<li>
Authenticator
</li>
<li>
Resource share: if projects contend for resources, the amount
Resource share: if projects contend for resources, the amount
allocated to a project is proportional to this number.
</li>
<li>
Whether to show email address on web site
</li>
<li>
Whether project should send emails to user
</li>
<li>
Whether this is the home project (see below)???.
</li>
<li>
Project-specific preferences
</li>
<li> Whether to show email address on web site
<li> Whether project should send emails to user
<li> Whether this is the home project (see below)???.
<li> Project-specific preferences
</ul>
</ul>
<p>
Each participant has a single set of preferences. If you want to
have different preferences for different hosts, you must create a
Each participant has a single set of preferences.
If you want to have different preferences for different hosts,
you must create a
separate accounts.
</p>
<h3>Propagation of preferences</h3>
<p>
The BOINC core client on each host stores a copy of its user's
preferences. Whenever a host contacts a scheduling server, the request
message includes the preferences and their last-modification time. If
the server has a more recently modified version of the preferences, it
returns these to the client. Thus a change to preferences is quickly
The BOINC core client on each host stores a copy of its user's preferences.
Whenever a host contacts a scheduling server, the request
message includes the preferences and their last-modification time.
If the server has a more recently modified version of the preferences, it
returns these to the client.
Thus a change to preferences is quickly
propagated to all hosts, and to the databases of all enrolled projects.
A participant may edit preferences on the web site of any enrolled
project; however, care should be taken to ensure that a change isn't
overwritten by an earlier change. The easiest way to do this is to edit
preferences only at one web site.
</p>
</body>
</html>
overwritten by an earlier change.
The easiest way to do this is to edit preferences only at one web site.

12
doc/prefs_mod.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Modifying Preferences</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Modifying Preferences</title>
<h2>Modifying Preferences</h2>
<p>
</p>
</body>
</html>

71
doc/project.html
View File

@ -1,68 +1,47 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Projects and Applications</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<h2>Projects and Applications</h2> A <b>project</b> is a group of one or
more distributed applications, run by a single organization, that use
BOINC. Projects are independent; each one has its own applications,
databases and servers, and is not affected by the status of other
projects.
<title>Projects and Applications</title>
<h2>Projects and Applications</h2>
A <b>project</b> is a group of one or
more distributed applications, run by a single organization, that use BOINC.
Projects are independent; each one has its own applications,
databases and servers, and is not affected by the status of other projects.
<p>
Each is identified by a <a href="master_url.html">master URL</a>,
Each is identified by a <a href="master_url.html">master URL</a>,
which refers to an XHTML document describing the project.
</p>
<p>
Creating projects is relatively easy. An organization can create
projects to do Alpha and Beta testing of applications. Testers can
register for these projects, in addition to or instead of the
Creating projects is relatively easy.
An organization can create
projects to do Alpha and Beta testing of applications.
Testers can register for these projects, in addition to or instead of the
organization's public project.
</p>
<p>
The components of a project are shown below.
</p>
The components of a project are shown below.
<br>
<img vspace="10" src="project.png" alt="Project Organization
Diagram">
<p>
The server side of a project consists of two parts:
</p>
The server side of a project consists of two parts:
<ul>
<li>
A <b>project back end</b> that supplies applications and work
units, and that handles the computational results. Input and output
<li> A <b>project back end</b> that supplies applications and work
units, and that handles the computational results.
Input and output
files are distributed by <b>data servers</b>, which are HTTP servers
able to handle CGI programs with POST commands. These servers need not
be owned or operated by the project. A project might, for example,
able to handle CGI programs with POST commands.
These servers need not be owned or operated by the project.
A project might, for example,
recruit other organizations to donate network bandwidth by hosting data
servers; data could be moved on tape between the project back end and
the data servers.
</li>
<li>
A <b>BOINC server complex</b> that manages data distribution and
<li> A <b>BOINC server complex</b> that manages data distribution and
collection.
</li>
</ul>
The BOINC server complex includes the following components:
<ul>
<li>
One or more <b>scheduling servers</b> that communicates with
<li> One or more <b>scheduling servers</b> that communicates with
participant hosts.
</li>
<li>
A relational database storing information about work, results,
<li> A relational database storing information about work, results,
and participants.
</li>
<li>
Utility programs and libraries that allow the project back end
<li> Utility programs and libraries that allow the project back end
to interact with the server complex.
</li>
<li>
Web interfaces for participants and developers.
</li>
<li>
Web interfaces for participants and developers.
</ul>
</body>
</html>

47
doc/project_startup.html
View File

@ -1,40 +1,13 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Project Startup Checklist</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Project Startup Checklist</title>
<h3>Project Startup Checklist</h3>
<ul>
<li>
Install auxiliary software (Apache, MySQL, PHP)
</li>
<li>
Install BOINC software
</li>
<li>
Develop an application
</li>
<li>
Start the MySQL server
</li>
<li>
Initialize the BOINC database
</li>
<li>
Choose a master URL
</li>
<li>
Put a page at the master URL pointing to the scheduling servers.
</li>
<li>
Generate key pairs for code signing and upload authentication.
</li>
<li>
Start the <b>feeder</b> program
</li>
<li> Install auxiliary software (Apache, MySQL, PHP)
<li> Install BOINC software
<li> Develop an application
<li> Start the MySQL server
<li> Initialize the BOINC database
<li> Choose a master URL
<li> Put a page at the master URL pointing to the scheduling servers.
<li> Generate key pairs for code signing and upload authentication.
<li> Start the <b>feeder</b> program
</ul>
</body>
</html>

27
doc/protocol.html
View File

@ -1,11 +1,4 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>The BOINC Client/Server Protocol</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>The BOINC Client/Server Protocol</title>
<h2>The BOINC Client/Server Protocol</h2>
<h3>Protocol nucleus</h3>
@ -29,7 +22,6 @@ version of the core client originating the request.
<p>
The form of the reply is:
</p>
<pre>
&lt;scheduler_reply&gt;
[ &lt;message priority="low"&gt; arbitrary text &lt;/message&gt; ... ]
@ -40,7 +32,7 @@ The form of the reply is:
</pre>
<p>
Each <b>message</b> element is a message to the participant.</p>
Each <b>message</b> element is a message to the participant.
<ul>
<li>
If the priority is "high", the core client should try
@ -50,32 +42,29 @@ It should not, however, wait for user input, as this
could starve other projects.
This should be reserved for situations where definitive action
is required, e.g. the user must download a new version of the
core client in order to continue participating in this project.</li>
core client in order to continue participating in this project.
<li>
If the priority is "low" (default) the core client should
allow the participant to see the message, but should not require it.
For example, it could the message to a log file.</li>
For example, it could the message to a log file.
</ul>
<p>
A reply message can contain multiple message elements.
</p>
<p>
A <b>request_delay</b> element instructs the client
to not issue another request until the indicated number
of seconds has elapsed.</p>
of seconds has elapsed.
<p>
A <b>redirect</b> element gives the URL for a scheduling
server for this project.
If present, the core client should replace its list
of scheduling servers for this project.
The reply may contain multiple <b>redirect</b> elements.
</p>
<h3>Extensible protocol</h3>
<p>
The remaining protocol may evolve over time.
Request elements include
</p>
<pre>
&lt;prefs_mod_time&gt;0&lt;/prefs_mod_time&gt;
&lt;authenticator&gt;3f7b90793a0175ad0bda68684e8bd136&lt;/authenticator&gt;
@ -116,7 +105,7 @@ Request elements include
</pre>
<p>
Reply elements include</p>
Reply elements include
<pre>
&lt;request_delay&gt;10&lt;/request_delay&gt;
&lt;message priority="low"&gt;no work available&lt;/message&gt;
@ -153,7 +142,3 @@ Reply elements include</p>
&lt;name&gt;uc_wu_0&lt;/name&gt;
&lt;/result_ack&gt;
</pre>
</body>
</html>

154
doc/result.html
View File

@ -1,77 +1,36 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Results</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Compute Model: Results</title>
<h2>Compute Model: Results</h2>
<p>
A <b>result</b> describes an instance of a computation, either to be
performed, in progress, or completed. Results are stored in the
<b>result</b> table of the BOINC DB. The attributes of a result include:
A <b>result</b> describes an instance of a computation, either to be
performed, in progress, or completed.
Results are stored in the <b>result</b> table of the BOINC DB.
The attributes of a result include:
</p>
<ul>
<li>
The name of the result (unique across all results in the
<li> The name of the result (unique across all results in the
project).
</li>
<li>
The name of the associated workunit.
</li>
<li>
The time when the completed result should be reported to a
scheduling server. This is assigned by the project, and is used by
clients to prioritize operations, and to initiate scheduler RPCs. There
is no guarantee that the result will actually be reported by this time.
</li>
<li>
An XML document listing the names of its output files; see
below.
</li>
<li>
An XML document giving the sizes and checksums of its output
<li> The name of the associated workunit.
<li> The time when the completed result should be reported to a
scheduling server.
This is assigned by the project, and is used by
clients to prioritize operations, and to initiate scheduler RPCs.
There is no guarantee that the result will actually be reported by this time.
<li> An XML document listing the names of its output files; see below.
<li> An XML document giving the sizes and checksums of its output
files (filled in after the result is completed).
</li>
<li>
The stderr output of the result.
</li>
<li>
The host that computed the result.
</li>
<li>
The times when the result was dispatched and received.
</li>
<li>
The exit status of the application.
</li>
<li>
The reported CPU time.
</li>
<li>
Its <b>state</b>. Values include:
</li>
<li> The stderr output of the result.
<li> The host that computed the result.
<li> The times when the result was dispatched and received.
<li> The exit status of the application.
<li> The reported CPU time.
<li> Its <b>state</b>. Values include:
<ul>
<li>
Inactive (not ready to dispatch)
</li>
<li>
Unsent (ready to dispatch, but not dispatched)
</li>
<li>
In progress (dispatched, not done)
</li>
<li>
Done successfully
</li>
<li>
Timed out
</li>
<li>
Done with error
</li>
<li> Inactive (not ready to dispatch)
<li> Unsent (ready to dispatch, but not dispatched)
<li> In progress (dispatched, not done)
<li> Done successfully
<li> Timed out
<li> Done with error
</ul>
</ul>
The XML document listing the output files has the form: <pre>
@ -84,48 +43,39 @@ The XML document listing the output files has the form: <pre>
&lt;file_ref&gt;...&lt;/file_ref&gt;
[ ... ]
&lt;/result&gt;
</pre> The components are:
</pre>
The components are:
<ul>
<li>
The <b>&lt;name&gt;</b> element is the result name.
</li>
<li>
The <b>&lt;wu_name&gt;</b> element is the workunit name.
</li>
<li>
Each <b>&lt;file_ref&gt;</b> element is an association to an
output file, described by a corresponding <b>&lt;file_info&gt;</b>
element.
</li>
<li> The <b>&lt;name&gt;</b> element is the result name.
<li> The <b>&lt;wu_name&gt;</b> element is the workunit name.
<li> Each <b>&lt;file_ref&gt;</b> element is an association to an
output file, described by a corresponding <b>&lt;file_info&gt;</b> element.
</ul>
<p>
The XML document describing the sizes and checksums of the output
The XML document describing the sizes and checksums of the output
files is just a list of <b>&lt;file_info&gt;</b> elements, with the
<b>nbytes</b> and <b>md5_cksum</b> fields present. The project back end
must parse this field to find the locations and checksums of output
files.
</p>
<b>nbytes</b> and <b>md5_cksum</b> fields present.
The project back end
must parse this field to find the locations and checksums of output files.
<p>
Several results may be associated with a single workunit. Results
may be generated in either of two ways (selected as part of the
application):
</p>
Several results may be associated with a single workunit.
Results
may be generated in either of two ways (selected as part of the application):
<ul>
<li>
<b>Advance generation</b> of results. One or more result records
are stored in the database when the workunit is produced. The scheduling
server dispatches each result to a single participant host. When all
result records have been dispatched, participants hosts are "turned
away".
</li>
<li>
<b>On-demand generation</b> of results. The application
<li> <b>Advance generation</b> of results.
One or more result records
are stored in the database when the workunit is produced.
The scheduling
server dispatches each result to a single participant host.
When all
result records have been dispatched, participants hosts are "turned away".
<li> <b>On-demand generation</b> of results.
The application
specifies a "result template", which has place-holder tokens for the
output filenames. The scheduling server, in response to a host request,
generates a new result record and sends the result template. The host
output filenames.
The scheduling server, in response to a host request,
generates a new result record and sends the result template.
The host
generates unique output filenames, and returns them along when it the
computation is done.
</li>
</ul>
</body>
</html>

113
doc/rpc_policy.html
View File

@ -1,96 +1,71 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Scheduler RPC Timing and Retry Policies</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Scheduler RPC Timing and Retry Policies</title>
<h2>Scheduler RPC Timing and Retry Policies</h2>
<p>
Each scheduler RPC reports results, gets work, or both. The client's
<b>scheduler RPC policy</b> has several components: when to make a
scheduler RPC, which project to contact, which scheduling server for
Each scheduler RPC reports results, gets work, or both.
The client's <b>scheduler RPC policy</b> has several components:
when to make a scheduler RPC, which project to contact,
which scheduling server for
that project, how much work to ask for, and what to do if the RPC fails.
</p>
<p>
The scheduler RPC policy has the following goals:
</p>
The scheduler RPC policy has the following goals:
<ul>
<li>
Make as few scheduler RPCs as possible.
</li>
<li>
Use random exponential backoff if a project's scheduling servers
are down. This avoids an RPC storm when the servers come back up.
</li>
<li>
Eventually re-read a project's master URL file in case its set
<li> Make as few scheduler RPCs as possible.
<li> Use random exponential backoff if a project's scheduling servers
are down.
This avoids an RPC storm when the servers come back up.
<li> Eventually re-read a project's master URL file in case its set
of schedulers changes.
</li>
<li>
Report results before or soon after their deadlines.
</li>
<li> Report results before or soon after their deadlines.
</ul>
<h3>Resource debt</h3>
<p>
The client maintains an exponentially-averaged sum of the CPU time
it has devoted to each project. The constant EXP_DECAY_RATE determines
The client maintains an exponentially-averaged sum of the CPU time
it has devoted to each project.
The constant EXP_DECAY_RATE determines
the decay rate (currently a factor of e every week).
</p>
<p>
Each project is assigned a <b>resource debt</b>, computed as
</p>
Each project is assigned a <b>resource debt</b>, computed as
<p>
resource_debt = resource_share / exp_avg_cpu
</p>
resource_debt = resource_share / exp_avg_cpu
<p>
Resource debt is a measure of how much work the client owes the
Resource debt is a measure of how much work the client owes the
project, and in general the project with the greatest resource debt is
the one from which work should be requested.
</p>
<h3>Minimum RPC time</h3>
<p>
</p>
<p>
The client maintains a <b>minimum RPC time</b> for each project.
The client maintains a <b>minimum RPC time</b> for each project.
This is the earliest time at which a scheduling RPC should be done to
that project (if zero, an RPC can be done immediately). The minimum RPC
time can be set for various reasons:
</p>
that project (if zero, an RPC can be done immediately).
The minimum RPC time can be set for various reasons:
<ul>
<li>
Because of a request from the project, i.e. a
<li> Because of a request from the project, i.e. a
&lt;request_delay&gt; element in a scheduler reply message.
</li>
<li>
Because RPCs to all of the project's scheduler has failed. An
exponential backoff policy is used.
</li>
<li>
Because one of the project's computations has failed (the
application crashed, or a file upload or download failed). An
exponential backoff policy is used to prevent a cycle of rapid failures.
</li>
<li> Because RPCs to all of the project's scheduler has failed.
An exponential backoff policy is used.
<li> Because one of the project's computations has failed (the
application crashed, or a file upload or download failed).
An exponential backoff policy is used to prevent a cycle of rapid failures.
</ul>
<h3>Scheduler RPC sessions</h3>
<p>
Communication with schedulers is organized into <b>sessions</b>,
each of which may involve many RPCs. There are two types of sessions:
Communication with schedulers is organized into <b>sessions</b>,
each of which may involve many RPCs.
There are two types of sessions:
</p>
<ul>
<li>
<b>Get-work</b> sessions, whose goal is to get a certain amount
of work. Results may be reported as a side-effect.
</li>
<li>
<b>Report-result</b> sessions, whose goal is to report results.
<li> <b>Get-work</b> sessions, whose goal is to get a certain amount of work.
Results may be reported as a side-effect.
<li>
<b>Report-result</b> sessions, whose goal is to report results.
Work may be fetched as a side-effect.
</li>
</ul>
The internal logic of scheduler sessions is encapsulated in the class
SCHEDULER_OP. This is implemented as a state machine, but its logic
expressed as a process might look like: <pre>
SCHEDULER_OP.
This is implemented as a state machine, but its logic
expressed as a process might look like:
<pre>
get_work_session() {
while estimated work &lt; high water mark
P = project with greatest debt and min_rpc_time &lt; now
@ -124,8 +99,10 @@ report_result_session(project P) {
P.nrpc_failures++;
P.min_rpc_time = exponential_backoff(P.min_rpc_failures)
}
</pre> The logic for initiating scheduler sessions is expressed in the
following poll function: <pre>
</pre>
The logic for initiating scheduler sessions is expressed in the
following poll function:
<pre>
if a scheduler RPC session is not active
if estimated work is less than low-water mark
start a get-work session
@ -135,5 +112,3 @@ if a scheduler RPC session is not active
the RPC request should ask for enough work to bring us up
to the high-water mark
</pre>
</body>
</html>

15
doc/sched_debug.html
View File

@ -1,18 +1,5 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Scheduling Server: Debugging</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Scheduling Server: Debugging</title>
<h2>Scheduling Server: Debugging</h2>
<p>
The scheduling server uses assert to verify that arguments to
functions have valid values. Specifically, assert statements are used to
verify that pointers are not NULL and lengths are greater than zero.
Error messages are also printed to stderr, which is routed by Apache to
the error log.
</p>
</body>
</html>

12
doc/sched_impl.html
View File

@ -1,13 +1,3 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Scheduling Server: Implementation</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Scheduling Server: Implementation</title>
<h2>Scheduling Server: Implementation</h2>
<p>
</p>
</body>
</html>

31
doc/sched_policy.html
View File

@ -1,29 +1,24 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Scheduling Server: Policy</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Scheduling Server: Policy</title>
<h2>Scheduling Server: Policy</h2>
<p>
The scheduling server will attempt to send enough work to excede a
hosts high water mark. If the amount of work the scheduling server is
sending excedes four weeks, the scheduling server will not attach more
work to a scheduler reply. This does not prevent the scheduling server
The scheduling server will attempt to send enough work to excede a
hosts high water mark.
If the amount of work the scheduling server is
sending exceeds four weeks, the scheduling server will not attach more
work to a scheduler reply.
This does not prevent the scheduling server
from sending a work unit that takes more than four weeks, but merely
from attaching more work after a scheduler reply has four weeks of work.
If a work unit uses more disk resources than a host has available, the
scheduling server will not attach that work unit. The scheduling server
scheduling server will not attach that work unit.
The scheduling server
estimates the amount of time a work unit will take to complete with the
formula <b>(number of fpops)/(fpops per second)+(number of iops)/(iops
per second)</b>. The number of fpops and number of iops are provided by
per second)</b>.
The number of fpops and number of iops are provided by
the backend when creating the work unit, and the calculation speeds are
included in a scheduler request. If no work is available, the scheduling
included in a scheduler request.
If no work is available, the scheduling
server sends the message <tt>no work available</tt> with priority
<tt>low</tt>, and requests that the client wait before sending another
scheduler request.
</p>
</body>
</html>

195
doc/security.html
View File

@ -1,165 +1,128 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Security</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body bgcolor="#FFFFFF">
<title>Security</title>
<h2>Security</h2>
<p>
Many types of attacks are possible in public-participation
Many types of attacks are possible in public-participation
distributed computing.
</p>
<ul>
<li>
<b>Result falsification</b>. Attackers return incorrect results.
</li>
<li>
<b>Credit falsification</b>. Attackers return results claiming
more CPU time than was actually used.
</li>
<li>
<b>Malicious executable distribution</b>. Attackers break into a
BOINC server and, by modifying the database and files, attempt to
<li> <b>Result falsification</b>.
Attackers return incorrect results.
<li> <b>Credit falsification</b>.
Attackers return results claiming more CPU time than was actually used.
<li>
<b>Malicious executable distribution</b>.
Attackers break into a BOINC server and,
by modifying the database and files, attempt to
distribute their own executable (e.g. a virus program) disguised as a
BOINC application.
</li>
<li>
<b>Overrun of data server</b>. Attackers repeatedly send large
files to BOINC data servers, filling up their disks and rendering them
unusable.
</li>
<li>
<b>Theft of participant account information by server
attack</b>. Attackers break into a BOINC server and steal email
<li>
<b>Overrun of data server</b>.
Attackers repeatedly send large files to BOINC data servers,
filling up their disks and rendering them unusable.
<li>
<b>Theft of participant account information by server attack</b>.
Attackers break into a BOINC server and steal email
addresses and other account information.
</li>
<li>
<b>Theft of participant account information by network
attack</b>. Attackers exploit the BOINC network protocols to steal
account information.
</li>
<li>
<b>Theft of project files</b>. Attackers steal input and/or
output files.
</li>
<li>
<b>Intentional abuse of participant hosts by projects</b>. A
project intentionally releases an application that abuses participant
<li>
<b>Theft of participant account information by network attack</b>.
Attackers exploit the BOINC network protocols to steal account information.
<li>
<b>Theft of project files</b>.
Attackers steal input and/or output files.
<li>
<b>Intentional abuse of participant hosts by projects</b>.
A project intentionally releases an application that abuses participant
hosts, e.g. by stealing sensitive information stored in files.
</li>
<li>
<b>Accidental abuse of participant hosts by projects</b>. A
project releases an application that unintentionally abuses particpant
<li>
<b>Accidental abuse of participant hosts by projects</b>.
A project releases an application that unintentionally abuses particpant
hosts, e.g. deleting files or causing crashes.
</li>
</ul>
BOINC provides mechanisms to reduce the likelihood of some of these
attacks.
BOINC provides mechanisms to reduce the likelihood of some of these attacks.
<p>
<b>Result falsification</b>
</p>
<b>Result falsification</b>
<p>
This can be probabilistically detected using redundant computing and
This can be probabilistically detected using redundant computing and
result verification: if a majority of results agree (according to an
application-specific comparison) then they are classified as correct.
Also, ringers or similar schemes can be used to prevent cheating. For
information about ringers see the paper "Uncheatable Distributed
Computations" by Philippe Golle and Ilya Mironov.
</p>
<p>
<b>Credit falsification</b>
</p>
<b>Credit falsification</b>
<p>
This can be probabilistically detected using redundant computing and
This can be probabilistically detected using redundant computing and
credit verification: each participant is given the minimum credit from
among the correct results.
</p>
<p>
<b>Malicious executable distribution</b>
</p>
<b>Malicious executable distribution</b>
<p>
BOINC uses code signing to prevent this. Each project has a key pair
for code signing. The private key should be kept on a network-isolated
machine used for generating digital signatures for executables. The
public key is distributed to, and stored on, clients. All files
BOINC uses code signing to prevent this. Each project has a key pair
for code signing.
The private key should be kept on a network-isolated
machine used for generating digital signatures for executables.
The public key is distributed to, and stored on, clients.
All files
associated with application versions are sent with digital signatures
using this key pair.
</p>
<p>
Even if attackers break into a project's BOINC servers, they will
Even if attackers break into a project's BOINC servers, they will
not be able to cause clients to accept a false code file.
</p>
<p>
BOINC provides a mechanism by which projects can periodically change
their code-signing key pair. The project generates a new key pair, then
BOINC provides a mechanism by which projects can periodically change
their code-signing key pair.
The project generates a new key pair, then
(using the code-signing machine) generates a signature for the new
public key, signed with the old private key. The core client will accept
a new key only if it's signed with the old key. This mechanism is
public key, signed with the old private key.
The core client will accept
a new key only if it's signed with the old key.
This mechanism is
designed to prevent attackers from breaking into a BOINC server and
distributing a false key pair.
</p>
<p>
<b>Overrun of data server</b>
</p>
<b>Overrun of data server</b>
<p>
Each result file has an associated maximum size. Each project has a
<b>upload authentication key pair</b>. The public key is stored on the
Each result file has an associated maximum size.
Each project has a
<b>upload authentication key pair</b>.
The public key is stored on the
project's data servers. Result file descriptions are sent to clients
with a digital signature, which is forwarded to the data server when the
file is uploaded. The data server verifies the file description, and
ensures that the amount of data uploaded does not exceed the maximum
size.
</p>
ensures that the amount of data uploaded does not exceed the maximum size.
<p>
<b>Theft of participant account information by server attack</b>
</p>
<b>Theft of participant account information by server attack</b>
<p>
Each project must address this using conventional security
practices. All server machines should be protected by a firewall, and
should have all unused network services disabled. Access to these
machines should be done only with encrypted protocols like SSH. The
machines should be subjected to regular security audits.
</p>
Each project must address this using conventional security practices.
All server machines should be protected by a firewall, and
should have all unused network services disabled.
Access to these machines should be done only with encrypted protocols like SSH.
The machines should be subjected to regular security audits.
<p>
Projects should be undertaken only the organizations that have
sufficient expertise and resources to secure their servers. A successful
Projects should be undertaken only the organizations that have
sufficient expertise and resources to secure their servers.
A successful
attack could discredit all BOINC-based projects, and
public-participation computing in general.
</p>
<p>
<b>Theft of participant account information by network attack</b>
</p>
<b>Theft of participant account information by network attack</b>
<p>
The
</p>
<b>Theft of project files</b>
<p>
<b>Theft of project files</b>
</p>
<p>
The input and output files used by BOINC applications are not
encrypted. Applications can do this themselves, but it has little effect
The input and output files used by BOINC applications are not encrypted.
Applications can do this themselves, but it has little effect
since data resides in cleartext in memory, where it is easy to access
with a debugger.
<p>
<b>Intentional abuse of participant hosts by projects</b>
</p>
<p>
<b>Intentional abuse of participant hosts by projects</b>
</p>
BOINC does nothing to prevent this (e.g. there is no "sandboxing" of
applications).
Participants must understand that when they join a BOINC project,
they are entrusting the security of their systems to that project.
<p>
BOINC does nothing to prevent this (e.g. there is no "sandboxing" of
applications). Participants must understand that when they join a BOINC
project, they are entrusting the security of their systems to that
project.
</p>
<b>Accidental abuse of participant hosts by projects</b>
<p>
<b>Accidental abuse of participant hosts by projects</b>
</p>
<p>
BOINC does nothing to prevent this. The chances of it happening can
be minimized by pre-released application testing. Projects should test
BOINC does nothing to prevent this.
The chances of it happening can
be minimized by pre-released application testing.
Projects should test
their applications thoroughly on all platforms and with all input data
scenarios before promoting them to production status.
</p>
</body>
</html>

78
doc/test.html
View File

@ -1,63 +1,43 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Test Applications and Scripts</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Test Applications and Scripts</title>
<h2>Test Applications and Scripts</h2>
<p>
The <b>apps</b> directory contains the following test applications:
</p>
The <b>apps</b> directory contains the following test applications:
<ul>
<li>
<b>concat</b>: concatenates its input files. Input and output
filenames are passed on the command line.
</li>
<li>
<b>upper_case</b>: reads from stdin, converts to upper case,
<li>
<b>concat</b>: concatenates its input files.
Input and output filenames are passed on the command line.
<li>
<b>upper_case</b>: reads from stdin, converts to upper case,
writes to stdout.
</li>
<li>
<b>uc_slow</b>: like upper_case, but processes only one
character per second. Checkpoints every 5 characters. Restartable.
</li>
<li>
<b>uc_slow</b>: like upper_case, but processes only one
character per second.
Checkpoints every 5 characters. Restartable.
</ul>
The <b>test</b> directory contains PHP scripts, together with XML
templates and sample input files, for initializing and testing the
entire system:
<ul>
<li>
<b>test_uc.php</b>: tests I/O connection using descriptors.
</li>
<li>
<b>test_concat.php</b>: tests I/O connection using command-line
<li>
<b>test_uc.php</b>: tests I/O connection using descriptors.
<li>
<b>test_concat.php</b>: tests I/O connection using command-line
args and filenames.
</li>
<li>
<b>test_uc_slow.php</b>: tests checkpoint/restart. You have to
run the client yourself, kill and restart it a few times.
</li>
<li>
<b>test_prefs.php</b>: tests some aspects of preferences.
</li>
<li>
<b>test_api.php</b>: tests to ensure the api is working
properly.
</li>
<li>
<b>test_water.php</b>: tests some aspects of water marks.
</li>
<li>
<b>test_rsc.php</b>: tests that scheduling server only sends
<li>
<b>test_uc_slow.php</b>: tests checkpoint/restart.
You have to run the client yourself, kill and restart it a few times.
<li>
<b>test_prefs.php</b>: tests some aspects of preferences.
<li>
<b>test_api.php</b>: tests to ensure the api is working properly.
<li>
<b>test_water.php</b>: tests some aspects of water marks.
<li>
<b>test_rsc.php</b>: tests that scheduling server only sends
feasable work units.
</li>
</ul>
<p>
These scripts use functions defined in the PHP include file
<b>init.inc</b>. You can use these functions to easily write test
These scripts use functions defined in the PHP include file
<b>init.inc</b>.
You can use these functions to easily write test
scripts for your own applications.
</p>
</body>
</html>

151
doc/tools_other.html
View File

@ -1,108 +1,77 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Operational Tools: Applications and Versions</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Operational Tools: Applications and Versions</title>
<h2>Operational Tools: Applications and Versions</h2>
<p>
BOINC provides a few tools for creating and operating projects:
</p>
BOINC provides a few tools for creating and operating projects:
<ul>
<li>
Utility programs (such as <b>add</b> and <b>create_work</b>).
<li>
Utility programs (such as <b>add</b> and <b>create_work</b>).
These can be run manually or invoked from scripts.
</li>
<li>
C++ functions (such as <b>create_work()</b>).
</li>
<li>
Web interfaces (currently these provide only read access).
</li>
<li>
C++ functions (such as <b>create_work()</b>).
<li>
Web interfaces (currently these provide only read access).
</ul>
Projects can create their own tools, either at a low level (e.g.
directly accessing the BOINC DB from PHP or Perl scripts) or by using
the BOINC DB C++ API (db/db.h). <h3>The Add utility program</h3>
<p>
The program <b>add</b> performs various types of initialization:
</p>
The program <b>add</b> performs various types of initialization:
<dl>
<dt>
add app -app_name name
</dt>
<dd>
Create a new application (just creates a DB record).
</dd>
<dt>
add platform name -platform_name name
</dt>
<dd>
Create a platform record (just creates a DB record);
</dd>
<dt>
add app_version
</dt>
<dd>
-app_name x
</dd>
<dd>
-platform_name y
</dd>
<dd>
-version a
</dd>
<dd>
-download_dir d
</dd>
<dd>
-url_base e
</dd>
<dd>
-exec_dir b
</dd>
<dd>
[ -message x ]
</dd>
<dd>
[ -message_priority y ]
</dd>
<dd>
[ -code_sign_keyfile x -exec_files file1 file2 ... ]
</dd>
<dd>
[ -signed_exec_files file1 sign1 file2 sign2 ... ]
</dd>
<dd>
<br>
Create an app_version record. Copy the executable file(s) from
the compilation directory (-exec_dir) to the download directory. If
-exec_files is used, each executable file is signed using the given
private key; this should be used only for test/debug purposes. If
-signed_exec_files is used, the signatures are passed explicitly; this
<dt>
add app -app_name name
</dt>
<dd>
Create a new application (just creates a DB record).
<dt>
add platform name -platform_name name
<dd>
Create a platform record (just creates a DB record);
<dt>
add app_version
<dd>
-app_name x
<dd>
-platform_name y
<dd>
-version a
<dd>
-download_dir d
<dd>
-url_base e
<dd>
-exec_dir b
<dd>
[ -message x ]
<dd>
[ -message_priority y ]
<dd>
[ -code_sign_keyfile x -exec_files file1 file2 ... ]
<dd>
[ -signed_exec_files file1 sign1 file2 sign2 ... ]
<dd>
<br>
Create an app_version record.
Copy the executable file(s) from
the compilation directory (-exec_dir) to the download directory.
If -exec_files is used, each executable file is signed using the given
private key; this should be used only for test/debug purposes.
If -signed_exec_files is used, the signatures are passed explicitly; this
should be used for production purposes, where the signatures are
generated on an offline computer. If -message is used, the version is
generated on an offline computer.
If -message is used, the version is
tagged with the given message and optional priority.
</dd>
<dt>
add user -email_addr x -name y -web_password z -authenticator a
</dt>
<dd>
Create a user record.
</dd>
<dt>
add prefs -email_addr x -prefs_file y
</dt>
<dd>
Create a preference set, and make it the default preferences for
<dt>
add user -email_addr x -name y -web_password z -authenticator a
<dd>
Create a user record.
<dt>
add prefs -email_addr x -prefs_file y
<dd>
Create a preference set, and make it the default preferences for
the given user.
</dd>
</dl>
<h3>Web Interfaces</h3>
<p>
The file <b>show_db.php</b> in the operational web site directory
The file <b>show_db.php</b> in the operational web site directory
displays the contents of the BOINC DB.
</p>
</body>
</html>

50
doc/tools_security.html
View File

@ -1,34 +1,24 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Security Tools</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Security Tools</title>
<h3>Security Tools</h3>
<p>
The program <b>lib/crypt_prog</b> can be used for several purposes:
<br>
<br>
<b>-genkey n private_keyfile public_keyfile</b>
<br>
Create a key pair with n bits (always use 1024). Write the keys in
encoded ASCII form to the indicated files.
<br>
<b>-sign file private_keyfile</b>
<br>
Create a digital signature for the given file. Write it in encoded
The program <b>lib/crypt_prog</b> can be used for several purposes:
<br>
<br>
<b>-genkey n private_keyfile public_keyfile</b>
<br>
Create a key pair with n bits (always use 1024).
Write the keys in encoded ASCII form to the indicated files.
<br>
<b>-sign file private_keyfile</b>
<br>
Create a digital signature for the given file. Write it in encoded
ASCII to stdout.
<br>
<b>-verify file signature_file public_keyfile</b>
<br>
Verify a signature for the given file.
<br>
<b>-test_crypt private_keyfile public_keyfile</b>
<br>
Perform an internal test, checking that encryption followed by
<br>
<b>-verify file signature_file public_keyfile</b>
<br>
Verify a signature for the given file.
<br>
<b>-test_crypt private_keyfile public_keyfile</b>
<br>
Perform an internal test, checking that encryption followed by
decryption works.
</p>
</body>
</html>

87
doc/tools_work.html
View File

@ -1,19 +1,10 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Operational Tools: Work and Results</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Operational Tools: Work and Results</title>
<h2>Operational Tools: Work and Results</h2>
<p>
Workunits and results can be created using either a utility program
Workunits and results can be created using either a utility program
or a C++ function.
</p>
<p>
The program
</p>
The program
<pre>
create_work
-appname name
@ -23,57 +14,44 @@ create_work
-nresults n
infile_1 ... infile_m
</pre>
<p> <b>-appname</b> specifies the name of the application
<p> <b>-wu_name</b> gives the name of the workunit.
<p>
<b>-appname</b> specifies the name of the application
</p>
<p>
<b>-wu_name</b> gives the name of the workunit.
</p>
<p>
<b>-wu_template</b> gives the filename of a template for the
workunit XML document. This template is macro-substituted as follows:
</p>
<b>-wu_template</b> gives the filename of a template for the
workunit XML document.
This template is macro-substituted as follows:
<ul>
<li>
&lt;INFILE_n/&gt; is replaced with the name of the nth input
<li>
&lt;INFILE_n/&gt; is replaced with the name of the nth input
file.
</li>
<li>
&lt;MD5_n/&gt; is replaced with the MD5 checksum of the nth
<li>
&lt;MD5_n/&gt; is replaced with the MD5 checksum of the nth
input file.
</li>
<li>
&lt;WU_NAME/&gt; is replaced with the workunit name.
</li>
<li>
&lt;WU_NAME/&gt; is replaced with the workunit name.
</ul>
<p>
<b>-result_template</b> gives the filename of a template for the
result XML document. This template is macro-substituted as follows:
</p>
<b>-result_template</b> gives the filename of a template for the
result XML document.
This template is macro-substituted as follows:
<ul>
<li>
&lt;OUTFILE_n&gt; is replaced with a string of the form
<li>
&lt;OUTFILE_n&gt; is replaced with a string of the form
"wuname_resultnum_n" where wuname is the workunit name and resultnum is
the ordinal number of the result (0, 1, ...).
</li>
<li>
&lt;WU_NAME&gt; is replaced with the workunit name.
</li>
<li>
&lt;RESULT_NAME&gt; is replaced with a string of the form
<li>
&lt;WU_NAME&gt; is replaced with the workunit name.
<li>
&lt;RESULT_NAME&gt; is replaced with a string of the form
"wuname_resultnum".
</li>
</ul>
<p>
<b>-nresults</b> gives the number of results to be created.
</p>
<b>-nresults</b> gives the number of results to be created.
<p>
<b>infile_1 ... infile_m</b> are the names of the input files.
</p>
<b>infile_1 ... infile_m</b> are the names of the input files.
<hr>
<p>
The C++ library (backend_lib.C,h) provides the function:
</p>
The C++ library (backend_lib.C,h) provides the function:
<pre>
int create_work(
int appid,
@ -87,17 +65,12 @@ int create_work(
);
</pre>
<p>
This creates a workunit and one or more results. The arguments are
This creates a workunit and one or more results.
The arguments are
the same as for the utility program, except that the application is
identified by its database ID.
</p>
<p>
"infile_dir" is the path of the directory containing the input
"infile_dir" is the path of the directory containing the input
files.
</p>
<p>
"infiles" is an array of names of the input files, of length
"ninfiles".
</p>
</body>
</html>
"infiles" is an array of names of the input files, of length "ninfiles".

59
doc/validation.html
View File

@ -1,54 +1,47 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Accounting and Result Validation</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Accounting and Result Validation</title>
<h2>Accounting and Result Validation</h2>
<p>
Participants are given <b>credit</b> for the computations performed
by their hosts. These credits are used to generate "leaderboards" of
individuals, teams, and categories (countries, CPU types, etc.). It is
Participants are given <b>credit</b> for the computations performed
by their hosts.
These credits are used to generate "leaderboards" of
individuals, teams, and categories (countries, CPU types, etc.).
It is
to be expected that users will explore ways of "cheating", i.e. getting
undeserved credit.
</p>
<p>
In principles credit should reflect network transfers and disk
storage as well as computation. However, it's hard to verify these
In principles credit should reflect network transfers and disk
storage as well as computation.
However, it's hard to verify these
activities, so they aren't included in credit.
</p>
<p>
The core client assigns credit for a completed work unit as a
The core client assigns credit for a completed work unit as a
function of the CPU time used, and the performance metrics of the CPU
(discussed later). This is sent back to the scheduling server; of
(discussed later).
This is sent back to the scheduling server; of
course, the number can't be trusted in general.
</p>
<p>
Output files may be wrong. This can happen because of hardware
Output files may be wrong.
This can happen because of hardware
failures, or because of tampering.
</p>
<p>
Both problems - credit-cheating and wrong result - can be addressed
by <b>redundant computing</b> and <b>result validation</b>. This means
that each workunit is processed at least twice. The project back end
Both problems - credit-cheating and wrong result - can be addressed
by <b>redundant computing</b> and <b>result validation</b>.
This means that each workunit is processed at least twice.
The project back end
waits until a minimum number of results have been returned, then
compares the results and decides which are "correct". The notion of
compares the results and decides which are "correct".
The notion of
"equality" of results, and the policy for deciding which are correct,
are project-specific.
</p>
<p>
The back end then marks correct results as "validated", finds the
The back end then marks correct results as "validated", finds the
minimum reported credit for the correct results of a given workunit, and
assigns this amount of credit to all the correct results. This ensures
assigns this amount of credit to all the correct results.
This ensures
that as long as a reasonable majority of participants don't falsify
credit, almost all credit accounting will be correct.
</p>
<p>
<b>To do</b>: database keeps track of two types of credit: validated
and unvalidated. Users can see the workunits that didn't pass
<b>To do</b>: database keeps track of two types of credit: validated
and unvalidated.
Users can see the workunits that didn't pass
validation, or that were given reduced credit.
</p>
</body>
</html>

21
doc/version.html
View File

@ -1,18 +1,9 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Versioning</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body>
<title>Versioning</title>
<h2>Versioning</h2>
<p>
Each version of an application is assigned an integer <b>version
number</b>. Projects can assign version numbers however they like; for
example, version 304 might represent major version 3 and minor version
4. Version numbers should be used consistently across platforms; Windows
Each version of an application is assigned an integer <b>version
number</b>.
Projects can assign version numbers however they like; for
example, version 304 might represent major version 3 and minor version 4.
Version numbers should be used consistently across platforms; Windows
version 304 should be functionally identical to Mac version 304.
</p>
</body>
</html>

81
doc/work.html
View File

@ -1,42 +1,23 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<html lang="en">
<head>
<title>Compute Model: Workunits</title>
<meta name="generator" content="BBEdit 6.1.2">
</head>
<body bgcolor="#FFFFFF">
<title>Compute Model: Workunits</title>
<h2>Compute Model: Workunits</h2>
<p>
A <b>workunit</b> describes a computation to be performed. Workunits
are maintained in the <b>workunit</b> table in the BOINC DB. The
attributes of a workunit include:
A <b>workunit</b> describes a computation to be performed. Workunits
are maintained in the <b>workunit</b> table in the BOINC DB.
The attributes of a workunit include:
</p>
<ul>
<li>
Its application.
</li>
<li>
Its name (unique across all workunits in the project).
</li>
<li>
An XML document describing its input files and other parameters
<li> Its application.
<li> Its name (unique across all workunits in the project).
<li> An XML document describing its input files and other parameters
(see below).
</li>
<li>
The estimated resource requirements of the work unit
<li> The estimated resource requirements of the work unit
(computation, memory, disk space, network traffic).
</li>
<li>
Counts of how many times this workunit should be dispatched, how
<li> Counts of how many times this workunit should be dispatched, how
many times it has been dispatched, how many results have been returned,
and how many failures have occurred.
</li>
</ul>
<p>
The inputs to a workunit are described by an XML document of the
form
</p>
The inputs to a workunit are described by an XML document of the form
<pre>
[ &lt;file_info&gt;...&lt;/file_info&gt; ]
[ ... ]
@ -49,42 +30,28 @@ form
[ &lt;file_ref&gt;...&lt;/file_ref&gt; ]
[ ... ]
&lt;workunit&gt;
</pre> The components are:
</pre>
The components are:
<ul>
<li>
The <b>&lt;name&gt;</b> element is the name of the workunit.
</li>
<li>
The <b>&lt;app_name&gt;</b> element is the name of the
<li> The <b>&lt;name&gt;</b> element is the name of the workunit.
<li> The <b>&lt;app_name&gt;</b> element is the name of the
application.
</li>
<li>
The <b>&lt;version_num&gt;</b> element is ???.
</li>
<li>
The <b>&lt;command_line&gt;</b> element, if present, is the
<li> The <b>&lt;version_num&gt;</b> element is ???.
<li> The <b>&lt;command_line&gt;</b> element, if present, is the
command-line arguments to be passed to the main program.
</li>
<li>
The <b>&lt;env_vars&gt;</b> element, if present, is a list of
<li> The <b>&lt;env_vars&gt;</b> element, if present, is a list of
environment variables to be passed to the main program.
</li>
<li>
Each <b>&lt;file_ref&gt;</b> element describes a <a
<li> Each <b>&lt;file_ref&gt;</b> element describes a <a
href="files.html">reference</a> to an input file, each of which is
described by a <b>&lt;file_info&gt;</b> element.
</li>
</ul>
<p>
A workunit is associated with an application, not with a particular
version or set of versions???. If the format of your input data changes
in
A workunit is associated with an application, not with a particular
version or set of versions???.
If the format of your input data changes in
a way that is incompatible with older versions, you must create a new
application. This can often be avoided by using XML data format.
</p>
application.
This can often be avoided by using XML data format.
<p>
The <a href="tools.html">create_work</a> utility program provides a
The <a href="tools.html">create_work</a> utility program provides a
simplified interface for creating workunits.
</p>
</body>
</html>