An Introduction to perl-ldap

If you have a large number of users on your system, it's likely you do not want to add each new user to the system one by one, through a GUI. So, one of the first things you write is a script that quickly adds lots of users in bulk. Or, perhaps you'll write a Web-based system where users can enter their personal information for themselves, with LDAP entries being added automatically. The add() method is used for adding an entry to the database:

$result = $ldap->add("uid=john,ou=People,dc=leapster,dc=org", 
                attr => [ 'cn' => 'John Smith',
                          'sn' => 'Smith',
                          'uid' => 'john',
                          'givenName' => 'John',
                          'homePhone' => '555-2020',
                          'mail' => 'john@domain.name',
                          'objectclass' => [ 'person', 'inetOrgPerson']
                        ]
           );

The above snippet of code adds a user named John Smith to our database. As you can see, the attributes are provided as a list to the attr parameter. Any attribute to which you wish to give multiple values should have them supplied as a list (in our example above, objectclass is such an attribute).

We're now at the point where we can write a simple script to add our large number of users in bulk, a script I've called ldap_addusers.

#!/usr/bin/perl
use Net::LDAP;
$ldap = Net::LDAP->new("localhost");
$ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");
while(<>) {
        chomp $_;
        ($uid,$givenName,$sn,$mail) = split(/:/,$_);
        $cn="$givenName $sn";
        $dn="uid=$uid,ou=People,dc=leapster,dc=org";
        $result = $ldap->add($dn,
                attr => [ 'uid' => $uid,
                          'cn' => $cn,
                          'sn' => $sn,
                          'mail' => $mail,
                          'givenName' => $givenName,
                          'objectclass' => [ 'person', 'inetOrgPerson']
                        ]
           );
        $result->code && warn "error: ", $result->error;
}

The above script takes a colon-separated file of users, one per line, on stdin:

tom:Tom:Jones:tom@domain.name
dick:Dick:Tracy:dick@domain.name
harry:Harry:Windsor:harry@domain.name

So, if these names are stored in a file called userlist, we can enter them into our LDAP database with the ldap_addusers script, as follows:

cat userlist | ./ldap_addusers

There's one line in the ldap_addusers script that we haven't seen before:

$result->code && warn "error: ", $result->error;

As mentioned earlier, the add() method returns an object of type Net::LDAP::Message. Here, this object is referenced by $result. $result->code is the code value returned from the LDAP server in the result message after a query (in this case, the request to add an entry). Generally, when the request is successful, a zero is returned. Hence, in our above statement, the warning is issued only when $result->code is not zero.

Some other useful methods in Net::LDAP::Message are:

$result->dn        The DN contained in the result message
$result->error     The error message in the result (only if there was an error)
$result->done      True if the request was completed
$result->is_error  True if the particular result is an error for the operation

For a full description of the other methods, see the perldoc manual for Net::LDAP::Message.

perl-ldap also provides the delete() method for deleting entries, when given their DN:

$dn="uid=paul,ou=People,dc=leapster,dc=org";
$ldap->delete($dn);

This would, for example, allow you to write a script to do a bulk delete of expired users from your system:

#!/usr/bin/perl
use Net::LDAP;
$ldap = Net::LDAP->new("localhost");
$ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");
while(<>) {
        chomp $_;
        $dn="uid=$_,ou=People,dc=leapster,dc=org";
        $ldap->delete($dn);
}

This script deletes all users whose uids are fed to it on standard input, one per line. Be careful when using this script on production servers; if you accidentally feed it the wrong file, you may find yourself with no users left in your directory.

It wouldn't be much use only to be able to write to our LDAP server; we need to be able to read from it also. The perl-ldap search command is used to perform lookups on an LDAP server.

$mesg = $ldap->search(filter=>"(uid=paul)", base=>"dc=leapster,dc=org");

The base parameter specifies the base object entry from which the search will be made. In the example above, it searches the entire LDAP tree. The search could be confined to only the ou=People branch with:

$mesg = $ldap->search(  filter=>"(uid=paul)", 
                        base=>"ou=People,dc=leapster,dc=org");

A number of other optional parameters are available to the search() method:

The search() method returns Net::LDAP::Search objects. The easiest way to get at the contents of this object is to use its entries() method, which returns an array of Net::LDAP::Entry objects (see below):

@entries = $mesg->entries;

The Net::LDAP::Search object also has a number of other useful methods:

$mesg->count;           The number of entries returned in the search
$mesg->entry(n);        Returns the n'th entry (initial entry is 0)
$mesg->sorted([list])   Returns a list of entry objects sorted by attr list

Now, we can write a small script to list every entry in the directory:

#!/usr/bin/perl
use Net::LDAP;
$ldap = Net::LDAP->new("localhost");
$ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");
$mesg = $ldap->search(filter=>"(objectClass=*)", base=>"dc=leapster,dc=org");
@entries = $mesg->entries;
foreach $entry (@entries) {
        $entry->dump;
}

I've cheated a little in the above script and used the dump() method of Net::LDAP::Entry, in order to make things clearer. dump() primarily is used for debugging; it merely dumps the DN and contents of an entry straight to standard output, without allowing for any manipulation of the results.

The most commonly used methods of the Net::LDAP::Entry object are:

Now that we've examined the Net::LDAP::Entry object, we can expand the above script further. We can write out the contents of the entries ourselves:

#!/usr/bin/perl
use Net::LDAP;
$ldap = Net::LDAP->new("localhost");
$ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");
$mesg = $ldap->search(filter=>"(objectClass=*)", base=>"dc=leapster,dc=org");
@entries = $mesg->entries;
foreach $entry (@entries) {
        print "dn: " . $entry->dn() . "\n";
        @attrs = $entry->attributes();
        foreach $attr (@attrs) {
                printf("\t%s: %s\n", $attr, $entry->get_value($attr));
        }
}