An Introduction to perl-ldap

A beginner's guide to using Net::LDAP

As systems get larger and the number of users they support increases, it becomes more difficult to manage systems using only the old-fashioned UNIX /etc/passwd file. A common solution to this problem is to use a Lightweight Directory Access Protocol (LDAP) server. The use of an LDAP server presents a problem to the system administrator, however, in that the contents of the database are no longer available in an easy to read or modify format. Hence, new tools must be written that allow standard, everyday tasks, such as adding or deleting users, to be performed.

This is where perl-ldap comes in. perl-ldap provides the Net::LDAP perl module, which enables easy access to the data contained in LDAP directories from Perl scripts. This makes the module a useful tool for system administrators and Web developers alike. The perl-ldap home page is located at

For this article, I assume you have a reasonable knowledge of LDAP and are a competent Perl programmer. If not, plenty of published material is available on the Internet covering both of these topics.


If you're running one of the popular Linux distributions, chances are perl-ldap already has been packaged for you, which makes installation simple. Under Debian Linux, perl-ldap is found in the libnet-ldap-perl package. Assuming that your /etc/apt/sources.list file contains an up-to-date Debian server, the following commands should install perl-ldap:

apt-get update 
apt-get install libnet-ldap-perl

Mandrake users will find what they need in the perl-ldap package; for Mandrake 9.1, the specific package is perl-ldap-0.27.01-1mdk.noarch.rpm. If you have urpmi configured correctly, you can install perl-ldap simply by entering:

urpmi perl-ldap

This command also installs the perl-Authen-SASL and perl-XML-Parser packages, which are perl-ldap dependencies in Mandrake.

Red Hat does not appear to provide a perl-ldap package, so users of this distribution either have to obtain it from another RPM-based distribution or install it from the tar.gz package as described below.

If a pre-built package isn't available for your system, you have to download the tar.gz package from CPAN and install it yourself. As the LDAP protocol uses ASN1 encodings, you also need the Convert::ASN1 library. Although you probably can install perl-ldap without it, perl-ldap certainly won't run unless this library available. Both of these libraries are easy to install:

perl Makefile.PL
make test
su root
make install            
Basic Usage

As with other Perl libraries, perl-ldap is invoked with the use statement:

use Net::LDAP 

A new LDAP connection is opened using the new() function call. In the following example, we open a connection to a machine with hostname

$ldap = Net::LDAP->new("");

Because we haven't specified which port number to use, perl-ldap assumes a default of port 389, the well-known LDAP port. If we want to use a different port, say 1389, we need to pass the port parameter:

$ldap = Net::LDAP->new("", port=>1389);

If the server is not reachable, the above function calls return an error after 120 seconds. You can use the timeout parameter to alter this:

$ldap = Net::LDAP->new("", timeout=>30);

After the connection has been initiated, you no longer need to refer explicitly to the Net::LDAP package. All of the perl-ldap functions are accessed as methods of the reference returned from the new() call. The most commonly used methods provided by perl-ldap are as follows:

$ldap->add();           # Add an entry to the server
$ldap->bind();          # Bind to a directory server
$ldap->delete();        # Delete an entry from the server
$ldap->moddn();         # Modify an entry's Distinguished Name (DN)
$ldap->modify();        # Modify the contents of an entry
$ldap->search();        # Perform a search on a directory
$ldap->unbind();        # Unbind from a server

These are described in detail below.

Binding to the Server - bind()

For this example, we assume that I have an LDAP directory with the following contents:

dn: dc=leapster,dc=org
-- dn: cn=admin,dc=leapster,dc=org
-- dn: ou=People,dc=leapster,dc=org
   -- dn: uid=paul,ou=People,dc=leapster,dc=org
   -- dn: uid=mike,ou=People,dc=leapster,dc=org

Put simply, my LDAP base DN is dc=leapster,dc=org. The administrative user of the system (the entry that has superuser control) is cn=admin,dc=leapster,dc=org. It also contains two user entries, uid=paul and uid=mike.

Once you have created a connection to an LDAP server, you need to bind to it. If you're writing a program to talk to public LDAP directories, chances are you need to use only an anonymous bind:

$mesg = $ldap->bind;

However, if you're writing scripts to manage the directory of a server used for storing the account information of local users or customers, you are likely to allow only write access to specific, high-privilege users. In this case, you need to give the DN of the LDAP entry which has these privileges, as well as the password. For example:

$mesg = $ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");

In this case, I use the following privileged user on my system: cn=admin,dc=leapster,dc=org. If I'd bound to one of the unprivileged users (for example, uid=paul,dc=leapster,dc=org), I may not have had any access to read or write options on the system at all, depending on how the server was configured.

The return value, which we store in $mesg, is an object of class New::LDAP::Message. It is discussed later in this article.

If you wish to close a connection, you must unbind from it:



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Awesome Work

Vineet Niranjan's picture

Awesome codes and illustrations.
Would have appreciated more if the Acronyms were clear.

How to add UserAccountControl

Anonymous's picture

How to add user ACcount Control Parameter ,it not working ?


Anonymous's picture

Cannot figure what the value of UID should be? I can dump all the contents with filter set as (objectclass=*) and get around 200 entries ; But, when I try to search for a particular UId, I do not get any results back. can anyone tell me what value should be put in for UID to search? I tried with filter=>"(uid=vinda)" filter=>"(uid=vinda norman)" filter=>"(uid=norman)" but no luck.

dn: CN=vinda Norman,OU=Users,OU=SysStaff,OU=SBCS,DC=ad,DC=cs,DC=sunysb,DC=edu
objectClass: top
cn: Vinda Norman
sn: Norman
givenName: Vinda
distinguishedName: CN=Vinda Norman,OU=Users,OU=SysStaff,OU=SBCS,DC=ad,DC=cs,DC=sunysb,DC=edu
instanceType: 4
whenCreated: 20080904132500.0Z
whenChanged: 20090906023318.0Z
displayName: Vinda norman
uSNCreated: 9019
memberOf: CN=System Staff Users,CN=Users,DC=ad,DC=cs,DC=sunysb,DC=edu
uSNChanged: 778762
name: Vinda Norman
objectGUID: *nÄsM¹lN_Aö
userAccountControl: 512
badPwdCount: 0
codePage: 0
countryCode: 0
badPasswordTime: 128975058670944212
lastLogoff: 0
lastLogon: 128975753602883244
pwdLastSet: 128965394154875698
primaryGroupID: 513
objectSid: ªl²p!Xù{®MZ
accountExpires: 9223372036854775807
logonCount: 267
sAMAccountName: vinda
sAMAccountType: 805306368

What happens if bind fails

Am's picture

$mesg = $ldap->bind("cn=admin,dc=leapster,dc=org", password=>"secret");

I tried this, but even with a wrong password, this line did not give an error.

you mean it still connects

Anonymous's picture

you mean it still connects to LDAP?

This tutorial has helped me

Ldap_guy's picture

This tutorial has helped me created a whole project in one week. This was exactly what i needed! Good job

use warnings; use strict;

Anonymous's picture

use warnings;
use strict;

perl-ldap vs. PerLDAP

Anonymous's picture

Not be be confused with another project, PerLDAP, which started back when Netscape was king. I had used PerLDAP for years, before perl-ldap even existed. It's now part of the Mozilla Foundation and is available here:

The one downside is that it requires the Netscape Directory SDK. But it's free and available for almost any platform.

PerLDAP came after perl-ldap

Anonymous's picture

PerLDAP was originally Net::LDAPapi by Clayton Donley. Netscape announced taking over the module and renaming it PerLDAP at the second perl conference, which was held in San Jose in August 1998.

perl-ldap (Net::LDAP) and Net::LDAPapi projects were both started in 1997 about the same time.

PerLDAP can be difficult to get working though!

Anonymous's picture

I've been trying to get Bugzilla to work with PerLDAP, and while I can successfully compile the Netscape directory code, I can't get PerLDAP itself to compile - too many miconfigurations it appears, maybe some problems with versioning b/w PerLDAP & Netscape's SDK. Anyway, I gave up, and I now use Paul's patch to bugzilla which allows bugzilla to work with Net::LDAP. Cheers Paul.