Docs for bug 284629: maildeliverymethod -> mail_delivery_method

2 files changed, 322 insertions, 132 deletions

diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index f96882e3b..284b9da98 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -82,7 +82,7 @@
 
       <varlistentry>
         <term>
-          maildeliverymethod
+          mail_delivery_method
         </term>
         <listitem>
           <para>
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index 7faa1619c..0dce1992f 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.124 2008/04/04 06:47:54 mozilla%colinogilvie.co.uk Exp $ -->
+<!-- $Id: installation.xml,v 1.134 2008/04/04 06:48:04 lpsolit%gmail.com Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -258,7 +258,7 @@
         <para>Many people complain that Perl modules will not install for
         them. Most times, the error messages complain that they are missing a
         file in 
-        <quote>@INC</quote>. 
+        <quote>@INC</quote>.
         Virtually every time, this error is due to permissions being set too
         restrictively for you to compile Perl modules or not having the
         necessary Perl development libraries installed on your system.
@@ -287,24 +287,12 @@
 
         <listitem>
           <para>
-            AppConfig (&min-appconfig-ver;)
+            CGI &min-cgi-ver; or CGI &min-mp-cgi-ver; if using mod_perl
           </para>
         </listitem>
 
         <listitem>
           <para>
-            CGI (&min-cgi-ver;)
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Data::Dumper (&min-data-dumper-ver;)
-          </para>
-        </listitem>
-    
-        <listitem>
-          <para>
             Date::Format (&min-date-format-ver;)
           </para>
         </listitem>
@@ -336,12 +324,6 @@
 
         <listitem>
           <para>
-            File::Temp (&min-file-temp-ver;)
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
             <link linkend="install-modules-template">Template</link>
             (&min-template-ver;)
           </para>
@@ -349,41 +331,42 @@
 
         <listitem>
           <para>
-            Text::Wrap (&min-text-wrap-ver;)
+            MIME::Base64 (&min-mime-base64-ver;)
           </para>
         </listitem>
 
         <listitem>
           <para>
-            Mail::Mailer (&min-mail-mailer-ver;)
+            MIME::Parser (&min-mime-parser-ver;)
           </para>
         </listitem>
 
         <listitem>
           <para>
-            MIME::Base64 (&min-mime-base64-ver;)
+            Email::Send (&min-email-send-ver;)
           </para>
         </listitem>
 
         <listitem>
           <para>
-            MIME::Parser (&min-mime-parser-ver;)
+            Email::MIME::Modifier (&min-email-mime-modifier-ver;)
           </para>
         </listitem>
+      </orderedlist>
 
+      Optional Perl modules:
+      <orderedlist>
         <listitem>
           <para>
-            Storable (&min-storable-ver;)
+            <link linkend="install-modules-gd">GD</link>
+            (&min-gd-ver;) for bug charting
           </para>
         </listitem>
-      </orderedlist>
 
-      Optional Perl modules:
-      <orderedlist>  
         <listitem>
           <para>
-            <link linkend="install-modules-gd">GD</link>
-            (&min-gd-ver;) for bug charting
+            Template::Plugin::GD::Image
+            (&min-gd-ver;) for Graphical Reports
           </para>
         </listitem>
 
@@ -403,8 +386,8 @@
 
         <listitem>
           <para>
-            <link linkend="install-modules-gd-text-align">GD::Text::Align</link>
-            (&min-gd-text-align-ver;) for bug charting
+            <link linkend="install-modules-gd-text">GD::Text</link>
+            (&min-gd-text-ver;) for bug charting
           </para>
         </listitem>
 
@@ -417,6 +400,13 @@
 
         <listitem>
           <para>
+            LWP::UserAgent
+            (&min-lwp-useragent-ver;) for Automatic Update Notifications
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
             <link linkend="install-modules-patchreader">PatchReader</link>
             (&min-patchreader-ver;) for pretty HTML view of patches
           </para>
@@ -427,7 +417,70 @@
             Image::Magick (&min-image-magick-ver;) for converting BMP image attachments to PNG
           </para>
         </listitem>
-      </orderedlist>          
+
+        <listitem>
+          <para>
+            Net::LDAP
+            (&min-net-ldap-ver;) for LDAP Authentication
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <link linkend="install-modules-soap-lite">SOAP::Lite</link>
+            (&min-soap-lite-ver;) for the web service interface
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            HTML::Parser
+            (&min-html-parser-ver;) for More HTML in Product/Group Descriptions
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            HTML::Scrubber
+            (&min-html-scrubber-ver;) for More HTML in Product/Group Descriptions
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Email::MIME::Attachment::Stripper
+            (&min-email-mime-attachment-stripper-ver;) for Inbound Email
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Email::Reply
+            (&min-email-reply-ver;) for Inbound Email
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            mod_perl2
+            (&min-mod_perl2-ver;) for mod_perl
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            CGI
+            (&min-cgi-ver;) for mod_perl
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Apache::DBI
+            (&min-apache-dbi-ver;) for mod_perl2
+          </para>
+        </listitem>
+      </orderedlist>
       </para>
 
       <section id="install-modules-dbd-mysql">
@@ -500,10 +553,10 @@
         </para>
       </section>
 
-      <section id="install-modules-gd-text-align">
-        <title>GD::Text::Align (&min-gd-text-align-ver;)</title>
+      <section id="install-modules-gd-text">
+        <title>GD::Text (&min-gd-text-ver;)</title>
 
-        <para>The GD::Text::Align module is only required if you want graphical 
+        <para>The GD::Text module is only required if you want graphical 
         reports.
         </para>
       </section>
@@ -518,6 +571,14 @@
         </para>
       </section>
 
+      <section id="install-modules-soap-lite">
+        <title>SOAP::Lite (&min-soap-lite-ver;)</title>
+        <para>Installing SOAP::Lite enables your Bugzilla installation to be
+        accessible at a standardized Web Service interface (SOAP/XML-RPC)
+        by third-party applications via HTTP(S).
+        </para>
+      </section>
+
       <section id="install-modules-patchreader">
         <title>PatchReader (&min-patchreader-ver;)</title>
 
@@ -547,8 +608,8 @@
         </para>
 
         <para>
-          For more information, see the "maildeliverymethod" parameter in 
-          <xref linkend="parameters" />.
+          For more information, see the <quote>mail_delivery_method</quote> parameter
+          in <xref linkend="parameters" />.
         </para>
       </note>
     
@@ -582,7 +643,23 @@
       </para>
 
     </section>  
-
+    <section id="using-mod_perl-with-bugzilla">
+      <title>Installing Bugzilla on mod_perl</title>
+      <para>It is now possible to run the Bugzilla software under <literal>mod_perl</literal> on
+      Apache. <literal>mod_perl</literal> has some additional requirements to that of running
+      Bugzilla under <literal>mod_cgi</literal> (the standard and previous way).</para>
+      
+      <para>Bugzilla requires <literal>mod_perl</literal> to be installed, which can be
+      obtained from <ulink url="http://perl.apache.org"/> - Bugzilla requires
+      version &min-mod_perl2-ver; (AKA 2.0.0-RC5) to be installed.</para>
+      
+      <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>
   
   
@@ -653,7 +730,7 @@
     <section id="database-engine">
       <title>Database Server</title>
       <para>This section deals with configuring your database server for use
-      with Bugzilla. Currently <xref linkend="mysql"/> and
+        with Bugzilla. Currently <xref linkend="mysql"/> and
       <xref linkend="postgresql"/> are available.</para>
       
       <section id="mysql">
@@ -880,107 +957,220 @@
       <para>
         Configure your web server according to the instructions in the
         appropriate section. (If it makes a difference in your choice,
-        the Bugzilla Team recommends Apache.) Regardless of which webserver
+        the Bugzilla Team recommends Apache.) To check whether your web server
+	is correctly configured, try to access <filename>testagent.cgi</filename>
+	from your web server. If "OK" is displayed, then your configuration
+	is successful. Regardless of which web server
         you are using, however, ensure that sensitive information is
         not remotely available by properly applying the access controls in
-        <xref linkend="security-webserver-access"/>.
+        <xref linkend="security-webserver-access"/>. You can run
+        <filename>testserver.pl</filename> to check if your web server serves
+        Bugzilla files as expected.
       </para>
 
       <section id="http-apache">
-        <title>Apache <productname>httpd</productname></title>
-
-        <para>
-          To configure your Apache web server to work with Bugzilla,
-          do the following:
+        <title>Bugzilla using Apache</title>
+        <para>You have two options for running Bugzilla under Apache - 
+          <link linkend="http-apache-mod_cgi">mod_cgi</link> (the default) and
+          <link linkend="http-apache-mod_perl">mod_perl</link> (new in Bugzilla
+          2.23)
         </para>
-           
-        <procedure>
-          <step>
-            <para>
-              Load <filename>httpd.conf</filename> in your editor.
-              In Fedora and Red Hat Linux, this file is found in
-              <filename class="directory">/etc/httpd/conf</filename>.
-            </para>
-          </step>
-
-          <step>
-            <para>
-              Apache uses <computeroutput>&lt;Directory&gt;</computeroutput>
-              directives to permit fine-grained permission setting. Add the
-              following lines to a directive that applies to the location
-              of your Bugzilla installation. (If such a section does not
-              exist, you'll want to add one.) In this example, Bugzilla has
-              been installed at 
-              <filename class="directory">/var/www/html/bugzilla</filename>.
-            </para>
-
-            <programlisting>
-&lt;Directory /var/www/html/bugzilla&gt;
-  AddHandler cgi-script .cgi
-  Options +Indexes +ExecCGI
-  DirectoryIndex index.cgi
-  AllowOverride Limit
-&lt;/Directory&gt;
-            </programlisting>
-
+        <section id="http-apache-mod_cgi">
+            <title>Apache <productname>httpd</productname> with mod_cgi</title>
+    
             <para>
-              These instructions: allow apache to run .cgi files found
-              within the bugzilla directory; instructs the server to look
-              for a file called <filename>index.cgi</filename> if someone
-              only types the directory name into the browser; and allows
-              Bugzilla's <filename>.htaccess</filename> files to override
-              global permissions.
+            To configure your Apache web server to work with Bugzilla while using
+            mod_cgi, do the following:
             </para>
-
+            
+            <procedure>
+            <step>
+                <para>
+                Load <filename>httpd.conf</filename> in your editor.
+                In Fedora and Red Hat Linux, this file is found in
+                <filename class="directory">/etc/httpd/conf</filename>.
+                </para>
+            </step>
+    
+            <step>
+                <para>
+                Apache uses <computeroutput>&lt;Directory&gt;</computeroutput>
+                directives to permit fine-grained permission setting. Add the
+                following lines to a directive that applies to the location
+                of your Bugzilla installation. (If such a section does not
+                exist, you'll want to add one.) In this example, Bugzilla has
+                been installed at 
+                <filename class="directory">/var/www/html/bugzilla</filename>.
+                </para>
+    
+                <programlisting>
+    &lt;Directory /var/www/html/bugzilla&gt;
+    AddHandler cgi-script .cgi
+    Options +Indexes +ExecCGI
+    DirectoryIndex index.cgi
+    AllowOverride Limit
+    &lt;/Directory&gt;
+                </programlisting>
+    
+                <para>
+                These instructions: allow apache to run .cgi files found
+                within the bugzilla directory; instructs the server to look
+                for a file called <filename>index.cgi</filename> if someone
+                only types the directory name into the browser; and allows
+                Bugzilla's <filename>.htaccess</filename> files to override
+                global permissions.
+                </para>
+    
+                <note>
+                <para>
+                    It is possible to make these changes globally, or to the
+                    directive controlling Bugzilla's parent directory (e.g.
+                    <computeroutput>&lt;Directory /var/www/html/&gt;</computeroutput>).
+                    Such changes would also apply to the Bugzilla directory...
+                    but they would also apply to many other places where they
+                    may or may not be appropriate. In most cases, including
+                    this one, it is better to be as restrictive as possible
+                    when granting extra access.
+                </para>
+                </note>
+            </step>                    
+    
+            <step>
+                <para>
+                <filename>checksetup.pl</filename> can set tighter permissions
+                on Bugzilla's files and directories if it knows what group the
+                webserver runs as. Find the <computeroutput>Group</computeroutput>
+                line in <filename>httpd.conf</filename>, place the value found
+                there in the <replaceable>$webservergroup</replaceable> variable
+                in <filename>localconfig</filename>, then rerun
+                <filename>checksetup.pl</filename>.
+                </para>
+            </step>
+    
+            <step>
+                <para>
+                Optional: If Bugzilla does not actually reside in the webspace
+                directory, but instead has been symbolically linked there, you
+                will need to add the following to the
+                <computeroutput>Options</computeroutput> line of the Bugzilla 
+                <computeroutput>&lt;Directory&gt;</computeroutput> directive
+                (the same one as in the step above):
+                </para>
+    
+                <programlisting>
+    +FollowSymLinks
+                </programlisting>
+    
+                <para>
+                Without this directive, Apache will not follow symbolic links
+                to places outside its own directory structure, and you will be
+                unable to run Bugzilla.
+                </para>
+            </step>
+            </procedure>
+        </section>
+        <section id="http-apache-mod_perl">
+            <title>Apache <productname>httpd</productname> with mod_perl</title>
+            
+            <para>Some configuration is required to make Bugzilla work with Apache
+            and mod_perl</para>
+            
+            <procedure>
+            <step>
+                <para>
+                Load <filename>httpd.conf</filename> in your editor.
+                In Fedora and Red Hat Linux, this file is found in
+                <filename class="directory">/etc/httpd/conf</filename>.
+                </para>
+            </step>
+            
+            <step>
+                <para>Add the following information to your httpd.conf file, substituting
+                where appropriate with your own local paths.</para>
+                
+                <note>
+                <para>This should be used instead of the &lt;Directory&gt; block
+                shown above. This should also be above any other <literal>mod_perl</literal>
+                directives within the <filename>httpd.conf</filename> and must be specified
+                in the order as below.</para>
+                </note>
+                <warning>
+                <para>You should also ensure that you have disabled <literal>KeepAlive</literal>
+                support in your Apache install when utilizing Bugzilla under mod_perl</para>
+                </warning> 
+                
+                <programlisting>
+    PerlSwitches -I/var/www/html/bugzilla -w -T
+    PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
+                </programlisting>
+            </step>
+			
+			<step>
+				<para>
+					<filename>checksetup.pl</filename> can set tighter permissions
+					on Bugzilla's files and directories if it knows what group the
+					webserver runs as. Find the <computeroutput>Group</computeroutput>
+					line in <filename>httpd.conf</filename>, place the value found
+					there in the <replaceable>$webservergroup</replaceable> variable
+					in <filename>localconfig</filename>, then rerun
+					<filename>checksetup.pl</filename>.
+				</para>
+            </step>
+            </procedure>
+            
+            <para>On restarting Apache, Bugzilla should now be running within the
+            mod_perl environment. Please ensure you have run checksetup.pl to set
+		    permissions before you restart Apache.</para>
+        
             <note>
-              <para>
-                It is possible to make these changes globally, or to the
-                directive controlling Bugzilla's parent directory (e.g.
-                <computeroutput>&lt;Directory /var/www/html/&gt;</computeroutput>).
-                Such changes would also apply to the Bugzilla directory...
-                but they would also apply to many other places where they
-                may or may not be appropriate. In most cases, including
-                this one, it is better to be as restrictive as possible
-                when granting extra access.
-              </para>
-            </note>
-          </step>                    
-
-          <step>
-            <para>
-              <filename>checksetup.pl</filename> can set tighter permissions
-              on Bugzilla's files and directories if it knows what group the
-              webserver runs as. Find the <computeroutput>Group</computeroutput>
-              line in <filename>httpd.conf</filename>, place the value found
-              there in the <replaceable>$webservergroup</replaceable> variable
-              in <filename>localconfig</filename>, then rerun
-              <filename>checksetup.pl</filename>.
-            </para>
-          </step>
-
-          <step>
-            <para>
-              Optional: If Bugzilla does not actually reside in the webspace
-              directory, but instead has been symbolically linked there, you
-              will need to add the following to the
-              <computeroutput>Options</computeroutput> line of the Bugzilla 
-              <computeroutput>&lt;Directory&gt;</computeroutput> directive
-              (the same one as in the step above):
+            <para>Please bear the following points in mind when looking at using 
+                Bugzilla under mod_perl: 
+            <itemizedlist>
+                <listitem>
+                <para>
+                    mod_perl support in Bugzilla can take up a HUGE amount of RAM. You could be
+                    lookng at 30MB per httpd child, easily. Basically, you just need a lot of RAM.
+                    The more RAM you can get, the better. mod_perl is basically trading RAM for
+                    speed. At least 2GB total system RAM is recommended for running Bugzilla under
+                    mod_perl.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    Under mod_perl, you have to restart Apache if you make any manual change to
+                    any Bugzilla file. You can't just reload--you have to actually 
+					<emphasis>restart</emphasis> the server (as in make sure it stops and starts 
+					again). You <emphasis>can</emphasis> change localconfig and the params file 
+					manually, if you want, because those are re-read every time you load a page.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    You must run in Apache's Prefork MPM (this is the default). The Worker MPM
+                    may not work--we haven't tested Bugzilla's mod_perl support under threads.
+					(And, in fact, we're fairly sure it <emphasis>won't</emphasis> work.)
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    Bugzilla generally expects to be the only mod_perl application running on
+                    your entire server. It may or may not work if there are other applications also
+                    running under mod_perl. It does try its best to play nice with other mod_perl
+                    applications, but it still may have conflicts.
+                </para>
+                </listitem>
+                <listitem>
+                <para>
+                    It is recommended that you have one Bugzilla instance running under mod_perl
+                    on your server. Bugzilla has not been tested with more than one instance running.
+                </para>
+                </listitem>
+            </itemizedlist>
             </para>
-
-            <programlisting>
- +FollowSymLinks
-            </programlisting>
-
-            <para>
-              Without this directive, Apache will not follow symbolic links
-              to places outside its own directory structure, and you will be
-              unable to run Bugzilla.
-            </para>
-          </step>
-        </procedure>
+            </note>
+        </section>
       </section>
-
+      
       <section id="http-iis">
         <title>Microsoft <productname>Internet Information Services</productname></title>