mirror of
https://github.com/apache/httpd.git
synced 2025-12-24 15:01:03 +03:00
b9f7303277
made apparent. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96904 13f79535-47bb-0310-9956-ffa450edef68
246 lines
9.4 KiB
XML
246 lines
9.4 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<modulesynopsis>
|
|
|
|
<name>mod_ldap</name>
|
|
<description>LDAP connection pooling and result caching
|
|
services for use by other LDAP modules</description>
|
|
<status>Experimental</status>
|
|
<sourcefile>util_ldap.c</sourcefile>
|
|
<identifier>ldap_module</identifier>
|
|
<compatibility>Available in version 2.0.41 and later</compatibility>
|
|
|
|
<summary>
|
|
<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 <code>--with-ldap</code>
|
|
flag to the <code>./configure</code> script when building
|
|
Apache.</p>
|
|
</summary>
|
|
|
|
<section id="exampleconfig"><title>Example Configuration</title>
|
|
|
|
<p>The following is an example configuration that uses
|
|
<module>mod_ldap</module> to increase the performance of HTTP Basic
|
|
authentication provided by <module>mod_auth_ldap</module>.</p>
|
|
|
|
<example>
|
|
<pre>
|
|
# Enable the LDAP connection pool and shared memory cache. Enable the
|
|
# LDAP cache status handler. Requires that mod_ldap and mod_auth_ldap
|
|
# be loaded. Change the "yourdomain.example.com" to match your domain.
|
|
|
|
LDAPSharedCacheSize 200000
|
|
LDAPCacheEntries 1024
|
|
LDAPCacheTTL 600
|
|
LDAPOpCacheEntries 1024
|
|
LDAPOpCacheTTL 600
|
|
|
|
<Location /ldap-status>
|
|
SetHandler ldap-status
|
|
Order deny,allow
|
|
Deny from all
|
|
Allow from yourdomain.example.com
|
|
AuthLDAPEnabled on
|
|
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
|
|
AuthLDAPAuthoritative on
|
|
require valid-user
|
|
</Location>
|
|
</pre></example>
|
|
</section>
|
|
|
|
<section id="pool"><title>LDAP Connection Pool</title>
|
|
|
|
<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>
|
|
</section>
|
|
|
|
<section id="cache"><title>LDAP Cache</title>
|
|
|
|
<p>For improved performance, <module>mod_ldap</module> 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><module>mod_ldap</module> supports two types of LDAP caching during the
|
|
search/bind phase with a <em>search/bind cache</em> and
|
|
during the compare phase with two <em>operation
|
|
caches</em>. Each LDAP URL that is used by the server has
|
|
its own set of these three caches.</p>
|
|
|
|
<section id="search-bind"><title>The Search/Bind Cache</title>
|
|
|
|
<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><module>mod_ldap</module> 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, <module>mod_ldap</module> 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,
|
|
<module>mod_ldap</module> bypasses the search/bind phase.</p>
|
|
|
|
<p>The search and bind cache is controlled with the <directive
|
|
module="mod_ldap">LDAPCacheEntries</directive> and <directive
|
|
module="mod_ldap">LDAPCacheTTL</directive> directives.</p>
|
|
</section>
|
|
|
|
<section id="opcaches"><title>Operation Caches</title>
|
|
|
|
<p>During attribute and distinguished name comparison
|
|
functions, <module>mod_ldap</module> 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 <directive module="mod_ldap">LDAPOpCacheEntries</directive>
|
|
and <directive module="mod_ldap">LDAPOpCacheTTL</directive>
|
|
directives.</p>
|
|
</section>
|
|
|
|
<section id="monitoring"><title>Monitoring the Cache</title>
|
|
|
|
<p><module>mod_ldap</module> has a content handler that allows
|
|
administrators to monitor the cache performance. The name of
|
|
the content handler is <code>ldap-status</code>, so the
|
|
following directives could be used to access the
|
|
<module>mod_ldap</module> cache information:</p>
|
|
<example><pre>
|
|
<Location /server/cache-info >
|
|
SetHandler ldap-status
|
|
</Location>
|
|
</pre></example>
|
|
|
|
<p>By fetching the URL
|
|
<code>http://servername/cache-info</code>, the administrator
|
|
can get a status report of every cache that is used by
|
|
<module>mod_ldap</module> cache. Note that if Apache does not
|
|
support shared memory, then each <code>httpd</code> instance has its
|
|
own cache, so reloading the URL will result in different
|
|
information each time, depending on which <code>httpd</code>
|
|
instance processes the request.</p>
|
|
</section>
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPSharedCacheSize</name>
|
|
<description>Size in bytes of the shared-memory cache</description>
|
|
<syntax>LDAPSharedCacheSize <em>bytes</em></syntax>
|
|
<default>LDAPSharedCacheSize 102400</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>Specifies the number of bytes to specify for the shared
|
|
memory cache. The default is 100kb.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPCacheEntries</name>
|
|
<description>Maximum number of entires in the primary LDAP cache</description>
|
|
<syntax>LDAPCacheEntries <em>number</em></syntax>
|
|
<default>LDAPCacheEntries 1024</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<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>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPCacheTTL</name>
|
|
<description>Time that cached items remain valid</description>
|
|
<syntax>LDAPCacheTTL <em>seconds</em></syntax>
|
|
<default>LDAPCacheTTL 600</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>Specifies the time (in seconds) that an item in the
|
|
search/bind cache remains valid. The default is 600 seconds (10
|
|
minutes).</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPOpCacheEntries</name>
|
|
<description>Number of entries used to cache LDAP compare
|
|
operations</description>
|
|
<syntax>LDAPOpCacheEntries <em>number</em></syntax>
|
|
<default>LDAPOpCacheEntries 1024</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>This specifies the number of entries <module>mod_ldap</module>
|
|
will use to cache LDAP compare operations. The default is 1024
|
|
entries. Setting it to 0 disables operation caching.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPOpCacheTTL</name>
|
|
<description>Time that entries in the operation cache remain
|
|
valid</description>
|
|
<syntax>LDAPOpCacheTTL <em>seconds</em></syntax>
|
|
<default>LDAPOpCacheTTL 600</default>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>Specifies the time (in seconds) that entries in the
|
|
operation cache remain valid. The default is 600 seconds.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>LDAPCertDBPath</name>
|
|
<description>Directory containing certificates for SSL support</description>
|
|
<syntax>LDAPCertDBPath <em>directory-path</em></syntax>
|
|
<contextlist><context>server config</context></contextlist>
|
|
|
|
<usage>
|
|
<p>This directive is only valid if Apache has been linked
|
|
against the Netscape/iPlanet Directory SDK.</p>
|
|
|
|
<p>It specifies in which directory <module>mod_ldap</module>
|
|
should look for the certificate authorities database for SSL
|
|
support. There should be a file named <code>cert7.db</code> in that
|
|
directory.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis> |