Bug 390603: Configuration paramaters documentation needs updating - Patch by Sam Folk-Williams <sam.folkwilliams@gmail.com> r/a=LpSolit

1 files changed, 71 insertions, 435 deletions

diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 03fed5f3b..6f8dc0536 100644
--- a/docs/en/xml/installation.xml
+++ b/docs/en/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.145 2008/04/04 06:48:15 mozilla%colinogilvie.co.uk Exp $ -->
+<!-- $Id: installation.xml,v 1.153 2008/04/04 06:48:23 lpsolit%gmail.com Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -473,12 +473,6 @@
           </para>
         </listitem>
 
-        <listitem>
-          <para>
-            Apache::DBI
-            (&min-apache-dbi-ver;) for mod_perl2
-          </para>
-        </listitem>
       </orderedlist>
       </para>
 
@@ -655,13 +649,9 @@
       <para>Bugzilla also requires a more up-to-date version of the CGI
       perl module to be installed, version &min-mp-cgi-ver; as opposed to &min-cgi-ver;
       </para>
-      
-      <para>Finally, Bugzilla also requires <literal>Apache::DBI</literal>
-      (&min-apache-dbi-ver;) to be installed as well.</para>
     </section>
   </section>
   
-  
   <section id="configuration">
     <title>Configuration</title>
 
@@ -707,9 +697,18 @@
         hosting account), you will need to leave
         <emphasis>webservergroup</emphasis> empty, ignoring the warnings 
         that <filename>checksetup.pl</filename> will subsequently display 
-        every time it in run.
+        every time it is run.
       </para>
       
+      <caution>
+        <para>
+          If you are using suexec, you should use your own primary group
+          for <emphasis>webservergroup</emphasis> rather than leaving it
+          empty, and see the additional directions in the suexec section
+          <xref linkend="suexec" />.
+        </para>
+      </caution>
+
       <para>
         The other options in the <filename>localconfig</filename> file
         are documented by their accompanying comments. If you have a slightly
@@ -1114,7 +1113,7 @@
                 </warning> 
                 
                 <programlisting>
-    PerlSwitches -I/var/www/html/bugzilla -w -T
+    PerlSwitches -I/var/www/html/bugzilla -I/var/www/html/bugzilla/lib -w -T
     PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
                 </programlisting>
             </step>
@@ -1318,7 +1317,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
     </section> 
   </section>
 
-
   <section id="extraconfig">
     <title>Optional Additional Configuration</title>
 
@@ -1373,54 +1371,6 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
       </note>
     </section>
 
-    <section>
-      <title>Dependency Charts</title>
-
-      <para>As well as the text-based dependency trees, Bugzilla also
-      supports a graphical view of dependency relationships, using a 
-      package called 'dot'.
-      Exactly how this works is controlled by the 'webdotbase' parameter,
-      which can have one of three values:
-      </para>
-
-      <para>
-        <orderedlist>
-          <listitem>
-            <para>
-            A complete file path to the command 'dot' (part of 
-            <ulink url="http://www.graphviz.org/">GraphViz</ulink>) 
-            will generate the graphs locally
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-            A URL prefix pointing to an installation of the webdot package will
-            generate the graphs remotely
-            </para>
-          </listitem>
-          <listitem>
-            <para>
-            A blank value will disable dependency graphing.
-            </para>
-          </listitem>
-        </orderedlist>
-      </para>
-      
-      <para>The easiest way to get this working is to install
-      <ulink url="http://www.graphviz.org/">GraphViz</ulink>. If you
-      do that, you need to
-      <ulink url="http://httpd.apache.org/docs/mod/mod_imap.html">enable
-      server-side image maps</ulink> in Apache.
-      Alternatively, you could set up a webdot server, or use the AT&amp;T 
-      public webdot server. This is the default for the webdotbase param, 
-      but it's often overloaded and slow. Note that AT&amp;T's server 
-      won't work
-      if Bugzilla is only accessible using HARTS. 
-      <emphasis>Editor's note: What the heck is HARTS? Google doesn't know...
-      </emphasis>
-      </para>
-   </section>
-
     <section id="installation-whining-cron">
       <title>The Whining Cron</title>
 
@@ -1485,229 +1435,7 @@ c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s
         </para>
       </note>
     </section>
-
-    <section id="patch-viewer">
-      <title>Patch Viewer</title>
-      
-      <para>
-        Patch Viewer is the engine behind Bugzilla's graphical display of
-        code patches. You can integrate this with copies of the
-        <filename>cvs</filename>, <filename>lxr</filename> and
-        <filename>bonsai</filename> tools if you have them, by giving
-        the locations of your installation of these tools in
-        <filename>editparams.cgi</filename>.
-      </para>
         
-      <para>
-        Patch Viewer also optionally will use the 
-        <filename>cvs</filename>, <filename>diff</filename> and 
-        <filename>interdiff</filename>
-        command-line utilities if they exist on the system.
-        Interdiff can be obtained from 
-        <ulink url="http://cyberelk.net/tim/patchutils/"/>.
-        If these programs are not in the system path, you can configure
-        their locations in <filename>localconfig</filename>.
-      </para>
-      
-
-    </section>
-    
-    <section id="bzradius">
-      <title>RADIUS Authentication</title>
-
-      <para>RADIUS authentication is a module for Bugzilla's plugin 
-      authentication architecture.
-      Most caveats that apply to LDAP authentication apply to RADIUS
-      authentication as well.
-      </para>
-
-      <para>Parameters required to use RADIUS Authentication:</para>
-
-      <variablelist>
-        <varlistentry id="param-user_verify_class_for_radius">
-          <term>user_verify_class</term>
-          <listitem>
-            <para>If you want to list <quote>RADIUS</quote> here,
-            make sure to have set up the other parameters listed below.
-            Unless you have other (working) authentication methods listed as
-            well, you may otherwise not be able to log back in to Bugzilla once
-            you log out.
-            If this happens to you, you will need to manually edit
-            <filename>data/params</filename> and set user_verify_class to
-            <quote>DB</quote>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry id="param-RADIUS_server">
-          <term>RADIUS_server</term>
-          <listitem>
-            <para>This parameter should be set to the name (and optionally the
-            port) of your RADIUS server.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry id="param-RADIUS_secret">
-          <term>RADIUS_secret</term>
-          <listitem>
-            <para>This parameter should be set to the RADIUS server's secret.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry id="param-RADIUS_email_suffix">
-          <term>RADIUS_email_suffix</term>
-          <listitem>
-            <para>Bugzilla needs an e-mail address for each user account.
-            Therefore, it needs to determine the e-mail address corresponding
-            to a RADIUS user.
-            Bugzilla offers only a simple way to do this: it can concatenate
-            a suffix to the RADIUS user name to convert it into an e-mail
-            address.
-            You can specify this suffix in the RADIUS_email_suffix parameter.
-            </para>
-            <para>If this simple solution does not work for you, you'll
-            probably need to modify
-            <filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your
-            requirements.
-            </para>
-          </listitem>
-        </varlistentry>
-      </variablelist>
-
-    </section>
-    
-    <section id="bzldap">
-      <title>LDAP Authentication</title>
-
-      <para>LDAP authentication is a module for Bugzilla's plugin 
-      authentication architecture.
-      </para>
-
-      <para>
-      The existing authentication
-      scheme for Bugzilla uses email addresses as the primary user ID, and a
-      password to authenticate that user. All places within Bugzilla where
-      you need to deal with user ID (e.g assigning a bug) use the email
-      address. The LDAP authentication builds on top of this scheme, rather
-      than replacing it. The initial log in is done with a username and
-      password for the LDAP directory. Bugzilla tries to bind to LDAP using
-      those credentials, and if successful, try to map this account to a
-      Bugzilla account. If a  LDAP mail attribute is defined, the value of this
-      attribute is used, otherwise emailsuffix parameter is appended to LDAP
-      username to form a full email address. If an account for this address
-      already exists in your Bugzilla system, it will log in to that account.
-      If no account for that email address exists, one is created at the time
-      of login. (In this case, Bugzilla will attempt to use the "displayName"
-      or "cn" attribute to determine the user's full name.) After
-      authentication, all other user-related tasks are still handled by email
-      address, not LDAP username. You still assign bugs by email address, query
-      on users by email address, etc.
-      </para>
-
-      <caution>
-        <para>Because the Bugzilla account is not created until the first time
-        a user logs in, a user who has not yet logged is unknown to Bugzilla.
-        This means they cannot be used as an assignee or QA contact (default or
-        otherwise), added to any cc list, or any other such operation. One
-        possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
-        script in the
-        <glossterm linkend="gloss-contrib"><filename class="directory">contrib</filename></glossterm> directory. Another possible solution is fixing
-        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
-        201069</ulink>.
-        </para>
-      </caution>
-
-      <para>Parameters required to use LDAP Authentication:</para>
-
-      <variablelist>
-        <varlistentry id="param-user_verify_class_for_ldap">
-          <term>user_verify_class</term>
-          <listitem>
-            <para>If you want to list <quote>LDAP</quote> here,
-            make sure to have set up the other parameters listed below.
-            Unless you have other (working) authentication methods listed as
-            well, you may otherwise not be able to log back in to Bugzilla once
-            you log out.
-            If this happens to you, you will need to manually edit
-            <filename>data/params</filename> and set user_verify_class to
-            <quote>DB</quote>.
-            </para>
-          </listitem>
-        </varlistentry>
-
-        <varlistentry id="param-LDAPserver">
-          <term>LDAPserver</term>
-          <listitem>
-            <para>This parameter should be set to the name (and optionally the
-            port) of your LDAP server. If no port is specified, it assumes
-            the default LDAP port of 389.
-            </para>
-            <para>Ex. <quote>ldap.company.com</quote>
-             or <quote>ldap.company.com:3268</quote>
-            </para>
-            <para>You can also specify a LDAP URI, so as to use other
-            protocols, such as LDAPS or LDAPI. If port was not specified in
-            the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
-            schemes respectively.
-            </para>
-            <para>Ex. <quote>ldap://ldap.company.com</quote>,
-            <quote>ldaps://ldap.company.com</quote> or
-            <quote>ldapi://%2fvar%2flib%2fldap_sock</quote>
-            </para>
-           </listitem>
-         </varlistentry>
-
-         <varlistentry id="param-LDAPbinddn">
-           <term>LDAPbinddn [Optional]</term>
-           <listitem>
-             <para>Some LDAP servers will not allow an anonymous bind to search
-             the directory. If this is the case with your configuration you
-             should set the LDAPbinddn parameter to the user account Bugzilla
-             should use instead of the anonymous bind.
-             </para>
-             <para>Ex. <quote>cn=default,cn=user:password</quote></para>
-           </listitem>
-         </varlistentry>
-
-         <varlistentry id="param-LDAPBaseDN">
-           <term>LDAPBaseDN</term>
-           <listitem>
-             <para>The LDAPBaseDN parameter should be set to the location in
-             your LDAP tree that you would like to search for email addresses.
-             Your uids should be unique under the DN specified here.
-             </para>
-             <para>Ex. <quote>ou=People,o=Company</quote></para>
-           </listitem>
-         </varlistentry>
-
-         <varlistentry id="param-LDAPuidattribute">
-           <term>LDAPuidattribute</term>
-           <listitem>
-             <para>The LDAPuidattribute parameter should be set to the attribute
-             which contains the unique UID of your users. The value retrieved
-             from this attribute will be used when attempting to bind as the
-             user to confirm their password.
-             </para>
-             <para>Ex. <quote>uid</quote></para>
-           </listitem>
-         </varlistentry>
-
-         <varlistentry id="param-LDAPmailattribute">
-           <term>LDAPmailattribute</term>
-           <listitem>
-             <para>The LDAPmailattribute parameter should be the name of the
-             attribute which contains the email address your users will enter
-             into the Bugzilla login boxes.
-             </para>
-             <para>Ex. <quote>mail</quote></para>
-           </listitem>
-          </varlistentry>
-      </variablelist>
-
-    </section>
-    
     <section id="apache-addtype">
       <title>Serving Alternate Formats with the right MIME type</title>
 
@@ -1812,6 +1540,15 @@ AddType application/rdf+xml .rdf</screen>
            The following instructions assume that you are using version
            5.8.1 of ActiveState.
           </para>
+
+          <note>
+            <para>
+             These instructions are for 32-bit versions of Windows. If you are
+             using a 64-bit version of Windows, you will need to install 32-bit
+             Perl in order to install the 32-bit modules as described below.
+            </para>
+          </note>
+
         </section>
   
       <section id="win32-perl-modules">
@@ -1835,9 +1572,16 @@ C:\perl&gt; <command>ppm install &lt;module name&gt;</command>
         </para>
 
         <programlisting>
-<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command>
+<command>ppm repo add landfill http://www.landfill.bugzilla.org/ppm/</command>
         </programlisting>
-
+        <note>
+          <para>
+            In versions prior to 5.8.8 build 819 of PPM the command is 
+            <programlisting>
+<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command>
+            </programlisting>
+          </para>
+        </note>
         <note>
           <para>
             The PPM repository stores modules in 'packages' that may have
@@ -2136,10 +1880,12 @@ pid-file=/home/foo/mymysql/the.pid
     <section>
       <title>Perl</title>
 
-      <para>On the extremely rare chance that you don't have Perl on
+      <para>
+      On the extremely rare chance that you don't have Perl on
       the machine, you will have to build the sources
       yourself. The following commands should get your system
-      installed with your own personal version of Perl:</para>
+      installed with your own personal version of Perl:
+      </para>
 
       <screen>
         <prompt>bash$</prompt>
@@ -2154,139 +1900,23 @@ pid-file=/home/foo/mymysql/the.pid
         <command>make &amp;&amp; make test &amp;&amp; make install</command>
       </screen>
 
-      <para>Once you have Perl installed into a directory (probably
-      in <filename class="directory">~/perl/bin</filename>), you'll have to
-      change the locations on the scripts, which is detailed later on
-      this page.</para>
+      <para>
+      Once you have Perl installed into a directory (probably
+      in <filename class="directory">~/perl/bin</filename>), you will need to
+      install the Perl Modules, described below.
+      </para>
     </section>
 
     <section id="install-perlmodules-nonroot">
       <title>Perl Modules</title>
 
-      <para>Installing the Perl modules as a non-root user is probably the
-      hardest part of the process. There are two different methods: a
-      completely independant Perl with its own modules, or personal
-      modules using the current (root installed) version of Perl. The
-      independant method takes up quite a bit of disk space, but is
-      less complex, while the mixed method only uses as much space as the
-      modules themselves, but takes more work to setup.</para>
-
-      <section>
-        <title>The Independant Method</title>
-
-        <para>The independant method requires that you install your own
-        personal version of Perl, as detailed in the previous section. Once
-        installed, you can start the CPAN shell with the following
-        command:</para>
-
-        <para>
-          <screen>
-            <prompt>bash$</prompt>
-            <command>/home/foo/perl/bin/perl -MCPAN -e 'shell'</command>
-          </screen>
-        </para>
-
-        <para>And then:</para>
-
-        <para>
-          <screen>
-            <prompt>cpan&gt;</prompt>
-            <command>install Bundle::Bugzilla</command>
-          </screen>
-        </para>
-
-        <para>With this method, module installation will usually go a lot
-        smoother, but if you have any hang-ups, you can consult the next
-        section.</para>
-      </section>
-
-      <section>
-        <title>The Mixed Method</title>
-
-        <para>First, you'll need to configure CPAN to
-        install modules in your home directory. The CPAN FAQ says the
-        following on this issue:</para>
-
-        <para>
-          <programlisting>
-5)  I am not root, how can I install a module in a personal directory?
-
-    You will most probably like something like this:
-
-      o conf makepl_arg "LIB=~/myperl/lib \
-                         INSTALLMAN1DIR=~/myperl/man/man1 \
-                         INSTALLMAN3DIR=~/myperl/man/man3"
-    install Sybase::Sybperl
-
-    You can make this setting permanent like all "o conf" settings with "o conf commit".
-
-    You will have to add ~/myperl/man to the MANPATH environment variable and also tell your Perl programs to
-    look into ~/myperl/lib, e.g. by including
-
-      use lib "$ENV{HOME}/myperl/lib";
-
-    or setting the PERL5LIB environment variable.
-
-    Another thing you should bear in mind is that the UNINST parameter should never be set if you are not root.</programlisting>
-        </para>
-
-        <para>So, you will need to create a Perl directory in your home
-        directory, as well as the <filename class="directory">lib</filename>,
-        <filename class="directory">man</filename>,
-        <filename class="directory">man/man1</filename>, and
-        <filename class="directory">man/man3</filename> directories in that
-        Perl directory. Set the MANPATH variable and PERL5LIB variable, so
-        that the installation of the modules goes smoother. (Setting
-        UNINST=0 in your "make install" options, on the CPAN first-time
-        configuration, is also a good idea.)</para>
-
-        <para>After that, go into the CPAN shell:</para>
-
-        <para>
-          <screen>
-            <prompt>bash$</prompt>
-            <command>perl -MCPAN -e 'shell'</command>
-          </screen>
-        </para>
-
-        <para>From there, you will need to type in the above "o conf" command
-        and commit the changes. Then you can run through the installation:</para>
-
-        <para>
-          <screen>
-            <prompt>cpan&gt;</prompt>
-            <command>install Bundle::Bugzilla</command>
-          </screen>
-        </para>
-
-        <para>Most of the module installation process should go smoothly. However,
-        you may have some problems with Template. When you first start, you will
-        want to try to install Template with the XS Stash options on. If this
-        doesn't work, it may spit out C compiler error messages and croak back
-        to the CPAN shell prompt. So, redo the install, and turn it off. (In fact,
-        say no to all of the Template questions.) It may also start failing on a
-        few of the tests. If the total tests passed is a reasonable figure (90+%),
-        force the install with the following command:</para>
-
-        <para>
-          <screen>
-            <prompt>cpan&gt;</prompt>
-            <command>force install Template</command>
-          </screen>
-        </para>
-
-        <para>You may also want to install the other optional modules:</para>
-
-        <screen>
-          <prompt>cpan&gt;</prompt>
-          <command>install GD</command>
-          <prompt>cpan&gt;</prompt>
-          <command>install Chart::Base</command>
-          <prompt>cpan&gt;</prompt>
-          <command>install MIME::Parser</command>
-        </screen>
-
-      </section>
+      <para>
+      Installing the Perl modules as a non-root user is accomplished by
+      running the <filename>install-module.pl</filename>
+      script. For more details on this script, see 
+      <ulink url="api/install-module.html"><filename>install-module.pl</filename>
+      documentation</ulink>
+      </para>
     </section>
 
     <section>
@@ -2331,30 +1961,16 @@ pid-file=/home/foo/mymysql/the.pid
     <section>
       <title>Bugzilla</title>
 
-      <para>If you had to install Perl modules as a non-root user
-      (<xref linkend="install-perlmodules-nonroot" />) or to non-standard
-      directories, you will need to change the scripts, setting the correct
-      location of the Perl modules:</para>
-
       <para>
-        <programlisting>perl -pi -e
-        's@use strict\;@use strict\; use lib \"/home/foo/perl/lib\"\;@'
-        *cgi *pl Bug.pm processmail syncshadowdb</programlisting>
-
-        Change <filename class="directory">/home/foo/perl/lib</filename> to
-        your personal Perl library directory. You can probably skip this
-        step if you are using the independant method of Perl module
-        installation.
-      </para>
-
-      <para>When you run <command>./checksetup.pl</command> to create
+      When you run <command>./checksetup.pl</command> to create
       the <filename>localconfig</filename> file, it will list the Perl
       modules it finds. If one is missing, go back and double-check the
-      module installation from the CPAN shell, then delete the
-      <filename>localconfig</filename> file and try again.</para>
+      module installation from <xref linkend="install-perlmodules-nonroot"/>, 
+      then delete the <filename>localconfig</filename> file and try again.
+      </para>
 
       <warning>
-        <para>The one option in <filename>localconfig</filename> you
+        <para>One option in <filename>localconfig</filename> you
         might have problems with is the web server group. If you can't
         successfully browse to the <filename>index.cgi</filename> (like
         a Forbidden error), you may have to relax your permissions,
@@ -2363,6 +1979,26 @@ pid-file=/home/foo/mymysql/the.pid
         limited access to shell accounts may lessen the security risk,
         but use at your own risk.</para>
       </warning>
+
+      <section id="suexec">
+        <title>suexec or shared hosting</title>
+
+        <para>If you are running on a system that uses suexec (most shared
+        hosting environments do this), you will need to set the
+        <emphasis>webservergroup</emphasis> value in <filename>localconfig</filename>
+        to match <emphasis>your</emphasis> primary group, rather than the one
+        the web server runs under.  You will need to run the following
+        shell commands after running <command>./checksetup.pl</command>,
+        every time you run it (or modify <filename>checksetup.pl</filename>
+        to do them for you via the system() command).
+        <programlisting>        for i in docs graphs images js skins; do find $i -type d -exec chmod o+rx {} \; ; done
+        for i in jpg gif css js png html rdf xul; do find . -name \*.$i -exec chmod o+r {} \; ; done
+        find . -name .htaccess -exec chmod o+r {} \;
+        chmod o+x . data data/webdot</programlisting>
+        Pay particular attention to the number of semicolons and dots.
+        They are all important.  A future version of Bugzilla will
+        hopefully be able to do this for you out of the box.</para>
+      </section>
     </section>
   </section>