Apache Module mod_ldap

Available Languages: en

- - - - -

Description:	LDAP connection pooling and result caching services for use -by other LDAP modules
Status:	Experimental
Module Identifier:	ldap_module
Source File:	util_ldap.c
Compatibility:	Available in version 2.0.41 and later

Summary

- -

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.

- -

To enable this module, LDAP support must be compiled into - apr-util. This is achieved by adding the --with-ldap - flag to the configure script when building - Apache.

- -

SSL support requires that mod_ldap be linked - with one of the following LDAP SDKs: - OpenLDAP SDK (both 1.x and 2.x), - Novell LDAP SDK or the - iPlanet(Netscape) SDK.

- -

Topics

Example Configuration
LDAP Connection Pool
LDAP Cache
Using SSL

Example Configuration

The following is an example configuration that uses - mod_ldap to increase the performance of HTTP Basic - authentication provided by mod_auth_ldap.

- -

- # 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> -

LDAP Connection Pool

- -

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.

- -

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.

- -

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.

LDAP Cache

- -

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.

- -

mod_ldap supports two types of LDAP caching during - the search/bind phase with a search/bind cache and - during the compare phase with two operation - caches. Each LDAP URL that is used by the server has - its own set of these three caches.

- -

The Search/Bind Cache

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.

- -

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.

- -

The search and bind cache is controlled with the LDAPCacheEntries and LDAPCacheTTL directives.

- - -

Operation Caches

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.

- -

The behavior of both of these caches is controlled with - the LDAPOpCacheEntries - and LDAPOpCacheTTL - directives.

- - -

Monitoring the Cache

mod_ldap has a content handler that allows - administrators to monitor the cache performance. The name of - the content handler is ldap-status, so the - following directives could be used to access the - mod_ldap cache information:

- -

- <Location /server/cache-info> - - SetHandler ldap-status - - </Location> -

- -

By fetching the URL http://servername/cache-info, - 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 httpd instance has its - own cache, so reloading the URL will result in different - information each time, depending on which httpd - instance processes the request.

- -

Using SSL

- -

The ability to create an SSL connections to an LDAP server - is defined by the directives - LDAPTrustedCA and - LDAPTrustedCAType. These directives specify the certificate - file or database and the certificate type. Whenever the LDAP url - includes ldaps://, mod_ldap will establish - a secure connection to the LDAP server.

- -

- # Establish an SSL LDAP connection. Requires that - # mod_ldap and mod_auth_ldap be loaded. Change the - # "yourdomain.example.com" to match your domain. - - LDAPTrustedCA /certs/certfile.der - LDAPTrustedCAType DER_FILE - - <Location /ldap-status> - - SetHandler ldap-status - Order deny,allow - Deny from all - Allow from yourdomain.example.com - AuthLDAPEnabled on - AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one - AuthLDAPAuthoritative on - Require valid-user - - </Location> -

- -

If mod_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_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 cert7.db - database. The easiest way to get this file is to start up a fresh - copy of Netscape, and grab the resulting - $HOME/.netscape/cert7.db file.

- -

LDAPCacheEntries Directive

- - - - - - - -

Description:	Maximum number of entries in the primary LDAP cache
Syntax:	`LDAPCacheEntries number`
Default:	`LDAPCacheEntries 1024`
Context:	server config
Status:	Experimental
Module:	mod_ldap

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.

- -

LDAPCacheTTL Directive

- - - - - - - -

Description:	Time that cached items remain valid
Syntax:	`LDAPCacheTTL seconds`
Default:	`LDAPCacheTTL 600`
Context:	server config
Status:	Experimental
Module:	mod_ldap

Specifies the time (in seconds) that an item in the - search/bind cache remains valid. The default is 600 seconds (10 - minutes).

- -

LDAPConnectionTimeout Directive

- - - - - - -

Description:	Specifies the socket connection timeout in seconds
Syntax:	`LDAPConnectionTimeout seconds`
Context:	server config
Status:	Experimental
Module:	mod_ldap

Specifies the timeout value (in seconds) in which the module will - attempt to connect to the LDAP server. If a connection is not - successful with the timeout period, either an error will be - returned or the module will attempt to connect to a secondary LDAP - server if one is specified. The default is 10 seconds.

- -

LDAPOpCacheEntries Directive

- - - - - - - -

Description:	Number of entries used to cache LDAP compare -operations
Syntax:	`LDAPOpCacheEntries number`
Default:	`LDAPOpCacheEntries 1024`
Context:	server config
Status:	Experimental
Module:	mod_ldap

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.

- -

LDAPOpCacheTTL Directive

- - - - - - - -

Description:	Time that entries in the operation cache remain -valid
Syntax:	`LDAPOpCacheTTL seconds`
Default:	`LDAPOpCacheTTL 600`
Context:	server config
Status:	Experimental
Module:	mod_ldap

Specifies the time (in seconds) that entries in the - operation cache remain valid. The default is 600 seconds.

- -

LDAPSharedCacheFile Directive

- - - - - - -

Description:	Sets the shared memory cache file
Syntax:	`LDAPSharedCacheFile directory-path/filename`
Context:	server config
Status:	Experimental
Module:	mod_ldap

Specifies the directory path and file name of the shared memory - cache file. If not set, anonymous shared memory will be used if the - platform supports it.

- -

LDAPSharedCacheSize Directive

- - - - - - - -

Description:	Size in bytes of the shared-memory cache
Syntax:	`LDAPSharedCacheSize bytes`
Default:	`LDAPSharedCacheSize 102400`
Context:	server config
Status:	Experimental
Module:	mod_ldap

Specifies the number of bytes to allocate for the shared - memory cache. The default is 100kb. If set to 0, shared memory - caching will not be used.

- -

LDAPTrustedCA Directive

- - - - - - -

Description:	Sets the file containing the trusted Certificate Authority certificate or database
Syntax:	`LDAPTrustedCA directory-path/filename`
Context:	server config
Status:	Experimental
Module:	mod_ldap

It specifies the directory path and file name of the trusted CA - mod_ldap should use when establishing an SSL - connection to an LDAP server. If using the Netscape/iPlanet Directory - SDK, the file name should be cert7.db.

- -

LDAPTrustedCAType Directive

- - - - - - -

Description:	Specifies the type of the Certificate Authority file
Syntax:	`LDAPTrustedCAType type`
Context:	server config
Status:	Experimental
Module:	mod_ldap

The following types are supported:
- DER_FILE - file in binary DER format
- BASE64_FILE - file in Base64 format
- CERT7_DB_PATH - Netscape certificate database file ")

- -