granicus.if.org Git - apache/blob - docs/manual/mod/mod_ldap.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_ldap.xml.meta">
  24
  25 <name>mod_ldap</name>
  26 <description>LDAP connection pooling and result caching services for use
  27 by other LDAP modules</description>
  28 <status>Extension</status>
  29 <sourcefile>util_ldap.c</sourcefile>
  30 <identifier>ldap_module</identifier>
  31 <compatibility>Available in version 2.0.41 and later</compatibility>
  32
  33 <summary>
  34     <p>This module was created to improve the performance of
  35     websites relying on backend connections to LDAP servers. In
  36     addition to the functions provided by the standard LDAP
  37     libraries, this module adds an LDAP connection pool and an LDAP
  38     shared memory cache.</p>
  39
  40     <p>To enable this module, LDAP support must be compiled into
  41     apr-util. This is achieved by adding the <code>--with-ldap</code>
  42     flag to the <program>configure</program> script when building
  43     Apache.</p>
  44
  45     <p>SSL/TLS support is dependant on which LDAP toolkit has been
  46     linked to <glossary>APR</glossary>. As of this writing, APR-util supports:
  47     <a href="http://www.openldap.org/">OpenLDAP SDK</a> (2.x or later),
  48     <a href="http://developer.novell.com/ndk/cldap.htm">Novell LDAP
  49     SDK</a>, <a href="http://www.mozilla.org/directory/csdk.html">
  50     Mozilla LDAP SDK</a>, native Solaris LDAP SDK (Mozilla based),
  51     native Microsoft LDAP SDK, or the
  52     <a href="http://www.iplanet.com/downloads/developer/">iPlanet
  53     (Netscape)</a> SDK. See the <a href="http://apr.apache.org">APR</a>
  54     website for details.</p>
  55
  56 </summary>
  57
  58 <section id="exampleconfig"><title>Example Configuration</title>
  59     <p>The following is an example configuration that uses
  60     <module>mod_ldap</module> to increase the performance of HTTP Basic
  61     authentication provided by <module>mod_authnz_ldap</module>.</p>
  62
  63     <example>
  64       # Enable the LDAP connection pool and shared<br />
  65       # memory cache. Enable the LDAP cache status<br />
  66       # handler. Requires that mod_ldap and mod_authnz_ldap<br />
  67       # be loaded. Change the "yourdomain.example.com" to<br />
  68       # match your domain.<br />
  69       <br />
  70       LDAPSharedCacheSize 500000<br />
  71       LDAPCacheEntries 1024<br />
  72       LDAPCacheTTL 600<br />
  73       LDAPOpCacheEntries 1024<br />
  74       LDAPOpCacheTTL 600<br />
  75       <br />
  76       &lt;Location /ldap-status&gt;<br />
  77       <indent>
  78         SetHandler ldap-status<br />
  79         Order deny,allow<br />
  80         Deny from all<br />
  81         Allow from yourdomain.example.com<br />
  82         Satisfy any<br />
  83         AuthType Basic<br />
  84         AuthName "LDAP Protected"<br />
  85         AuthBasicProvider ldap<br />
  86         AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one<br />
  87         Require valid-user<br />
  88       </indent>
  89       &lt;/Location&gt;
  90     </example>
  91 </section>
  92
  93 <section id="pool"><title>LDAP Connection Pool</title>
  94
  95     <p>LDAP connections are pooled from request to request. This
  96     allows the LDAP server to remain connected and bound ready for
  97     the next request, without the need to unbind/connect/rebind.
  98     The performance advantages are similar to the effect of HTTP
  99     keepalives.</p>
 100
 101     <p>On a busy server it is possible that many requests will try
 102     and access the same LDAP server connection simultaneously.
 103     Where an LDAP connection is in use, Apache will create a new
 104     connection alongside the original one. This ensures that the
 105     connection pool does not become a bottleneck.</p>
 106
 107     <p>There is no need to manually enable connection pooling in
 108     the Apache configuration. Any module using this module for
 109     access to LDAP services will share the connection pool.</p>
 110
 111     <p>LDAP connections can keep track of the ldap client
 112     credentials used when binding to an LDAP server. These
 113     credentials can be provided to LDAP servers that do not
 114     allow anonymous binds during referral chasing. To control
 115     this feature, see the <directive module="mod_ldap">
 116     LDAPReferrals</directive> and <directive module="mod_ldap">
 117     LDAPReferralHopLimit</directive> directives. By default,
 118     this feature is enabled.</p>
 119 </section>
 120
 121 <section id="cache"><title>LDAP Cache</title>
 122
 123     <p>For improved performance, <module>mod_ldap</module> uses an aggressive
 124     caching strategy to minimize the number of times that the LDAP
 125     server must be contacted. Caching can easily double or triple
 126     the throughput of Apache when it is serving pages protected
 127     with mod_authnz_ldap. In addition, the load on the LDAP server
 128     will be significantly decreased.</p>
 129
 130     <p><module>mod_ldap</module> supports two types of LDAP caching during
 131     the search/bind phase with a <em>search/bind cache</em> and
 132     during the compare phase with two <em>operation
 133     caches</em>. Each LDAP URL that is used by the server has
 134     its own set of these three caches.</p>
 135
 136     <section id="search-bind"><title>The Search/Bind Cache</title>
 137       <p>The process of doing a search and then a bind is the
 138       most time-consuming aspect of LDAP operation, especially if
 139       the directory is large. The search/bind cache is used to
 140       cache all searches that resulted in successful binds.
 141       Negative results (<em>i.e.</em>, unsuccessful searches, or searches
 142       that did not result in a successful bind) are not cached.
 143       The rationale behind this decision is that connections with
 144       invalid credentials are only a tiny percentage of the total
 145       number of connections, so by not caching invalid
 146       credentials, the size of the cache is reduced.</p>
 147
 148       <p><module>mod_ldap</module> stores the username, the DN
 149       retrieved, the password used to bind, and the time of the bind
 150       in the cache. Whenever a new connection is initiated with the
 151       same username, <module>mod_ldap</module> compares the password
 152       of the new connection with the password in the cache. If the
 153       passwords match, and if the cached entry is not too old,
 154       <module>mod_ldap</module> bypasses the search/bind phase.</p>
 155
 156       <p>The search and bind cache is controlled with the <directive
 157       module="mod_ldap">LDAPCacheEntries</directive> and <directive
 158       module="mod_ldap">LDAPCacheTTL</directive> directives.</p>
 159     </section>
 160
 161     <section id="opcaches"><title>Operation Caches</title>
 162       <p>During attribute and distinguished name comparison
 163       functions, <module>mod_ldap</module> uses two operation caches
 164       to cache the compare operations. The first compare cache is
 165       used to cache the results of compares done to test for LDAP
 166       group membership. The second compare cache is used to cache
 167       the results of comparisons done between distinguished
 168       names.</p>
 169
 170       <p>Note that, when group membership is being checked, any sub-group
 171       comparison results are cached to speed future sub-group comparisons.</p>
 172
 173       <p>The behavior of both of these caches is controlled with
 174       the <directive module="mod_ldap">LDAPOpCacheEntries</directive>
 175       and <directive module="mod_ldap">LDAPOpCacheTTL</directive>
 176       directives.</p>
 177     </section>
 178
 179     <section id="monitoring"><title>Monitoring the Cache</title>
 180       <p><module>mod_ldap</module> has a content handler that allows
 181       administrators to monitor the cache performance. The name of
 182       the content handler is <code>ldap-status</code>, so the
 183       following directives could be used to access the
 184       <module>mod_ldap</module> cache information:</p>
 185
 186       <example>
 187         &lt;Location /server/cache-info&gt;<br />
 188         <indent>
 189           SetHandler ldap-status<br />
 190         </indent>
 191         &lt;/Location&gt;
 192       </example>
 193
 194       <p>By fetching the URL <code>http://servername/cache-info</code>,
 195       the administrator can get a status report of every cache that is used
 196       by <module>mod_ldap</module> cache. Note that if Apache does not
 197       support shared memory, then each <program>httpd</program> instance has its
 198       own cache, so reloading the URL will result in different
 199       information each time, depending on which <program>httpd</program>
 200       instance processes the request.</p>
 201     </section>
 202 </section>
 203
 204 <section id="usingssltls"><title>Using SSL/TLS</title>
 205
 206     <p>The ability to create an SSL and TLS connections to an LDAP server
 207     is defined by the directives <directive module="mod_ldap">
 208     LDAPTrustedGlobalCert</directive>, <directive module="mod_ldap">
 209     LDAPTrustedClientCert</directive> and <directive module="mod_ldap">
 210     LDAPTrustedMode</directive>. These directives specify the CA and
 211     optional client certificates to be used, as well as the type of
 212     encryption to be used on the connection (none, SSL or TLS/STARTTLS).</p>
 213
 214     <example>
 215       # Establish an SSL LDAP connection on port 636. Requires that <br />
 216       # mod_ldap and mod_authnz_ldap be loaded. Change the <br />
 217       # "yourdomain.example.com" to match your domain.<br />
 218       <br />
 219       LDAPTrustedGlobalCert CA_DER /certs/certfile.der<br />
 220       <br />
 221       &lt;Location /ldap-status&gt;<br />
 222       <indent>
 223         SetHandler ldap-status<br />
 224         Order deny,allow<br />
 225         Deny from all<br />
 226         Allow from yourdomain.example.com<br />
 227         Satisfy any<br />
 228         AuthType Basic<br />
 229         AuthName "LDAP Protected"<br />
 230         AuthBasicProvider ldap<br />
 231         AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one<br />
 232         Require valid-user<br />
 233       </indent>
 234       &lt;/Location&gt;
 235     </example>
 236
 237     <example>
 238       # Establish a TLS LDAP connection on port 389. Requires that <br />
 239       # mod_ldap and mod_authnz_ldap be loaded. Change the <br />
 240       # "yourdomain.example.com" to match your domain.<br />
 241       <br />
 242       LDAPTrustedGlobalCert CA_DER /certs/certfile.der<br />
 243       <br />
 244       &lt;Location /ldap-status&gt;<br />
 245       <indent>
 246         SetHandler ldap-status<br />
 247         Order deny,allow<br />
 248         Deny from all<br />
 249         Allow from yourdomain.example.com<br />
 250         Satisfy any<br />
 251         AuthType Basic<br />
 252         AuthName "LDAP Protected"<br />
 253         AuthBasicProvider ldap<br />
 254         AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one TLS<br />
 255         Require valid-user<br />
 256       </indent>
 257       &lt;/Location&gt;
 258     </example>
 259
 260 </section>
 261
 262 <section id="settingcerts"><title>SSL/TLS Certificates</title>
 263
 264     <p>The different LDAP SDKs have widely different methods of setting
 265     and handling both CA and client side certificates.</p>
 266
 267     <p>If you intend to use SSL or TLS, read this section CAREFULLY so as to
 268     understand the differences between configurations on the different LDAP
 269     toolkits supported.</p>
 270
 271     <section id="settingcerts-netscape"><title>Netscape/Mozilla/iPlanet SDK</title>
 272         <p>CA certificates are specified within a file called cert7.db.
 273         The SDK will not talk to any LDAP server whose certificate was
 274         not signed by a CA specified in this file. If
 275         client certificates are required, an optional key3.db file may
 276         be specified with an optional password. The secmod file can be
 277         specified if required. These files are in the same format as
 278         used by the Netscape Communicator or Mozilla web browsers. The easiest
 279         way to obtain these files is to grab them from your browser
 280         installation.</p>
 281
 282         <p>Client certificates are specified per connection using the
 283         LDAPTrustedClientCert directive by referring
 284         to the certificate "nickname". An optional password may be
 285         specified to unlock the certificate's private key.</p>
 286
 287         <p>The SDK supports SSL only. An attempt to use STARTTLS will cause
 288         an error when an attempt is made to contact the LDAP server at
 289         runtime.</p>
 290
 291         <example>
 292             # Specify a Netscape CA certificate file<br />
 293             LDAPTrustedGlobalCert CA_CERT7_DB /certs/cert7.db<br />
 294             # Specify an optional key3.db file for client certificate support<br />
 295             LDAPTrustedGlobalCert CERT_KEY3_DB /certs/key3.db<br />
 296             # Specify the secmod file if required<br />
 297             LDAPTrustedGlobalCert CA_SECMOD /certs/secmod<br />
 298             &lt;Location /ldap-status&gt;<br />
 299             <indent>
 300                 SetHandler ldap-status<br />
 301                 Order deny,allow<br />
 302                 Deny from all<br />
 303                 Allow from yourdomain.example.com<br />
 304                 Satisfy any<br />
 305                 AuthType Basic<br />
 306                 AuthName "LDAP Protected"<br />
 307                 AuthBasicProvider ldap<br />
 308                 LDAPTrustedClientCert CERT_NICKNAME &lt;nickname&gt; [password]<br />
 309                 AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one<br />
 310                 Require valid-user<br />
 311             </indent>
 312             &lt;/Location&gt;
 313         </example>
 314
 315     </section>
 316
 317     <section id="settingcerts-novell"><title>Novell SDK</title>
 318
 319         <p>One or more CA certificates must be specified for the Novell
 320         SDK to work correctly. These certificates can be specified as
 321         binary DER or Base64 (PEM) encoded files.</p>
 322
 323         <p>Note: Client certificates are specified globally rather than per
 324         connection, and so must be specified with the LDAPTrustedGlobalCert
 325         directive as below. Trying to set client certificates via the
 326         LDAPTrustedClientCert directive will cause an error to be logged
 327         when an attempt is made to connect to the LDAP server..</p>
 328
 329         <p>The SDK supports both SSL and STARTTLS, set using the
 330         LDAPTrustedMode parameter. If an ldaps:// URL is specified,
 331         SSL mode is forced, override this directive.</p>
 332
 333         <example>
 334              # Specify two CA certificate files<br />
 335              LDAPTrustedGlobalCert CA_DER /certs/cacert1.der<br />
 336              LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem<br />
 337              # Specify a client certificate file and key<br />
 338              LDAPTrustedGlobalCert CERT_BASE64 /certs/cert1.pem<br />
 339              LDAPTrustedGlobalCert KEY_BASE64 /certs/key1.pem [password]<br />
 340              # Do not use this directive, as it will throw an error<br />
 341              #LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem<br />
 342         </example>
 343
 344     </section>
 345
 346     <section id="settingcerts-openldap"><title>OpenLDAP SDK</title>
 347
 348         <p>One or more CA certificates must be specified for the OpenLDAP
 349         SDK to work correctly. These certificates can be specified as
 350         binary DER or Base64 (PEM) encoded files.</p>
 351
 352         <p>Both CA and client certificates may be specified globally
 353         (LDAPTrustedGlobalCert) or per-connection (LDAPTrustedClientCert).
 354         When any settings are specified per-connection, the global
 355         settings are superceded.</p>
 356
 357         <p>The documentation for the SDK claims to support both SSL and
 358         STARTTLS, however STARTTLS does not seem to work on all versions
 359         of the SDK. The SSL/TLS mode can be set using the
 360         LDAPTrustedMode parameter. If an ldaps:// URL is specified,
 361         SSL mode is forced. The OpenLDAP documentation notes that SSL
 362         (ldaps://) support has been deprecated to be replaced with TLS,
 363         although the SSL functionality still works.</p>
 364
 365         <example>
 366              # Specify two CA certificate files<br />
 367              LDAPTrustedGlobalCert CA_DER /certs/cacert1.der<br />
 368              LDAPTrustedGlobalCert CA_BASE64 /certs/cacert2.pem<br />
 369             &lt;Location /ldap-status&gt;<br />
 370             <indent>
 371                 SetHandler ldap-status<br />
 372                 Order deny,allow<br />
 373                 Deny from all<br />
 374                 Allow from yourdomain.example.com<br />
 375                 LDAPTrustedClientCert CERT_BASE64 /certs/cert1.pem<br />
 376                 LDAPTrustedClientCert KEY_BASE64 /certs/key1.pem<br />
 377                 # CA certs respecified due to per-directory client certs<br />
 378                 LDAPTrustedClientCert CA_DER /certs/cacert1.der<br />
 379                 LDAPTrustedClientCert CA_BASE64 /certs/cacert2.pem<br />
 380                 Satisfy any<br />
 381                 AuthType Basic<br />
 382                 AuthName "LDAP Protected"<br />
 383                 AuthBasicProvider ldap<br />
 384                 AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one<br />
 385                 Require valid-user<br />
 386             </indent>
 387             &lt;/Location&gt;
 388         </example>
 389
 390     </section>
 391
 392     <section id="settingcerts-solaris"><title>Solaris SDK</title>
 393
 394         <p>SSL/TLS for the native Solaris LDAP libraries is not yet
 395         supported. If required, install and use the OpenLDAP libraries
 396         instead.</p>
 397
 398     </section>
 399
 400     <section id="settingcerts-microsoft"><title>Microsoft SDK</title>
 401
 402         <p>SSL/TLS certificate configuration for the native Microsoft
 403         LDAP libraries is done inside the system registry, and no
 404         configuration directives are required.</p>
 405
 406         <p>Both SSL and TLS are supported by using the ldaps:// URL
 407         format, or by using the LDAPTrustedMode directive accordingly.</p>
 408
 409         <p>Note: The status of support for client certificates is not yet known
 410         for this toolkit.</p>
 411
 412     </section>
 413
 414 </section>
 415
 416 <directivesynopsis>
 417 <name>LDAPSharedCacheSize</name>
 418 <description>Size in bytes of the shared-memory cache</description>
 419 <syntax>LDAPSharedCacheSize <var>bytes</var></syntax>
 420 <default>LDAPSharedCacheSize 500000</default>
 421 <contextlist><context>server config</context></contextlist>
 422
 423 <usage>
 424     <p>Specifies the number of bytes to allocate for the shared
 425     memory cache. The default is 500kb. If set to 0, shared memory
 426     caching will not be used.</p>
 427 </usage>
 428 </directivesynopsis>
 429
 430 <directivesynopsis>
 431 <name>LDAPSharedCacheFile</name>
 432 <description>Sets the shared memory cache file</description>
 433 <syntax>LDAPSharedCacheFile <var>directory-path/filename</var></syntax>
 434 <contextlist><context>server config</context></contextlist>
 435
 436 <usage>
 437     <p>Specifies the directory path and file name of the shared memory
 438     cache file. If not set, anonymous shared memory will be used if the
 439     platform supports it.</p>
 440 </usage>
 441 </directivesynopsis>
 442
 443 <directivesynopsis>
 444 <name>LDAPCacheEntries</name>
 445 <description>Maximum number of entries in the primary LDAP cache</description>
 446 <syntax>LDAPCacheEntries <var>number</var></syntax>
 447 <default>LDAPCacheEntries 1024</default>
 448 <contextlist><context>server config</context></contextlist>
 449
 450 <usage>
 451     <p>Specifies the maximum size of the primary LDAP cache. This
 452     cache contains successful search/binds. Set it to 0 to turn off
 453     search/bind caching. The default size is 1024 cached
 454     searches.</p>
 455 </usage>
 456 </directivesynopsis>
 457
 458 <directivesynopsis>
 459 <name>LDAPCacheTTL</name>
 460 <description>Time that cached items remain valid</description>
 461 <syntax>LDAPCacheTTL <var>seconds</var></syntax>
 462 <default>LDAPCacheTTL 600</default>
 463 <contextlist><context>server config</context></contextlist>
 464
 465 <usage>
 466     <p>Specifies the time (in seconds) that an item in the
 467     search/bind cache remains valid. The default is 600 seconds (10
 468     minutes).</p>
 469 </usage>
 470 </directivesynopsis>
 471
 472 <directivesynopsis>
 473 <name>LDAPOpCacheEntries</name>
 474 <description>Number of entries used to cache LDAP compare
 475 operations</description>
 476 <syntax>LDAPOpCacheEntries <var>number</var></syntax>
 477 <default>LDAPOpCacheEntries 1024</default>
 478 <contextlist><context>server config</context></contextlist>
 479
 480 <usage>
 481     <p>This specifies the number of entries <module>mod_ldap</module>
 482     will use to cache LDAP compare operations. The default is 1024
 483     entries.  Setting it to 0 disables operation caching.</p>
 484 </usage>
 485 </directivesynopsis>
 486
 487 <directivesynopsis>
 488 <name>LDAPOpCacheTTL</name>
 489 <description>Time that entries in the operation cache remain
 490 valid</description>
 491 <syntax>LDAPOpCacheTTL <var>seconds</var></syntax>
 492 <default>LDAPOpCacheTTL 600</default>
 493 <contextlist><context>server config</context></contextlist>
 494
 495 <usage>
 496     <p>Specifies the time (in seconds) that entries in the
 497     operation cache remain valid. The default is 600 seconds.</p>
 498 </usage>
 499 </directivesynopsis>
 500
 501 <directivesynopsis>
 502 <name>LDAPReferralHopLimit</name>
 503 <description>The maximum number of referral hops to chase before terminating an LDAP query.</description>
 504 <syntax>LDAPReferralHopLimit <var>number</var></syntax>
 505 <default>SDK dependent, typically between 5 and 10</default>
 506 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
 507 <override>AuthConfig</override>
 508
 509 <usage>
 510     <p>This directive, if enabled by the <code>LDAPReferrals</code> directive,
 511     limits the number of referral hops that are followed before terminating an
 512     LDAP query.</p>
 513
 514 <note type="warning">
 515 <p> Support for this tunable is uncommon in LDAP SDKs.</p>
 516 </note>
 517 </usage>
 518 </directivesynopsis>
 519
 520 <directivesynopsis>
 521 <name>LDAPReferrals</name>
 522 <description>Enable referral chasing during queries to the LDAP server.</description>
 523 <syntax>LDAPReferrals <var>On|Off</var></syntax>
 524 <default>LDAPReferrals On</default>
 525 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
 526 <override>AuthConfig</override>
 527
 528 <usage>
 529     <p>Some LDAP servers divide their directory among multiple domains and use referrals
 530     to direct a client when a domain boundary is crossed. By setting <code>LDAPReferrals On</code>
 531     referrals will be chased (setting it to off causes referrals to be ignored). The directive
 532     <code>LDAPReferralHopLimit</code> works in conjunction with this directive to limit the
 533     number of referral hops to follow before terminating the LDAP query. When referral processing
 534     is enabled client credentials will be provided, via a rebind callback, for any LDAP server
 535     requiring them. </p>
 536 </usage>
 537 </directivesynopsis>
 538
 539 <directivesynopsis>
 540 <name>LDAPTrustedGlobalCert</name>
 541 <description>Sets the file or database containing global trusted
 542 Certificate Authority or global client certificates</description>
 543 <syntax>LDAPTrustedGlobalCert <var>type</var> <var>directory-path/filename</var> <var>[password]</var></syntax>
 544 <contextlist><context>server config</context></contextlist>
 545
 546 <usage>
 547     <p>It specifies the directory path and file name of the trusted CA
 548     certificates and/or system wide client certificates <module>mod_ldap</module>
 549     should use when establishing an SSL or TLS connection to an LDAP
 550     server. Note that all certificate information specified using this directive
 551     is applied globally to the entire server installation. Some LDAP toolkits
 552     (notably Novell) require all client certificates to be set globally using
 553     this directive. Most other toolkits require clients certificates to be set
 554     per Directory or per Location using LDAPTrustedClientCert. If you get this
 555     wrong, an error may be logged when an attempt is made to contact the LDAP
 556     server, or the connection may silently fail (See the SSL/TLS certificate
 557     guide above for details).
 558     The type specifies the kind of certificate parameter being
 559     set, depending on the LDAP toolkit being used. Supported types are:</p>
 560     <ul>
 561       <li>CA_DER - binary DER encoded CA certificate</li>
 562       <li>CA_BASE64 - PEM encoded CA certificate</li>
 563       <li>CA_CERT7_DB - Netscape cert7.db CA certificate database file</li>
 564       <li>CA_SECMOD - Netscape secmod database file</li>
 565       <li>CERT_DER - binary DER encoded client certificate</li>
 566       <li>CERT_BASE64 - PEM encoded client certificate</li>
 567       <li>CERT_KEY3_DB - Netscape key3.db client certificate database file</li>
 568       <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
 569       <li>CERT_PFX - PKCS#12 encoded client certificate (Novell SDK)</li>
 570       <li>KEY_DER - binary DER encoded private key</li>
 571       <li>KEY_BASE64 - PEM encoded private key</li>
 572       <li>KEY_PFX - PKCS#12 encoded private key (Novell SDK)</li>
 573     </ul>
 574 </usage>
 575 </directivesynopsis>
 576
 577 <directivesynopsis>
 578 <name>LDAPTrustedClientCert</name>
 579 <description>Sets the file containing or nickname referring to a per
 580 connection client certificate. Not all LDAP toolkits support per
 581 connection client certificates.</description>
 582 <syntax>LDAPTrustedClientCert <var>type</var> <var>directory-path/filename/nickname</var> <var>[password]</var></syntax>
 583 <contextlist><context>directory</context><context>.htaccess</context></contextlist>
 584
 585 <usage>
 586     <p>It specifies the directory path, file name or nickname of a
 587     per connection client certificate used when establishing an SSL
 588     or TLS connection to an LDAP server. Different locations or
 589     directories may have their own independant client certificate
 590     settings. Some LDAP toolkits (notably Novell)
 591     do not support per connection client certificates, and will throw an
 592     error on LDAP server connection if you try to use this directive
 593     (Use the LDAPTrustedGlobalCert directive instead for Novell client
 594     certificates - See the SSL/TLS certificate guide above for details).
 595     The type specifies the kind of certificate parameter being
 596     set, depending on the LDAP toolkit being used. Supported types are:</p>
 597     <ul>
 598       <li>CA_DER - binary DER encoded CA certificate</li>
 599       <li>CA_BASE64 - PEM encoded CA certificate</li>
 600       <li>CERT_DER - binary DER encoded client certificate</li>
 601       <li>CERT_BASE64 - PEM encoded client certificate</li>
 602       <li>CERT_NICKNAME - Client certificate "nickname" (Netscape SDK)</li>
 603       <li>KEY_DER - binary DER encoded private key</li>
 604       <li>KEY_BASE64 - PEM encoded private key</li>
 605     </ul>
 606 </usage>
 607 </directivesynopsis>
 608
 609 <directivesynopsis>
 610 <name>LDAPTrustedMode</name>
 611 <description>Specifies the SSL/TLS mode to be used when connecting to an LDAP server.</description>
 612 <syntax>LDAPTrustedMode <var>type</var></syntax>
 613 <contextlist><context>server config</context><context>virtual host</context></contextlist>
 614
 615 <usage>
 616     <p>The following modes are supported:</p>
 617     <ul>
 618       <li>NONE - no encryption</li>
 619       <li>SSL - ldaps:// encryption on default port 636</li>
 620       <li>TLS - STARTTLS encryption on default port 389</li>
 621     </ul>
 622
 623     <p>Not all LDAP toolkits support all the above modes. An error message
 624     will be logged at runtime if a mode is not supported, and the
 625     connection to the LDAP server will fail.
 626     </p>
 627
 628     <p>If an ldaps:// URL is specified, the mode becomes SSL and the setting
 629     of LDAPTrustedMode is ignored.</p>
 630 </usage>
 631 </directivesynopsis>
 632
 633 <directivesynopsis>
 634 <name>LDAPConnectionTimeout</name>
 635 <description>Specifies the socket connection timeout in seconds</description>
 636 <syntax>LDAPConnectionTimeout <var>seconds</var></syntax>
 637 <contextlist><context>server config</context></contextlist>
 638
 639 <usage>
 640     <p>This directive configures the LDAP_OPT_NETWORK_TIMEOUT option in the
 641     underlying LDAP client library, when available.  This value typically
 642     controls how long the LDAP client library will wait for the TCP connection
 643     to the LDAP server to complete.</p>
 644
 645     <p> If a connection is not successful with the timeout period, either an error will be
 646     returned or the LDAP client library will attempt to connect to a secondary LDAP
 647     server if one is specified (via a space-separated list of hostnames in the
 648     <directive module="mod_ldap">AuthLDAPURL</directive>).</p>
 649
 650     <p>The default is 10 seconds, if the LDAP client library linked with the
 651     server supports the LDAP_OPT_NETWORK_TIMEOUT option.</p>
 652
 653     <note>LDAPConnectionTimeout is only available when the LDAP client library linked
 654     with the server supports the LDAP_OPT_NETWORK_TIMEOUT option, and the
 655     ultimate behavior is dictated entirely by the LDAP client library.
 656     </note>
 657 </usage>
 658 </directivesynopsis>
 659
 660 <directivesynopsis>
 661 <name>LDAPTimeout</name>
 662 <description>Specifies the timeout for LDAP search and bind operations, in seconds</description>
 663 <syntax>LDAPTimeout <var>seconds</var></syntax>
 664 <default>LDAPTimeout 60</default>
 665 <contextlist><context>server config</context></contextlist>
 666
 667 <usage>
 668     <p>This directive configures the timeout for bind and search operations, as well as
 669     the LDAP_OPT_TIMEOUT option in the underlying LDAP client library, when available.</p>
 670
 671     <p> If the timeout expires, httpd will retry in case an existing connection has
 672     been silently dropped by a firewall. However, performance will be much better if
 673     the firewall is configured to send TCP RST packets instead of silently dropping
 674     packets.</p>
 675
 676     <note>
 677     <p>Timeouts for ldap compare operations requires an SDK with LDAP_OPT_TIMEOUT, such as OpenLDAP &gt;= 2.4.4.</p>
 678     </note>
 679
 680 </usage>
 681 </directivesynopsis>
 682
 683
 684 <directivesynopsis>
 685 <name>LDAPVerifyServerCert</name>
 686 <description>Force server certificate verification</description>
 687 <syntax>LDAPVerifyServerCert <var>On|Off</var></syntax>
 688 <default>LDAPVerifyServerCert On</default>
 689 <contextlist><context>server config</context></contextlist>
 690
 691 <usage>
 692     <p>Specifies whether to force the verification of a
 693      server certificate when establishing an SSL connection to the
 694      LDAP server.</p>
 695 </usage>
 696 </directivesynopsis>
 697
 698 <directivesynopsis>
 699 <name>LDAPLibraryDebug</name>
 700 <description>Enable debugging in the LDAP SDK</description>
 701 <syntax>LDAPLibraryDebug <var>7</var></syntax>
 702 <default>disabled</default>
 703 <contextlist><context>server config</context></contextlist>
 704
 705 <usage>
 706     <p>Turns on SDK-specific LDAP debug options that generally cause the LDAP
 707     SDK to log verbose trace information to the main Apache error log.
 708     The trace messages from the LDAP SDK provide gory details that
 709     can be useful during debugging of connectivity problems with backend LDAP servers</p>
 710
 711     <p>This option is only configurable when Apache HTTP Server is linked with
 712     an LDAP SDK that implements <code>LDAP_OPT_DEBUG</code> or
 713     <code>LDAP_OPT_DEBUG_LEVEL</code>, such as OpenLDAP (a value of 7 is verbose)
 714     or Tivoli Directory Server (a value of 65535 is verbose).</p>
 715
 716     <note type="warning">
 717     <p>The logged information will likely contain plaintext credentials being used or
 718     validated by LDAP authentication, so care should be taken in protecting and purging
 719     the error log when this directive is used.</p>
 720     </note>
 721
 722 </usage>
 723 </directivesynopsis>
 724
 725
 726 </modulesynopsis>