mod_ldap - Apache HTTP Server Version 2.2 中文文档
Apache模块 mod_ldap
| 说明 | 为其它LDAP模块提供LDAP连接池和结果缓冲服务 |
|---|---|
| 状态 | 扩展(E) |
| 模块名 | ldap_module |
| 源文件 | util_ldap.c |
| 兼容性 | 仅在 Apache 2.0.41 及以后的版本中可用 |
概述
本模块通过后端连接LDAP服务来改善网站性能。除了标准LDAP库提供的功能外，本模块增加了一个LDAP连接池和一个LDAP共享内存缓冲区。
为了使用本模块的功能，LDAP支持必须编译进APU。这是通过在编译Apache时，在configure脚本命令行上增加 --with-ldap 开关来实现的。
为了支持SSL/TLS ，需要APR连接以下一个LDAP SDK ：OpenLDAP SDK(2.x或更新), Novell LDAP SDK, Mozilla LDAP SDK, 本地 Solaris LDAP SDK (基于Mozilla), 本地 Microsoft LDAP SDK, iPlanet (Netscape) SDK 。参见APR网站以获取更多信息。
示例配置
下面的配置是一个使用mod_ldap模块来提升mod_authnz_ldap提供的HTTP基本认证性能的例子。
# 开启LDAP连接池及共享内存缓冲。
# 开启LDAP缓冲状态处理器。需要载入mod_ldap和mod_authnz_ldap模块。
# 把"yourdomain.example.com"改为你真实的域名。
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连接池
LDAP连接是在请求之间共享的。这就允许LDAP服务器在跳过unbind->connect->rebind这样一个工作周期的情况下，保留连接以减少为下一次请求准备连接的时间。这种性能优化有点象HTTP服务的Keep-Alives功能。
在一个比较繁忙的服务器上，很有可能许多请求同时尝试与同一个LDAP服务进行连接并得到它的服务。如果一个LDAP连接正在使用，Apache会在原来连接的基础上，生成一个新的连接。这将确保连接池不会成为瓶颈。
不需要在Apache配置中手动开启连接池功能。任何使用本模块来访问LDAP服务的模块会自动共享连接池。
LDAP缓冲
为了改善性能，mod_ldap模块使用一种积极的缓冲策略以尽量减少与LDAP服务器的联系。通过缓冲，可以方便地使Apache在提供受mod_authnz_ldap保护的页面时，得到二倍或三倍的吞吐量。同时，LDAP服务器的负载也会明显地减小。
mod_ldap支持两种类型的LDAP缓冲。在search/bind阶段，使用一个search/bind缓冲，在compare阶段，使用两个operation缓冲。服务器引用的每个LDAP URL都有一组它自己的上述三个缓冲。
Search/Bind缓冲
处理一个查询和绑定操作对LDAP实施来讲，是非常耗时，尤其当目录很大时，这一点更加明显。Search/bind缓冲用来缓冲所有的最终能成功绑定的查询。失败的结果(比如：不成功的查询或查询结果无法成功绑定)不会被缓冲。这样做是因为信任关系失败的连接在所有连接中只占了很小的一个百分比，因此，通过不缓冲这些连接，可以减少缓冲区的大小。
mod_ldap在缓冲区里储存了用户名、得到的DN 、用来绑定的口令、绑定的时间。当一个新的连接用同一个用户名来初始化的时候，mod_ldap将新的连接的口令与保存在缓冲区里的口令进行比较。如果口令匹配，并且那个缓冲项目尚未失效的话，mod_ldap就跳过search/bind阶段。
查询与绑定缓冲由LDAPCacheEntries和LDAPCacheTTL指令来控制。
Operation缓冲
在区分与辨别过程中，mod_ldap使用两个操作缓冲区来缓冲比较的操作。第一个缓冲区用来缓冲是否LDAP组成员的测试结果，第二个用来缓冲不同名字间鉴别的比较结果。
这两个缓冲区都是由LDAPOpCacheEntries和LDAPOpCacheTTL指令来控制的。
缓冲区的监控
mod_ldap包含了一个完整的处理器，通过它可以使管理员监控缓冲区的性能。这个处理器的名字是ldap-status ，因此可以用下列指令来得到mod_ldap缓冲区的相关信息：
<Location /server/cache-info>
SetHandler ldap-status
</Location>
通过URL http://servername/cache-info ，管理员可以得到mod_ldap使用的每个缓冲的状态报告。注意，如果Apache不支持共享内存，那么每个httpd实例都有它自己的缓冲区，因此，每次使用上述URL都可能会得到不同的结果，这取决于具体哪个httpd实例处理了这个请求。
使用SSL/TSL
通过LDAPTrustedGlobalCert, LDAPTrustedClientCert, LDAPTrustedMode指令可以定义与LDAP服务器建立SSL/TSL联接。这些指令指定了使用的CA和可选的客户端证书，以及连接使用的加密类型(none, SSL, TLS/STARTTLS)。
# 在636端口建立一个SSL LDAP联接。需要模块mod_ldap和mod_authnz_ldap的支持。
# 将"yourdomain.example.com"修改为您自己的域名。
LDAPTrustedGlobalCert CA_DER /certs/certfile.der
<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>
# 在389端口建立一个TLS LDAP联接。需要模块mod_ldap和mod_authnz_ldap的支持。
# 将"yourdomain.example.com"修改为您自己的域名。
LDAPTrustedGlobalCert CA_DER /certs/certfile.der
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
LDAPTrustedMode TLS
AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
</Location>
SSL/TLS Certificates
The different LDAP SDKs have widely different methods of setting and handling both CA and client side certificates.
If you intend to use SSL or TLS, read this section CAREFULLY so as to understand the differences between configurations on the different LDAP toolkits supported.
Netscape/Mozilla/iPlanet SDK
CA certificates are specified within a file called cert7.db. The SDK will not talk to any LDAP server whose certificate was not signed by a CA specified in this file. If client certificates are required, an optional key3.db file may be specified with an optional password. The secmod file can be specified if required. These files are in the same format as used by the Netscape Communicator or Mozilla web browsers. The easiest way to obtain these files is to grab them from your browser installation.
Client certificates are specified per connection using the LDAPTrustedClientCert directive by referring to the certificate "nickname". An optional password may be specified to unlock the certificate's private key.
The SDK supports SSL only. An attempt to use STARTTLS will cause an error when an attempt is made to contact the LDAP server at runtime.
# Specify a Netscape CA certificate file
LDAPTrustedGlobalCert CA_CERT7_DB /certs/cert7.db
# Specify an optional key3.db file for client certificate support
LDAPTrustedGlobalCert CERT_KEY3_DB /certs/key3.db
# Specify the secmod file if required
LDAPTrustedGlobalCert CA_SECMOD /certs/secmod
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
LDAPTrustedClientCert CERT_NICKNAME <nickname> [password]
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
</Location>
Novell SDK
One or more CA certificates must be specified for the Novell SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.
Note: Client certificates are specified globally rather than per connection, and so must be specified with the LDAPTrustedGlobalCert directive as below. Trying to set client certificates via the LDAPTrustedClientCert directive will cause an error to be logged when an attempt is made to connect to the LDAP server..
The SDK supports both SSL and STARTTLS, set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced, override this directive.
# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER /certs/cacert1.der
LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem
# Specify a client certificate file and key
LDAPTrustedGlobalCert CERT_BASE64 /certs/cert1.pem
LDAPTrustedGlobalCert KEY_BASE64 /certs/key1.pem [password]
# Do not use this directive, as it will throw an error
#LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem
OpenLDAP SDK
One or more CA certificates must be specified for the OpenLDAP SDK to work correctly. These certificates can be specified as binary DER or Base64 (PEM) encoded files.
Client certificates are specified per connection using the LDAPTrustedClientCert directive.
The documentation for the SDK claims to support both SSL and STARTTLS, however STARTTLS does not seem to work on all versions of the SDK. The SSL/TLS mode can be set using the LDAPTrustedMode parameter. If an ldaps:// URL is specified, SSL mode is forced. The OpenLDAP documentation notes that SSL (ldaps://) support has been deprecated to be replaced with TLS, although the SSL functionality still works.
# Specify two CA certificate files
LDAPTrustedGlobalCert CA_DER /certs/cacert1.der
LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem
<Location /ldap-status>
SetHandler ldap-status
Order deny,allow
Deny from all
Allow from yourdomain.example.com
AuthLDAPEnabled on
LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem
LDAPTrustedClientCert KEY_BASE64 /certs/key1.pem
AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one
AuthLDAPAuthoritative on
require valid-user
</Location>
Solaris SDK
SSL/TLS for the native Solaris LDAP libraries is not yet supported. If required, install and use the OpenLDAP libraries instead.
Microsoft SDK
SSL/TLS certificate configuration for the native Microsoft LDAP libraries is done inside the system registry, and no configuration directives are required.
Both SSL and TLS are supported by using the ldaps:// URL format, or by using the LDAPTrustedMode directive accordingly.
Note: The status of support for client certificates is not yet known for this toolkit.
LDAPCacheEntries 指令
| 说明 | 主LDAP缓冲的最大条目数 |
|---|---|
| 语法 | LDAPCacheEntries number |
| 默认值 | LDAPCacheEntries 1024 |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
指定主LDAP缓冲的最大条目数。这个缓冲区包含了成功的search/bind对。把它设为0可以关闭search/bind缓冲。默认值是1024 。
LDAPCacheTTL 指令
| 说明 | search/bind缓冲项目有效时限 |
|---|---|
| 语法 | LDAPCacheTTL seconds |
| 默认值 | LDAPCacheTTL 600 |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
指定search/bind缓冲项目有效的时间，以秒为单位。默认为600秒(10分钟)。
LDAPConnectionTimeout 指令
| 说明 | 指定套接字连接超时秒数 |
|---|---|
| 语法 | LDAPConnectionTimeout seconds |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | 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 指令
| 说明 | LDAP compare缓冲区的大小 |
|---|---|
| 语法 | LDAPOpCacheEntries number |
| 默认值 | LDAPOpCacheEntries 1024 |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
指定mod_ldap使用的LDAP compare缓冲区大小。默认值是1024条。把它设为0可以关闭操作缓冲。
LDAPOpCacheTTL 指令
| 说明 | 操作缓冲有效时限 |
|---|---|
| 语法 | LDAPOpCacheTTL seconds |
| 默认值 | LDAPOpCacheTTL 600 |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
指定操作缓冲项目的有效时长，以秒为单位。默认为600秒。
LDAPSharedCacheFile 指令
| 说明 | 设置共享内存缓冲区文件 |
|---|---|
| 语法 | LDAPSharedCacheFile directory-path/filename |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
设置共享内存缓冲区文件。若未设置，将使用匿名共享内存(若平台支持)。
LDAPSharedCacheSize 指令
| 说明 | 共享内存缓冲区的字节大小 |
|---|---|
| 语法 | LDAPSharedCacheSize bytes |
| 默认值 | LDAPSharedCacheSize 102400 |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
指定共享内存缓冲区的大小，以Byte为单位。默认为100KB。
LDAPTrustedClientCert 指令
| 说明 | Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates. |
|---|---|
| 语法 | LDAPTrustedClientCert type directory-path/filename/nickname [password] |
| 作用域 | server config, virtual host, directory, .htaccess |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
It specifies the directory path, file name or nickname of a per connection client certificate used when establishing an SSL or TLS connection to an LDAP server. Different locations or directories may have their own independant client certificate settings. Some LDAP toolkits (notably Novell) do not support per connection client certificates, and will throw an error on LDAP server connection if you try to use this directive (Use the LDAPTrustedGlobalCert directive instead for Novell client certificates - See the SSL/TLS certificate guide above for details). The type specifies the kind of certificate parameter being set, depending on the LDAP toolkit being used. Supported types are:
- CERT_DER - binary DER encoded client certificate
- CERT_BASE64 - PEM encoded client certificate
- CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
- KEY_DER - binary DER encoded private key
- KEY_BASE64 - PEM encoded private key
LDAPTrustedGlobalCert 指令
| 说明 | Sets the file or database containing global trusted Certificate Authority or global client certificates |
|---|---|
| 语法 | LDAPTrustedGlobalCert type directory-path/filename [password] |
| 作用域 | server config |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
It specifies the directory path and file name of the trusted CA
certificates and/or system wide client certificates mod_ldap
should use when establishing an SSL or TLS connection to an LDAP
server. Note that all certificate information specified using this directive
is applied globally to the entire server installation. Some LDAP toolkits
(notably Novell) require all client certificates to be set globally using
this directive. Most other toolkits require clients certificates to be set
per Directory or per Location using LDAPTrustedClientCert. If you get this
wrong, an error may be logged when an attempt is made to contact the LDAP
server, or the connection may silently fail (See the SSL/TLS certificate
guide above for details).
The type specifies the kind of certificate parameter being
set, depending on the LDAP toolkit being used. Supported types are:
- CA_DER - binary DER encoded CA certificate
- CA_BASE64 - PEM encoded CA certificate
- CA_CERT7_DB - Netscape cert7.db CA certificate database file
- CA_SECMOD - Netscape secmod database file
- CERT_DER - binary DER encoded client certificate
- CERT_BASE64 - PEM encoded client certificate
- CERT_KEY3_DB - Netscape key3.db client certificate database file
- CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)
- CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)
- KEY_DER - binary DER encoded private key
- KEY_BASE64 - PEM encoded private key
- KEY_PFX - PKCS#12 encoded private key (Novell SDK)
LDAPTrustedMode 指令
| 说明 | Specifies the SSL/TLS mode to be used when connecting to an LDAP server. |
|---|---|
| 语法 | LDAPTrustedMode type |
| 作用域 | server config, virtual host, directory, .htaccess |
| 状态 | 扩展(E) |
| 模块 | mod_ldap |
The following modes are supported:
- NONE - no encryption
- SSL - ldaps:// encryption on default port 636
- TLS - STARTTLS encryption on default port 389
Not all LDAP toolkits support all the above modes. An error message will be logged at runtime if a mode is not supported, and the connection to the LDAP server will fail.
If an ldaps:// URL is specified, the mode becomes SSL and the setting of LDAPTrustedMode is ignored.