Bug 211126 - As a part of fixing bug 180642 the directions for using LDAP authentication has changed.

2 files changed, 125 insertions, 58 deletions

diff --git a/docs/en/xml/glossary.xml b/docs/en/xml/glossary.xml
index d43b699dd..3893094c0 100644
--- a/docs/en/xml/glossary.xml
+++ b/docs/en/xml/glossary.xml
@@ -170,6 +170,26 @@
         particular task.</para>
       </glossdef>
     </glossentry>
+
+    <glossentry id="gloss-contrib">
+      <glossterm><filename class="directory">contrib</filename></glossterm>
+
+      <glossdef>
+        <para>The <filename class="directory">contrib</filename> directory is
+        a location to put scripts that have been contributed to Bugzilla but
+        are not a part of the official distribution. These scripts are written
+        by third parties and may be in languages other than perl. For those
+        that are in perl, there may be additional modules or other requirements
+        than those of the offical distribution.
+        <note>
+          <para>Scripts in the <filename class="directory">contrib</filename>
+          directory are not offically supported by the Bugzilla team and may
+          break in between versions.
+          </para>
+        </note>
+        </para>
+      </glossdef>
+    </glossentry>
   </glossdiv>
 
   <glossdiv id="gloss-d">
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml
index b067ce413..02dff197c 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.49 2008/04/04 06:46:39 jake%bugzilla.org Exp $ -->
+<!-- $Id: installation.xml,v 1.50 2008/04/04 06:46:40 jake%bugzilla.org Exp $ -->
 <chapter id="installation">
   <title>Installation</title>
 
@@ -937,15 +937,22 @@ man 5 crontab
 
     <section id="bzldap">
       <title>LDAP Authentication</title>
-      <para>
-        <warning>
-          <para>This information on using the LDAP
-            authentication options with Bugzilla is old, and the authors do
-            not know of anyone who has tested it. Approach with caution.
+
+      <note>
+        <para>LDAP authentication has been rewritten for the 2.18 release of
+        Bugzilla. It no longer requires the Mozilla::LDAP module and now uses
+        Net::LDAP instead. This rewrite was part of a larger landing that
+        allowed for additional authentication schemes to be easily added
+        (<ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=180642">bug
+        180642</ulink>).
+        </para>
+        <![%bz-devel;[
+          <para>This patch originally landed in 21-Mar-2003 and was included
+          in the 2.17.4 development release.
           </para>
-        </warning>
-      </para>
-      
+        ]]>
+      </note>
+
       <para>
       The existing authentication
       scheme for Bugzilla uses email addresses as the primary user ID, and a
@@ -964,58 +971,98 @@ man 5 crontab
       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>Using LDAP for Bugzilla authentication requires the 
-      Mozilla::LDAP (aka PerLDAP) Perl module. The
-      Mozilla::LDAP module in turn requires Netscape's Directory SDK for C.
-      After you have installed the SDK, then install the PerLDAP module.
-      Mozilla::LDAP and the Directory SDK for C are both 
-      <ulink url="http://www.mozilla.org/directory/">available for
-      download</ulink> from mozilla.org. 
-      </para>
-      
-      <para>
-      Set the Param 'useLDAP' to "On" **only** if you will be using an LDAP
-      directory for
-      authentication. Be very careful when setting up this parameter; if you
-      set LDAP authentication, but do not have a valid LDAP directory set up,
-      you will not be able to log back in to Bugzilla once you log out. (If
-      this happens, you can get back in by manually editing the data/params
-      file, and setting useLDAP back to 0.)
-      </para>
-      
-      <para>If using LDAP, you must set the
-      three additional parameters: Set LDAPserver to the name (and optionally
-      port) of your LDAP server. If no port is specified, it defaults to the
-      default port of 389. (e.g "ldap.mycompany.com" or
-      "ldap.mycompany.com:1234") Set LDAPBaseDN to the base DN for searching
-      for users in your LDAP directory. (e.g. "ou=People,o=MyCompany") uids
-      must be unique under the DN specified here. Set LDAPmailattribute to
-      the name of the attribute in your LDAP directory which contains the
-      primary email address. On most directory servers available, this is
-      "mail", but you may need to change this.
-      </para>      
-
-      <para>You can also try using <ulink url="http://www.openldap.org/">
-      OpenLDAP</ulink> with Bugzilla, using any of a number of administration
-      tools.  You should apply the patch attached to 
-      <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=158630">bug 158630</ulink>
-      , then set the following object classes for your users:
+      <para>Parameters required to use LDAP Authentication:</para>
 
-      <orderedlist>
-      <listitem><para>objectClass: person</para></listitem>
-      <listitem><para>objectClass: organizationalPerson</para></listitem>
-      <listitem><para>objectClass: inetOrgPerson</para></listitem>
-      <listitem><para>objectClass: top</para></listitem>
-      <listitem><para>objectClass: posixAccount</para></listitem>
-      <listitem><para>objectClass: shadowAccount</para></listitem>
-      </orderedlist>
+      <variablelist>
+        <varlistentry id="param-loginmethod">
+          <term>loginmethod</term>
+          <listitem>
+            <para>This parameter should be set to <quote>LDAP</quote>
+            <emphasis>only</emphasis> if you will be using an LDAP directory
+            for authentication. If you set this param to <quote>LDAP</quote> but
+            fail to set up the other parameters listed below you will not be
+            able to log back in to Bugzilla one you log out. If this happens
+            to you, you will need to manually edit
+            <filename>data/params</filename> and set loginmethod 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>
+           </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 e-mail 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 e-mail address your users will enter
+             into the Bugzilla login boxes.
+             </para>
+             <para>Ex. <quote>mail</quote></para>
+           </listitem>
+          </varlistentry>
+      </variablelist>
 
-      Please note that this patch <emphasis>has not</emphasis> yet been
-      accepted by the Bugzilla team, and so you may need to do some
-      manual tweaking.  That said, it looks like Net::LDAP is probably
-      the way to go in the future.
-      </para>
     </section>
     
     <section id="content-type"