
                     ldapuserdata plugin for Squirrelmail

   Based on the [1]SquirrelMail [2]Retrieve User Data Plugin (0.4/0.5)
   by Ralf Kraudelt (kraude at wiwi.uni-rostock.de)

Introduction

   There are two backends for Squirrelmail: the standard backend stores
   users' profile/preferences in text files (file_prefs.php), and the
   MySQL one stores them in a MySQL database (file_db.php).

   This one adds an LDAP backend. However, things are treated much
   differently, due to the difference in nature between LDAP and other
   databases. Namely: LDAP writes are expensive. Extensive caching is
   used to reduce the overhead on the LDAP server, especially in a setup
   with a lot of users.

   This makes a big difference, from the user's point of view. Whenever
   changing some option, the change is for the current session only. The
   change will only be saved permanently, if and only if the user logs
   out from Squirrelmail, thus ending the session.

   If having automatically saved preferences is important, then this
   plugin might not be for you. (Or you can modify setPref() to write
   back the changes to LDAP immediately and be prepared for a heavy
   loaded LDAP server)..

   You may ask, why put the user's profile in LDAP, in the first place?
   One word: centralization. There is a centralized store for
   preferences. If you have multiple webmail machines, they all get the
   same preferences for each user (one can achieve this with the MySQL
   backend too). No need for NFS'ing the data directory. Also, we
   connected to the LDAP server anyway, to get the cn (real name), mail
   (email address) and mailHost (IMAP server address to connect to). Even
   if there are applications other than squirrelmail that need this data
   in the future, they can get them. Last but not least, the complexity
   is reduced in that a single database is used; no other text files nor
   MySQL databases that all have some common information with LDAP.

   Here's a poor attempt for a block diagram of what happens behind the
   curtains:

   ldapuserdata diagram

   (Also available in [3]Dia drawing native format and [4]encapsulated
   postscript (.eps)).

  Things to Note

   Note that there are some issues that should be taken into
   consideration when using ldapuserdata.

   New/other plugins cannot just add preference variables and expect
   these to be saved. As long as they are not in the schema, they will
   only survive for the current user session and will be lost when the
   user logs out.

   Some preferences have been changed: specifically some options that we
   don't intend to allow changing, are not saved. All our
   src/options_*.php have been modified to show this. And yes, this is a
   feature. ldapuserdata is intended for a fully scalable mail system
   that will accomodate thousands of users.

   The code was largely based on [5]Ralf Kraudelt's retrieveuserdata
   plugin (v0.4). If you are looking for a solution based on MySQL, use
   the MySQL backend for Squirrelmail and additionally the MySQL module
   from retrieveuserdata. If you are just interested in getting the Name
   and Email address for an account from LDAP, just use retrieveuserdata.

Download

     * [6]ldapuserdata-0.4.tar.gz
     * [7]Signature

   [8]Download older versions

Installation

  Prerequisites

     * Squirrelmail 1.4.0 or greater. (Squirrelmail 1.2.x users can use
       version 0.2).
     * Working Squirrelmail setup (meaning its requirements are sufficed.
     * Working LDAP Server. Tested with [9]OpenLDAP.

  Installation Steps

   Word of warning: This is one of them intrusive plugins, in that you'll
   have to replace a file of the original Squirrelmail distribution with
   the one I'm providing you with. Having said that, installation is
   pretty much straightforward.
    1. Untar the distribution under the plugins directory of your
       Squirrelmail.
    2. Edit config.php to suit your preferences. The file is
       self-commented.
    3. Substitute the default functions/file_prefs.php with
       ldap_prefs.php. Make a backup of your file_prefs.php first:
cd ../functions
mv file_prefs.php file_prefs.php.original
mv ../plugins/ldapuserdata/file_prefs.php ./
    4. Incorporate the provided LDAP schema, squirrelmail.schema, into
       your LDAP server schema. See the manual of your LDAP server for
       details.
    5. In your Squirrelmail configuration, set the IMAP server address to
       be 'map:ldapuserdata_get_imapserveraddress', i.e.:
       $imapServerAddress = 'map:ldapuserdata_get_imapserveraddress';
    6. Optionally, add a squirrelmail virtual user under the Services of
       your LDAP tree. Mine is:
       uid=squirrel,ou=Squirrel,ou=Services,o=uoa,c=gr. This is
       configurable in config.php. At the moment, you can bind as Manager
       all the time and do the work; however, this is not a good
       practice, and the best thing would be to have a separate
       squirrelmail virtual user and the appropriate ACLs. In the future,
       ideally ldapuserdata will not bind as Manager at all. As it is
       now, it binds as Manager in two cases: when adding the user to the
       SquirrelmailUser objectclass, and when writing the preferences
       back to LDAP, when logging out.
    7. Optionally, substitute the original include/options/*.php files
       with the ones provided in the directory options_screens; their
       purpose is to remove the functionality that is available to the
       user by removing the options that are not saved in LDAP.

   Good luck... :-) There might be some things I've left out, so feel
   free to email me with questions. (Do read this manual first!).

  Adding New Attributes

   You can easily add new attributes to be saved on the LDAP server. Say
   you want to add 'squirrelmail_variable_name' in the preferences, and
   name the corresponding LDAP attribute ldapAttributeName. Simply:
    1. Add an entry like 'ldapattributename' =>
       'squirrelmail_variable_name' in $ldap_attributes array in
       config.php.
    2. If it is a boolean attribute, add the same thing in $boolean_attrs
       array.
    3. Add a default value for it, in $prefs_default array, as in
       'squirrelmail_variable_name' => 2.
    4. Of course, add it to your LDAP schema!

  Making the Options Screens Lighter

   Occasionally people on the Squirrelmail-devel mailing list have
   complained that there are too many options in the various options
   screens, and this is against usability and user-friendliness. Since
   part of the concept was to cut down on options anyway, you can also
   remove, i.e. comment-out, the options that are not used, in the files
   include/options/*.php. This will make these screens lighter and
   provide only the preferences that will be saved across sessions.

   The relevant files are provided here, if you wish to use the exact,
   provided schema.

   Remember that for all variables, even those that are not part of the
   LDAP schema, you can always provide resonable and nice defaults in the
   $prefs_default array.

History

  0.4

     register_globals = off compatible

     error_reporting = E_ALL compatible

     New option needed in the Squirrelmail configuration: set the IMAP
   server address to be 'map:ldapuserdata_get_imapserveraddress', i.e.:
   $imapServerAddress = 'map:ldapuserdata_get_imapserveraddress';

     Small fixes in the supplied config_sample.php.

     New schema for OpenLDAP 2.1.x is provided.

  0.3

     * Works with Squirrelmail 1.4.x. (Uses SM_PATH et al).
     * Various minor bugfixes and cleanups.

  0.2

     * Updated the LDAP schema.
     * Bugfix: Server side sorting is broken without a 'sort' attribute.
     * Bugfix: Fixed some variable names.
     * Bugfix: Now the special folders behave more correctly, as the
       appropriate attributes (move_to_trash, move_to_sent, save_as_draft
       are used).
     * The Options/Identities screen has been improved very much upon.
     * Added the new options screens, based on an early Squirrelmail
       1.3.0 CVS.
     * Supports the mailalternateaddress and mailauthorizedaddress LDAP
       multivalue attributes, for an easy way to support different
       "identities".
     * Now allows the POP Fetch plugin attributes to be saved on the
       LDAP.

  0.1

     * First public release.

TODO

     * More beta testing!

Support

   If you need help with this, or see improvements that can be made,
   please email me at the address below, or post a message to
   [10]squirrelmail-plugins mailing list. This plugin, as is the case
   with all [11]SquirrelMail plugins, is not directly supported by the
   developers.

Author


    [12]Alexandros Vellis, [13]Network Operations Centre, [14]Edunet,
    [15]University of Athens
    ([16]Personal home page).

Thanks, Credits

     * Based on retrieveuserdata code from [17]Ralf Kraudelt. Many thanks
       for giving me a code base to start from.
     * Nikos Voutsinas (nvoutsin at noc uoa gr), for helping with the
       LDAP schema, for bug reports, criticism etc..
     * Maria Nasiakou for bringing us ice cream.

References

   1. http://www.squirrelmail.org/
   2. http://www.squirrelmail.org/plugin_view.php?id=11
   3. file://localhost/var/www/squirrelmail/plugins/ldapuserdata/doc/ldapuserdata/ldap_prefs.dia
   4. file://localhost/var/www/squirrelmail/plugins/ldapuserdata/doc/ldapuserdata/ldap_prefs.eps
   5. mailto:kraude@wiwi.uni-rostock.de
   6. file://localhost/var/www/squirrelmail/plugins/ldapuserdata/download/squirrelmail/ldapuserdata/ldapuserdata-0.4.tar.gz
   7. file://localhost/var/www/squirrelmail/plugins/ldapuserdata/download/squirrelmail/ldapuserdata/ldapuserdata-0.4.tar.gz.sig
   8. file://localhost/var/www/squirrelmail/plugins/ldapuserdata/download/squirrelmail/ldapuserdata/
   9. http://www.openldap.org/
  10. http://lists.sourceforge.net/lists/listinfo/squirrelmail-plugins
  11. http://www.squirrelmail.org/plugins.php
  12. mailto:avel@users.sourceforge.net
  13. http://www.noc.uoa.gr/
  14. http://www.edunet.gr/
  15. http://www.uoa.gr/
  16. http://www.noc.uoa.gr/~avel/
  17. mailto:kraude@wiwi.uni-rostock.de
