From 5e1dd0c5cb7b5633d5bba6f0a49ed1a72914cc8e Mon Sep 17 00:00:00 2001 From: Bruce Allen Date: Mon, 15 Nov 2004 14:46:15 +0000 Subject: [PATCH] Work on documentation. Add explanation, missing material. More work needed. svn path=/trunk/boinc/; revision=4562 --- checkin_notes | 5 ++ doc/configuration.php | 140 ++++++++++++++++++++++++++++++------------ 2 files changed, 106 insertions(+), 39 deletions(-) diff --git a/checkin_notes b/checkin_notes index 793f315a5a..dd46664116 100755 --- a/checkin_notes +++ b/checkin_notes @@ -19473,3 +19473,8 @@ Rom 14 Nov 2004 win_build/ boinc_guirpc_test.vcproj boinc_ss.vcproj + +Bruce 15 Nov 2004 + - Work on documentation. Add explanation, missing material. More work needed. + doc/configuration.php + diff --git a/doc/configuration.php b/doc/configuration.php index 65c6ea68fa..95f7452bb6 100644 --- a/doc/configuration.php +++ b/doc/configuration.php @@ -1,7 +1,12 @@ ELEMENTS SHOULD BE CHANGED TO 1 . +// MANY OF THE TAGS BELOW ARE NOT EXPLAINED IN THE DOCUMENTATION, AND THE LIST HERE IS PROBABLY NOT COMPLETE. + require_once("docutil.php"); +echo "<-- \$Id$ -->\n"; + page_head("The project configuration file"); echo" @@ -11,73 +16,130 @@ A config.xml file looks like this: 
",
 htmlspecialchars("
 
+
   
-    main_host
-    x
-    x
-    x
-    x
-    x
-    x
-    x
-    x
-    x
-    x
-    x
-    [  ]
-    [  ]
-    [ 10 ]
-    [  ]
+                      project.hostname.ip   
+                   databasename          
+                   database.host.ip      
+                   database_user_name    
+                 database_password     
+                 shared_memory_key     
+              http://A/URL          
+              /path/to/directory    
+                http://A/URL          
+                /path/to/directory    
+                   http://A/URL          
+        http://A/URL          
+                   /path/to/directory    
+
+    [                                  ]
+    [                                              ]
+    [                                ]
+    [               N          ]
+    [         N    ]
+    [            N       ]
+    [                                       ]
+
     
-    ../     
-    bin             
-    cgi-bin
-     ...
+      ../        
+          bin            
+      cgi-bin        
   
+
   
     
-      [ foobar ]
-      [ 1 ]
-      feeder -d 3
+                feeder -d 3   
+      [        hostname.ip        ]
+      [    1              ]
+    
+    
+    ...
     
   
+
   
     
-      [ foobar ]
-      [ 1 ]
-      [ 1 ]
-      get_load
-      get_load.out
-      5 min
+                get_load        
+             get_load.out    
+             5 min           
+      [        host.ip                ]
+      [    1                  ]
+      [  1                ]
     
     
-      echo \"HI\" | mail quarl
-      /dev/null
-      1 day
+            echo \"HI\" | mail root@example.com     
+         /dev/null                             
+         1 day                                 
     
+    
+    ...
+    
   
+
 
 "),
 "
-The elements are: "; + +echo "The general project configuration elements are:"; list_start(); list_item("host", "name of project's main host, as given by Python's socket.hostname(). Daemons and tasks run on this host by default."); -list_item("db_name, etc.", "Database connection info"); +list_item("db_name", "Database name"); +list_item("db_host", "Database host machine"); +list_item("db_user", "Database user name"); +list_item("db_passwd", "Database password"); list_item("shmem_key", "ID of scheduler shared memory. Must be unique on host."); list_item("download_url", "URL of data server for download"); list_item("download_dir", "absolute path of download directory"); list_item("upload_url", "URL of file upload handler"); list_item("upload_dir", "absolute path of upload directory"); list_item("cgi_url", "URL of scheduling server"); -list_item("one_result_per_user_per_wu", "If present, send at most one result of a given workunit to a given user"); +list_item("stripchart_cgi_url", "URL of stripchart server"); +list_item("log_dir", "Path to the directory where the assimilator, feeder, transitioner and +cgi output logs are stored. This allows you to change the default log +directory path. If set explicitly, you can also use the 'grep logs' +features on the administrative pages. Note: enabling 'grep logs' with +very long log files can hang your server, since grepping GB files can +take a long time. If you enable this feature, be sure to rotate the +logs so that they are not too big."); +list_end(); + +echo "The following control features that you may or may not want available to users."; +list_start(); list_item("disable_account_creation", "If present, disallow account creation"); -list_item("max_wus_to_send", "Maximum results sent per scheduler RPC"); -list_item("enforce_delay_bound", "Don't send results to hosts - too slow to complete them within delay bound"); list_item("show_results", "Enable web site features that show results (per user, host, etc.)"); list_end(); + +echo "The following control the way in which results are scheduled, sent, and assigned to users and hosts."; +list_start(); +list_item("one_result_per_user_per_wu", "If present, send at most one result of a given workunit to a given +user. This is useful for checking accuracy/validity of results. It +ensures that the results for a given workunit are generated by +different users. If you have a validator that compares +different results for a given workunits to ensure that they are +equivalent, you should probably enable this. Otherwise you may end up +validating results from a given user with results from the same +user."); +list_item("max_wus_to_send", "Maximum results sent per scheduler RPC. Helps prevent hosts with +trouble from getting too many results and trashing them. But you +should set this large enough so that a host which is only connected to +the net at intervals has enough work to keep it occupied in between +connections."); +list_item("min_sendwork_interval", "Minimum number of seconds to wait after sending results to a given +host, before new results are sent to the same host. Helps prevent +hosts with download or application problems from trashing lots of +results by returning lots of error results. But don't set it to be so +long that a host goes idle after completing its work, before getting +new work."); +list_item("daily_result_quota", "Maximum number of results sent to a given host in a 24-hour +period. Helps prevent hosts with download or application problems from +returning lots of error results. Be sure to set it large enough that +a host does not go idle in a 24-hour period, and can download enough +work to keep it busy if disconnected from the net for a few days."); +list_item("enforce_delay_bound", "Don't send results to hosts too slow to complete them within delay bound"); +list_end(); + +// THE INFORMATION BELOW NEEDS TO BE ORGANIZED AND PUT INTO TABLES OR SOME OTHER LESS CRAMPED FORM echo " Tasks are periodic, short-running jobs. <cmd> and <period> are required.