From 6a5eedfcbc1b7883d397fd7842af26c24639d4b7 Mon Sep 17 00:00:00 2001 From: David Anderson Date: Thu, 3 Oct 2002 20:41:23 +0000 Subject: [PATCH] test docs svn path=/trunk/boinc/; revision=458 --- checkin_notes | 3 + doc/client_data.html | 7 +- doc/create_project.html | 4 - doc/install.html | 160 --------------------------------- doc/master_url.html | 23 ----- doc/security.html | 2 +- doc/test.html | 190 +++++++++++++++++++++++++++++++++++++++- test/test.inc | 1 + 8 files changed, 195 insertions(+), 195 deletions(-) delete mode 100644 doc/install.html delete mode 100644 doc/master_url.html diff --git a/checkin_notes b/checkin_notes index 05356f0994..76a7150bff 100755 --- a/checkin_notes +++ b/checkin_notes @@ -2065,6 +2065,9 @@ David Oct 3 2002 main.C validate.C validate_test.C + test/ + test.inc (new) + test_uc.php tools/ add.C backend_lib.C,h diff --git a/doc/client_data.html b/doc/client_data.html index 6b66dc073a..b709b9137a 100644 --- a/doc/client_data.html +++ b/doc/client_data.html @@ -57,11 +57,10 @@ and installs a pointer.

Handling a scheduler RPC reply

A similar approach is used when handling the reply -from an scheduling server RPC (CLIENT_STATE::handle_scheduler_reply). +from a scheduling server RPC (CLIENT_STATE::handle_scheduler_reply). The RPC returns a interconnected set of basic objects, represented in a SCHEDULER_REPLY object. For each of these basic objects, we see (e.g. lookup_app()) -if it's alread present in the CLIENT_STATE structure. +if it's already present in the CLIENT_STATE structure. If not, we create and insert a new object, -then link it (e.g., link_app()) to establish pointers to -associated objects in CLIENT_STATE. \ No newline at end of file +then link it (e.g., link_app()) to existing objects in CLIENT_STATE. diff --git a/doc/create_project.html b/doc/create_project.html index adba1260af..aba094a28f 100644 --- a/doc/create_project.html +++ b/doc/create_project.html @@ -53,10 +53,6 @@ Setting up a BOINC server

  • Test applications and scripts
  • Project startup checklist - diff --git a/doc/install.html b/doc/install.html deleted file mode 100644 index 6e16d11eae..0000000000 --- a/doc/install.html +++ /dev/null @@ -1,160 +0,0 @@ -Installing a BOINC server - - -

    Installing a BOINC server

    -

    -To create a BOINC server you must have the following software installed: -

      -
    • MySQL -
    • Apache with PHP -
    -If Apache is configured to run with Fast CGI, rename fcgi to cgi in -the "boinc/sched" directory, replacing the existing cgi. -

    -Add the following environment variables (with appropriate changes) to your .tcshrc -

    -# These 5 are used at compile time
-setenv BOINC_DB_NAME        boinc_barry
-setenv BOINC_DB_PASSWD
-setenv BOINC_KEY            0xdabacafe
-setenv BOINC_KEY_DIR        ~/keys
-setenv BOINC_UPLOAD_DIR     ~/upload
-
-# These 3 are used at runtime
-setenv BOINC_DOWNLOAD_DIR   ~/download
-setenv BOINC_UPLOAD_URL     http://maggie.ssl.berkeley.edu/barry/cgi/file_upload_handler
-setenv BOINC_DOWNLOAD_URL   http://maggie.ssl.berkeley.edu/barry/download
-
-# These 4 are for test scripts
-setenv BOINC_PLATFORM       sparc-sun-solaris2.7
-setenv BOINC_EMAIL          barry@ssl.berkeley.edu
-setenv BOINC_USER           barry
-setenv BOINC_MASTER_URL     http:\\\\\/\\\\/maggie.ssl.berkeley.edu\\\\/~barry
-
    - -Each time BOINC_DB_NAME, BOINC_DB_PASSWD, BOINC_KEY, BOINC_KEY_DIR, or BOINC_UPLOAD_DIR are -changed you must recompile the scheduler by going into the sched/ directory, typing -"make clean", "make", and "make install". - -

    -After setting your necessary environment variables you must edit your httpd.conf to -configure Apache. - -Add the following lines (with appropriate changes) where aliases are placed. - -

    -Alias /barry/ "/disks/philmor/a/users/barry/"
-
-<Directory>
-    Options Indexes FollowSymlinks MultiViews
-    AllowOverride None
-    Order allow,deny
-    Alias from all
-</Directory>
-
    - -This allows you to resolve URL's and path names that go to your home directory. -This way you can have your upload and download directories, key directory, and cgi -directory in your home directory and still have them reacheable through the web. -

    -In addition add the following lines (with appropriate changes) where script -aliases are placed. - -

    -ScriptAlias /barry-cgi/ "/disks/philmor/a/users/barry/cgi/"
-
-<Directory "/disks/philmor/a/users/barry/cgi/">
-    AllowOverride None
-    Options None
-    Order allow,deny
-    Allow from all
-</Directory>
-
    - -This allows CGI files to be executed in the specified directory. You will put -your scheduler and file_upload_handler into this directory. -

    -You must make a directory for downloads and a directory for uploads. Make sure -that the download directory is world readable. You must also make a directory to hold -the different necessary keys. -

    -Now you are ready to install BOINC. -Unzip and untar the BOINC release. Type -"configure", "make", and "make install". "make" will compile all the source -code and "make install" will install a BOINC server in the INSTALL_DIR (currently -set to /usr/local/boinc/) specified in the Makefile. - -

    -Go into the boinc/test directory, and type -

    -test_uc.php -

    -This script runs a test case that initializes the database with a -user account, application and workunits, runs the client, and checks the -results. - -

    -BOINC_DB_NAME -

    -This is name of the database that the particular BOINC project you are running -uses. Each BOINC project must have a different BOINC_DB_NAME. -

    -BOINC_DB_PASSWD -

    -

    -BOINC_KEY -

    -This should be set to any 32 bit hex value desired. To run -multiple BOINC projects on one machine, each project needs to have -a different BOINC_KEY compiled into it. The BOINC_KEY is used to create -a shared memory segment. Each project has a different shared memory segment. -

    -BOINC_KEY_DIR -

    -This should be set to a directory in which the public and private -keys for BOINC are to be created. If you wish to place this in a -different directory, change the variable appropriately. -

    -BOINC_UPLOAD_DIR -

    -This is where clients will upload their results to. It is important -that this directory is different from the BOINC_DOWNLOAD_DIR. -

    -BOINC_DOWNLOAD_DIR -

    -This is where clients will download project applications and other necessary files to run -those applications from. It is important that this directory is different from -the BOINC_UPLOAD_DIR. -

    -BOINC_UPLOAD_URL -

    -This is the url to the file_upload_handler. -

    -BOINC_DOWNLOAD_URL -

    -This is the url to the BOINC_DOWNLOAD_DIR. -

    -BOINC_PLATFORM_NAME -

    -This is currently used by one of the test scripts. -It is not critical for the running of BOINC. Normally, projects -will have a list of platforms that their applications will be allowed to run -on. -

    -BOINC_EMAIL -

    -This is currently used by one of the test scripts to create a user. -It is not critical for the running of BOINC. -

    -BOINC_USER -

    -This is currently used by one of the test scripts to create a user. -It is not critical for the running of BOINC. -

    -BOINC_MASTER_URL -

    -This is currently used by one of the test scripts. -It is not critical for the running of BOINC. -Normally, each project will be identified by a BOINC_MASTER_URL. -The client will go to this URL and will be told where to go -to get work from the scheduler. diff --git a/doc/master_url.html b/doc/master_url.html deleted file mode 100644 index 2f2ff6043d..0000000000 --- a/doc/master_url.html +++ /dev/null @@ -1,23 +0,0 @@ -The master URL - -

    The master URL

    -

    -Each project is publicly identified by a master URL. -The master page at this URL has two functions. -

      -
    • 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. -
    • It contains XML elements of the form 
      -<scheduler>http://host.domain.edu/cgi/scheduler<scheduler>
-<scheduler>http://host2.domain.edu/cgi/scheduler<scheduler>
-
      -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 locate scheduling servers. -If at any point it is unable to -connect to any scheduling server for a project, -it rereads the master page. -This mechanism lets a project change the locations of its scheduling -servers, or add new servers. diff --git a/doc/security.html b/doc/security.html index 21b8dece8e..1af8168139 100644 --- a/doc/security.html +++ b/doc/security.html @@ -35,7 +35,7 @@ A project intentionally releases an application that abuses participant hosts, e.g. by stealing sensitive information stored in files.
    • Accidental abuse of participant hosts by projects. -A project releases an application that unintentionally abuses particpant +A project releases an application that unintentionally abuses participant hosts, e.g. deleting files or causing crashes.
    BOINC provides mechanisms to reduce the likelihood of some of these attacks. diff --git a/doc/test.html b/doc/test.html index 879a8fc930..0f5dc4d62f 100644 --- a/doc/test.html +++ b/doc/test.html @@ -1,19 +1,200 @@ -Test applications and scripts +Testing BOINC -

    Test applications and scripts

    +

    Testing BOINC

    +

    1) PHP-based testing framework

    + +doc/test.php is a library of PHP classes that make it easy to +write "test scripts" that perform end-to-end tests of BOINC. + +

    1.1) Goals of the testing framework

    + +The goal of the framework is to support automated testing of BOINC itself, +and of BOINC applications. +Each test is performed by a PHP script that initializes +the system to a deterministic state, executes the system, +detects termination, and returns success or failure depending +on the final state. +

    +Many BOINC features involve multiple projects and/or multiple hosts. +It would be prohibitively complex to do automated testing +on multiple physical hosts. +Fortunately the BOINC architecture makes it possible for +multiple projects and (virtual) hosts to reside on a single physical host. +So the testing framework uses this approach. + +

    +The framework lets you write scripts with any of the following attributes: +

      +
    • Multiple projects +
    • Multiple applications per project +
    • Multiple participants per project +
    • Multiple hosts, with arbitrary enrollment in projects +
    + + +

    1.2) Directory structure

    + +Each project has various files that must be kept separate. +You must designate a "BOINC projects" directory on your test host. +The framework will create subdirectories as follows: +
    +boinc_projects/
+    proj1/
+        cgi/
+        download/
+        html_ops/
+        html_user/
+        keys/
+        upload/
+    proj2/
+    ...
+
    +where proj1, proj2 etc. are the names of the projects in your scripts. + +

    +Similarly, each virtual host has various files that must be kept separate. +You must designate a "BOINC hosts" directory on your test host. +The framework will create subdirectories as follows: +

    +boinc_hosts/
+    host1/
+        projects/
+        slots/
+        client_state.xml
+        log_flags.xml
+    host2/
+    ...
+
    +where host1, host2 etc. are the names of the hosts in your scripts. + +

    1.3) Classes

    + +The framework provides the following classes +
    +class Project {                 // represents a project
+    var $name;                  // defaults to "test"; override if needed
+    function add_user($user);   // add a User to project's DB
+    function add_app($app);     // add an application
+    function add_app_version($app_version);     // add an app version
+    function install();         // set up directories and DB
+    function start();           // start feeder
+    function stop();            // stop feeder
+    function check_results_done();  // verify that all results are in state DONE
+    function compare_file($out, $correct);  // verify that a result file
+                                // matches a known-correct file
+}
+
+class User {                    // represents an account on a project
+    var $name;                  // override if needed
+    var $email_addr;
+    var $authenticator;
+}
+
+class Host {                    // represents a (virtual) host
+    function Host($user);
+    function add_project($project);
+    function install();
+    function run($flags);
+}
+
+class App {                     // represents an application
+    function App($name);
+}
+
+class App_Version {             // represents an application version
+    var $version;               // defaults to 1
+    var $exec_name;             // name of executable; default to app name
+    function App_Version($app);
+}
+
+class Work {                    // represents a workunit and some results
+    var $wu_template;           // name of workunit template file
+    var $result_template;       // name of result template file
+    var $nresults;              // number of results for this WU
+    var $input_files;           // array of input file names
+    function Work($project, $app);
+    function install();         // install in DB and directories
+}
+
    +A test script instantiates one or more instances of +these classes, links them as needed, +installs them, starts the projects, runs the hosts. +It then checks the final state +(typically, that results are done and result files are correct). + +

    1.4) Environment vars

    + +Before using the test framework, +you must define the following environment variables +(example values are given - you must supply your own): 
     setenv BOINC_PROJECTS_DIR   /home/david/boinc_projects
+# BOINC projects directory
 setenv BOINC_HOSTS_DIR      /home/david/boinc_hosts
+# BOINC hosts directory
 setenv BOINC_USER_NAME      david
+# prepended to web error log entries
 setenv BOINC_SRC_DIR        /home/david/boinc_cvs/boinc
+# BOINC source directory
 setenv BOINC_CGI_DIR        /home/david/cgi-bin
+# path of a CGI directory
 setenv BOINC_CGI_URL        http://localhost/cgi-bin
+# URL of that directory
 setenv BOINC_HTML_DIR       /home/david/html
+# path of a web-page directory
 setenv BOINC_HTML_URL       http://localhost
+# URL of that directory
 setenv BOINC_KEY_DIR        /home/david/boinc_keys
+# path of some pre-generated security keys
 setenv BOINC_PLATFORM       i686-pc-linux-gnu
+# platform name of this machine
    +

    1.5) Example script

    + +The following script (test/test_uc.php) +illustrates the use of the testing framework. +
    +#! /usr/local/bin/php
+<?php
+    include_once("test.inc");
+
+    $project = new Project;
+    $user = new User();
+    $host = new Host($user);
+    $app = new App("upper_case");
+    $app_version = new App_Version($app);
+
+    $project->add_user($user);
+    $project->add_app($app);
+    $project->add_app_version($app_version);
+    $project->install();      // must install projects before adding to hosts
+
+    $host->add_project($project);
+    $host->install();
+
+    echo "adding work\n";
+
+    $work = new Work($project, $app);
+    $work->wu_template = "uc_wu";
+    $work->result_template = "uc_result";
+    $work->nresults = 2;
+    array_push($work->input_files, "input");
+    $work->install();
+
+    $project->start();
+    $host->run("-exit_when_idle");
+    $project->stop();
+
+    $project->check_results_done();
+    $project->compare_file("uc_wu_0_0", "uc_correct_output");
+    $project->compare_file("uc_wu_1_0", "uc_correct_output");
+?>
+
    + +

    1.6) Implementation

    + +

    2) Test applications

    The apps directory contains the following test applications:

      @@ -28,6 +209,9 @@ writes to stdout. character per second. Checkpoints every 5 characters. Restartable.
    + +

    3) Test scripts

    +

    The test directory contains PHP scripts, together with XML templates and sample input files, for initializing and testing the entire system: @@ -48,7 +232,7 @@ You have to run the client yourself, kill and restart it a few times. test_water.php: tests some aspects of water marks.

  • test_rsc.php: tests that scheduling server only sends -feasable work units. +feasible work units.

    These scripts use functions defined in the PHP include file diff --git a/test/test.inc b/test/test.inc index 64a6d8da72..12a8515678 100644 --- a/test/test.inc +++ b/test/test.inc @@ -252,6 +252,7 @@ class Project { class User { var $name; + var $email_addr; var $authenticator; function User() {