MAN page from OpenSuSE perl-Mozilla-LDAP-1.5.3-11.7.x86_64.rpm

Conn

Section: User Contributed Perl Documentation (3)
Updated: 2010-08-03
Index

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 LDAPmodule. Even though it's certainly possible, and sometimes even necessary,to call the native LDAP C SDK functions, we strongly recommend you usethese object classes.

It's not required to use our Mozilla::LDAP::Utils.pm package, but it'sconvenient and good for portability if you use as much as you can fromthat 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::Entrydocument. Both modules depend on each other heavily.

DESCRIPTION

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

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

The search and nextEntry methods returns Mozilla::LDAP::Entryobjects, 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 LDAPserver. Alternatively, the add() method will also take a hash array asargument, to make it easy to create new LDAP entries.

To assure that changes to an entry are updated properly, we stronglyrecommend you use the native methods of the ::Entry object class. Eventhough you can modify certain elements directly, it could cause changesnot to be committed to the LDAP server. If there's something missing fromthe 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 attributevalues. Each attribute value (except the DN) is an array, but you have toremember the hash array in the entry stores pointers to the array, not thearray. 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::Entrymethods, this package will take care of most the work. Once you masterthis, working with LDAP in Perl is surprisingly easy.

We already mentioned DN, which stands for Distinguished Name. Every entryon an LDAP server must have a DN, and it's always guaranteed to be uniquewithin 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 DistinguishedName. 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 beunique 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 nameconflict.

CREATING A NEW OBJECT INSTANCE

Before you can do anything with PerLDAP, you'll need to instantiate atleast one Mozilla::LDAP::Conn object, and connect it to an LDAP server. Asyou 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'spassword, 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 willbe bound as the anonymous user. If the certificate file is specified, theconnection will be over SSL, and you should then probably connect to port636. You have to check that the object was created properly, and takeproper actions if you couldn't get a connection.

There's one convenient alternative call method to this function. Instead ofproviding 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 forthe LDAP connection. This obviously only works if PerLDAP has been compiledwith NSPR support and libraries. The default is for NSPR to be disabled.

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

During the bind process, you can provide a callback function to be calledwhen the asynchronus bind has completed. The callback should take twoarguments, a reference to the ::Conn object (``self'') and a result structureas returned by the call to ldap_result().

Finally, you can optionally specify what class the different methodsshould use when instantiating Entry result objects. The default isMozilla::LDAP::Entry.

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

PERFORMING LDAP SEARCHES

We assume that you are familiar with the LDAP filter syntax already, allsearches performed by this object class uses these filters. You shouldalso be familiar with LDAP URLs, and LDAP object classes. There are someof the few things you actually must know about LDAP. Perhaps the simplesfilter is

    (uid=leif)

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

    (cn=*leif*)

A more complicated search involves logic operators. To find all mailgroups 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 itwe have to specify the entire DN in the filter above. We could of coursealso do a sub string ``wild card'' match, but it's less efficient, andrequires 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 commandline utility. The search method returns an Mozilla::LDAP::Entryobject (or derived subclass),which holds the first entry from the search, if any. To get the second andsubsequent entries you call the entry method, until there are no moreentries. The printLDIF method is a convenient function, requesting theentry to print itself on STDOUT, in LDIF format.

The arguments to the search methods are the LDAP Base-DN, thescope of the search (``base'', ``one'' or ``sub''), and the actual LDAPfilter. The entry return contains the DN, and all attribute values. Toaccess 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 hasharray is another array (or actually a pointer to an array). In many casesyou can just assume the value is in the first slot (indexed by [0]), butfor some attributes you have to support multiple values. To find out howmany 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 inthe Mozilla::LDAP::Entry package are not aware of this. Hence, if youcompare values with case sensitivity, you can experience weirdbehavior. If you know an attribute is CIS (Case Insensitive), make sureyou do case insensitive string comparisons.

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

There is an alternative search method, to use LDAP URLs instead of afilter string. This can be used to easily parse and process URLs, which isa compact way of storing a ``link'' to some specific LDAP information. Toprocess 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. Ifthe search filter looks like a proper URL, we will actually do an URLsearch instead. This is for backward compatibility, and for ease of use.

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

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

The last argument specifies an array of attributes to retrieve, the fewerthe attributes, the faster the search will be. The second to last argumentis a boolean value indicating if we should retrieve only the attributenames (and no values). In most cases you want this to be FALSE, toretrieve both the attribute names, and all their values. To do this withthe 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 argumentsas the search method but returns an instance of SearchIter insteadof Entry. As its name implies, the SearchIter is used to iteratethrough the search results. The nextEntry method works just likethe nextEntry method of Conn. The abandon method should be calledif search result processing is aborted before the last result isreceived, 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 toget a new empty object, you are ready to modify it. If you are creating anew 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 (orDN) for such an entry must be done with modifyRDN. To populate (ormodify) some other attributes, we can do

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

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

    $conn->update($entry);

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

    $conn->add($entry);

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

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

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

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

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

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

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

OBJECT CLASS METHODS

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

Searching and updating entries

add

Add a new entry to the LDAP server. Make sure you use the new methodfor the Mozilla::LDAP::Entry object, to create a proper entry.

browse

Searches for an LDAP entry, but sets some default values to begin with,such as scope=BASE, filter=(objectclass=*) and so on. Much like searchexcept for these defaults. Requires a DN valueas an argument. An optional second argument is an array of whichattributes to return from the entry. Note that this does not support the``attributesOnly'' flag.

    $secondEntry = $conn->browse($entry->getDN());

close

Close the LDAP connection, and clean up the object. If you don'tcall this directly, the destructor for the object instance will do the jobfor you.

compare

Compares an attribute and value to a given DN without first doing asearch. Requires three arguments: a DN, the attribute name, and the valueof the attribute. Returns TRUE if the attribute/value compared ok.

    print "not" unless $conn->compare($entry->getDN(), "cn", "Big Swede");    print "ok";

delete

This will delete the current entry, or possibly an entry as specified withthe optional argument. You can use this function to delete any entry youlike, by passing it an explicit DN. If you don't pass it this argument,delete defaults to delete the current entry, from the last call tosearch or entry. I'd recommend doing a delete with the explicit DN,like

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

modifyRDN

This will rename the specified LDAP entry, by modifying it's RDN. Forexample, assuming you have a DN of

    uid=leif, ou=people, dc=netscape, dc=com

and you wish to rename to

    uid=fiel, ou=people, dc=netscape, dc=com

you'd do something like

    $rdn = "uid=fiel";    $conn->modifyRDN($rdn, $entry->getDN());

Note that this can only be done on the RDN, you could not change say"ou=people" to be "ou=hackers" in the example above. To do that, you haveto add a new entry (a copy of the old one), and then remove the oldentry.

The last argument is a boolean (0 or 1), which indicates if the old RDNvalue should be removed from the entry. The default is TRUE (``1'').

new

This creates and initialized a new LDAP connection and object. Therequired arguments are host name, port number, bind DN and the bindpassword. An optional argument is a certificate (public key), which causesthe LDAP connection to be established over an SSL channel. Currently we donot support Client Authentication, so you still have to use the simpleauthentication method (i.e. with a password).

A typical usage could be something like

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

Also, remember that if you use SSL, the port is (usually) 636.

newEntry

This will create an empty Mozilla::LDAP::Entry object, which is properlytied into the appropriate objectclass. Use this method instead of manuallycreating new Entry objects, or at least make sure that you use the ``tie''function when creating the entry. This function takes no arguments, andreturns a pointer to an ::Entry object. For instance

    $entry = $conn->newEntry();

    $entry = Mozilla::LDAP::Conn->newEntry();

nextEntry

This method will return the next entry from the search result, and cantherefore only be called after a succesful search has been initiated. Ifthere are no more entries to retrieve, it returns nothing (empty string).

search

The search method is the main entry point into this module. It requiresat least three arguments: The Base DN, the scope, and the searchstrings. Two more optional arguments can be given, the first specifies ifonly attribute names should be returned (TRUE or FALSE). The secondargument is a list (array) of attributes to return.

The last option is very important for performance. If you are onlyinterested in say the ``mail'' and ``mailHost'' attributes, specifying this inthe search will signficantly reduce the search time. An example of anefficient search is

    @attr = ("cn", "uid", "mail");    $filter = "(uid=*)";    $entry = $conn->search($base, $scope, $filter, 0, @attr);    while ($entry) {        # do something        $entry = $conn->nextEntry();    }

searchURL

This is almost identical to search, except this function takes only twoarguments, an LDAP URL and an optional flag to specify if we only want theattribute names to be returned (and no values). This function isn't veryuseful, since the search method will actually honor properly formedLDAP URL's, and use it if appropriate.

simpleAuth

This method will rebind the LDAP connection using new credentials (i.e. anew user-DN and password). To rebind ``anonymously'', just don't pass a DNand password, and it will default to binding as the unprivleged user. Forexample:

    $user = "leif";    $password = "secret";    $conn = Mozilla::LDAP::Conn->new($host, $port);     # Anonymous bind    die "Could't connect to LDAP server $host" unless $conn;    $entry = $conn->search($base, $scope, "(uid=$user)", 0, (uid));    exit (-1) unless $entry;    $ret = $conn->simpleAuth($entry->getDN(), $password);    exit (-1) unless $ret;    $ret = $conn->simpleAuth();         # Bind as anon again.

update

After modifying an Ldap::Entry entry (see below), use the updatemethod to commit changes to the LDAP server. Only attributes that has beenchanged will be updated, assuming you have used the appropriate methods inthe Entry object. For instance, do not use push or splice tomodify an entry, the update will not recognize such changes.

To change the CN value for an entry, you could do

    $entry->{cn} = ["Leif Hedstrom"];    $conn->update($entry);

Other methods

getErrorCode

Return the error code (numeric) from the last LDAP API functioncall. Remember that this can only be called after the successfulcreation of a new :Conn object instance. A typical usage could be

    if (! $opt_n) {        $conn->modifyRDN($rdn, $entry->getDN());        $conn->printError() if $conn->getErrorCode();    }

Which will report any error message as generated by the call tomodifyRDN. Some LDAP functions return extra error information, whichcan be retrieved like:

   $err = getErrorCode(\$matched, \$string);

$matched will then contain the portion of the matched DN (if applicable tothe error code), and $string will contain any additional error stringreturned by the LDAP server.

getErrorString

Very much like getErrorCode, but return a string with a human readableerror message. This can then be used to print a good error message on theconsole.

getLD

Return the (internal) LDAP* connection handle, which you can use(carefully) to call the native LDAP API functions. You shouldn't have touse this in most cases, unless of course our OO layer is seriously flawed.

getRes

Just like getLD, except it returns the internal LDAP return messagestructure. Again, use this very carefully, and be aware that this mightbreak in future releases of PerLDAP. These two methods can be used to callsome useful API functions, like

    $cld = $conn->getLD();    $res = $conn->getRes();    $count = Mozilla::LDAP::API::ldap_count_entries($cld, $res);

isURL

Returns TRUE or FALSE if the given argument is a properly formed URL.

printError

Print the last error message on standard output.

setRebindProc

Tell the LDAP SDK to call the provided Perl function when it has to followreferrals. The Perl function should return an array of three elements, thenew Bind DN, password and authentication method. A typical usage is

    sub rebindProc {        return ("uid=ldapadmin", "secret", LDAP_AUTH_SIMPLE);    }    $ld->setRebindProc(\&rebindProc);

setDefaultRebindProc

This is very much like the previous function, except instead of specifyingthe function to use, you give it the DN, password and Auth method. Thenwe'll use a default rebind procedure (internal in C) to handle the rebindcredentials. This was a solution for the Windows/NT problem/bugs we havewith rebind procedures written in Perl.

setVersion

Change the LDAP protocol version on the already initialized connection.The default is LDAP v3 (new for PerLDAP v1.5!), but you can downgradethe connection to LDAP v2 if necessary using this function. Example:

    $conn->setVersion(2);

getVersion

Return the protocol version currently in used by the connection.

setSizelimit

Set the sizelimit on a connection, to limit the maximum number ofentries that we want to retrieve. For example:

   $conn->setSizelimit(10);

getSizelimit

Get the current sizelimit on a connection (if any).

setOption

Set an (integer) LDAP option.

getOption

Get an (integer) LDAP option.

installNSPR

Install NSPR I/O, threading, and DNS functions so they will be used by'ld'.

Pass a non-zero value for the 'shared' parameter if you plan to usethis LDAP * handle from more than one thread. This is highly unlikelysince PerLDAP is asynchronous.

setNSPRTimeout

Set the TCP timeout value, in millisecond, for the NSPR enabled connection.It's an error to call this before calling installNSPR(), unless youcreated the new connection object with the nspr option.

This method can also be invoked as a class method, and it will then applyto all new connections created. Like

    Mozilla::LDAP::Conn->installNSPR(1);    Mozilla::LDAP::Conn->setNSPRTimeout(1000);

EXAMPLES

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

INSTALLATION

Installing this package is part of the Makefile supplied in thepackage. 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 CommunicationsCorporation.

BUGS

None. :)

Index

SOME PERLDAP/OO BASICS

CREATING A NEW OBJECT INSTANCE

PERFORMING LDAP SEARCHES

PERFORMING ASYNCHRONOUS SEARCHES

MODIFYING AND CREATING NEW LDAP ENTRIES

OBJECT CLASS METHODS

Searching and updating entries
Other methods

This document was created byman2html,using the manual pages.