mirror of
https://github.com/apache/httpd.git
synced 2025-10-22 23:12:44 +03:00
22c671d0e0
it when the httpd-ldap project was created. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96488 13f79535-47bb-0310-9956-ffa450edef68
325 lines
13 KiB
HTML
325 lines
13 KiB
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>
|
|
<Location /server/cache-info >
|
|
SetHandler ldap-status
|
|
</Location>
|
|
</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>
|
|
|