summaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorjake%bugzilla.org <>2008-04-04 13:46:40 +0200
committerjake%bugzilla.org <>2008-04-04 13:46:40 +0200
commit9ccb15f6f063c269cd85f74998d466cbc7d5d35d (patch)
tree506495e75fd6f033f889bb6a3658f4a38c2749e5 /docs
parent5be47f013ebfc6d916f62911d328e24606c73b1e (diff)
downloadbugzilla-9ccb15f6f063c269cd85f74998d466cbc7d5d35d.tar.gz
bugzilla-9ccb15f6f063c269cd85f74998d466cbc7d5d35d.tar.xz
Bug 211126 - As a part of fixing bug 180642 the directions for using LDAP authentication has changed.
Diffstat (limited to 'docs')
-rw-r--r--docs/en/xml/glossary.xml20
-rw-r--r--docs/en/xml/installation.xml163
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"