Update web pages to correct statements that are no longer accurate for

distcc 3.0.

Reviewers: Craig Silverstein


git-svn-id: http://distcc.googlecode.com/svn/trunk@141 01de4be4-8c4a-0410-9132-4925637da917

4 files changed, 42 insertions, 28 deletions

diff --git a/doc/web/compared.html b/doc/web/compared.html
index 1aa9880..67bab17 100644
--- a/doc/web/compared.html
+++ b/doc/web/compared.html
@@ -87,10 +87,8 @@
         linking or other tasks.  (Some clustering systems can
         distribute any task.)</li>
 
-   <p><li>distcc can only use up to about ten or twenty machines.</li>
-
    <p><li>distcc comes with no warranty (as does most software), though
-        it has been successfully used by many people for more than two
+        it has been successfully used by many people for many
         years.</li></ul>
 
 
@@ -128,7 +126,7 @@
    <li>distcc volunteers can have different processor architectures
     or even operating systems to the machines they're serving.  (You
     do need to install a cross compiler though.)</li>
-   <li>distcc is only about 6000 lines of C, so you may find it
+   <li>distcc is only about 13000 lines of C, so you may find it
     easier to hack or patch.</li></ul>
 
    <p>Barnowl writes:
diff --git a/doc/web/compilers.html b/doc/web/compilers.html
index 4729549..6ca74fe 100644
--- a/doc/web/compilers.html
+++ b/doc/web/compilers.html
@@ -88,7 +88,8 @@ on all machines participating in the build.
 <p>The main feature required by distcc is that the compiler must be able
 to run the preprocessor separately, and then compile the preprocessor
 output from a file.  This was a basic part of the original design of
-C, but  some compilers seem to have lost the ability to do this.
+C, but some compilers seem to have lost the ability to do this.
+However, this feature is not required if you use distcc's "pump" mode.
 
 <p>Secondarily, distcc is currently hardcoded to suit gcc's behaviour and
 command-line syntax, so only compilers that act like gcc will work.
diff --git a/doc/web/faq.html b/doc/web/faq.html
index a797302..70e9e3b 100644
--- a/doc/web/faq.html
+++ b/doc/web/faq.html
@@ -75,7 +75,8 @@
 The main feature required by distcc is that the compiler must be able
 to run the preprocessor separately, and then compile the preprocessor
 output from a file.  This was a basic part of the original design of
-C, but  some compilers seem to have lost the ability to do this.
+C, but some compilers seem to have lost the ability to do this.
+However, this feature is not required if you use distcc's "pump" mode.
 
 Secondarily, distcc is currently hardcoded to suit gcc's behaviour and
 command-line syntax, so only compilers that act like gcc will work.
@@ -220,24 +221,25 @@ This could in principle be changed.
   faster than distcc, because it can distribute many different jobs.
   In practice, however, for many projects compiling C or C++ takes
   over 80% of the time.  Many of the other jobs, such as linking,
-  cannot be parallelized anyhow. 
+  cannot be parallelized anyhow.
 
 <p>
-  I don't know how their performace compares but I would be interested
+  I don't know how their performance compares but I would be interested
   to hear.
 
 
   <h3>Has anybody yet thought of integrating distcc with ccache?</h3>
 
 <p>
-  They work pretty well as separate programs that call each other.
+   If you don't use distcc's "pump" mode, then
+   they work pretty well as separate programs that call each other.
    You can either set <tt>CC='ccache distcc gcc'</tt>, or arrange for
    both ccache and distcc to be "masqueraded" on the path.  (See the
    manual for information on how to install this.)
 
 <p>
    Normally it is better for ccache to be run before distcc.
-   
+
 <p>
    This is very nearly as efficient as making them both part of a
    single program.  The preprocessor will only run once and the
@@ -251,16 +253,20 @@ This could in principle be changed.
   than making one monolithic one.
 
 <p>
-  It would be nice to allow a cache of
-  compiled files to be shared across several users or machines.
-  Possibly this would justify merging the programs at some point in
-  the future, but I'm still philosophically inclined towards
-  cooperation rather than merger.
-<p>
-  Joerg Beyer has started a new project called <a href="http://gecc.sourceforge.net/">gecc</a> to explore this architecture.
+  However, all of that said, now that we have "pump" mode, the
+  trade-offs have changed.  Using ccache prevents the use of "pump"
+  mode.  It would make sense to integrate caching into distcc
+  so that you can get distributed preprocessing, distributed
+  compilation, and caching all at the same time.  This would make
+  a great project for someone...
 
-  
+<p>
+  Also, it would be nice to allow a cache of
+  compiled files to be shared across several users or machines.
 
+<p>
+  Joerg Beyer started a project called <a href="http://gecc.sourceforge.net/">gecc</a>
+  to explore this architecture, but development appears to have stalled in 2002.
 
 <h3>Temporary files in strange location?</h3>
 <p>
@@ -339,10 +345,9 @@ performance ?
 </blockquote>
 
 <p>
-
-You should use about twice the total number of CPUs available, but it
-depends on your network, program being compiled, available memory,
-etc.  Experiment with different values.
+For plain (that is, non-pump) mode, you should use about twice the total
+number of CPUs available, but it depends on your network, program being
+compiled, available memory, etc.  Experiment with different values.
 
 <p>
 Client machines tend to be saturated at about 10-20 jobs, so using
@@ -350,6 +355,10 @@ values above -j10 is rarely useful.  (Perhaps higher levels would work
 well on clients with two or more CPUs and very fast network
 connections, memory and disk.)
 
+<p>
+The advice above is all for plain mode; for "pump" mode, you
+may see benefit from higher -j values.  Please experiment and
+<a href="mailto:distcc@lists.samba.org">let us know</a> what works best.
 
 
 <h3>Should I include localhost in the host list?</h3>
@@ -368,7 +377,7 @@ that finish their distcc compilation jobs.
 
 <p>
 I'm just hoping to collect some opinions on this
-matter. For a large project a for a cluster of about 8
+matter. For a large project and for a cluster of about 8
 machines, is it actually better to dedicated the
 driving machine to do preprocessing only? (and so not
 include it in the hosts file).
@@ -1188,4 +1197,4 @@ understand. Any body know if it work with distcc?
 <p>
 This <a href="http://lists.samba.org/archive/distcc/2006q1/003271.html"><tt>watch-ssaver</tt> script</a>
  from <a href="http://sourceforge.net/projects/dmucs">DMUCS</a>
- enables distcc only when the screenaver is running.
+ enables distcc only when the screensaver is running.
diff --git a/doc/web/security.html b/doc/web/security.html
index 331d381..ad60fa6 100644
--- a/doc/web/security.html
+++ b/doc/web/security.html
@@ -56,7 +56,8 @@ documentation, but it must be properly configured.
 <b>Anyone who can connect to the distcc server port can run arbitrary
 commands on that machine as the distccd user.  If you are not using
 SSH, you must use the <tt>--allow</tt> rule and/or firewall
-rules to limit access to port 3632.</b>
+rules to limit access to port 3632.</b>  Since version 3.0, distccd now
+enforces that, refusing to run if the --allow option is not specified.
 <p>
 Someone has written a 
 <a href="http://www.metasploit.com/projects/Framework/modules/exploits/distcc_exec.pm">
@@ -114,9 +115,14 @@ been no security audit of the code that runs after a connection is
 established.  It is possible that a hostile server could gain control
 of a client directly, as well as modifying the object code.
 <p>
-Some people have proposed that the server should perform
-reasonableness checks on the command or source code submitted from
-clients.  This is probably futile because gcc is not secure against
+If the DISTCC_CMDLIST environment variable is set when invoking
+distccd, distccd will only execute commands from that list.
+(The RPM and Debian distributions of distcc set this variable
+via the /etc/distcc/commands.allow.sh file which is sourced by
+/etc/init.d/distcc).  This mechanism can be used to only allow
+the execution of compilation commands rather than arbitrary
+commands.  However, <b>this should not be relied on as a security
+measure</b>, because gcc is not secure against
 hostile input, and it might be possible for an attacker to gain
 control of the gcc process through a carefully crafted input file or
 command line.  You should assume that anyone able to submit jobs is