NAME¶

  Mozilla::LDAP::Conn - Object Oriented API for the LDAP SDK.

SYNOPSIS¶

  use Mozilla::LDAP::Conn;
  use Mozilla::LDAP::Utils;

ABSTRACT¶

This package is the main API for using our Perl Object Oriented LDAP module. Even though it's certainly possible, and sometimes even necessary, to call the native LDAP C SDK functions, we strongly recommend you use these object classes.

It's not required to use our Mozilla::LDAP::Utils.pm package, but it's convenient and good for portability if you use as much as you can from that package as well. This implies using the LdapConf package as well, even though you usually don't need to use it directly.

You should read this document in combination with the Mozilla::LDAP::Entry document. Both modules depend on each other heavily.

DESCRIPTION¶

First, this is not ment to be a crash course in how LDAP works, if you have no experience with LDAP, I suggest you read some of the literature that's available out there. The LDAP Deployment Book from Netscape, or the LDAP C SDK documentation are good starting points.

This object class basically tracks and manages the LDAP connection, it's current status, and the current search operation (if any). Every time you call the search method of an object instance, you'll reset it's internal state. It depends heavily on the ::Entry class, which are used to retrieve, modify and update a single entry.

The search and nextEntry methods returns Mozilla::LDAP::Entry objects, or an appropriately subclass of it. You also have to instantiate (and modify) a new ::Entry object when you want to add new entries to an LDAP server. Alternatively, the add() method will also take a hash array as argument, to make it easy to create new LDAP entries.

To assure that changes to an entry are updated properly, we strongly recommend you use the native methods of the ::Entry object class. Even though you can modify certain elements directly, it could cause changes not to be committed to the LDAP server. If there's something missing from the API, please let us know, or even fix it yourself.

SOME PERLDAP/OO BASICS¶

An entry consist of a DN, and a hash array of pointers to attribute values. Each attribute value (except the DN) is an array, but you have to remember the hash array in the entry stores pointers to the array, not the array. So, to access the first CN value of an entry, you'd do

    $cn = $entry->{cn}[0];

To set the CN attribute to a completely new array of values, you'd do

    $entry->{cn} = [ "Leif Hedstrom", "The Swede" ];

As long as you remember this, and try to use native Mozilla::LDAP::Entry methods, this package will take care of most the work. Once you master this, working with LDAP in Perl is surprisingly easy.

We already mentioned DN, which stands for Distinguished Name. Every entry on an LDAP server must have a DN, and it's always guaranteed to be unique within your database. Some typical DNs are

    uid=leif,ou=people,o=netscape.com
    cn=gene-staff,ou=mailGroup,o=netscape.com
    dc=data,dc=netscape,dc=com

There's also a term called RDN, which stands for Relative Distinguished Name. In the above examples, "uid=leif", "cn=gene-staff" and "dc=data" are all RDNs. One particular property for a RDN is that they must be unique within it's sub-tree. Hence, there can only be one user with "uid=leif" within the "ou=people" tree, there can never be a name conflict.

CREATING A NEW OBJECT INSTANCE¶

Before you can do anything with PerLDAP, you'll need to instantiate at least one Mozilla::LDAP::Conn object, and connect it to an LDAP server. As you probably guessed already, this is done with the new method:

    $conn = Mozilla::LDAP::Conn->new("ldap", "389", $bind, $pswd, $cert, $ver);
    die "Couldn't connect to LDAP server ldap" unless  $conn;

The arguments are: Host name, port number, and optionally a bind-DN, it's password, and a certificate. A recent addition is the LDAP protocol version, which is by default LDAP v3. If there is no bind-DN, the connection will be bound as the anonymous user. If the certificate file is specified, the connection will be over SSL, and you should then probably connect to port 636. You have to check that the object was created properly, and take proper actions if you couldn't get a connection.

There's one convenient alternative call method to this function. Instead of providing each individual argument, you can provide one hash array (actually, a pointer to a hash). For example:

    %ld = Mozilla::LDAP::Utils::ldapArgs();
    $conn = Mozilla::LDAP::Conn->new(\%ld);

The components of the hash are:

    $ld->{"host"}
    $ld->{"port"}
    $ld->{"base"}
    $ld->{"bind"}
    $ld->{"pswd"}
    $ld->{"cert"}
    $ld->{"vers"}

and (not used in the new method)

    $ld->{"scope"}

New for PerLDAP v1.5 and later are the following:

    $ld->{"nspr"}
    $ld->{"timeout"}
    $ld->{"callback"}
    $ld->{"entryclass"}

The nspr flag (1/0) indicates that we wish to use the NSPR layer for the LDAP connection. This obviously only works if PerLDAP has been compiled with NSPR support and libraries. The default is for NSPR to be disabled.

For an NSPR enabled connection, you can also provide an optional timeout parameter, which will be used during the lifetime of the connection. This includes the initial setup and connection to the LDAP server. You can change this parameter later using the setNSPRTimeout() method.

During the bind process, you can provide a callback function to be called when the asynchronus bind has completed. The callback should take two arguments, a reference to the ::Conn object ("self") and a result structure as returned by the call to ldap_result().

Finally, you can optionally specify what class the different methods should use when instantiating Entry result objects. The default is Mozilla::LDAP::Entry.

Once a connection is established, the package will take care of the rest. If for some reason the connection is lost, the object should reconnect on it's own, automatically. [Note: This doesn't work now... ]. You can use the Mozilla::LDAP:Conn object for any number of operations, but since everything is currently done synchronously, you can only have one operation active at any single time. You can of course have multiple Mozilla::LDAP::Conn instanced active at the same time.

PERFORMING LDAP SEARCHES¶

We assume that you are familiar with the LDAP filter syntax already, all searches performed by this object class uses these filters. You should also be familiar with LDAP URLs, and LDAP object classes. There are some of the few things you actually must know about LDAP. Perhaps the simples filter is

    (uid=leif)

This matches all entries with the UID set to "leif". Normally that would only match one entry, but there is no guarantee for that. To find everyone with the name "leif", you'd instead do

    (cn=*leif*)

A more complicated search involves logic operators. To find all mail groups owned by "leif" (or actually his DN), you could do

    (&(objectclass=mailGroup)(owner=uid=leif,ou=people,o=netscape))

The owner attribute is what's called a DN attribute, so to match on it we have to specify the entire DN in the filter above. We could of course also do a sub string "wild card" match, but it's less efficient, and requires indexes to perform reasonably well.

Ok, now we are prepared to actually do a real search on the LDAP server:

    $base = "o=netscape.com";
    $conn = Mozilla::LDAP::Conn->new("ldap", "389", "", ""); die "No LDAP
    connection" unless $conn;
    $entry = $conn->search($base, "subtree", "(uid=leif)");
    if (! $entry)
      { # handle this event, no entries found, dude!
      }
    else
      {
        while ($entry)
          {
            $entry->printLDIF();
            $entry = $conn->nextEntry();
          }
      }

This is in fact a poor mans implementation of the ldapsearch command line utility. The search method returns an Mozilla::LDAP::Entry object (or derived subclass), which holds the first entry from the search, if any. To get the second and subsequent entries you call the entry method, until there are no more entries. The printLDIF method is a convenient function, requesting the entry to print itself on STDOUT, in LDIF format.

The arguments to the search methods are the LDAP Base-DN, the scope of the search ("base", "one" or "sub"), and the actual LDAP filter. The entry return contains the DN, and all attribute values. To access a specific attribute value, you just have to use the hash array:

    $cn = $entry->{cn}[0];

Since many LDAP attributes can have more than one value, value of the hash array is another array (or actually a pointer to an array). In many cases you can just assume the value is in the first slot (indexed by [0]), but for some attributes you have to support multiple values. To find out how many values a specific attribute has, you'd call the size method:

    $numVals = $entry->size("objectclass");

One caveat: Many LDAP attributes are case insensitive, but the methods in the Mozilla::LDAP::Entry package are not aware of this. Hence, if you compare values with case sensitivity, you can experience weird behavior. If you know an attribute is CIS (Case Insensitive), make sure you do case insensitive string comparisons.

Unfortunately some methods in this package can't do this, and by default will do case sensitive comparisons. We are working on this, and in a future release some of the methods will handle this more gracefully. As an extension (for LDAP v3.0) we could also use schema discovery for handling this even better.

There is an alternative search method, to use LDAP URLs instead of a filter string. This can be used to easily parse and process URLs, which is a compact way of storing a "link" to some specific LDAP information. To process such a search, you use the searchURL method:

    $entry->searchURL("ldap:///o=netscape.com??sub?(uid=leif)");

As it turns out, the search method also supports LDAP URL searches. If the search filter looks like a proper URL, we will actually do an URL search instead. This is for backward compatibility, and for ease of use.

To achieve better performance and use less memory, you can limit your search to only retrieve certain attributes. With the LDAP URLs you specify this as an optional parameter, and with the search method you add two more options, like

    $entry = $conn->search($base, "sub", $filter, 0, ("mail", "cn"));

The last argument specifies an array of attributes to retrieve, the fewer the attributes, the faster the search will be. The second to last argument is a boolean value indicating if we should retrieve only the attribute names (and no values). In most cases you want this to be FALSE, to retrieve both the attribute names, and all their values. To do this with the searchURL method, add a second argument, which should be 0 or 1.

PERFORMING ASYNCHRONOUS SEARCHES¶

Conn also supports an async_search method that takes the same arguments as the search method but returns an instance of SearchIter instead of Entry. As its name implies, the SearchIter is used to iterate through the search results. The nextEntry method works just like the nextEntry method of Conn. The abandon method should be called if search result processing is aborted before the last result is received, to allow the client and server to release resources. Example:

        $iter = $conn->async_search($base, $scope, $filter, ...);
    if ($rc = $iter->getResultCode()) {
            # process error condition
        } else {
            while (my $entry = $iter->nextEntry) {
                        # process entry
            if (some abort condition) {
                $iter->abandon;
                last;
            }
        }
    }

MODIFYING AND CREATING NEW LDAP ENTRIES¶

Once you have an LDAP entry, either from a search, or created directly to get a new empty object, you are ready to modify it. If you are creating a new entry, the first thing to set it it's DN, like

    $entry = $conn->newEntry();
    $entry->setDN("uid=leif,ou=people,o=netscape.com");

alternatively you can still use the new method on the Entry class, like

    $entry = Mozilla::LDAP::Entry->new();

You should not do this for an existing LDAP entry, changing the RDN (or DN) for such an entry must be done with modifyRDN. To populate (or modify) some other attributes, we can do

    $entry->{objectclass} = [ "top", "person", "inetOrgPerson" ];
    $entry->{cn} = [ "Leif Hedstrom" ];
    $entry->{mail} = [ "leif@netscape.com" ];

Once you are done modifying your LDAP entry, call the update method from the Mozilla::LDAP::Conn object instance:

    $conn->update($entry);

Or, if you are creating an entirely new LDAP entry, you must call the add method:

    $conn->add($entry);

If all comes to worse, and you have to remove an entry again from the LDAP server, just call the delete method, like

    $conn->delete($entry->getDN());

You can't use native Perl functions like push() and splice() on attribute values, since they won't update the ::Entry instance state properly. Instead use one of the methods provided by the Mozilla::LDAP::Entry object class, for instance

    $entry->addValue("cn", "The Swede");
    $entry->removeValue("mailAlternateAddress", "leif@mcom.com");
    $entry->remove("seeAlso");

These methods return a TRUE or FALSE value, depending on the outcome of the operation. If there was no value to remove, or a value already exists, we return FALSE, otherwise TRUE. To check if an attribute has a certain value, use the hasValue method, like

    if ($entry->hasValue("mail", "leif@netscape.com")) {
        # Do something
    }

There is a similar method, matchValue, which takes a regular expression to match against, instead of the entire string. For more information this and other methods in the Entry class, see below.

OBJECT CLASS METHODS¶

We have already described the fundamentals of this class earlier. This is a summary of all available methods which you can use. Be careful not to use any undocumented features or heaviour, since the internals in this module is likely to change.

EXAMPLES¶

There are plenty of examples to look at, in the examples directory. We are adding more examples every day (almost).

INSTALLATION¶

Installing this package is part of the Makefile supplied in the package. See the installation procedures which are part of this package.

AVAILABILITY¶

This package can be retrieved from a number of places, including:

    http://www.mozilla.org/directory/
    Your local CPAN server

CREDITS¶

Most of this code was developed by Leif Hedstrom, Netscape Communications Corporation.

BUGS¶

None. :)

SEE ALSO¶

Mozilla::LDAP::Entry, LDAP::Mozilla:Utils LDAP::Mozilla:API and of course Perl.