NukeLDAP 2.xx Overview

This is the second incarnation of my LDAP support for PHP-Nuke. It is also
suitable for providing directory synchronization with any other database
assuming you make the appropriate modifications.

It provides user management and password synchronization between and LDAP
server and a PHP-Nuke system. It was tested on Linux but it should run
on any system that runs PHP. Any LDAP server should be usable with the system.

It is designed to work with PHP-Nuke 7.5 and later.
It was built and tested using Mandrake 10.1, OpenLDAP 4.3.8, and samba 3.x.
It no longer requires UserManager support but it still lacks many features.

*   This program is free software; you can redistribute it and/or modify
*   it under the terms of the GNU General Public License as published by
*   the Free Software Foundation; either version 2 of the License, or
*   (at your option) any later version.


- Bill Wong
  bwong at voicenet dot com
  http://www.voicenet.com/~bwong/nukeldap/index.htm


Versions
--------
2.01	Added most (not all) nuke user attributes to nuke.schema
	synch-ldap-qmail.php updated to include qmail fields
	added utility scripts
	added support for adding fields to user/admin forms
	updated GPL licensing information
2.00	Original redesign


License: GPL 2.0
----------------
These programs are free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

These programs are distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

The PHP-Nuke files included with this release were also covered under
GPL 2.0. Modifications are noted and the license text was updated to
match the current GPL requirements and recommendations.


Known problems or limitations
-----------------------------
The system is essentially in a beta stage. I have not
done extensive testing yet. All feedback is welcome.

2.01 - Samba passwords must still be done using scripts
2.00 - Samba, Posix and Qmail scripts are not implemented
       Samba passwords are not generated, use Samba LDAP suport and
       call smbpasswd from a script file. Future versions may
       eliminate this requirement.


Wish List
---------
This section includes items that will eventually be added to nukeldap.
These are in no particular order as bug fixing takes top priority.

1. More diagnostic support
2. Improved administrator feedback
3. Improved logging
4. Block user creation/removal scripts
5. Posix/Samba list management
6. Instructions for implementing secure communication
   (this can be done but you need to read up on how your LDAP server works)
7. Language support


Design Philosophy
-----------------
This version of nukeldap is designed to operate as a standalone system
where all user interaction is managed from within PHP-Nuke. The nukeldap
implementation is primarily table driven using a simple substition system
for customization. Scripts can be initiated for almost all operations
allowing external customization. This requires some expertise at this
time as does system configuration but the design tries to minimize this
work.

The system requires minimal changes to PHP-Nuke. It requires no changes
to the PHP-Nuke database. The system is designed to work before or after
PHP-Nuke user management operations. This means calling functions like
synchLogin(). A copy of the Your_Account index.php module and admin
module are included. This is a stock version with modifications so they
should be usable as is unless additional changes have been made to your
files.

The other major change is in the db/db.php file that includes the
synch-ldap.php file. Any customization for other database should be
done by creating a new file and makin changes in both db.php and the
new file. There should be on need to change the Your_Account files.
There is a single global variable used to store all the data for the
ldap support, $ldapconfig. Most of the settings are found in the
synch-ldap.php file although some will be found in other files
depending upon the type of support required.

Currently there are three other support files that can be included.
The include statements are found at the end of the synch-ldap.php file.
The can be removed or commented out if necessary. These provide
additional support for LDAP objectclass'es that may be used for other
services such as POSIX (Linux) users, Samba users and mail users.
Other configuration files can be created and used as well.

The customization settings are built around tables and text strings.
A simple text substitution system has been implemente that should
handle most system need. It works in the following fashion.

The synchSet() and synchGet() functions are used to store and
retrieve data from the $ldapconfig variable. The synchTranslate()
function takes a string or an array of strings (arbitrary hierarchy)
and generates a matching result with substitutions being made in the
result. The substitutions use the variable names in curly brackets.
Assuming a synchSet('foo','foo value') is called first then a
synchTranslate call with the string "{foo} bar {FOO} {bar}" will
result in:

   "foo value bar foo value {bar}"

assuming 'bar' is not a variable. If 'bar' is set to "123" then the
result would be:

   "foo value bar foo value 123"

There are two sets of prefix values that are loaded. One is from the
PHP-Nuke database and the other is from the LDAP database. The field
names for these values are prefixed with nuke_ and ldap_ respectively.
This means that nuke_username will refer to the username field in the
PHP-Nuke SQL database.

The other major design item is how the various tables are processed.
The following procedure is essentially followed by each of the main
functions:

	synchMapCall('callFirst');
	synchMapLog();
	synchMapCall('call');
	synchMapCall('ldap');
	synchMapScript();
	synchMapCall('callLast');

This approach allows custom functions to be called first followed
by general logging. Custom functions can then be called followed
by the associated LDAP operations and then any scripts. A final
round of function calls can then be invoked.

In general, only a fraction of these will invoke an operation but
this will allow significant customization without requiring changes
to the overall system.



Configuration Information
-------------------------
The system is designed to require minimal changes for a stock Mandrake
installation with the Apache web server, PHP 4.x, PHP-Nuke 7.5+, an OpenLDAP
server, and standard shell scripts.


There are a number of configuration variables at the start of the
synch-ldap.php file that are used to customize the linkage between
the LDAP server and nukeldap. Some are listed below. These must be
changed to matchh the LDAP configuration. The default configuration
assumes the uid LDAP key will be used for the user name.

$ldapconfig['ldapVersion']	=3;				// sometimes required, remove line if version selected automatically
$ldapconfig['server']		="ldap://localhost";
$ldapconfig['port']		=389;				// 389 is default ldap port
$ldapconfig['bind_dn']		="cn=manager,dc=wong,dc=dom";
$ldapconfig['password']		="secret";

synchSet('ldapSearchPattern',"{ldapKey}={myName}");
synchSet('ldapKey',"uid");					// ldap user name attribute name
synchSet('passwordAttribute','userPassword');			// ldap password attribute, "" if scripts change password


In addition the system configuration variables there are a number of tables.
In general, related information is stored in $ldapconfig within a subarray
with a matching key such as 'add' or 'del'. For example:

$ldapconfig['add']['log'][]				="Adding user {myName}";

$ldapconfig['add']['ldap'][]				="synchLdapCreate";

$ldapconfig['add']['ldif']['objectclass'][]		="top";
$ldapconfig['add']['ldif']['objectclass'][]		="person";

The first 'log' line is used to call the logging function with a text
string generated by calling synchTranslate on the string provided.
Note that is used the special variable myName that is set when one
of the main system functions is called. The second line includes the
name of a no parameter function to be called during the 'ldap' phase.
Finally, there are some of the 'ldif' entries used by the 'ldap' phase
function. The third key is the LDAP attribute name. Multiple value fields
like objectclass are set using anonymous array assignments shown above.
Single value fields do not use the additional array level.

The main system functions include:

	synchIsUser($uname)
	syncLoad($uname)
	synchLogin($uname,$passwd)
	synchLogout($uname)
	synchAdd($uname,$passwd)
	synchDelete($uname)
	synchSave($uname,$passwd="")
	synchSetPassword($uname,$passwd)

These are called from the index.php files in Your_Account and do not have
to be changed. In general, only the table data must be changed unless a
custom function is added.

Because of the table driven architecture, additional files like
synch-ldap-posix.php can be added with minimal changes.

A more detailed description of the configuration may be forthcoming
but for now it requires a little PHP expertise. This should not be a
problem as getting OpenLDAP and Samba running are usually much more
difficult tasks.

Comments, criticisms, etc. are welcome. Please send me any enhancements,
bug fixes or changes so they can be incorporated into the next release.


Utility script
--------------
Remove or rename these scripts if you do not use them. They are found
in /opt/scripts. They use /usr/bin/logger to log the operation.

copydir.sh username uid gid source destination
	copies contents of the source directory and sets the
	destination owner to uid:gid.
deldir.sh username directory
	delete the contents of the directroy
backupdir.sh username directory destination
	copy contents of the directory to the specified destination
	file
