Apache模塊 mod_ldap

說(shuō)明	為其它LDAP模塊提供LDAP連接池和結(jié)果緩沖服務(wù)
狀態(tài)	擴(kuò)展(E)
模塊名	ldap_module
源文件	util_ldap.c
兼容性	僅在 Apache 2.0.41 及以后的版本中可用

概述

本模塊通過后端連接LDAP服務(wù)來(lái)改善網(wǎng)站性能。除了標(biāo)準(zhǔn)LDAP庫(kù)提供的功能外，本模塊增加了一個(gè)LDAP連接池和一個(gè)LDAP共享內(nèi)存緩沖區(qū)。

為了使用本模塊的功能，LDAP支持必須編譯進(jìn)APU。這是通過在編譯Apache時(shí)，在configure腳本命令行上增加 --with-ldap 開關(guān)來(lái)實(shí)現(xiàn)的。

為了支持SSL/TLS ，需要APR連接以下一個(gè)LDAP SDK ：OpenLDAP SDK(2.x或更新), Novell LDAP SDK, Mozilla LDAP SDK, 本地 Solaris LDAP SDK (基于Mozilla), 本地 Microsoft LDAP SDK, iPlanet (Netscape) SDK 。參見APR網(wǎng)站以獲取更多信息。

示例配置

下面的配置是一個(gè)使用mod_ldap模塊來(lái)提升mod_authnz_ldap提供的HTTP基本認(rèn)證性能的例子。

# 開啟LDAP連接池及共享內(nèi)存緩沖。 # 開啟LDAP緩沖狀態(tài)處理器。需要載入mod_ldap和mod_authnz_ldap模塊。 # 把"yourdomain.example.com"改為你真實(shí)的域名。 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連接是在請(qǐng)求之間共享的。這就允許LDAP服務(wù)器在跳過unbind->connect->rebind這樣一個(gè)工作周期的情況下，保留連接以減少為下一次請(qǐng)求準(zhǔn)備連接的時(shí)間。這種性能優(yōu)化有點(diǎn)象HTTP服務(wù)的Keep-Alives功能。

在一個(gè)比較繁忙的服務(wù)器上，很有可能許多請(qǐng)求同時(shí)嘗試與同一個(gè)LDAP服務(wù)進(jìn)行連接并得到它的服務(wù)。如果一個(gè)LDAP連接正在使用，Apache會(huì)在原來(lái)連接的基礎(chǔ)上，生成一個(gè)新的連接。這將確保連接池不會(huì)成為瓶頸。

不需要在Apache配置中手動(dòng)開啟連接池功能。任何使用本模塊來(lái)訪問LDAP服務(wù)的模塊會(huì)自動(dòng)共享連接池。

LDAP緩沖

為了改善性能，mod_ldap模塊使用一種積極的緩沖策略以盡量減少與LDAP服務(wù)器的聯(lián)系。通過緩沖，可以方便地使Apache在提供受mod_authnz_ldap保護(hù)的頁(yè)面時(shí)，得到二倍或三倍的吞吐量。同時(shí)，LDAP服務(wù)器的負(fù)載也會(huì)明顯地減小。

mod_ldap支持兩種類型的LDAP緩沖。在search/bind階段，使用一個(gè)search/bind緩沖，在compare階段，使用兩個(gè)operation緩沖。服務(wù)器引用的每個(gè)LDAP URL都有一組它自己的上述三個(gè)緩沖。

Search/Bind緩沖

處理一個(gè)查詢和綁定操作對(duì)LDAP實(shí)施來(lái)講，是非常耗時(shí)，尤其當(dāng)目錄很大時(shí)，這一點(diǎn)更加明顯。Search/bind緩沖用來(lái)緩沖所有的最終能成功綁定的查詢。失敗的結(jié)果(比如：不成功的查詢或查詢結(jié)果無(wú)法成功綁定)不會(huì)被緩沖。這樣做是因?yàn)樾湃侮P(guān)系失敗的連接在所有連接中只占了很小的一個(gè)百分比，因此，通過不緩沖這些連接，可以減少緩沖區(qū)的大小。

mod_ldap在緩沖區(qū)里儲(chǔ)存了用戶名、得到的DN 、用來(lái)綁定的口令、綁定的時(shí)間。當(dāng)一個(gè)新的連接用同一個(gè)用戶名來(lái)初始化的時(shí)候，mod_ldap將新的連接的口令與保存在緩沖區(qū)里的口令進(jìn)行比較。如果口令匹配，并且那個(gè)緩沖項(xiàng)目尚未失效的話，mod_ldap就跳過search/bind階段。

查詢與綁定緩沖由LDAPCacheEntries和LDAPCacheTTL指令來(lái)控制。

Operation緩沖

在區(qū)分與辨別過程中，mod_ldap使用兩個(gè)操作緩沖區(qū)來(lái)緩沖比較的操作。第一個(gè)緩沖區(qū)用來(lái)緩沖是否LDAP組成員的測(cè)試結(jié)果，第二個(gè)用來(lái)緩沖不同名字間鑒別的比較結(jié)果。

這兩個(gè)緩沖區(qū)都是由LDAPOpCacheEntries和LDAPOpCacheTTL指令來(lái)控制的。

緩沖區(qū)的監(jiān)控

mod_ldap包含了一個(gè)完整的處理器，通過它可以使管理員監(jiān)控緩沖區(qū)的性能。這個(gè)處理器的名字是ldap-status ，因此可以用下列指令來(lái)得到mod_ldap緩沖區(qū)的相關(guān)信息：

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

通過URL http://servername/cache-info ，管理員可以得到mod_ldap使用的每個(gè)緩沖的狀態(tài)報(bào)告。注意，如果Apache不支持共享內(nèi)存，那么每個(gè)httpd實(shí)例都有它自己的緩沖區(qū)，因此，每次使用上述URL都可能會(huì)得到不同的結(jié)果，這取決于具體哪個(gè)httpd實(shí)例處理了這個(gè)請(qǐng)求。

使用SSL/TSL

通過LDAPTrustedGlobalCert, LDAPTrustedClientCert, LDAPTrustedMode指令可以定義與LDAP服務(wù)器建立SSL/TSL聯(lián)接。這些指令指定了使用的CA和可選的客戶端證書，以及連接使用的加密類型(none, SSL, TLS/STARTTLS)。

# 在636端口建立一個(gè)SSL LDAP聯(lián)接。需要模塊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端口建立一個(gè)TLS LDAP聯(lián)接。需要模塊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 指令

說(shuō)明	主LDAP緩沖的最大條目數(shù)
語(yǔ)法	`LDAPCacheEntries number`
默認(rèn)值	`LDAPCacheEntries 1024`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

指定主LDAP緩沖的最大條目數(shù)。這個(gè)緩沖區(qū)包含了成功的search/bind對(duì)。把它設(shè)為0可以關(guān)閉search/bind緩沖。默認(rèn)值是1024 。

LDAPCacheTTL 指令

說(shuō)明	search/bind緩沖項(xiàng)目有效時(shí)限
語(yǔ)法	`LDAPCacheTTL seconds`
默認(rèn)值	`LDAPCacheTTL 600`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

指定search/bind緩沖項(xiàng)目有效的時(shí)間，以秒為單位。默認(rèn)為600秒(10分鐘)。

LDAPConnectionTimeout 指令

說(shuō)明	指定套接字連接超時(shí)秒數(shù)
語(yǔ)法	`LDAPConnectionTimeout seconds`
作用域	server config
狀態(tài)	擴(kuò)展(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 指令

說(shuō)明	LDAP compare緩沖區(qū)的大小
語(yǔ)法	`LDAPOpCacheEntries number`
默認(rèn)值	`LDAPOpCacheEntries 1024`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

指定mod_ldap使用的LDAP compare緩沖區(qū)大小。默認(rèn)值是1024條。把它設(shè)為0可以關(guān)閉操作緩沖。

LDAPOpCacheTTL 指令

說(shuō)明	操作緩沖有效時(shí)限
語(yǔ)法	`LDAPOpCacheTTL seconds`
默認(rèn)值	`LDAPOpCacheTTL 600`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

指定操作緩沖項(xiàng)目的有效時(shí)長(zhǎng)，以秒為單位。默認(rèn)為600秒。

LDAPSharedCacheFile 指令

說(shuō)明	設(shè)置共享內(nèi)存緩沖區(qū)文件
語(yǔ)法	`LDAPSharedCacheFile directory-path/filename`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

設(shè)置共享內(nèi)存緩沖區(qū)文件。若未設(shè)置，將使用匿名共享內(nèi)存(若平臺(tái)支持)。

LDAPSharedCacheSize 指令

說(shuō)明	共享內(nèi)存緩沖區(qū)的字節(jié)大小
語(yǔ)法	`LDAPSharedCacheSize bytes`
默認(rèn)值	`LDAPSharedCacheSize 102400`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

指定共享內(nèi)存緩沖區(qū)的大小，以Byte為單位。默認(rèn)為100KB。

LDAPTrustedClientCert 指令

說(shuō)明	Sets the file containing or nickname referring to a per connection client certificate. Not all LDAP toolkits support per connection client certificates.
語(yǔ)法	`LDAPTrustedClientCert type directory-path/filename/nickname [password]`
作用域	server config, virtual host, directory, .htaccess
狀態(tài)	擴(kuò)展(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 指令

說(shuō)明	Sets the file or database containing global trusted Certificate Authority or global client certificates
語(yǔ)法	`LDAPTrustedGlobalCert type directory-path/filename [password]`
作用域	server config
狀態(tài)	擴(kuò)展(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 指令

說(shuō)明	Specifies the SSL/TLS mode to be used when connecting to an LDAP server.
語(yǔ)法	`LDAPTrustedMode type`
作用域	server config, virtual host, directory, .htaccess
狀態(tài)	擴(kuò)展(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.

LDAPVerifyServerCert 指令

說(shuō)明	Force server certificate verification
語(yǔ)法	`LDAPVerifyServerCert On\|Off`
默認(rèn)值	`LDAPVerifyServerCert On`
作用域	server config
狀態(tài)	擴(kuò)展(E)
模塊	mod_ldap

Specifies whether to force the verification of a server certificate when establishing an SSL connection to the LDAP server.