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

2 files changed, 833 insertions, 530 deletions

diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index b7897215d..583042520 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -7,322 +7,897 @@
 
     <para>
       Bugzilla is configured by changing various parameters, accessed
-      from the "Edit parameters" link in the page footer. Here are
-      some of the key parameters on that page. You should run down this
-      list and set them appropriately after installing Bugzilla.
+      from the "Parameters" link in the Administration page (the 
+      Administration page can be found by clicking the "Administration"
+      link in the footer). The parameters are divided into several categories,
+      accessed via the menu on the left. Following is a description of the 
+      different categories and important parameters within those categories. 
     </para>
 
-    <indexterm>
-      <primary>checklist</primary>
-    </indexterm>
+      <section id="param-requiredsettings">
+        <title>Required Settings</title>
 
-    <variablelist>
-      <varlistentry>
-        <term>
-          maintainer
-        </term>
-        <listitem>
-          <para> 
-            The maintainer parameter is the email address of the person 
-            responsible for maintaining this Bugzilla installation.
-            The address need not be that of a valid Bugzilla account.
-          </para>
-        </listitem>
-      </varlistentry>
+        <para>
+          The core required parameters for any Bugzilla installation are set
+          here. These parameters must be set before a new Bugzilla installation
+          can be used. Administrators should review this list before 
+          deploying a new Bugzilla installation.
+        </para>
 
-      <varlistentry>
-        <term>
-          urlbase
-        </term>
-        <listitem>
-          <para>
-            This parameter defines the fully qualified domain name and web 
-            server path to your Bugzilla installation.
-          </para>
+        <indexterm>
+          <primary>checklist</primary>
+        </indexterm>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              maintainer
+            </term>
+            <listitem>
+              <para> 
+              Email address of the person 
+              responsible for maintaining this Bugzilla installation.
+              The address need not be that of a valid Bugzilla account.
+            </para>
+            </listitem>
+          </varlistentry>
 
+          <varlistentry>
+            <term>
+              urlbase
+            </term>
+            <listitem>
+              <para>
+                Defines the fully qualified domain name and web 
+                server path to this Bugzilla installation.
+              </para>
+              <para>
+                For example, if the Bugzilla query page is
+                <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
+                the <quote>urlbase</quote> should be set
+                to <filename>http://www.foo.com/bugzilla/</filename>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              docs_urlbase
+            </term>
+            <listitem>
+              <para>
+                Defines the fully qualified domain name and web 
+                server path to the Bugzilla documentation.
+              </para>
+              <para>
+                For example, if the "Bugzilla Configuration" page 
+                of the documentation is
+                <filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>, 
+                set the <quote>docs_urlbase</quote>
+                to <filename>http://www.foo.com/bugzilla/docs/html/</filename>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              sslbase
+            </term>
+            <listitem>
+              <para>
+                Defines the fully qualified domain name and web 
+                server path for HTTPS (SSL) connections to this Bugzilla installation.
+              </para>
+              <para>
+                For example, if the Bugzilla main page is
+                <filename>https://www.foo.com/bugzilla/index.cgi</filename>, 
+                the <quote>sslbase</quote> should be set
+                to <filename>https://www.foo.com/bugzilla/</filename>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              ssl
+            </term>
+            <listitem>
+              <para>
+                Determines when Bugzilla will force HTTPS (SSL) connections, using
+                the URL defined in <command>sslbase</command>. 
+                Options include "always", "never", and "authenticated sessions". 
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              cookiedomain
+            </term>
+            <listitem>
+              <para>
+               Defines the domain for Bugzilla cookies. This is typically left blank.
+               If there are multiple hostnames that point to the same webserver, which
+               require the same cookie, then this parameter can be utilized. For
+               example, If your website is at 
+               <filename>https://www.foo.com/</filename>, setting this to 
+               <filename>.foo.com/</filename> will also allow 
+               <filename>bar.foo.com/</filename> to access Bugzilla cookies.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              cookiepath
+            </term>
+            <listitem>
+              <para>
+                Defines a path, relative to the web server root, that Bugzilla
+                cookies will be restricted to. For example, if the 
+                <command>urlbase</command> is set to
+                <filename>http://www.foo.com/bugzilla/</filename>, the 
+                <command>cookiepath</command> should be set to 
+                <filename>/bugzilla/</filename>. Setting it to "/" will allow all sites 
+                served by this web server or virtual host to read Bugzilla cookies.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              timezone
+            </term>
+            <listitem>
+              <para>
+                Timezone of server. The timezone is displayed with timestamps. If 
+                this parameter is left blank, the timezone is not displayed.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              utf8
+            </term>
+            <listitem>
+              <para>
+               Determines whether to use UTF-8 (Unicode) encoding for all text in 
+               Bugzilla. New installations should set this to true to avoid character 
+               encoding problems. Existing databases should set this to true only 
+               after the data has been converted from existing legacy character 
+               encoding to UTF-8, using the 
+               <filename>contrib/recode.pl</filename> script.
+              </para>
+              <note>
+                <para>
+                  If you turn this parameter from "off" to "on", you must re-run 
+                  <filename>checksetup.pl</filename> immediately afterward.
+                </para>
+              </note>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              shutdownhtml
+            </term>
+            <listitem>
+              <para>
+                If there is any text in this field, this Bugzilla installation will
+                be completely disabled and this text will appear instead of all
+                Bugzilla pages for all users, including Admins. Used in the event 
+                of site maintenance or outage situations. 
+              </para>
+              <note>
+                <para>
+                  Although regular log-in capability is disabled while 
+                  <command>shutdownhtml</command>
+                  is enabled, safeguards are in place to protect the unfortunate 
+                  admin who loses connection to Bugzilla. Should this happen to you,
+                  go directly to the <filename>editparams.cgi</filename> (by typing
+                  the URL in manually, if necessary). Doing this will prompt you to
+                  log in, and your name/password will be accepted here (but nowhere
+                  else). 
+                </para>
+              </note>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              announcehtml
+            </term>
+            <listitem>
+              <para>
+                Any text in this field will be displayed at the top of every HTML
+                page in this Bugzilla installation. The text is not wrapped in any
+                tags. For best results, wrap the text in a <quote>&lt;div&gt;</quote>
+                tag. Any style attributes from the CSS can be applied. For example,
+                to make the text green inside of a red box, add <quote>id=message</quote>
+                to the <quote>&lt;div&gt;</quote> tag.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              proxy_url
+            </term>
+            <listitem>
+              <para>
+                If this Bugzilla installation is behind a proxy, enter the proxy 
+                information here to enable Bugzilla to access the Internet. Bugzilla
+                requires Internet access to utilize the 
+                <command>upgrade_notification</command> parameter (below). If the 
+                proxy requires authentication, use the syntax:
+                <filename>http://user:pass@proxy_url/</filename>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              upgrade_notification
+            </term>
+            <listitem>
+              <para>
+                Enable or disable a notification on the homepage of this Bugzilla
+                installation when a newer version of Bugzilla is available. This
+                notification is only visible to administrators. Choose "disabled",
+                to turn off the notification. Otherwise, choose which version of
+                Bugzilla you want to be notified about: "development_snapshot" is the
+                latest release on the trunk; "latest_stable_release" is the most 
+                recent release available on the most recent stable branch; 
+                "stable_branch_release" the most recent release on the branch 
+                this installation is based on.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-admin-policies">
+          <title>Administrative Policies</title>
+        <para>
+        This page contains parameters for basic administrative functions.
+        Options include whether to allow the deletion of bugs and users, whether
+        to allow users to change their email address, and whether to allow
+        user watching (one user receiving all notifications of a selected
+        other user). 
+        </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              supportwatchers
+            </term>
+            <listitem>
+              <para>
+                Turning on this option allows users to ask to receive copies 
+                of bug mail sent to another user.  Watching a user with
+                different group permissions is not a way to 'get around' the
+                system; copied emails are still subject to the normal groupset
+                permissions of a bug, and <quote>watchers</quote> will only be 
+                copied on emails from bugs they would normally be allowed to view. 
+              </para> 
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-user-authentication">
+          <title>User Authentication</title>
           <para>
-            For example, if your Bugzilla query page is
-            <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
-            set your <quote>urlbase</quote>
-            to <filename>http://www.foo.com/bugzilla/</filename>.
+            This page contains the settings that control how this Bugzilla
+            installation will do its authentication. Choose what authentication
+            mechanism to use (the Bugzilla database, or an external source such
+            as LDAP), and set basic behavioral parameters. For example, choose
+            whether to require users to login to browse bugs, the management
+            of authentication cookies, and the regular expression used to
+            validate email addresses. Some parameters are highlighted below.
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          makeproductgroups
-        </term>
-        <listitem>
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              emailregexp
+            </term>
+            <listitem>
+              <para>
+                Defines the regular expression used to validate email addresses
+                used for login names. The default attempts to match fully
+                qualified email addresses (i.e. 'user@example.com'). Some
+                Bugzilla installations allow only local user names (i.e 'user' 
+                instead of 'user@example.com'). In that case, the 
+                <command>emailsuffix</command> parameter should be used to define
+                the email domain.    
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              emailsuffix
+            </term>
+            <listitem>
+              <para>
+                This string is appended to login names when actually sending 
+                email to a user. For example,
+                If <command>emailregexp</command> has been set to allow
+                local usernames,
+                then this parameter would contain the email domain for all users
+                (i.e. '@example.com').   
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-attachments">
+          <title>Attachments</title>
           <para>
-            This dictates whether or not to automatically create groups
-            when new products are created.
+            This page allows for setting restrictions and other parameters
+            regarding attachments to bugs. For example, control size limitations
+            and whether to allow uploading of remote files via a URI.
           </para>
-        </listitem>
-      </varlistentry>
+        </section>
 
-      <varlistentry>
-        <term>
-          useentrygroupdefault
-        </term>
-        <listitem>
+        <section id="param-bug-change-policies">
+          <title>Bug Change Policies</title>
           <para>
-            Bugzilla products can have a group associated with them, so that
-            certain users can only see bugs in certain products. When this 
-            parameter is set to <quote>on</quote>, this 
-            causes the initial group controls on newly created products 
-            to place all newly-created bugs in the group 
-            having the same name as the product immediately.
-            After a product is initially created, the group controls
-            can be further adjusted without interference by 
-            this mechanism.
+            Set policy on default behavior for bug change events. For example,
+            choose which status to set a bug to when it is marked as a duplicate,
+            and choose whether to allow bug reporters to set the priority or
+            target milestone. Also allows for configuration of what changes
+            should require the user to make a comment, described below.    
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          mail_delivery_method
-        </term>
-        <listitem>
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              commenton*
+            </term>
+            <listitem>
+              <para>
+                All these fields allow you to dictate what changes can pass
+                without comment, and which must have a comment from the
+                person who changed them.  Often, administrators will allow
+                users to add themselves to the CC list, accept bugs, or
+                change the Status Whiteboard without adding a comment as to
+                their reasons for the change, yet require that most other
+                changes come with an explanation.
+              </para>
+
+              <para>
+                Set the "commenton" options according to your site policy. It
+                is a wise idea to require comments when users resolve, reassign, or
+                reopen bugs at the very least. 
+              </para>
+
+              <note>
+                <para>
+                  It is generally far better to require a developer comment
+                  when resolving bugs than not. Few things are more annoying to bug
+                  database users than having a developer mark a bug "fixed" without
+                  any comment as to what the fix was (or even that it was truly
+                  fixed!)
+                </para>
+              </note>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>
+              noresolveonopenblockers
+            </term>
+            <listitem>
+              <para>
+                This option will prevent users from resolving bugs as FIXED if
+                they have unresolved dependencies. Only the FIXED resolution
+                is affected. Users will be still able to resolve bugs to
+                resolutions other than FIXED if they have unresolved dependent
+                bugs.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-bugfields">
+          <title>Bug Fields</title>
           <para>
-            This is used to specify how email is sent, or if it is sent at 
-            all.  There are several options included for different MTAs, 
-            along with two additional options that disable email sending.  
-            "testfile" does not send mail, but instead saves it in 
-            <filename>data/mailer.testfile</filename> for later review.  
-            "none" disables email sending entirely.
+            The parameters in this section determine the default settings of
+            several Bugzilla fields for new bugs, and also control whether
+            certain fields are used. For example, choose whether to use the
+            "target milestone" field or the "status whiteboard" field.
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          shadowdb
-        </term>
-        <listitem>
+        <variablelist>
+
+          <varlistentry>    
+            <term>
+              useqacontact
+            </term>
+            <listitem>
+              <para>
+                This allows you to define an email address for each component, 
+                in addition to that of the default assignee, who will be sent
+                carbon copies of incoming bugs.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              usestatuswhiteboard
+            </term>
+            <listitem>
+              <para>
+                This defines whether you wish to have a free-form, overwritable field
+                associated with each bug. The advantage of the Status Whiteboard is
+                that it can be deleted or modified with ease, and provides an
+                easily-searchable field for indexing some bugs that have some trait
+                in common.         
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-bugmoving">
+          <title>Bug Moving</title>
           <para>
-            You run into an interesting problem when Bugzilla reaches a
-            high level of continuous activity. MySQL supports only table-level
-            write locking. What this means is that if someone needs to make a
-            change to a bug, they will lock the entire table until the operation
-            is complete. Locking for write also blocks reads until the write is
-            complete. Note that more recent versions of mysql support row level
-            locking using different table types. These types are slower than the
-            standard type, and Bugzilla does not yet take advantage of features
-            such as transactions which would justify this speed decrease. The
-            Bugzilla team are, however, happy to hear about any experiences with
-            row level locking and Bugzilla.
+            This page controls whether this Bugzilla installation allows certain
+            users to move bugs to an external database. If bug moving is enabled,
+            there are a number of parameters that control bug moving behaviors. 
+            For example, choose which users are allowed to move bugs, the location
+            of the external database, and the default product and component that
+            bugs moved <emphasis>from</emphasis> other bug databases to this 
+            Bugzilla installation are assigned to. 
           </para>
 
+        </section>
+
+        <section id="param-dependency-graphs">
+          <title>Dependency Graphs</title>
           <para>
-            The <quote>shadowdb</quote> parameter was designed to get around
-            this limitation. While only a single user is allowed to write to
-            a table at a time, reads can continue unimpeded on a read-only
-            shadow copy of the database. Although your database size will
-            double, a shadow database can cause an enormous performance
-            improvement when implemented on extremely high-traffic Bugzilla
-            databases.
+            This page has one parameter that sets the location of a Web Dot
+            server, or of the Web Dot binary on the local system, that is used
+            to generate dependency graphs. Web Dot is a CGI program that creates
+            images from <filename>.dot</filename> graphic description files. If
+            no Web Dot server or binary is specified, then dependency graphs will
+            be disabled.
           </para>
-        
-          <para>
-            As a guide, on reasonably old hardware, mozilla.org began needing 
-            <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
-            users with several hundred Bugzilla bug changes and comments per day.
+        </section>
+
+        <section id="param-group-security">
+          <title>Group Security</title>
+            <para>
+              Bugzilla allows for the creation of different groups, with the
+              ability to restrict the visibility of bugs in a group to a set of 
+              specific users. Specific products can also be associated with
+              groups, and users restricted to only see products in their groups.
+              Several parameters are described in more detail below. Most of the
+              configuration of groups and their relationship to products is done
+              on the "Groups" and "Product" pages of the "Administration" area.
+              The options on this page control global default behavior. 
+              For more information on Groups and Group Security, see
+              <xref linkend="groups"/> 
+            </para>
+
+        <variablelist>
+
+          <varlistentry>
+            <term>
+              makeproductgroups
+            </term>
+            <listitem>
+              <para>
+                Determines whether or not to automatically create groups
+                when new products are created. If this is on, the groups will be
+                used for querying bugs.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              useentrygroupdefault
+            </term>
+            <listitem>
+              <para>
+                Bugzilla products can have a group associated with them, so that
+                certain users can only see bugs in certain products. When this 
+                parameter is set to <quote>on</quote>, this 
+                causes the initial group controls on newly created products 
+                to place all newly-created bugs in the group 
+                having the same name as the product immediately.
+                After a product is initially created, the group controls
+                can be further adjusted without interference by 
+                this mechanism.
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              querysharegroup
+            </term>
+            <listitem>
+              <para>
+                The name of the group of users who are allowed to share saved
+                searches with one another. For more information on using 
+                saved searches, see <xref linkend="savedsearches"/>.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+    
+        </section>
+
+        <section id="bzldap">
+          <title>LDAP Authentication</title>
+
+          <para>LDAP authentication is a module for Bugzilla's plugin 
+          authentication architecture. This page contains all the parameters
+          necessary to configure Bugzilla for use with LDAP authentication.
           </para>
 
           <para>
-            The value of the parameter defines the name of the shadow bug
-            database. You will need to set the host and port settings from
-            the params page, and set up replication in your database server
-            so that updates reach this readonly mirror. Consult your database
-            documentation for more detail.
+          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 that
+          require a 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, tries to map this account to a
+          Bugzilla account. If an LDAP mail attribute is defined, the value of this
+          attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
+          username to form a full email address. If an account for this address
+          already exists in the Bugzilla installation, 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. For example, bugs are still assigned by
+          email address and users are still queried by email address.
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          shutdownhtml
-        </term>
-        <listitem>
+          <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="https://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="bzradius">
+          <title>RADIUS Authentication</title>
+
           <para>
-            If you need to shut down Bugzilla to perform administration, enter
-            some descriptive text (with embedded HTML codes, if you'd like)
-            into this box. Anyone who tries to use Bugzilla (including admins)
-            will receive a page displaying this text. Users can neither log in
-            nor log out while shutdownhtml is enabled.
+          RADIUS authentication is a module for Bugzilla's plugin 
+          authentication architecture. This page contains all the parameters
+          necessary for configuring Bugzilla to use RADIUS authentication.
           </para>
-
           <note>
             <para>
-              Although regular log-in capability is disabled while 'shutdownhtml'
-              is enabled, safeguards are in place to protect the unfortunate 
-              admin who loses connection to Bugzilla. Should this happen to you,
-              go directly to the <filename>editparams.cgi</filename> (by typing
-              the URL in manually, if necessary). Doing this will prompt you to
-              log in, and your name/password will be accepted here (but nowhere
-              else). 
+              Most caveats that apply to LDAP authentication apply to RADIUS
+              authentication as well. See <xref linkend="bzldap"/> for details.
             </para>
           </note>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          movebugs
-        </term>
-        <listitem>
-          <para>
-            This option is an undocumented feature to allow moving bugs
-            between separate Bugzilla installations.  You will need to understand
-            the source code in order to use this feature.  Please consult
-            <filename>movebugs.pl</filename> in your Bugzilla source tree for
-            further documentation, such as it is.
-          </para>
-        </listitem>
-      </varlistentry>
+          <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>
 
-      <varlistentry>
-        <term>
-          useqacontact
-        </term>
-        <listitem>
+        </section>
+    
+        <section id="param-email">
+          <title>Email</title>
           <para>
-            This allows you to define an email address for each component, 
-            in addition to that of the default assignee, who will be sent
-            carbon copies of incoming bugs.
+            This page contains all of the parameters for configuring how
+            Bugzilla deals with the email notifications it sends. See below
+            for a summary of important options. 
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          globalwatcher
-        </term>
-        <listitem>
-          <para>
-            This allows you to define specific users who will
-            receive notification each time a new bug in entered, or when
-            an existing bug changes, according to the normal groupset
-            permissions. It may be useful for sending notifications to a
-            mailing-list, for instance.
-          </para>
-        </listitem>
-      </varlistentry>
+        <variablelist>
 
-      <varlistentry>
-        <term>
-          usestatuswhiteboard
-        </term>
-        <listitem>
-          <para>
-            This defines whether you wish to have a free-form, overwritable field
-            associated with each bug. The advantage of the Status Whiteboard is
-            that it can be deleted or modified with ease, and provides an
-            easily-searchable field for indexing some bugs that have some trait
-            in common.         
-          </para>
-        </listitem>
-      </varlistentry>
+          <varlistentry>
+            <term>
+              mail_delivery_method
+            </term>
+            <listitem>
+              <para>
+                This is used to specify how email is sent, or if it is sent at 
+                all.  There are several options included for different MTAs, 
+                along with two additional options that disable email sending.  
+                "Test" does not send mail, but instead saves it in 
+                <filename>data/mailer.testfile</filename> for later review.  
+                "None" disables email sending entirely.
+              </para>
+            </listitem>
+          </varlistentry>
 
-      <varlistentry>
-        <term>
-          whinedays
-        </term>
-        <listitem>
+          <varlistentry>
+            <term>
+              sendmailnow
+            </term>
+            <listitem>
+              <para>
+                When Bugzilla is using Sendmail older than 8.12, turning this option
+                off will improve performance by not waiting for Sendmail to actually
+                send mail.  If Sendmail 8.12 or later is being used, there is 
+                nothing to gain by turning this off.  If another MTA is being used, 
+                such as Postfix, then this option *must* be turned on (even if you 
+                are using the fake sendmail executable that Postfix provides).
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              whinedays
+            </term>
+            <listitem>
+              <para>
+                Set this to the number of days you want to let bugs go
+                in the NEW or REOPENED state before notifying people they have
+                untouched new bugs. If you do not plan to use this feature, simply 
+                do not set up the whining cron job described in the installation
+                instructions, or set this value to "0" (never whine).
+              </para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>
+              globalwatcher
+            </term>
+            <listitem>
+              <para>
+                This allows you to define specific users who will
+                receive notification each time a new bug in entered, or when
+                an existing bug changes, according to the normal groupset
+                permissions. It may be useful for sending notifications to a
+                mailing-list, for instance.
+              </para>
+            </listitem>
+          </varlistentry>
+
+        </variablelist>
+
+        </section>
+
+        <section id="param-patchviewer">
+          <title>Patch Viewer</title>
           <para>
-            Set this to the number of days you want to let bugs go
-            in the NEW or REOPENED state before notifying people they have
-            untouched new bugs. If you do not plan to use this feature, simply 
-            do not set up the whining cron job described in the installation
-            instructions, or set this value to "0" (never whine).
+            This page contains configuration parameters for the CVS server, 
+            Bonsai server and LXR server that Bugzilla will use to enable the
+            features of the Patch Viewer. Bonsai is a tool that enables queries 
+            to a CVS tree. LXR is a tool that can cross reference and index source
+            code.
           </para>
-        </listitem>
-      </varlistentry>
+        </section>
 
-      <varlistentry>
-        <term>
-          commenton*
-        </term>
-        <listitem>
+        <section id="param-querydefaults">
+          <title>Query Defaults</title>
           <para>
-            All these fields allow you to dictate what changes can pass
-            without comment, and which must have a comment from the
-            person who changed them.  Often, administrators will allow
-            users to add themselves to the CC list, accept bugs, or
-            change the Status Whiteboard without adding a comment as to
-            their reasons for the change, yet require that most other
-            changes come with an explanation.
+            This page controls the default behavior of Bugzilla in regards to 
+            several aspects of querying bugs. Options include what the default
+            query options are, what the "My Bugs" page returns, whether users
+            can freely add bugs to the quip list, and how many duplicate bugs are 
+            needed to add a bug to the "most frequently reported" list.
           </para>
+        </section>
 
+        <section id="param-shadowdatabase">
+          <title>Shadow Database</title>
           <para>
-            Set the "commenton" options according to your site policy. It
-            is a wise idea to require comments when users resolve, reassign, or
-            reopen bugs at the very least. 
+            This page controls whether a shadow database is used, and all the
+            parameters associated with the shadow database. Versions of Bugzilla
+            prior to 3.2 used the MyISAM table type, which supports
+            only table-level write locking. With MyISAM, any time someone is making a change to 
+            a bug, the entire table is locked until the write operation is complete.
+            Locking for write also blocks reads until the write is complete.
+          </para> 
+          <para>
+            The <quote>shadowdb</quote> parameter was designed to get around
+            this limitation. While only a single user is allowed to write to
+            a table at a time, reads can continue unimpeded on a read-only
+            shadow copy of the database.
           </para>
 
           <note>
             <para>
-              It is generally far better to require a developer comment
-              when resolving bugs than not. Few things are more annoying to bug
-              database users than having a developer mark a bug "fixed" without
-              any comment as to what the fix was (or even that it was truly
-              fixed!)
+              As of version 3.2, Bugzilla no longer uses the MyISAM table type.
+              Instead, InnoDB is used, which can do transaction-based locking.
+              Therefore, the limitations the Shadow Database feature was designed
+              to workaround no longer exist.
             </para>
           </note>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          supportwatchers
-        </term>
-        <listitem>
-          <para>
-            Turning on this option allows users to ask to receive copies 
-            of bug mail sent to another user.  Watching a user with
-            different group permissions is not a way to 'get around' the
-            system; copied emails are still subject to the normal groupset
-            permissions of a bug, and <quote>watchers</quote> will only be 
-            copied on emails from bugs they would normally be allowed to view. 
-          </para> 
-        </listitem>
-      </varlistentry>
 
+        </section>
 
-      <varlistentry>
-        <term>
-          noresolveonopenblockers
-        </term>
-        <listitem>
+        <section id="admin-usermatching">
+          <title>User Matching</title>
           <para>
-            This option will prevent users from resolving bugs as FIXED if
-            they have unresolved dependencies. Only the FIXED resolution
-            is affected. Users will be still able to resolve bugs to
-            resolutions other than FIXED if they have unresolved dependent
-            bugs.
+            The settings on this page control how users are selected and queried
+            when adding a user to a bug. For example, users need to be selected
+            when choosing who the bug is assigned to, adding to the CC list or 
+            selecting a QA contact. With the "usemenuforusers" parameter, it is 
+            possible to configure Bugzilla to 
+            display a list of users in the fields instead of an empty text field.
+            This should only be used in Bugzilla installations with a small number
+            of users. If users are selected via a text box, this page also
+            contains parameters for how user names can be queried and matched
+            when entered.
           </para>
-        </listitem>
-      </varlistentry>
 
-      <varlistentry>
-        <term>
-          sendmailnow
-        </term>
-        <listitem>
-          <para>
-            When Bugzilla is using Sendmail older than 8.12, turning this option
-            off will improve performance by not waiting for Sendmail to actually
-            send mail.  If Sendmail 8.12 or later is being used, there is 
-            nothing to gain by turning this off.  If another MTA is being used, 
-            such as Postfix, then this option *must* be turned on (even if you 
-            are using the fake sendmail executable that Postfix provides).
-          </para>
-        </listitem>
-      </varlistentry>
+        </section>
 
-    </variablelist>
   </section>
 
   <section id="useradmin">
diff --git a/docs/xml/installation.xml b/docs/xml/installation.xml
index 1d4b8cbe4..526fa7c9e 100644
--- a/docs/xml/installation.xml
+++ b/docs/xml/installation.xml
@@ -1,5 +1,5 @@
 <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
-<!-- $Id: installation.xml,v 1.152 2008/01/24 22:35:16 lpsolit%gmail.com Exp $ -->
+<!-- $Id: installation.xml,v 1.153 2008/02/06 21:58:55 lpsolit%gmail.com Exp $ -->
 <chapter id="installing-bugzilla">
   <title>Installing Bugzilla</title>
 
@@ -652,7 +652,6 @@
     </section>
   </section>
   
-  
   <section id="configuration">
     <title>Configuration</title>
 
@@ -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>