README

mod_ldap_userdir v1.1.19
========================

mod_ldap_userdir is a module that enables the Apache web server to look up
user home directories (for /~user URLs) from an LDAP directory.


Sections:
1. Author
2. Licensing
3. How do I install and set up mod_ldap_userdir?
4. Changes
5. To Do
6. Thanks


=========
1. Author
=========

John Morrissey, <jwm@horde.net>,
http://horde.net/~jwm/software/mod_ldap_userdir/. Feedback is much
appreciated. If you're using mod_ldap_userdir successfully, are having
problems getting mod_ldap_userdir up and running at your site, or have some
code improvements or ideas for development, please let me know!

============
2. Licensing
============

mod_ldap_userdir is licensed under the GPL, with an exception to allow for
linking against OpenSSL:

The linking of mod_ldap_userdir with OpenSSL is allowed. You may distribute
the resulting executable without including the source code for OpenSSL in
the source distribution.

================================================
3. How do I install and set up mod_ldap_userdir?
================================================

* gzip -dc mod_ldap_userdir-1.1.19.tar.gz | tar xf -
* cd mod_ldap_userdir-1.1.19
* ./configure --with-activate
  Run './configure --help' for information on other build options.
* make
* make install

  If the installation fails and you manually copy mod_userdir_ldap.so into
  place, you will need to add something like:

  LoadModule ldap_userdir_module modules/mod_ldap_userdir.so

  to your httpd.conf.

* If your LDAP server runs OpenLDAP 1.x, you need to add the posixAccount
  schema definition.  Add the contents of posixAccount-objectclass to your
  slapd.oc.conf and restart your LDAP server. OpenLDAP 2.x (and most other
  LDAP servers) ship with this schema predefined.
* The 'user-ldif' file contains a sample user ldif. Modify it to your liking
  and say ldapadd -D your-root-dn -w your-root-dn-password < ldif
* You are *strongly* encouraged to read up on the LDAP config-file
  directives in the DIRECTIVES file, included with the distribution.

  At bare minimum, you'll need LDAPUserDir and LDAPUserDirBaseDN directives. 
  If you are not binding anonymously to your LDAP server, you must also
  include LDAPUserDirDNInfo.

  A set of basic mod_ldap_userdir configuration directives would look like:

    LDAPUserDir        public_html
    LDAPUserDirDNInfo  cn=your-dn,dc=example,dc=com dnpass
    LDAPUserDirBaseDN  ou=People,dc=example,dc=com

  Of course, you will need to update these configuration directives with
  the proper values for your environment.

  If you wish to use the user's home directory itself (instead of a
  subdirectory below it) for Apache-accessible content, specify "."
  for the directory:

    LDAPUserDir .

==========
4. Changes
==========

v1.1.19:
* Avoid a segfault when LDAPUserDirUseTLS is enabled, and the
  LDAPUserDirUseTLS configuration directive is specified later in
  the configuration than LDAPUserDirServerURL.

v1.1.18:
* Remove Apache 1.3.x support. Apache 1.3.x has been end of life since
  January 2010.
* Use remote path to the source tarball in the included .spec, which
  makes 'rpmbuild -tb' work on the source tarball.

v1.1.17:
* Implement an internal failover mechanism instead of relying on the LDAP
  SDK's built-in failover (if any). Fixes failover regression introduced
  in v1.1.13 when ldap_initialize() was first used.
* Multiple LDAP URL arguments may now be passed to LDAPUserDirServerURL:

  LDAPUserDirServerURL ldap://127.0.0.1/??sub ldap://172.16.0.1/??sub
* Portability fix: don't use ldap_initialize() and ldap_unbind_ext_s()
  unless we're building against the corresponding versions of the OpenLDAP
  SDK.
* Updated documentation to mention using "." (the current directory) when
  the user's home directory itself should be exposed, instead of a
  subdirectory below it. Thanks to Peter Tselios <tselios.petros@gmail.com>
  for mentioning this issue.

v1.1.16:
* TLS support was not being enabled when the --with-tls option was
  explicitly passed to configure. Replace --with-tls with the more
  correct option --enable-tls.

v1.1.15:
* Fix segfault when LDAPUserDirDNInfo isn't specified (implicitly specifying
  anonymous binds) with modern LDAP SDKs (LDAP_API_VERSION >= 2000).

v1.1.14:
* Avoid segfault attempting to free() uninitialized pointer when a user
  does not have a uid or homeDirectory attr, one or both of those attrs
  are not readable by the DN configured by LDAPUserDirDNInfo, or an
  out-of-memory condition is encountered while fetching any LDAP attribute.

v1.1.13:
* Missed ldap_init() -> ldap_initialize() change when making changes to
  comply with draft-ietf-ldapext-ldap-c-api-04. Older versions may segfault
  on 64-bit systems when mod_ldap_userdir is built with more recent OpenLDAP
  SDK headers.
* Previous versions enabled TLS when the ldaps:// scheme was specified in
  LDAPUserdirServerURL URL. This behavior was incorrect, since ldaps://
  indicates LDAP over SSL (port 636 by default) should be enabled. If you
  wish to continue using TLS, you must modify your configuration to specify
  the ldap:// scheme in the LDAPUserdirServerURL URL and add the directive
  'LDAPUserDirUseTLS on' to your configuration.
* LDAPUserDirUseTLS now throws a configuration error when TLS is enabled and
  the ldaps:// scheme is specified in the LDAPUserdirServerURL URL.
* Fixes to bugs in suexec support submitted by Witold Baryluk
  <baryluk@smp.if.uj.edu.pl>.
* Avoid infinite loop when LDAPUserDirDNInfo bind DN doesn't have access to
  one or more LDAP attributes.
* Logging improvements
  * Don't complain about inaccessible [ug]idNumber values when reading the
    user's LDAP entry, since we might not be using suexec.
  * Complain in suexec handler if we found the user's LDAP entry but it
    was missing [ug]idNumber values.

v1.1.12:
* Updated the suexec hooks to fetch the user's UID and GID (uidNumber and
  gidNumber attributes, respectively) from the LDAP directory instead of
  relying on Apache to fetch them for us. This allows suexec access for
  LDAP-only users with no OS support required for looking up these users'
  UID/GIDs.
* Removed the LDAPUserDirCacheTimeout directive from the Apache 1.x build. 
  Caching is only supported with Apache 2.0 and later, so this directive was
  being silently ignored under Apache 1.x. If you run Apache 1.x, you *must*
  remove the LDAPUserDirCacheTimeout directive from your configuration.
* Fix handling of the cache timeout, so setting it to 0 seconds (to disable
  caching) now works.
* Use non-deprecated LDAP API functions if the LDAP SDK is new enough to
  comply with draft-ietf-ldapext-ldap-c-api-04.

v1.1.11:
* Add LDAPProtocolVersion directive to specify the LDAP protocol version
  to use. The LDAP protocol version now defaults to LDAPv3 instead of
  LDAPv2. Thanks to Aaron Brace <abrace@metrocastcablevision.com> for
  the patch.
* Fetch the user's canonical username (as returned by the LDAP directory)
  to pass to suEXEC instead of passing the username as received in the URL.
  Thanks to Aaron Brace <abrace@metrocastcablevision.com> for the patch.
* The previous change also removes the LDAPUserDirHomeAttribute directive
  in favor of the new LDAPAttribute directive. To migrate your previous
  configuration, change:

    LDAPUserDirHomeAttribute username

  to:

    LDAPAttribute uid username

  More information on LDAPAttribute is in DIRECTIVES.
* Fix libldap/liblber autodetection when using --with-sdk-headers and/or
  --with-sdk-libdir configure options. Thanks to Daniel Lark
  <dlark@viaccess.net> for the bug report.
* No longer require GNU make.

v1.1.10:
* Apache 2.2 support. Thanks to Hiroto Kagotani <hiroto.kagotani@gmail.com>
  and Takeshi Inagaki <ts-inagaki@kmn.co.jp> for reporting this.
* Refined LDAP over TLS support. Thanks to Hiroto Kagotani
  <hiroto.kagotani@gmail.com> and Takeshi Inagaki <ts-inagaki@kmn.co.jp>
  for reporting problems when building in non-TLS mode.
* Sun/Solaris LDAP SDK support. Thanks to Takeshi Inagaki
  <ts-inagaki@kmn.co.jp> for reporting this.
* Better sanity checking of the timeout value. Thanks to Italo Foppiano
  Reyes <ifoppian@udec.cl> for reporting a problem with this.

v1.1.9:
* Add LDAPUserDirServerURL directive, which takes a single LDAP URL
  argument. Suggested by Fabien Picarougne
  <fabien.picarougne@polytech.univ-nantes.fr>.
* Register a configuration merge handler so directives from the main
  server (outside a VirtualHost) are merged down and treated as overridable
  defaults inside VirtualHosts. Errant behavior reported by Alexander Perlis
  <alexanderperlis@yahoo.com>.
* Fix building with Apache1.
* Build system improvements:
  * Build with LDAP TLS support automatically, if present.
  * Use proper build path to mod_ldap_userdir.so with Apache2 builds.
  * Improve autoconf usage.
  * Drop autoconf support for Netscape LDAP SDK. autoconf support for it was
    broken, and I can't find anyone still using it.

v1.1.8:
* Add caching support (with accompanying LDAPUserDirCacheTimeout directive),
  reducing the number of LDAP searches that need to be performed.

v1.1.7:
* Add LDAPUserDirHomeAttribute attribute instead of depending on a
  build-time change to switch the homeDirectory attribute's name, loosely
  based on code by O'Shaughnessy Evans <shaug@wumpus.org>.
* Now running module/child init handlers for Apache 2, too.
* Remove child exit handler; I can't find a good way to replicate this
  with Apache 2's hooks and it's not really necessary anyway, since the
  connection will be closed on child exit.

v1.1.6:
* Fix Apache 2-ism that crept into v1.1.5. Tohru Murakami
  <murakami-toru.nospam@nexs.nec.co.jp> and Jerome Spenlehauer
  <j.spenlehauer@calixo.net>.

v1.1.5:
* Add suexec hooks for Apache 2, contributed by Marc Lewis <marc@blarg.net>.

v1.1.4:
* Fixed bug that prevented startup if LDAPUserDirSearchScope was configured.

v1.1.3:
* Fixed Apache2-isms that crept into 1.1.2.

v1.1.2:
* Update the mod_ldap_userdir version added by ap_add_version_component.
* Build fixes for Netware and Win32 by Guenter Knauf <gk@gknw.de>.
* Support for wildcards and redirection by Shyokou Ouyou
  <shyokou@scientist.com>.

v1.1.1:
* Compilation fix for platforms that don't define TRUE in their headers.

v1.1:
* Apache 2.x support. Thanks to Shane Boulter (sboulter at ariasolutions dot
  com) for providing an account with which I could implement Apache 2.x
  support.
* Improved build system.
* Got rid of dependency on ldap_build_filter(), which will fix builds against
  OpenLDAP 2.1.x, Novell eDirectory and a couple others.
* Postcard-ware licensing addition.

v1.0.1:
* Fixed a couple hard-coded references to the "homeDirectory" attr. (Thanks
  to Christian Zoffoli [czoffoli at xmerlin dot org] for pointing this out.)

v1.0:
* Initial revision of standalone module. mod_ldap_userdir includes the same
  functionality as apache-userdirldap 1.5 and adds TLS/SSL support for
  connections to the LDAP server.

========
5. To Do
========

* Currently, nothing.

=========
6. Thanks
=========

* Everyone who's downloaded, used, and/or offered feedback.