mod_ldap.html revision 1f778a67534ea050f458e927143191fb8868eea3
<!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>