mod_auth_ldap v 2.16 for Apache 2.x

[mod_auth_ldap Release With cache, v2.16 for Apache 2.x]

This document is about the caching mechanism in the LDAP authentication module for Apache 2.x. You should read the main mod_auth_ldap_apache2.html page for details. It'll be part of the main page as soon as I get some time.

The source is sitting in my disk for a while, so I'm writing up this quick note to get you started. In my initial testing, the code seems to be solid, but pelease give me your feedback. I'm interested to know how it performs in very large sites.

Download

Please read the instructions in the main mod_auth_ldap_apache2.html page for how to install the module. Note: The MS Windows DLL is compiled with Apache 2.0.48, that means you should use it wth Apache 2.0.48. It may or may not work with other version of Apache. Also it is compiled with iPlanet C SDK, so you've to get the dlls. Please look at the Notes in the download section in the main mod_auth_ldap_apache2.html page for the link of iPlanet LDAP C SDK.

For MS Windows, the DLL is compiled with apache 2.0.49, so use the DLL may or may not work with any other version of apache.

This is a development release. It has initial cut of memory and persistent disk based caching support. I'm releasing it so that you can play with it and give me feedback. This version has tons of bug fixes and improvements over the previous versions. So you should try this version even if you're not interested in caching support. If you've thousands of protected files, caching will improve server performence dramatically!

You can compile the support for both memory and disk based caching but can use only one.

For memory cache, the module uses the excellent libghthash library. I wasted lots of time with another hash library called hashit, which is simple but extremely unportable and and was buggy at the time I played with it. In the future release of the module, I'll add support for various heuristics libghthash supports. I'm supplying a slightly modified version of libghthash with the module.

For persistent cache, I use fast disk based database. Disk based cache is only tested with Berkeley db v4.2.52 available at http://www.sleepycat.com. Although the module has supporting code for gdbm, ndbm, sdbm etc, but they're not tested at the moment.

I only tested the module as a DSO, compiling in with Apache is not tested yet. If caching is enabled, in Unix the module runs order of magnitude faster than older versions. However in Windows, I noticed it's not as fast as Unix, probably because Windows version of Apache is threaded and large section ofcode is mutexed. I'll look into it.

Compatibily

LDAP_Persistent is gone. The new directive is LDAP_Persistent_G and it is a global directive and can be used in httpd.conf file only and can not be used in side <Directory>, <Location> etc. The global directives have _G at the end. The cache related directives are all global directives.

Compile with memory and disk based cache support in Unix

If you do not want caching support:

This version of the module has more features, you've to look at the code for that or wait till I document it.

Directives for memory caching (global directives)

# Turn on memory caching
    LDAP_UseMemoryCache_G   On
# Size of hash table
    LDAP_HashTableSize_G    1024
# Expire cahce after these many seconds. Default is 300 seconds
    LDAP_CacheTTL_G       600

Directives for persistent disk based Caching (global directives)

# Turn of disk based caching
    LDAP_UseDiskCache_G     On
# Path of a  web writable directory. It must exist. A fast disk based dbm
# will be created there by the web server
    LDAP_CacheDbDirPath_G   /usr/local/apache/mod_auth_ldap_disk_cache
# Expire cahce after these many seconds. Default is 300 seconds
    LDAP_CacheTTL_G       600
    SupportNestedGroups_G   Off

By global directives, it means that those directives can be used only in the server httpd.conf file and can not be used inside <Directory>, <Location> etc.

Example (memory cache)

Persistent disk based cache

Caching Mechanism

The following flow diagrams show the caching mechanism:

PDF version: cache.pdf

PDF version: cache_group.pdf

The authorization flow is similar as above if user is authorized by a LDAP attribute or by a LDAP filter.

Please let me know if you see any problem with the mechanism. Suggestions bug reports are always welcome!

ChageLog

2.16
• The directive SupportNestedGroups is a global directive and changed to SupportNestedGroups_G. Nested group code was broken as well. Thanks to james jurack for reporting it.

• Do not specify LDAP_Persistent_G Off. This code may have some bugs.
  (May-23-2004)

  v2.15

• If Uid_Attr_Alt is set, the module could crash if debugging is on. Also none of the environment variables were set if the authentication was done from cache. Thanks to fpinho for reporting the bug.
  (May-02-2004)

• If authentication is done from cache, a new env variable MOD_AUTH_LDAP_CACHE_TYPE will be set. The value of this variable will be set to "Memory" or "Disk".
  (May-02-2004)

  v2.14

• The multiple group, filter or any ldap attribute can be specified. That means if you specifiy 3 different group with require group, all of them will be checked for authorization. In earlier version, only the first line was used. example,

  require group cn=itstaff,ou=Groups
  require group cn=webgroup,ou=Groups
  require group cn=foogroup,ou=Groups
  
  or
  require telephonenumber 215-123-4567
  require telephonenumber 610-678-9012
  
  or
  require filter "(mail=muquit@muquit.com)"
  require filter "(mail=foo@bar.com)"
  require filter "(mail=bar@example.com)"
  

  
  (Apr-25-2004)

• Caching was not working for filter directive.
  (Apr-25-2004)

  v2.13

• First release with memory and disk based cache support.
  (Feb-16-2004)

-- 
Muhammad A Muquit, muquit@muquit.com
Updated: Feb-16-2004