httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bnicho...@apache.org
Subject cvs commit: httpd-ldap/docs mod_ldap.html mod_auth_ldap.html
Date Thu, 22 Aug 2002 18:21:31 GMT
bnicholes    2002/08/22 11:21:31

  Added:       docs     mod_ldap.html mod_auth_ldap.html
  Log:
  Adding the LDAP docs back into the LDAP project.  They didn't seem to make
  it when the httpd-ldap project was created.
  
  Revision  Changes    Path
  1.1                  httpd-ldap/docs/mod_ldap.html
  
  Index: mod_ldap.html
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  
  <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <meta name="generator" content="HTML Tidy, see www.w3.org" />
  
      <title>Apache module mod_ldap</title>
      <!--
                  Copyright (C) 2000,2001 Dave Carrigan <dave@rudedog.org>
                      Copyright (C) 2001-2002 The Apache Software Foundation
                -->
    </head>
    <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  
    <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
    vlink="#000080" alink="#FF0000">
      <!--#include virtual="header.html" -->
  
      <h1 align="CENTER">Module mod_ldap</h1>
  
  <blockquote><strong>This module is not included with the standard
  distribution.  It is available via CVS in the <a
  href="http://cvs.apache.org/viewcvs.cgi/httpd-ldap/">http-ldap</a>
  module.</strong></blockquote>
  
      <p>This module adds LDAP connection pooling and result caching
      to other Apache LDAP modules (like <a
      href="mod_auth_ldap.html">mod_auth_ldap</a>).</p>
  
      <p><a href="module-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="module-dict.html#SourceFile"
      rel="Help"><strong>Source File:</strong></a> util_ldap.c<br />
       <a href="module-dict.html#ModuleIdentifier"
      rel="Help"><strong>Module Identifier:</strong></a>
      ldap_module<br />
       <a href="module-dict.html#Compatibility"
      rel="Help"><strong>Compatibility:</strong></a> Available in
      Apache 2.0 and later.</p>
  
      <h2>Summary</h2>
  
      <p>This module was created to improve the performance of
      websites relying on backend connections to LDAP servers. In
      addition to the functions provided by the standard LDAP
      libraries, this module adds an LDAP connection pool and an LDAP
      shared memory cache.</p>
  
      <p>To enable this module, LDAP support must be compiled into
      apr-util. This is achieved by adding the <em>--with-ldap</em>
      flag to the <tt>./configure</tt> script when building
      Apache.</p>
  
      <h2>Directives</h2>
  
      <ul>
        <li><a
        href="#LDAPCacheEntries"><tt>LDAPCacheEntries</tt></a></li>
  
        <li><a href="#LDAPCacheTTL"><tt>LDAPCacheTTL</tt></a></li>
  
        <li><a
        href="#LDAPCertDBPath"><tt>LDAPCertDBPath</tt></a></li>
  
        <li><a
        href="#LDAPOpCacheEntries"><tt>LDAPOpCacheEntries</tt></a></li>
  
        <li><a
        href="#LDAPOpCacheTTL"><tt>LDAPOpCacheTTL</tt></a></li>
  
        <li><a
        href="#LDAPSharedCacheSize"><tt>LDAPSharedCacheSize</tt></a></li>
      </ul>
  
      <h2>LDAP Connection Pool</h2>
  
      <p>LDAP connections are pooled from request to request. This
      allows the LDAP server to remain connected and bound ready for
      the next request, without the need to unbind/connect/rebind.
      The performance advantages are similar to the effect of HTTP
      keepalives.</p>
  
      <p>On a busy server it is possible that many requests will try
      and access the same LDAP server connection simultaneously.
      Where an LDAP connection is in use, Apache will create a new
      connection alongside the original one. This ensures that the
      connection pool does not become a bottleneck.</p>
  
      <p>There is no need to manually enable connection pooling in
      the Apache configuration. Any module using this module for
      access to LDAP services will share the connection pool.</p>
  
      <h2>LDAP Cache</h2>
  
      <p>For improved performance, mod_ldap uses an aggressive
      caching strategy to minimize the number of times that the LDAP
      server must be contacted. Caching can easily double or triple
      the throughput of Apache when it is serving pages protected
      with mod_auth_ldap. In addition, the load on the LDAP server
      will be significantly decreased.</p>
  
      <p>mod_ldap supports two types of LDAP caching during the
      search/bind phase with a <em><b>search/bind cache</b></em> and
      during the compare phase with two <em><b>operation
      caches</b></em>. Each LDAP URL that is used by the server has
      its own set of these three caches.</p>
  
      <ul>
        <li>
          <h3>The Search/Bind Cache</h3>
  
          <p>The process of doing a search and then a bind is the
          most time-consuming aspect of LDAP operation, especially if
          the directory is large. The search/bind cache is used to
          cache all searches that resulted in successful binds.
          Negative results (i.e., unsuccessful searches, or searches
          that did not result in a successful bind) are not cached.
          The rationale behind this decision is that connections with
          invalid credentials are only a tiny percentage of the total
          number of connections, so by not caching invalid
          credentials, the size of the cache is reduced.</p>
  
          <p>mod_ldap stores the username, the DN retrieved, the
          password used to bind, and the time of the bind in the
          cache. Whenever a new connection is initiated with the same
          username, mod_ldap compares the password of the new
          connection with the password in the cache. If the passwords
          match, and if the cached entry is not too old, mod_ldap
          bypasses the search/bind phase.</p>
  
          <p>The search and bind cache is controlled with the <a
          href="#LDAPCacheEntries"><tt>LDAPCacheEntries</tt></a> and
          <a href="#LDAPCacheTTL"><tt>LDAPCacheTTL</tt></a>
          directives.</p>
        </li>
  
        <li>
          <h3><a id="opcaches" name="opcaches">Operation
          Caches</a></h3>
  
          <p>During attribute and distinguished name comparison
          functions, mod_ldap uses two operation caches to cache the
          compare operations. The first compare cache is used to
          cache the results of compares done to test for LDAP group
          membership. The second compare cache is used to cache the
          results of comparisons done between distinguished
          names.</p>
  
          <p>The behavior of both of these caches is controlled with
          the <a
          href="#LDAPOpCacheEntries"><tt>LDAPOpCacheEntries</tt></a>
          and <a href="#LDAPOpCacheTTL"><tt>LDAPOpCacheTTL</tt></a>
          directives.</p>
        </li>
  
        <li>
          <h3>Monitoring the Cache</h3>
  
          <p>mod_ldap has a content handler that allows
          administrators to monitor the cache performance. The name
          of the content handler is <i>ldap-status</i>, so the
          following directives could be used to access the mod_ldap
          cache information:</p>
  <pre>
  &lt;Location /server/cache-info &gt;
   SetHandler ldap-status
  &lt;/Location&gt;
  </pre>
  
          <p>By fetching the URL <i>http://servername/cache-info</i>,
          the administrator can get a status report of every cache
          that is used by mod_ldap cache. Note that if Apache does
          not support shared memory, then each <i>httpd</i> instance
          has its own cache, so reloading the URL will result in
          different information each time, depending on which
          <i>httpd</i> instance processes the request.</p>
        </li>
      </ul>
      <hr />
  
      <h2><a id="LDAPSharedCacheSize"
      name="LDAPSharedCacheSize">LDAPSharedCacheSize
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> LDAPSharedCacheSize
      <em>bytes</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>Specifies the number of bytes to specify for the shared
      memory cache. The default is 100kb.</p>
      <hr />
  
      <h2><a id="LDAPCacheEntries"
      name="LDAPCacheEntries">LDAPCacheEntries directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a>LDAPCacheEntries
      <em>size</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>Specifies the maximum size of the primary LDAP cache. This
      cache contains successful search/binds. Set it to 0 to turn off
      search/bind caching. The default size is 1024 cached
      searches.</p>
      <hr />
  
      <h2><a id="LDAPCacheTTL" name="LDAPCacheTTL">LDAPCacheTTL
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> LDAPCacheTTL
      <em>seconds</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>Specifies the time (in seconds) that an item in the
      search/bind cache remains valid. The default is 600 seconds (10
      minutes).</p>
      <hr />
  
      <h2><a id="LDAPOpCacheEntries"
      name="LDAPOpCacheEntries">LDAPOpCacheEntries directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> LDAPOpCacheEntries
      <em>seconds</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>This specifies the number of entries mod_ldap will use to
      cache LDAP compare operations. The default is 1024 entries.
      Setting it to 0 disables operation caching.</p>
      <hr />
  
      <h2><a id="LDAPOpCacheTTL" name="LDAPOpCacheTTL">LDAPOpCacheTTL
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> LDAPOpCacheTTL
      <em>seconds</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>Specifies the time (in seconds) that entries in the
      operation cache remain valid. The default is 600 seconds.</p>
      <hr />
  
      <h2><a id="LDAPCertDBPath" name="LDAPCertDBPath">LDAPCertDBPath
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> LDAPCertDBPath
      <em>directory-path</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> server config<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Override"
       rel="Help"><strong>Override:</strong></a> Not Applicable<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Status"
       rel="Help"><strong>Status:</strong></a> Extension<br />
       <a
      href="http://www.apache.org/docs/mod/directive-dict.html#Module"
       rel="Help"><strong>Module:</strong></a> mod_ldap</p>
  
      <p>This directive is only valid if Apache has been linked
      against the Netscape/iPlanet Directory SDK.</p>
  
      <p>It specifies in which directory mod_ldap should look for the
      certificate authorities database for SSL support. There should
      be a file named <tt>cert7.db</tt> in that directory.</p>
      <!--#include virtual="footer.html" -->
    </body>
  </html>
  
  
  
  
  1.1                  httpd-ldap/docs/mod_auth_ldap.html
  
  Index: mod_auth_ldap.html
  ===================================================================
  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  
  <html xmlns="http://www.w3.org/1999/xhtml">
    <head>
      <meta name="generator" content="HTML Tidy, see www.w3.org" />
  
      <title>Apache module mod_ldap</title>
      <!--
                  Copyright (C) 2000,2001 Dave Carrigan <dave@rudedog.org>
                      Copyright (C) 2001-2002 The Apache Software Foundation
                -->
    </head>
    <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  
    <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
    vlink="#000080" alink="#FF0000">
      <!--#include virtual="header.html" -->
  
      <h1 align="CENTER">Module mod_auth_ldap</h1>
  
      <p>This is an authentication module that allows Apache to
      authenticate HTTP clients using user entries in an LDAP
      directory.</p>
  
      <p><a href="module-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="module-dict.html#SourceFile"
      rel="Help"><strong>Source File:</strong></a> util_ldap.c<br />
       <a href="module-dict.html#ModuleIdentifier"
      rel="Help"><strong>Module Identifier:</strong></a>
      ldap_module<br />
       <a href="module-dict.html#Compatibility"
      rel="Help"><strong>Compatibility:</strong></a> Available in
      Apache 2.0 and later.</p>
  
      <h2>Summary</h2>
  
      <p>mod_auth_ldap supports the following features:</p>
  
      <ul>
        <li>Known to support the <a
        href="http://www.openldap.org/">OpenLDAP SDK</a> (both 1.x
        and 2.x), and the <a
        href="http://www.iplanet.com/downloads/developer/">iPlanet
        (Netscape)</a> SDK.</li>
  
        <li>Complex authorization policies can be implemented by
        representing the policy with LDAP filters.</li>
  
        <li>Support for Microsoft FrontPage allows FrontPage users to
        control access to their webs, while retaining LDAP for user
        authentication.</li>
  
        <li>Uses extensive caching of LDAP operations via <a
        href="mod_ldap.html">mod_ldap</a>.</li>
  
        <li>Support for LDAP over SSL (requires the Netscape SDK) or
        TLS (requires the OpenLDAP 2.x SDK).</li>
      </ul>
  
      <h2>Directives</h2>
  
      <ul>
        <li><a
        href="#AuthLDAPAuthoritative">AuthLDAPAuthoritative</a></li>
  
        <li><a href="#AuthLDAPBindDN">AuthLDAPBindDN</a></li>
  
        <li><a
        href="#AuthLDAPBindPassword">AuthLDAPBindPassword</a></li>
  
        <li><a
        href="#AuthLDAPCompareDNOnServer">AuthLDAPCompareDNOnServer</a></li>
  
        <li><a
        href="#AuthLDAPDereferenceAliases">AuthLDAPDereferenceAliases</a></li>
  
        <li><a href="#AuthLDAPEnabled">AuthLDAPEnabled</a></li>
  
        <li><a
        href="#AuthLDAPFrontPageHack">AuthLDAPFrontPageHack</a></li>
  
        <li><a
        href="#AuthLDAPGroupAttribute">AuthLDAPGroupAttribute</a></li>
  
        <li><a
        href="#AuthLDAPGroupAttributeIsDN">AuthLDAPGroupAttributeIsDN</a></li>
  
        <li><a
        href="#AuthLDAPRemoteUserIsDN">AuthLDAPRemoteUserIsDN</a></li>
  
        <li><a href="#AuthLDAPStartTLS">AuthLDAPStartTLS</a></li>
  
        <li><a href="#AuthLDAPUrl">AuthLDAPUrl</a></li>
      </ul>
  
      <h2>Contents</h2>
  
      <ul>
        <li>
          <a href="#operation">Operation</a> 
  
          <ul>
            <li><a href="#authenphase">The Authentication
            Phase</a></li>
  
            <li><a href="#authorphase">The Authorization
            Phase</a></li>
          </ul>
        </li>
  
        <li>
          <a href="#requiredirectives">The require Directives</a> 
  
          <ul>
            <li><a href="#reqvaliduser">require valid-user</a></li>
  
            <li><a href="#requser">require user</a></li>
  
            <li><a href="#reqgroup">require group</a></li>
  
            <li><a href="#reqdn">require dn</a></li>
          </ul>
        </li>
  
        <li><a href="#examples">Examples</a></li>
  
        <li><a href="#usingtls">Using TLS</a></li>
  
        <li><a href="#usingssl">Using SSL</a></li>
  
        <li>
          <a href="#frontpage">Using Microsoft FrontPage with
          mod_auth_ldap</a> 
  
          <ul>
            <li><a href="#howitworks">How It Works</a></li>
  
            <li><a href="#fpcaveats">Caveats</a></li>
          </ul>
        </li>
      </ul>
  
      <h2><a id="operation" name="operation">Operation</a></h2>
  
      <p>There are two phases in granting access to a user. The first
      phase is authentication, in which mod_auth_ldap verifies that
      the user's credentials are valid. This also called the
      <em><b>search/bind</b></em> phase. The second phase is
      authorization, in which mod_auth_ldap determines if the
      authenticated user is allowed access to the resource in
      question. This is also known as the <em><b>compare</b></em>
      phase.</p>
  
      <h3><a id="authenphase" name="authenphase">The Authentication
      Phase</a></h3>
  
      <p>During the authentication phase, mod_auth_ldap searches for
      an entry in the directory that matches the username that the
      HTTP client passes. If a single unique match is found, then
      mod_auth_ldap attempts to bind to the directory server using
      the DN of the entry plus the password provided by the HTTP
      client. Because it does a search, then a bind, it is often
      referred to as the search/bind phase. Here are the steps taken
      during the search/bind phase.</p>
  
      <ol>
        <li>Generate a search filter by combining the attribute and
        filter provided in the <a
        href="#AuthLDAPURL"><tt>AuthLDAPURL</tt></a> directive with
        the username passed by the HTTP client.</li>
  
        <li>Search the directory using the generated filter. If the
        search does not return exactly one entry, deny or decline
        access.</li>
  
        <li>Fetch the distinguished name of the entry retrieved from
        the search and attempt to bind to the LDAP server using the
        DN and the password passed by the HTTP client. If the bind is
        unsuccessful, deny or decline access.</li>
      </ol>
  
      <p>The following directives are used during the search/bind
      phase</p>
  
      <table border="0" bgcolor="#ffffff">
        <tr valign="top">
          <td colspan="1" align="left"><a
          href="#AuthLDAPURL">AuthLDAPURL</a> </td>
  
          <td colspan="1" align="left">Specifies the LDAP server, the
          base DN, the attribute to use in the search, as well as the
          extra search filter to use.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left"><a
          href="#AuthLDAPBindDN">AuthLDAPBindDN</a> </td>
  
          <td colspan="1" align="left">An optional DN to bind with
          during the search phase.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left"><a
          href="#AuthLDAPBindPassword">AuthLDAPBindPassword</a> </td>
  
          <td colspan="1" align="left">An optional password to bind
          with during the search phase.</td>
        </tr>
      </table>
  
      <h3><a id="authorphase" name="authorphase">The Authorization
      Phase</a></h3>
  
      <p>During the authorization phase, mod_auth_ldap attempts to
      determine if the user is authorized to access the resource.
      Many of these checks require mod_auth_ldap to do a compare
      operation on the LDAP server. This is why this phase is often
      referred to as the compare phase. mod_auth_ldap accepts the
      following <a href="#requiredirectives"><tt>require</tt>
      directives</a> to determine if the credentials are
      acceptable:</p>
  
      <ul>
        <li>Grant access if there is a <a href="#requser"><tt>require
        valid-user</tt></a> directive.</li>
  
        <li>Grant access if there is a <a
        href="#reqgroup"><tt>require user</tt></a> directive, and the
        username in the directive matches the username passed by the
        client.</li>
  
        <li>Grant access if there is a <a href="#reqdn"><tt>require
        dn</tt></a> directive, and the DN in the directive matches
        the DN fetched from the LDAP directory.</li>
  
        <li>Grant access if there is a <a
        href="#reqgroup"><tt>require group</tt></a> directive, and
        the DN fetched from the LDAP directory (or the username
        passed by the client) occurs in the LDAP group.</li>
  
        <li>otherwise, deny or decline access</li>
      </ul>
  
      <p>mod_auth_ldap uses the following directives during the
      compare phase:</p>
  
      <table border="0" bgcolor="#ffffff">
        <tr>
          <td><a href="#AuthLDAPURL"><tt>AuthLDAPURL</tt></a> </td>
  
          <td colspan="1" align="left">The attribute specified in the
          URL is used in compare operations for the <tt>require
          user</tt> operation.</td>
        </tr>
  
        <tr>
          <td><a
          href="#AuthLDAPCompareDNOnServer"><tt>AuthLDAPCompareDNOnServer</tt></a>
          </td>
  
          <td colspan="1" align="left">Determines the behavior of the
          <tt>require dn</tt> directive.</td>
        </tr>
  
        <tr>
          <td><a
          href="#AuthLDAPGroupAttribute"><tt>AuthLDAPGroupAttribute</tt></a>
          </td>
  
          <td colspan="1" align="left">Determines the attribute to
          use for comparisons in the <tt>require group</tt>
          directive.</td>
        </tr>
  
        <tr>
          <td><a
          href="#AuthLDAPGroupAttributeIsDN"><tt>AuthLDAPGroupAttributeIsDN</tt></a>
          </td>
  
          <td colspan="1" align="left">Specifies whether to use the
          user DN or the username when doing comparisons for the
          <tt>require group</tt> directive.</td>
        </tr>
      </table>
  
      <h2><a id="requiredirectives" name="requiredirectives">The
      require Directives</a></h2>
  
      <p>Apache's <tt>require</tt> directives are used during the
      authorization phase to ensure that a user is allowed to access
      a resource.</p>
  
      <h3><a id="reqvaliduser" name="reqvaliduser">require
      valid-user</a></h3>
  
      <p>If this directive exists, mod_auth_ldap grants access to any
      user that has successfully authenticated during the search/bind
      phase.</p>
  
      <h3><a id="requser" name="requser">require user</a></h3>
  
      <p>The <tt>require user</tt> directive specifies what usernames
      can access the resource. Once mod_auth_ldap has retrieved a
      unique DN from the directory, it does an LDAP compare operation
      using the username specified in the <tt>require user</tt> to
      see if that username is part of the just-fetched LDAP entry.
      Multiple users can be granted access by putting multiple
      usernames on the line, separated with spaces. If a username has
      a space in it, then it must be the only user on the line. In
      this case, multiple users can be granted access by using
      multiple <tt>require user</tt> directives, with one user per
      line. For example, with a <tt>AuthLDAPURL</tt> of
      <i>ldap://ldap/o=Airius?cn</i> (i.e., <tt>cn</tt> is used for
      searches), the following require directives could be used to
      restrict access:</p>
  <pre>
  require user Barbara Jenson
  require user Fred User
  require user Joe Manager
  </pre>
  
      <p>Because of the way that mod_auth_ldap handles this
      directive, Barbara Jenson could sign on as <i>Barbara
      Jenson</i>, <i>Babs Jenson</i> or any other <tt>cn</tt> that
      she has in her LDAP entry. Only the single <tt>require
      user</tt> line is needed to support all values of the attribute
      in the user's entry.</p>
  
      <p>If the <tt>uid</tt> attribute was used instead of the
      <tt>cn</tt> attribute in the URL above, the above three lines
      could be condensed to</p>
  <pre>
  require user bjenson fuser jmanager
  </pre>
  
      <h3><a id="reqgroup" name="reqgroup">require group</a></h3>
  
      <p>This directive specifies an LDAP group whose members are
      allowed access. It takes the distinguished name of the LDAP
      group. For example, assume that the following entry existed in
      the LDAP directory:</p>
  <pre>
  dn: cn=Administrators, o=Airius
  objectClass: groupOfUniqueNames
  uniqueMember: cn=Barbara Jenson, o=Airius
  uniqueMember: cn=Fred User, o=Airius
  </pre>
  
      <p>The following directive would grant access to both Fred and
      Barbara:</p>
  <pre>
  require group cn=Administrators, o=Airius
  </pre>
  
      <p>Behavior of this directive is modified by the <a
      href="#AuthLDAPGroupAttribute"><tt>AuthLDAPGroupAttribute</tt></a>
      and <a
      href="#AuthLDAPGroupAttributeIsDN"><tt>AuthLDAPGroupAttributeIsDN</tt></a>
      directives.</p>
  
      <h3><a id="reqdn" name="reqdn">require dn</a></h3>
  
      <p>The <tt>require dn</tt> directive allows the administrator
      to grant access based on distinguished names. It specifies a DN
      that must match for access to be granted. If the distinguished
      name that was retrieved from the directory server matches the
      distinguished name in the <tt>require dn</tt>, then
      authorization is granted.</p>
  
      <p>The following directive would grant access to a specific
      DN:</p>
  <pre>
  require dn cn=Barbara Jenson, o=Airius
  </pre>
  
      <p>Behavior of this directive is modified by the <a
      href="#AuthLDAPCompareDNOnServer"><tt>AuthLDAPCompareDNOnServer</tt></a>
      directive.</p>
  
      <h2><a id="examples" name="examples">Examples</a></h2>
  
      <ul>
        <li>
          Grant access to anyone who exists in the LDAP directory,
          using their UID for searches. 
  <pre>
  AuthLDAPURL ldap://ldap1.airius.com:389/ou=People, o=Airius?uid?sub?(objectClass=*)
  require valid-user
  </pre>
        </li>
  
        <li>
          The next example is the same as above; but with the fields
          that have useful defaults omitted. Also, note the use of a
          redundant LDAP server. 
  <pre>
  AuthLDAPURL ldap://ldap1.airius.com ldap2.airius.com/ou=People, o=Airius
  require valid-user
  </pre>
        </li>
  
        <li>
          The next example is similar to the previous one, but is
          uses the common name instead of the UID. Note that this
          could be problematical if multiple people in the directory
          share the same <tt>cn</tt>, because a search on <tt>cn</tt>
          <em><b>must</b></em> return exactly one entry. That's why
          this approach is not recommended: it's a better idea to
          choose an attribute that is guaranteed unique in your
          directory, such as <tt>uid</tt>. 
  <pre>
  AuthLDAPURL ldap://ldap.airius.com/ou=People, o=Airius?cn
  require valid-user
  </pre>
        </li>
  
        <li>
          Grant access to anybody in the Administrators group. The
          users must authenticate using their UID. 
  <pre>
  AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid
  require group cn=Administrators, o=Airius
  </pre>
        </li>
  
        <li>
          The next example assumes that everyone at Airius who
          carries an alphanumeric pager will have an LDAP attribute
          of <tt>qpagePagerID</tt>. The example will grant access
          only to people (authenticated via their UID) who have
          alphanumeric pagers: 
  <pre>
  AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(qpagePagerID=*)
  require valid-user
  </pre>
        </li>
  
        <li>
          <p>The next example demonstrates the power of using filters
          to accomplish complicated administrative requirements.
          Without filters, it would have been necessary to create a
          new LDAP group and ensure that the group's members remain
          synchronized with the pager users. This becomes trivial
          with filters. The goal is to grant access to anyone who has
          a filter, plus grant access to Joe Manager, who doesn't
          have a pager, but does need to access the same
          resource:</p>
  <pre>
  AuthLDAPURL ldap://ldap.airius.com/o=Airius?uid??(|(qpagePagerID=*)(uid=jmanager))
  require valid-user
  </pre>
  
          <p>This last may look confusing at first, so it helps to
          evaluate what the search filter will look like based on who
          connects, as shown below. The text in blue is the part that
          is filled in using the attribute specified in the URL. The
          text in red is the part that is filled in using the filter
          specified in the URL. The text in green is filled in using
          the information that is retrieved from the HTTP client. If
          Fred User connects as <i>fuser</i>, the filter would look
          like</p>
  
          <p><tt>(&amp;<font
          color="red">(|(qpagePagerID=*)(uid=jmanager))</font>(<font
          color="blue">uid</font>=<font
          color="green">fuser</font>))</tt></p>
  
          <p>The above search will only succeed if <i>fuser</i> has a
          pager. When Joe Manager connects as <i>jmanager</i>, the
          filter looks like</p>
  
          <p><tt>(&amp;<font
          color="red">(|(qpagePagerID=*)(uid=jmanager))</font>(<font
          color="blue">uid</font>=<font
          color="green">jmanager</font>))</tt></p>
  
          <p>The above search will succeed whether <i>jmanager</i>
          has a pager or not.</p>
        </li>
      </ul>
  
      <h2><a id="usingtls" name="usingtls">Using TLS</a></h2>
  
      <p>To use TLS, simply set the <tt>AuthLDAPStartTLS</tt> to on.
      Nothing else needs to be done (other than ensure that your LDAP
      server is configured for TLS).</p>
  
      <h2><a id="usingssl" name="usingssl">Using SSL</a></h2>
  
      <p>If mod_auth_ldap is linked against the Netscape/iPlanet LDAP
      SDK, it will not talk to any SSL server unless that server has
      a certificate signed by a known Certificate Authority. As part
      of the configuration mod_auth_ldap needs to be told where it
      can find a database containing the known CAs. This database is
      in the same format as Netscape Communicator's <tt>cert7.db</tt>
      database. The easiest way to get this file is to start up a
      fresh copy of Netscape, and grab the resulting
      <tt>$HOME/.netscape/cert7.db</tt> file.</p>
  
      <p>To specify a secure LDAP server, use <i>ldaps://</i> in the
      <tt>AuthLDAPURL</tt> directive, instead of <i>ldap://</i>.</p>
  
      <h2><a id="frontpage" name="frontpage">Using Microsoft
      FrontPage with mod_auth_ldap</a></h2>
  
      <p>Normally, FrontPage uses FrontPage-web-specific user/group
      files (i.e., the <i>mod_auth</i> module) to handle all
      authentication. Unfortunately, it is not possible to just
      change to LDAP authentication by adding the proper directives,
      because it will break the <em><b>Permissions</b></em> forms in
      the FrontPage client, which attempt to modify the standard
      text-based authorization files.</p>
  
      <p>Once a FrontPage web has been created, adding LDAP
      authentication to it is a matter of adding the following
      directives to <em><b>every</b></em> <tt>.htaccess</tt> file
      that gets created in the web</p>
  <pre>
  AuthLDAPURL            the url
  AuthLDAPAuthoritative  off
  AuthLDAPFrontPageHack  on
  </pre>
  
      <p><tt>AuthLDAPAuthoritative</tt> must be off to allow
      mod_auth_ldap to decline group authentication so that Apache
      will fall back to file authentication for checking group
      membership. This allows the FrontPage-managed group file to be
      used.</p>
  
      <h3><a id="howitworks" name="howitworks">How It Works</a></h3>
  
      <p>FrontPage restricts access to a web by adding the
      <tt>require valid-user</tt> directive to the <tt>.htaccess</tt>
      files. If <tt>AuthLDAPFrontPageHack</tt> is not on, the
      <tt>require valid-user</tt> directive will succeed for any user
      who is valid <em><b>as far as LDAP is concerned</b></em>. This
      means that anybody who has an entry in the LDAP directory is
      considered a valid user, whereas FrontPage considers only those
      people in the local user file to be valid. The purpose of the
      hack is to force Apache to consult the local user file (which
      is managed by FrontPage) - instead of LDAP - when handling the
      <tt>require valid-user</tt> directive.</p>
  
      <p>Once directives have been added as specified above,
      FrontPage users will be able to perform all management
      operations from the FrontPage client.</p>
  
      <h3><a id="fpcaveats" name="fpcaveats">Caveats</a></h3>
  
      <ul>
        <li>When choosing the LDAP URL, the attribute to use for
        authentication should be something that will also be valid
        for putting into a <i>mod_auth</i> user file. The user ID is
        ideal for this.</li>
  
        <li>When adding users via FrontPage, FrontPage administrators
        should choose usernames that already exist in the LDAP
        directory (for obvious reasons). Also, the password that the
        administrator enters into the form is ignored, since Apache
        will actually be authenticating against the password in the
        LDAP database, and not against the password in the local user
        file. This could cause confusion for web administrators.</li>
  
        <li>Apache must be compiled with <i>mod_auth</i> in order to
        use FrontPage support. This is because Apache will still use
        the <i>mod_auth</i> group file for determine the extent of a
        user's access to the FrontPage web.</li>
  
        <li>The directives must be put in the <tt>.htaccess</tt>
        files. Attempting to put them inside
        <tt>&lt;Location&gt;</tt> or <tt>&lt;Directory&gt;</tt>
        directives won't work. This is because mod_auth_ldap has to
        be able to grab the <tt>AuthUserFile</tt> directive that is
        found in FrontPage <tt>.htaccess</tt> files so that it knows
        where to look for the valid user list. If the mod_auth_ldap
        directives aren't in the same <tt>.htaccess</tt> file as the
        FrontPage directives, then the hack won't work, because
        mod_auth_ldap will never get a chance to process the
        <tt>.htaccess</tt> file, and won't be able to find the
        FrontPage-managed user file.</li>
      </ul>
      <hr />
  
      <h2><a id="AuthLDAPAuthoritative"
      name="AuthLDAPAuthoritative">AuthLDAPAuthoritative
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPAuthoritative
      on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a>
      <code>AuthLDAPAuthoritative on</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>Set to <i>off</i> if this module should let other
      authentication modules attempt to authenticate the user, should
      authentication with this module fail. Control is only passed on
      to lower modules if there is no DN or rule that matches the
      supplied user name (as passed by the client).</p>
      <hr />
  
      <h2><a id="AuthLDAPBindDN" name="AuthLDAPBindDN">AuthLDAPBindDN
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPBindDN
      <em>distinguished-name</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>An optional DN used to bind to the server when searching for
      entries. If not provided, mod_auth_ldap will use an anonymous
      bind.</p>
      <hr />
  
      <h2><a id="AuthLDAPBindPassword"
      name="AuthLDAPBindPassword">AuthLDAPBindPassword
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPBindPassword
      <em>password</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>A bind password to use in conjunction with the bind DN. Note
      that the bind password is probably sensitive data, and should
      be properly protected. You should only use the <a
      href="#AuthLDAPBindDN"><tt>AuthLDAPBindDN</tt></a> and <a
      href="#AuthLDAPBindPassword"><tt>AuthLDAPBindPassword</tt></a>
      if you absolutely need them to search the directory.</p>
      <hr />
  
      <h2><a id="AuthLDAPCompareDNOnServer"
      name="AuthLDAPCompareDNOnServer">AuthLDAPCompareDNOnServer
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a>
      AuthLDAPCompareDNOnServer on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a>
      <code>AuthLDAPCompareDNOnServer on</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>When set, mod_auth_ldap will use the LDAP server to compare
      the DNs. This is the only foolproof way to compare DNs.
      mod_auth_ldap will search the directory for the DN specified
      with the <a href="#reqdn"><tt>require dn</tt></a> directive,
      then, retrieve the DN and compare it with the DN retrieved from
      the user entry. If this directive is not set, mod_auth_ldap
      simply does a string comparison. It is possible to get false
      negatives with this approach, but it is much faster. Note the
      mod_ldap cache can speed up DN comparison in most
      situations.</p>
      <hr />
  
      <h2><a id="AuthLDAPDereferenceAliases"
      name="AuthLDAPDereferenceAliases">AuthLDAPDereferenceAliases
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a>
      AuthLDAPDereferenceAliases never|searching|finding|always<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a>
      <code>AuthLDAPDereferenceAliases Always</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>This directive specifies when mod_auth_ldap will
      de-reference aliases during LDAP operations. The default is
      <i>always</i>.</p>
      <hr />
  
      <h2><a id="AuthLDAPEnabled"
      name="AuthLDAPEnabled">AuthLDAPEnabled directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPEnabled
      on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a> <code>AuthLDAPEnabled
      on</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>Set to <i>off</i> to disable mod_auth_ldap in certain
      directories. This is useful if you have mod_auth_ldap enabled
      at or near the top of your tree, but want to disable it
      completely in certain locations.</p>
      <hr />
  
      <h2><a id="AuthLDAPFrontPageHack"
      name="AuthLDAPFrontPageHack">AuthLDAPFrontPageHack
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPFrontPageHack
      on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a>
      <code>AuthLDAPFronPageHack off</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>See the section on <a href="#frontpage">using Microsoft
      FrontPage</a> with mod_auth_ldap.</p>
      <hr />
  
      <h2><a id="AuthLDAPGroupAttribute"
      name="AuthLDAPGroupAttribute">AuthLDAPGroupAttribute
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPGroupAttribute
      <em>attribute</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>This directive specifies which LDAP attributes are used to
      check for group membership. Multiple attributes can be used by
      specifying this directive multiple times. If not specified,
      then mod_auth_ldap uses the <tt>member</tt> and
      <tt>uniquemember</tt> attributes.</p>
      <hr />
  
      <h2><a id="AuthLDAPGroupAttributeIsDN"
      name="AuthLDAPGroupAttributeIsDN">AuthLDAPGroupAttributeIsDN
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a>
      AuthLDAPGroupAttributeIsDN on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a>
      <code>AuthLDAPGroupAttributeIsDN on</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>When set, this directive says to use the distinguished name
      of the client username when checking for group membership.
      Otherwise, the username will be used. For example, assume that
      the client sent the username <i>bjenson</i>, which corresponds
      to the LDAP DN <i>cn=Babs Jenson, o=Airius</i>. If this
      directive is set, mod_auth_ldap will check if the group has
      <i>cn=Babs Jenson, o=Airius</i> as a member. If this directive
      is not set, then mod_auth_ldap will check if the group has
      <i>bjenson</i> as a member.</p>
      <hr />
  
      <h2><a id="AuthLDAPRemoteUserIsDN"
      name="AuthLDAPRemoteUserIsDN">AuthLDAPRemoteUserIsDN
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPRemoteUserIsDN
      on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a> <code>AuthLDAPUserIsDN
      off</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>If this directive is set to on, the value of the
      <i>REMOTE_USER</i> environment variable will be set to the full
      distinguished name of the authenticated user, rather than just
      the username that was passed by the client. It is turned off by
      default.</p>
      <hr />
  
      <h2><a id="AuthLDAPStartTLS"
      name="AuthLDAPStartTLS">AuthLDAPStartTLS directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPStartTLS
      on|off<br />
       <a href="directive-dict.html#Default"
      rel="Help"><strong>Default:</strong></a> <code>AuthLDAPStartTLS
      off</code><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>If this directive is set to on, mod_auth_ldap will start a
      secure TLS session after connecting to the LDAP server. This
      requires your LDAP server to support TLS.</p>
      <hr />
  
      <h2><a id="AuthLDAPUrl" name="AuthLDAPUrl">AuthLDAPUrl
      directive</a></h2>
  
      <p><a href="directive-dict.html#Syntax"
      rel="Help"><strong>Syntax:</strong></a> AuthLDAPUrl
      <em>url</em><br />
       <a href="directive-dict.html#Context"
      rel="Help"><strong>Context:</strong></a> directory,
      .htaccess<br />
       <a href="directive-dict.html#Override"
      rel="Help"><strong>Override:</strong></a> AuthConfig<br />
       <a href="directive-dict.html#Status"
      rel="Help"><strong>Status:</strong></a> Extension<br />
       <a href="directive-dict.html#Module"
      rel="Help"><strong>Module:</strong></a> mod_auth_ldap</p>
  
      <p>An RFC 2255 URL which specifies the LDAP search parameters
      to use. The syntax of the URL is</p>
  <pre>
  ldap://host:port/basedn?attribute?scope?filter
  </pre>
  
      <table border="0" bgcolor="#ffffff">
        <tr valign="top">
          <td colspan="1" align="left">ldap</td>
  
          <td colspan="1" align="left">For regular ldap, use the
          string <i>ldap</i>. For secure LDAP, use <i>ldaps</i>
          instead. Secure LDAP is only available if Apache was linked
          to an LDAP library with SSL support.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left">host:port</td>
  
          <td colspan="1" align="left">
            <p>The name/port of the ldap server (defaults to
            <i>localhost:389</i> for <i>ldap</i>, and
            <i>localhost:636</i> for <i>ldaps</i>). To specify
            multiple, redundant LDAP servers, just list all servers,
            separated by spaces. mod_auth_ldap will try connecting to
            each server in turn, until it makes a successful
            connection.</p>
  
            <p>Once a connection has been made to a server, that
            connection remains active for the life of the
            <i>httpd</i> process, or until the LDAP server goes
            down.</p>
  
            <p>If the LDAP server goes down and breaks an existing
            connection, mod_auth_ldap will attempt to re-connect,
            starting with the primary server, and trying each
            redundant server in turn. Note that this is different
            than a true round-robin search.</p>
          </td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left">basedn</td>
  
          <td colspan="1" align="left">The DN of the branch of the
          directory where all searches should start from. At the very
          least, this must be the top of your directory tree, but
          could also specify a subtree in the directory.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left">attribute</td>
  
          <td colspan="1" align="left">The attribute to search for.
          Although RFC 2255 allows a comma-separated list of
          attributes, only the first attribute will be used, no
          matter how many are provided. If no attributes are
          provided, the default is to use <tt>uid</tt>. It's a good
          idea to choose an attribute that will be unique across all
          entries in the subtree you will be using.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left">scope</td>
  
          <td colspan="1" align="left">The scope of the search. Can
          be either <i>one</i> or <i>sub</i>. Note that a scope of
          <i>base</i> is also supported by RFC 2255, but is not
          supported by this module. If the scope is not provided, or
          if <i>base</i> scope is specified, the default is to use a
          scope of <i>sub</i>.</td>
        </tr>
  
        <tr valign="top">
          <td colspan="1" align="left">filter</td>
  
          <td colspan="1" align="left">A valid LDAP search filter. If
          not provided, defaults to <tt>(objectClass=*)</tt>, which
          will search for all objects in the tree. Filters are
          limited to approximately 8000 characters (the definition of
          <i>MAX_STRING_LEN</i> in the Apache source code). This
          should be than sufficient for any application.</td>
        </tr>
      </table>
  
      <p>When doing searches, the attribute, filter and username
      passed by the HTTP client are combined to create a search
      filter that looks like
      <tt>(&amp;(<i>filter</i>)(<i>attribute</i>=<i>username</i>))</tt>.</p>
  
      <p>For example, consider an URL of
      <i>ldap://ldap.airius.com/o=Airius?cn?sub?(posixid=*)</i>. When
      a client attempts to connect using a username of <i>Babs
      Jenson</i>, the resulting search filter will be
      <tt>(&amp;(posixid=*)(cn=Babs Jenson))</tt>.</p>
  
      <p>See above for examples of <a
      href="#AuthLDAPURL"><tt>AuthLDAPURL</tt></a> URLs.</p>
      <!--#include virtual="footer.html" -->
    </body>
  </html>
  
  
  
  

Mime
View raw message