Net::LDAPapi Module v1.40 for Perl5

=======================================================================
Net::LDAPapi Module v1.40 for Perl5
Clayton Donley, <[email protected]>
=======================================================================

COPYRIGHT
=========

Copyright (c) 1998 Clayton Donley. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

INTRODUCTION
============

This module acts as a Perl5 interface to the LDAP C Development Kits from
University of Michigan and Netscape. The module itself is written completely
in C. Full documentation is included, as are commented example scripts.

REQUIREMENTS
============

This module requires Perl5, a C compiler, and the LDAP libraries and include
files from either of the following:

Netscape LDAP C SDK (used by author):
http://developer.netscape.com/one/directory/downloads.html
University of Michigan LDAP-3.3:
ftp://terminator.rs.itd.umich.edu/ldap/ldap-3.3.tar.Z

It should also works with the ISODE libraries and includes.

A C Compiler is not required for the NT version if you download Perl5
and module binaries and the Netscape SDK (you must copy the DLL into your
system directory).

PLATFORMS SUPPORTED
===================

This version should be easily compiled on various platforms. It has be tested
extensively under Solaris and verified to work under HPUX 10, AIX,
BSD/OS, and Redhat Linux.

Additionally, as of 1.39, the module has been verified to work with NT 4.0
and Perl 5.004+.

Please let me know if you compile it successfully on a new platform or have
any problems. For problems, please include the compilation errors.

NEW PERL-OO INTERFACE
=====================

As of version 1.40, a new Perl-OO layer has been added to allow more
object oriented access into the API. All of the original commands are
unchanged, but are no longer documented. You are encouraged to use the
new OO style routines, which are documented in the man-page.

Named arguments are not yet supported, but will definately be added by
the time I release the next version.

UNIX INSTALLATION
=================

After extracting the archive, simply type the following:

$ perl5 Makefile.PL
$ make

Edit the file test.pl to contain your LDAP server, BASEDN, and filter
string. Next type:

$ make test

It should complete all of its tests with no problems. To install the
module you will likely need to become root and type:

# make install

That's it. You can now 'use Net::LDAPapi' and make LDAP calls within your
PERL5 scripts with ease.

NT SOURCE INSTALLATION
======================

I use Microsoft Visual C++ 5.0. I am not certain what procedures you will
need to follow with other compilers.

C:\> perl Makefile.PL

Answer the questions appropriately. Supply the path to PERL.EXE and the
Netscape library and include files from their SDK.

C:\> nmake

The module will now be built.

c:\> edit test.pl

Change the LDAP server name and other attributes as necessary.

C:\> nmake test

If it passes most of the tests, it probably works, so you'll want to
install. For this, just type:

C:\> nmake install

You can now do a 'use Net::LDAPapi' from your NT Perl modules. You will
also want be be sure to copy the nsldap32v11.dll file into your system32
folder.

NT BINARY INSTALLATION
======================

First, obtain Perl 5.004 binaries for Windows NT. You can get it at the
following URL: http://www.perl.com/CPAN-local/authors/id/GSAR/. Simply get
one of the files starting with 'perl5.004'.

You will also need the Netscape LDAP SDK mentioned previously. Copy the
nsldap32v11.dll file from that archive into your system32 folder.

Finally, unzip the archive into the C:\ directory if you installed
PERL in C:\PERL. Otherwise, extract to the parent directory of your PERL
installation directory.

EXAMPLES
========

There exists six examples in the 'examples' directory. The current
examples are:

o ldapwalk.pl - This script demonstrates the use of Asynchronous LDAP
calls to return all the attributes and values for entries matching
a filter specified on the command line. Simply change the variables
at the start of the file to match your environment.

o ldapwalk2.pl - This is the same as ldapwalk.pl, only it shows how to
replace the portion that retrieves results and packages them in
the hash of hashes with the new get_all_entries function.

o testwrite.pl - This script demonstrates using synchronous Add, Modify,
and Delete calls to manage an LDAP server. You need update access
to an LDAP server to run this example. Once again, simply change
the variables at the top of the file.

o www-ldap.pl - This script uses both this module and the CGI.pm
module available on the Internet (and included in 5.004). It
allows users to authenticate and modify their own information.
You can easily customize this program, or learn from it and
write your own CGIs. The BIND and WEB_AUTHENTICATE subroutines
would be especially useful in incorporating LDAP authentication
into your own CGI scripts, even if the script has nothing to
do with LDAP otherwise.

o web500.pl - This script is a complete Web->LDAP gateway. It uses
CGI.pm and this module. It can be easily customized, supports
searching, modifications, and even things like jpegphoto uploads
and displaying. The original design used frames, but switched
to a WebPH style interface for the search part on the advice of
Douglas Gray Stephens.

o updatepw.pl - Updates a password entry for a user from Unix into
the LDAP server. You'll likely have to tinker with this program
to get it to do exactly what you want, but it exists as an idea
as to how you can do this.

In addition, the test.pl program in the top level directory shows some
of the basic synchronous search functionality.

LDAP C API SUPPORT
==================

The following is a list of LDAP API calls supported by this API. You can
find more information on each one in the man page generated when you make
the module.

While direct access to these calls is still available, it is suggested
that you use the Perl-OO style interface if you have never used the C API.

Calls marked with (*) are only available using the Netscape SDK.

ldap_abandon
ldap_add
ldap_add_s
ldap_bind
ldap_bind_s
ldap_compare
ldap_compare_s
ldap_count_entries
ldap_delete
ldap_delete_s
ldap_dn2ufn
ldap_err2string
ldap_explode_dn (*)
ldap_explode_rdn (*)
ldap_explode_dns (*)
ldap_first_attribute
ldap_first_entry
ldap_get_dn
ldap_msgid
ldap_get_lderrno
ldap_get_option
ldap_get_values
ldap_get_values_len
ldap_init (*)
ldap_msgfree (*)
ldap_modify
ldap_modify_s
ldap_modrdn2
ldap_modrdn2_s
ldap_next_attribute
ldap_next_entry
ldap_open
ldap_perror
ldap_result
ldap_result2error
ldap_search
ldap_search_s
ldap_search_st
ldap_set_option
ldap_set_rebind_proc
ldap_simple_bind
ldap_simple_bind_s
ldap_unbind
ldapssl_client_init (*)
ldapssl_init (*)
ldapssl_install_routines (*)

FEEDBACK
========

I'm looking for any feedback regarding this package or how you use this
package. If you've got other good examples or such, please send them my
way and I'll include them. I also read comp.lang.perl.*, so any problems
or bugs, you might want to report there as well, in case others have them.

BUGS
====

The non-OO stuff should work well. Please let me know if I've introduced
any bugs in the OO stuff or the cahnged examples. I've used these routines
in all my examples and they seem to work.

Please let me know your Operating System, Perl Version, and LDAP API version
when reporting any bugs.

--
Clayton Donley
Rolling Meadows, IL, USA
email: [email protected]
web: http://www.wwa.com/~donley
CPAN: /authors/id/CDONLEY