1Net::LDAP::FAQ(3) User Contributed Perl Documentation Net::LDAP::FAQ(3)
2
6 Net::LDAP::FAQ - Frequently Asked Questions about Net::LDAP
7
9 perldoc Net::LDAP::FAQ
10
12 This document serves to answer the most frequently asked questions on
13 both the perl-ldap Mailing List and those sent to Graham Barr.
14 The latest version of this FAQ can be found at
16 http://ldap.perl.org/FAQ.html
18
20 What is perl-ldap?
21 perl-ldap is the distribution name. The perl-ldap distribution contains
22 the Net::LDAP modules.
23 Why another Perl LDAP implementation?
25 perl-ldap's goal is to be as portable as possible. It does this by
26 being implemented completely in Perl. So basically anywhere that Perl
27 runs perl-ldap will run. This is not true for other implementations
28 which require a C compiler.
29 Where can I get it?
31 Perl-ldap is available from CPAN. You can find the released versions
32 at:
33 http://search.cpan.org/dist/perl-ldap/
35 Is there a web page for perl-ldap?
37 Yes there is at http://ldap.perl.org/
38 Is there a mailing list?
40 Yes there is at perl-ldap@perl.org
41 You can subscribe to this list by mailing perl-ldap-subscribe@perl.org
43 Is the mailing list archived?
45 Yes, at http://nntp.perl.org/group/perl.ldap
46 Archives with messages before we switched to using perl.org can be
48 found at
49 http://marc.theaimsgroup.com/?l=perl-ldap-dev
51 There is also an archive of the perl-ldap mailing list at
53 http://www.xray.mpe.mpg.de/mailing-lists/perl-ldap/
55 which also has messages from before the move.
57 Is there any online documentation?
59 Yes. perl-ldap has online documentation at
60 http://ldap.perl.org/
62 which will have the latest documentation available.
64 Is there a public repository?
66 Yes, there is a public Git repository at
67 https://github.com/perl-ldap/perl-ldap
69 Can I get perl-ldap from the public Git repository?
71 Yes, anyone can pull perl-ldap from the public Git repository on
72 GitHub.
73 There are several ways this can be done - see below.
75 CPAN
77 You can download it from CPAN by following the "Download" link on:
78 http://search.cpan.org/dist/perl-ldap/
80 Example;
82 http://search.cpan.org/CPAN/authors/id/M/MA/MARSCHAP/perl-ldap-0.54.tar.gz
84 Git - fork on GitHub
86 If you have an account on GitHub (there's a free variant), you can
87 easily fork the perl-ldap repository on GitHub. When logged on to
88 GitHub, navigate to the perl-ldap repository
89 https://github.com/perl-ldap/perl-ldap
91 and simply click on the "Fork" button near the top-right corner.
93 Git - clone repository
95 You can download latest development version of perl-ldap from
96 GitHub by cloning the repository using the command:
97 git clone https://github.com/perl-ldap/perl-ldap.git
99 This command will create a directory named 'perl-ldap' in your
101 current directory containing a local clone of the repository.
102 Keeping your local repository in sync with perl-ldap's GitHub
104 repository is easy:
105 cd perl-ldap
107 git pull
108 Web page
110 Most of the time there is a URL link on the perl-ldap home page on
111 ldap.perl.org that points to the latest released version of perl-
112 ldap. Due to the fact that humans must update the web page to
113 point to a new release it sometimes does not get updated as quickly
114 as it should.
115 What is Git?
117 Git (see http://git-scm.com) is a distributed version control system
118 designed to keep track of source changes made by groups of developers
119 working on the same files, allowing them to stay in sync with each
120 other as each individual chooses.
121
123 In order to help the user understand the perl-ldap module better some
124 key LDAP terminology is defined here.
125 What is a directory?
127 A directory is a special purpose hierarchical database that usually
128 contains typed information such as text strings, binary data, or X.509
129 certificates.
130 What is LDAP?
132 LDAP stands for Lightweight Directory Access Protocol. The word
133 Protocol is the key word in the definition given in the preceding
134 sentence, LDAP is NOT hardware or software. It is a protocol that
135 defines how a client and server will communicate with one another.
136 The Lightweight Directory Access Protocol is defined in a series of
138 Requests For Comments, better known as RFCs. The RFCs can be found on
139 the Internet at http://www.ietf.org/ (the master repository) and many
140 other places. There's a link to all the LDAP-related RFCs at perl-
141 ldap's web site, http://ldap.perl.org/rfc.html. Some of the more
142 important RFC numbers are RFC 4510 - 4519 for LDAP (previously called
143 LDAPv3) and the historic RFC 1777 for LDAPv2.
144 What is a LDAP Directory?
146 In the strictest terms of the definition there is no such thing as a
147 LDAP directory. To be practical about this situation every day
148 directory professionals refer to their directory as " a LDAP directory"
149 because it is easy to say and it does convey the type of protocol used
150 to communicate with their directory. Using this definition a LDAP
151 directory is a directory whose server software conforms to the
152 Lightweight Directory Access Protocol when communicating with a client.
153 What is an Entry?
155 The traditional directory definition of a directory object is called an
156 Entry. Entries are composed of attributes that contain the information
157 to be recorded about the object.
158 (An entry in LDAP is somewhat analogous to a record in a table in an
160 SQL database, but don't get too hung up about this analogy!)
161 Entries are held in an upside-down tree structure. Entries can
163 therefore contain subordinate entries, and entries must have one direct
164 superior entry.
165 Entries with subordinate entries are called 'non-leaf' entries.
167 Entries without subordinate entries are called 'leaf' entries.
169 An entry's direct superior entry is called the entry's 'parent'.
171 'Non-leaf' entries are also said to have 'child' entries.
173 What is an attribute?
175 The entry(s) in a directory are composed of attributes that contain
176 information about the object. Each attribute has a type and can
177 contain one or more values.
178 For example:
180 cn=Road Runner
182 is an attribute with a type named "cn", and one value.
184 Each attribute is described by a 'syntax' which defines what kind of
186 information can be stored in the attributes values. Trying to store a
187 value that doesn't conform to the attribute's syntax will result in an
188 error.
189 For example:
191 jpegPhoto=unknown
193 is not permitted by the directory, because jpegPhotos may only contain
195 JPEG-formatted images.
196 Most syntaxes used in LDAP however describe text strings rather than
198 binary objects (like JPEGs or certificates.)
199 In LDAPv3 most of these syntaxes support Unicode encoded using UTF-8.
201 Because the Net::LDAP modules do not change the strings that you pass
202 in as attribute values (they get sent to the LDAP server as-is) to use
203 accented characters you simply need to encode your strings in UTF-8.
204 There are modules on CPAN that will help you here.
205 Note that LDAPv2 servers used something called T.61 instead of Unicode
207 and UTF-8. Most servers do not implement T.61 correctly, and it is
208 recommended that you use LDAPv3 instead.
209 Attributes may also be searched. The algorithms used to perform
211 different kinds of searches are described by the attribute's 'matching
212 rules'. Some matching rules are case-sensitive and some are case-
213 insensitive, for example. Sometimes matching rules aren't defined for
214 a particular attribute: there's no way to search for jpegPhotos that
215 contain a substring!
216 You can examine all of a server's attribute definitions by reading the
218 schema from the server.
219 What is an object class?
221 An object class is the name associated with a group of attributes that
222 must be present in an entry, and the group of attributes that may also
223 be present in an entry.
224 Object classes may be derived (subclassed) from other object classes.
226 For example the widely used 'inetOrgPerson' object class is derived
227 from 'organizationalPerson', which is itself derived from 'person'
228 which is itself derived from 'top'.
229 Every entry has an attribute called 'objectClass' that lists all the
231 names of object classes (and their superclasses) being used with the
232 entry.
233 You can examine all of a server's objectclass definitions by reading
235 the schema from the server.
236 What is a Distinguished Name (DN)?
238 Every entry in a directory has a Distinguished Name, or DN. It is a
239 unique Entry identifier throughout the complete directory. No two
240 Entries can have the same DN within the same directory.
241 Examples of DNs:
243 cn=Road Runner, ou=bird, dc=cartoon, dc=com
245 ou=bird, dc=cartoon, dc=com
246 dc=cartoon, dc=com
247 dc=com
248 What is a Relative Distinguished Name?
250 Every DN is made up of a sequence of Relative Distinguished Names, or
251 RDNs. The sequences of RDNs are separated by commas (,). In LDAPv2
252 semi-colons (;) were also allowed. There can be more than one
253 identical RDN in a directory, but they must have different parent
254 entries.
255 Technically, an RDN contains attribute-value assertions, or AVAs. When
257 an AVA is written down, the attribute name is separated from the
258 attribute value with an equals (=) sign.
259 Example of a DN:
261 cn=Road Runner,ou=bird,dc=cartoon,dc=com
263 RDNs of the proceeding DN:
265 RDN => cn=Road Runner
266 RDN => ou=bird
267 RDN => dc=cartoon
268 RDN => dc=com
269 RDNs can contain multiple attributes, though this is somewhat unusual.
271 They are called multi-AVA RDNs, and each AVA is separated in the RDN
272 from the others with a plus sign (+).
273 Example of a DN with a multi-AVA RDN:
275 cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com
277 Where is an entry's name held?
279 Entries do not contain their DN. When you retrieve an entry from a
280 search, the server will tell you the DN of each entry.
281 On the other hand, entries do contain their RDN. Recall that the RDN is
283 formed from one or more attribute-value assertions (AVAs); each entry
284 must contain all the attributes and values in the RDN.
285 For example the entry:
287 cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com
289 must contain a 'cn' attribute containing at least the value "Road
291 Runner", and an 'l' attribute containing at least the value "Arizona".
292 The attributes used in the RDN may contain additional values, but the
294 entry still only has one DN.
295 What is a search base?
297 A search base is a Distinguished Name that is the starting point of
298 search queries.
299 Example of a DN:
301 cn=Road Runner,ou=bird,dc=cartoon,dc=com
303 Possible search base(s) for the proceeding DN:
305 Base => cn=Road Runner,ou=bird,dc=cartoon,dc=com
307 Base => ou=bird,dc=cartoon,dc=com
308 Base => dc=cartoon,dc=com
309 Base => dc=com
310 Setting the search base to the lowest possible branch of the directory
312 will speed up searches considerably.
313 What is the difference between a LDAP server and a relational database?
315 The most basic difference is that a directory server is a specialized
316 database designed to provide fast searches. While a relational database
317 is optimized for transactions (where a series of operations is counted
318 as 1, thus if one of the steps fails, the RDBMS can roll-back to the
319 state it was in before you started).
320 Directories also typically are hierarchical in nature (RDBMS is
322 typically flat, but you can implement a hierarchy using tables and
323 queries), networkable, distributed and replicated.
324 LDAP provides an open-standard to a directory service.
326 Typically we use LDAP for email directories (all popular email clients
328 provide an LDAP client now) and authorization services (authentication
329 and access control).
330 You could use a RDBMS for these types of queries but there's no set
332 standard, in particular over TCP/IP to connect to databases over the
333 network. There's language specific protocols (like Perl's DBI and
334 Java's JDBC) that hide this problem behind an API abstraction, but
335 that's not a replacement for a standard access protocol.
336 LDAP is starting to be used on roles traditionally played by RDBMS in
338 terms of general data management because it's easier to setup a LDAP
339 server (once you understand the basic nomenclature) and you don't need
340 a DBA to write your queries and more importantly all LDAP servers speak
341 the same essential protocol, thus you don't have to fuss with a
342 database driver trying to connect it to the Internet. Once you have an
343 LDAP server up and running, it's automatically available over the 'net.
344 It's possible to connect to a LDAP server from a variety of mechanisms,
345 including just about every possible programming language.
346 More information on this topic can be found on the following URLs;
348 http://www.openldap.org/faq/data/cache/378.html
350 http://www.isode.com/whitepapers/ic-6055.html
352 What is the difference between a ldap reference and a ldap referral?
354 A referral is returned when the entire operation must be resent to
355 another server.
356 A continuation reference is returned when part of the operation must be
358 resent to another server.
359 See RFC 4511 section 4.5.3 for more details.
361
363 How do I install perl-ldap?
364 To install the modules that are in the perl-ldap distribution follow
365 the same steps that you would for most other distributions found on
366 CPAN, that is
367 # replace 0.62 with the version you have
369 gunzip perl-ldap-0.62.tar.gz
371 tar xvf perl-ldap-0.62.tar
372 cd perl-ldap-0.62
373 perl Makefile.PL
375 make
376 make test
377 make install
378 But I do not have make, how can I install perl-ldap?
380 Well as luck would have it the modules in perl-ldap do not do anything
381 complex, so a simple copy is enough to install. First run
382 perl -V
384 This will output information about the version of Perl you have
386 installed. Near the bottom you will find something like
387 @INC:
389 /usr/local/lib/perl/5.18.2
390 /usr/local/share/perl/5.18.2
391 /usr/lib/perl5
392 /usr/share/perl5
393 /usr/lib/perl/5.18
394 /usr/share/perl/5.18
395 /usr/local/lib/site_per
396 This is a list of directories that Perl searches when it is looking for
398 a module. The directory you need is the site_perl directory, but
399 without the system architecture name, in this case it is
400 "/usr/local/lib/site_perl". The files required can then be installed
401 with
402 # replace 0.62 with the version you have
404 gunzip perl-ldap-0.62.tar.gz
406 tar xvf perl-ldap-0.62.tar
407 cd perl-ldap-0.62/lib
408 cp -r * /usr/local/lib/site_perl
410 How can I load perl-ldap into an ActiveState Perl installation?
412 There are several ways that perl-ldap can be installed into an
413 ActiveState Perl tree.
414 1. The ActiveState ppm command can be used to install perl-ldap. When
416 a new version of perl-ldap is released, it takes ActiveState a
417 period of time to get the new release into the ActiveState ppm
418 system.
419 2. If the user has nmake installed, the user can do a normal Perl
421 module install using nmake instead of make.
422 3. If the user does not have nmake or make, the user can install perl-
424 ldap using the install-nomake script by issuing the following
425 command.
426 perl install-nomake
428 The install-nomake script can be used on any system that does not
430 have make installed.
431 What other modules will I need?
433 perl-ldap uses other Perl modules. Some are required, but some are
434 optional (i.e. required to use certain features only).
435 If you are using a Linux system, many of the distributions have
437 packages that you can install using the distribution's package
438 management tools (e.g. apt, rpm, ...).
439 Alternatively, you may use your favorite web search engine to find the
441 package that you need.
442 Convert::ASN1
444 This module converts between Perl data structures and ASN.1, and is
445 required for perl-ldap to work.
446 You can obtain the latest release from
448 http://search.cpan.org/search?module=Convert::ASN1
449 OpenSSL and IO::Socket::SSL
451 If you want to use encrypted connections, either via start_tls or
452 LDAPS connections, you will need this module and the OpenSSL
453 software package.
454 You can obtain the latest release of IO::Socket::SSL from
456 http://search.cpan.org/search?module=IO::Socket::SSL
457 You can obtain the latest release of OpenSSL from
459 http://www.openssl.org/
460 IO::Socket::INET6
462 For connecting to LDAP servers via IPv6, IO::Socket::INET6 is
463 required. Its presence is detected at runtime, so that perl-ldap
464 can be installed without it, and automatically gains IPv6 support
465 as soon as IO::Socket::INET6 gets installed.
466 You can obtain the latest releases from
468 http://search.cpan.org/search?module=IO::Socket::INET6
469 IO::Socket::IP
471 This is an alternative to using IO::Socket::INET6. Like that
472 module, it gets detected automatically at runtime. If version 0.20
473 or higher is installed, is is preferred over IO::Socket::INET6 and
474 IO::Socket::INET for all IP connections.
475 You can obtain the latest releases from
477 http://search.cpan.org/search?module=IO::Socket::IP
478 Authen::SASL
480 This module is optional. You only need to install Authen::SASL if
481 you want to use the SASL authentication methods.
482 You can obtain the latest release from
484 http://search.cpan.org/search?module=Authen::SASL
485 Digest::MD5
487 This module is optional. It also requires a C compiler when
488 installing. You only need to install Digest::MD5 if you want to
489 use the SASL DIGEST-MD5 authentication mechanism.
490 You can obtain the latest release from
492 http://search.cpan.org/search?module=Digest::MD5
493 As Digest::MD5 is part of the Perl core modules since Perl 5.7.3,
495 you only need a C compiler if you want to install a version that is
496 newer than the version distributed with your Perl installation.
497 Digest::HMAC_MD5
499 This optional module is required only if you want to use the SASL
500 CRAM-MD5 authentication mechanism.
501 You can obtain the latest release from
503 http://search.cpan.org/search?module=Digest::HMAC_MD5
504 GSSAPI
506 This optional module is required only if you want to use the SASL
507 GSSAPI authentication mechanism (e.g. for Kerberos authentication).
508 You can obtain the latest release from
510 http://search.cpan.org/search?module=GSSAPI
511 URI::ldap, URI::ldaps, and URI::ldapi
513 These modules are optional. You only need to install them if you
514 want to parse ldap://, ldaps:// or ldapi:// URIs using
515 ldap_parse_uri in Net::LDAP::Util. or use LWP::Protocol::ldap,
516 LWP::Protocol::ldaps, or LWP::Protocol::ldapi.
517 You can obtain the latest releases from
519 http://search.cpan.org/search?module=URI::ldap
520 http://search.cpan.org/search?module=URI::ldaps
521 http://search.cpan.org/search?module=URI::ldapi
522 LWP::Protocol, LWP::MediaTypes, HTTP::Negotiate, and HTTP::Response
524 These optional modules are needed if you want to use perl-ldap's
525 LWP::Protocol::ldap, LWP::Protocol::ldaps, or LWP::Protocol::ldapi
526 modules.
527 You can obtain the latest releases from
529 http://search.cpan.org/search?module=LWP::Protocol
530 http://search.cpan.org/search?module=LWP::MediaTypes
531 http://search.cpan.org/search?module=HTTP::Negotiate
532 http://search.cpan.org/search?module=HTTP::Response
533 JSON
535 This optional module is required for JSON-formatted output of perl-
536 ldap's LWP::Protocol::ldap, LWP::Protocol::ldaps, or
537 LWP::Protocol::ldapi modules.
538 If you need it, you can obtain the latest releases from
540 http://search.cpan.org/search?module=JSON
541 Time::Local
543 This module is optional, and only required if you want to convert
544 between UNIX time and generalizedTime using the functions provided
545 in Net::LDAP::Util.
546 XML::SAX and XML::SAX::Writer
548 If you want to parse or write DSMLv1 documents with Net::LDAP::DSML
549 to you will need these optional modules.
550 You can obtain the latest releases from
552 http://search.cpan.org/search?module=XML::SAX
553 http://search.cpan.org/search?module=XML::SAX::Writer
554 ResourcePool::Factory::Net::LDAP
556 If you want to use failover the ResourcePool::Factory::Net::LDAP
557 Perl module provides methods to do this.
558 You can obtain the latest release from
560 http://search.cpan.org/search?module=ResourcePool::Factory::Net::LDAP
561
563 How do I connect to my server?
564 The connection to the server is created when you create a new Net::LDAP
565 object, e.g.
566 $ldap = Net::LDAP->new($server);
568 Net::LDAP->new sometimes returns undef, why?
570 The constructor will return undef if there was a problem connecting to
571 the specified server. Any error message will be available in $@
572 What is the proper format of the bind DN?
574 The DN used to bind to a directory is a FULLY QUALIFIED DN. The exact
575 structure of the DN will depend on what data has been stored in the
576 server.
577 The following are valid examples.
579 uid=clif,ou=People,dc=umich,dc=edu
581 cn=directory manager,ou=admins,dc=umich,dc=edu
583 In some servers the following would be a valid fully qualified DN of
585 the directory manager.
586 cn=directory manager
588 How can I tell when the server returns an error, bind() always returns
590 true?
591 Most methods in Net::LDAP return a Net::LDAP::Message object, or a sub-
592 class of that. This object will hold the results from the server,
593 including the result code.
594 So, for example, to determine the result of the bind operation.
596 $mesg = $ldap->bind( $dn, password => $passwd );
598 if ( $mesg->code ) {
600 # Handle error codes here
601 }
602 How can I set the LDAP version of a connection to my LDAP server?
604 This is done by adding the version option when connecting or binding to
605 the LDAP server.
606 For example;
608 $ldap = Net::LDAP->new( $server, version => 3 );
610 or
612 $mesg = $ldap->bind( $dn, password => $passwd, version => 3 );
614 Valid version numbers are 2 and 3. As of perl-ldap 0.27 the default
616 LDAP version is 3.
617 I did a search on my directory using the 'search' method. Where did the
619 results go?
620 Your search results are stored in a 'search object'. Consider the
621 following:
622 use Net::LDAP;
624 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
626 $mesg = $ldap->search(
627 base => "o=acme.com",
628 filter => "uid=jsmith",
629 );
630 $mesg is a search object. It is a reference blessed into the
632 Net::LDAP::Search package. By calling methods on this object you can
633 obtain information about the result and also the individual entries.
634 The first thing to check is if the search was successful. This is done
636 with the method $mesg->code. This method will return the status code
637 that the server returned. A success will yield a zero value, but there
638 are other values, some of which could also be considered a success.
639 See Net::LDAP::Constant
640 use Net::LDAP::Util qw(ldap_error_text);
642 die ldap_error_text($mesg->code)
644 if $mesg->code;
645 There are two ways in which you can access the entries. You can access
647 then with an index or you can treat the container like a stack and
648 shift each entry in turn. For example
649 # as an array
651 # How many entries were returned from the search
653 my $max = $mesg->count;
654 for (my $index = 0 ; $index < $max ; $index++) {
656 my $entry = $mesg->entry($index);
657 # ...
658 }
659 # or as a stack
661 while (my $entry = $mesg->shift_entry) {
663 # ...
664 }
665 In each case $entry is an entry object. It is a reference blessed into
667 the Net::LDAP::Entry package. By calling methods on this object you can
668 obtain information about the entry.
669 For example, to obtain the DN for the entry
671 $dn = $entry->dn;
673 To obtain the attributes that a given entry has
675 @attrs = $entry->attributes;
677 And to get the list of values for a given attribute
679 @values = $entry->get( 'sn' );
681 And to get the first of the values for a given attribute
683 $values = $entry->get( 'cn' );
685 One thing to remember is that attribute names are case insensitive, so
687 'sn', 'Sn', 'sN' and 'SN' are all the same.
688 So, if you want to print all the values for the attribute 'ou' then
690 this is as simple as
691 foreach ($entry->get_value( 'ou' )) {
693 print $_,"\n";
694 }
695 Now if you just want to print all the values for all the attributes you
697 can do
698 foreach my $attr ($entry->attributes) {
700 foreach my $value ($entry->get_value($attr)) {
701 print $attr, ": ", $value, "\n";
702 }
703 }
704 How do I limit the scope of a directory search?
706 You limit the scope of a directory search by setting the scope
707 parameter of search request. Consider the following:
708 use Net::LDAP;
710 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
712 $mesg = $ldap->search(
713 base => "o=acme.com",
714 scope => 'sub',
715 filter => "uid=jsmith",
716 );
717 Values for the scope parameter are as follows.
719 base
721 Search only the base object.
722 one Search the entries immediately below the base object.
724 sub
726 subtree
727 Search the whole tree below (and including) the base object. This
728 is the default.
729 children
731 Search the whole subtree below the base object, excluding the base
732 object itself.
733 Note: children scope requires LDAPv3 subordinate feature extension.
735
737 There are two ways of retrieving the results of a requested LDAP
738 search; inline and by using a callback subroutine.
739 USING THE INLINE APPROACH
741 Using the inline approach involves requesting the data and then waiting
742 for all of the data to be returned before the user starts processing
743 the data.
744 Example:
746 use Net::LDAP;
748 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
750 $mesg = $ldap->search(
751 base => "o=acme.com",
752 scope => 'sub',
753 filter => "sn=smith",
754 );
755 #
756 # At this point the user can get the returned data as an array
757 # or as a stack.
758 # In this example we will use an array
759 # How many entries were returned from the search
761 my $max = $mesg->count;
762 for (my $index = 0 ; $index < $max ; $index++)
764 {
765 my $entry = $mesg->entry($index);
766 my $dn = $entry->dn; # Obtain DN of this entry
767 @attrs = $entry->attributes; # Obtain attributes for this entry.
769 foreach my $var (@attrs)
770 {
771 #get a list of values for a given attribute
772 $attr = $entry->get_value( $var, asref => 1 );
773 if ( defined($attr) )
774 {
775 foreach my $value ( @$attr )
776 {
777 print "$var: $value\n"; # Print each value for the attribute.
778 }
779 }
780 }
781 }
782 As you can see the example is straightforward, but there is one
784 drawback to this approach. You must wait until all entries for the
785 request search to be returned before you can process the data. If
786 there several thousand entries that match the search filter this could
787 take quite a long time period.
788 USING THE CALLBACK SUBROUTINE APPROACH
790 Using the callback approach involves requesting the data be sent to a
791 callback subroutine as each entry arrives at the client.
792 A callback is just a subroutine that is passed two parameters when it
794 is called, the mesg and entry objects.
795 Example:
797 use Net::LDAP;
799 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
801 $mesg = $ldap->search(
802 base => "o=acme.com",
803 scope => 'sub',
804 filter => "sn=smith",
805 callback => \&callback,
806 );
807 #
808 # At this point the user needs to check the status of the
809 # ldap search.
810 #
811 if ( $mesg->code )
813 {
814 $errstr = $mesg->code;
815 print "Error code: $errstr\n";
816 $errstr = ldap_error_text($errstr);
817 print "$errstr\n";
818 }
819 sub callback
822 {
823 my ( $mesg, $entry) = @_;
824 #
826 # First you must check to see if something was returned.
827 # Last execution of callback subroutine will have no
828 # defined entry and mesg object
829 #
830 if ( !defined($entry) )
831 {
832 print "No records found matching filter $match.\n"
833 if ($mesg->count == 0) ; # if mesg is not defined nothing will print.
834 return;
835 }
836 my $dn = $entry->dn; # Obtain DN of this entry
838 @attrs = $entry->attributes; # Obtain attributes for this entry.
840 foreach my $var (@attrs)
841 {
842 #get a list of values for a given attribute
843 $attr = $entry->get_value( $var, asref => 1 );
844 if ( defined($attr) )
845 {
846 foreach my $value ( @$attr )
847 {
848 print "$var: $value\n"; # Print each value for the attribute.
849 }
850 }
851 }
852 #
853 # For large search requests the following line of code
854 # may be very important, it will reduce the amount of memory
855 # used by the search results.
856 #
857 # If the user is not worried about memory usage then the line
858 # of code can be omitted.
859 #
860 $mesg->pop_entry;
861 } # End of callback subroutine
863 As you can see the example is straightforward and it does not waste
865 time waiting for all of the entries to be returned. However if the
866 pop_entry method is not used the callback approach can allocate a lot
867 of memory to the search request.
868
870 Using an SSL network connection, how do I connect to my server?
871 This class is a subclass of Net::LDAP so all the normal Net::LDAP
872 methods can be used with a Net::LDAPS object; see the documentation for
873 Net::LDAP to find out how to query a directory server using the LDAP
874 protocol.
875 The connection to the server is created when you create a new
877 Net::LDAPS object, e.g.
878 $ldaps = Net::LDAPS->new($server,
880 port => '10000',
881 verify => 'require',
882 capath => '/usr/local/cacerts/',
883 );
884 Starting with version 0.28 perl-ldap also supports URIs in the new
886 method. So, the above can also be expressed as:
887 $ldaps = Net::LDAP->new("ldaps://$server",
889 port => '10000',
890 verify => 'require',
891 capath => '/usr/local/cacerts/',
892 );
893 There are additional options to the new method with LDAPS URIs and the
895 LDAPS new method and several additional methods are included in the
896 LDAPS object class.
897 For further information and code examples read the LDAPS module
899 documentation; perldoc Net::LDAPS
900
902 What are LDAP groups?
903 LDAP groups are object classes that contain an attribute that can store
904 multiple DN values. Two standard object classes are 'groupOfNames'
905 (which has a 'member' attribute) and 'groupOfUniqueNames' (which has a
906 'uniqueMember' attribute.)
907 According to the RFCs a group can be a member of another group, but
909 some LDAP server vendors restrict this flexibility by not allowing
910 nested groups in their servers.
911 Two scripts for working with groups are available in the contrib
913 directory. They are isMember.pl and printMembers.pl.
914 How do you format a filter to search for entries whose 'member' attribute
916 has a particular value?
917 Asking for (member=*) is OK - the directory uses the equality matching
918 rule which is defined for the member attribute.
919 Asking for (member=c*) is not OK - there is no defined substring
921 matching rule for the member attribute. That's because the member
922 values are *not* strings, but distinguished names. There is no
923 substring matching rule for DNs, see RFC 4519 section 2.7.
924 What you have to do is get the results of (member=*) and then select
926 the required results from the returned values. You need to do this
927 using knowledge of the string representation of DNs defined in RFC
928 4514, which is important because the same DN can have different string
929 representations. So you need to perform some canonicalization if you
930 want to be correct.
931
933 How can I access DSML features from perl-ldap?
934 Directory Service Markup Language (DSML) is the XML standard for
935 representing directory service information in XML.
936 Support for DSML is included in perl-ldap starting with version .20.
938 At the moment this module only reads and writes DSML entry entities. It
940 cannot process any schema entities because schema entities are
941 processed differently than elements.
942 Eventually this module will be a full level 2 consumer and producer
944 enabling you to give you full DSML conformance.
945 The specification for DSML is at http://www.oasis-open.org/specs/
947 For further information and code examples read the DSML module
949 documentation; perldoc Net::LDAP::DSML
950
952 How do I access the Control features?
953 Support for LDAP version 3 Control objects is included in perl-ldap
954 starting with version .20.
955 For further information and code examples read the Control module
957 documentation; perldoc Net::LDAP::Control
958 How do I access the Virtual List features?
960 Support for Virtual Lists is included in perl-ldap starting with
961 version .20.
962 For further information and code examples read the Control module
964 documentation; perldoc Net::LDAP::Control
965
967 Are there any other code examples.
968 Yes, there is an Examples pod file. To view the pod do the following
969 command; perldoc Net::LDAP::Examples
970 There is user contributed software in the contrib directory that is
972 supplied with the perl-ldap distribution. This is an excellent source
973 of information on how to use the perl-ldap module.
974 Are there any performance issues with perl-ldap?
976 In the vast majority of use cases (one user has suggested 9 out of 10)
977 there are no performance issues with perl-ldap.
978 Where you may wish to use perl-ldap to perform, for example, a very
980 large number of queries (e.g. 10,000) in succession you may find a
981 noticeable performance difference between perl-ldap and non pure-Perl
982 modules. This is not because of perl-ldap itself but because of the
983 pure-Perl Convert::ASN1 module that it depends on.
984 You should make up your own mind, based upon your own situation
986 (performance requirements, hardware etc.) as to whether you should use
987 perl-ldap or not. The figures quoted in this answer are only
988 indicative, and will differ for different people.
989 Can I contribute Perl scripts that use perl-ldap to the contrib section?
991 Any one can submit a Perl script that uses perl-ldap for inclusion in
992 the contrib section. The perl-ldap maintainers will determiner if the
993 script will be included and will do the initial check in of the script
994 to the Git repository at https://github.com/perl-ldap/perl-ldap.
995 There are a couple of requirements for consideration.
997 You must supply a one line description of your script to be included in
999 the contrib README file.
1000 Inside the script will be the pod documentation for the script. No
1002 auxiliary documentation will be allowed. For examples of how to do
1003 this see the tklkup script currently in the contrib section.
1004 Is it possible to get a complete entry, DN and attributes without
1006 specifying the attributes name?
1007 Yes, just specify you want a list of no attributes back. The RFC says
1008 that this tells the server to return all readable attributes back
1009 (there may be access controls to prevent some from being returned.)
1010 So in the search method, just set (for LDAPv2):
1012 attrs => [ ]
1014 If you are using LDAPv3, you can specify an attribute called "*"
1016 instead, which lets you ask for additional (i.g. operational)
1017 attributes in the same search.
1018 attrs => [ "*" ]
1020 To get all operational attributes in a search, some servers allow the
1022 use of the "+" pseudo attribute. So that with these servers
1023 attrs => [ "*", "+" ]
1025 will return the most information from the server.
1027 How do I put a JPEG photo into a entry in the directory?
1029 Follow the following code example, replacing the (...) with whatever is
1030 relevant to your setup.
1031 use Net::LDAP;
1033 use Net::LDAP::Util qw(ldap_error_text);
1034 use CGI;
1035 local $/ = undef;
1037 my $jpeg = <$filename>;
1038 my $ldap = Net::LDAP->new(...);
1040 my $res = $ldap->bind(...);
1041 $res = $ldap->modify(...,
1042 add => [ 'jpegPhoto' => [ $jpeg ] ]);
1043 $res = $ldap->unbind();
1044 How do I add a jpeg photo into a entry in the directory via html-forms?
1046 Follow the following code example, replacing the (...) with whatever is
1047 relevant to your setup.
1048 use Net::LDAP;
1050 use Net::LDAP::Util qw(ldap_error_text);
1051 use CGI;
1052 my $q = new CGI;
1054 print $q->header;
1056 print $q->start_html(-title => 'Change JPEG photo');
1057 if ($q->param('Update')) {
1059 my $filename = $q->param('jpeg');
1060 local $/ = undef;
1061 my $jpeg = <$filename>;
1062 my $ldap = Net::LDAP->new(...);
1064 my $res = $ldap->bind(...);
1065 $res = $ldap->modify(...,
1066 add => [ 'jpegPhoto' => [ $jpeg ] ]);
1067 $res = $ldap->unbind();
1068 } else {
1069 print $q->start_multipart_form();
1070 print $q->filefield(-name => 'jpeg', -size => 50);
1071 print $q->submit('Update');
1072 print $q->end_form();
1073 }
1074 print $q->end_html();
1076 What happens when you delete an attribute that does not exist?
1078 It is an error to delete an attribute that doesn't exist. When you get
1079 the error back the server ignores the entire modify operation you sent
1080 it, so you need to make sure the error doesn't happen.
1081 Another approach, if you are using LDAPv3 (note beginning with version
1083 .27 Net::LDAP uses LDAPv3 by default) is to use a 'replace' with your
1084 attribute name and no values. In LDAPv3, this is defined to always
1085 work even if that attribute doesn't exist in the entry.
1086 I.e.:
1088 my $mesg = $ldap->modify( $entry, replace => { %qv_del_arry } );
1090 But make sure you are using LDAPv3, because that is defined to not work
1092 in LDAPv2. (A nice incompatibility between LDAPv2 and LDAPv3.)
1093 How can I delete a referral from an LDAP tree?
1095 Since this is a proprietary feature, you will have to check your
1096 server's documentation. You might find that you need to use a control.
1097 If there is a control called something like ManageDsaIT, that's the one
1098 you should probably use. For proper operation you will need the oid
1099 number for ManageDsaIT; 2.16.840.1.113730.3.4.2 and do not specify a
1100 value for type.
1101 The code required will look similar to the following code snippet.
1103 $mesg = $ldap->delete("ref=\"ldap://acme/c=us,o=bricks\",o=clay",
1105 control => {type => "2.16.840.1.113730.3.4.2"} );
1106 How do I add an ACI/ACL entry to a directory server with perl-ldap?
1108 ACIs and ACLs are proprietary features in LDAP. The following code
1109 snippet works with a Netscape directory server. You will need the
1110 specify the correct DN (-DN-) and correct attribute(s) (-ATTRNAMEs-).
1111 my $aci = '(target="ldap:///-DN-")(targetattr="-ATTRNAMEs-")(version 3.0;
1113 acl "-ACLNAME-"; deny(all) userdn = "ldap:///self";)' ;
1114 $ldap->modify($dn_modif, add => {'aci' => $aci });
1116 How do I avoid file type and data type mis-matching when loading data from
1118 a Win32 system?
1119 When loading a binary attribute with data read from a file on a Win32
1120 system, it has been noted that you should set "binmode" on the file
1121 before reading the file contents into the data array.
1122 Another possible solution to this problem is to convert the binary data
1124 into a base64 encoded string and then store the encoded string in the
1125 file. Then when reading the file, decode the base64 encoded string
1126 back to binary and then use perl-ldap to store the data in the
1127 directory.
1128 How do I create an account in Active Directory?
1130 Active Directory accounts need some AD-specific attributes (only the
1131 method we're interested in, no error checking):
1132 $mesg = $ldap->add( 'cn=John Doe,cn=Users,dc=your,dc=ads,dc=domain',
1134 attrs => [
1135 objectClass => [ qw/top user/ ],
1136 cn => 'John Doe',
1137 sn => 'Doe',
1138 givenName => 'John',
1139 displayName => 'John "the one" Doe',
1140 userAccountControl => 514, # disabled regular user
1141 sAMAccountName => 'JohnDoe',
1142 userPrincipalName => 'JohnDoe@your.ads.domain'
1143 ]
1144 );
1145 In order to find out what other attributes can be set, interactively
1147 edit the user in the Active Directory Users and Computers MCC plugin,
1148 perform an LDAP search operation to find out what changed, and update
1149 your "add" routine accordingly.
1150 How can I create a group in Active Directory?
1152 Similar to accounts, groups need some AD-specific attributes too:
1153 $mesg = $ldap->add( 'cn=NewGroup,cn=Users,dc=your,dc=ads,dc=domain',
1155 attrs => [
1156 objectClass => [ qw/top group/ ],
1157 cn => 'NewGroup',
1158 sAMAccountName => 'NewGroup',
1159 groupType => 0x80000002 # global, security enabled group
1160 ]
1161 );
1162 How do I search for disabled accounts in Active Directory
1164 The bit values in "userAccountControl" require the
1165 LDAP_MATCHING_RULE_BIT_AND matching rule's OID to be used in an
1166 extensible filter term:
1167 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1169 filter => '(&(objectclass=user)' .
1170 (userAccountControl:1.2.840.113556.1.4.803:=2))',
1171 attrs => [ '1.1' ]
1172 );
1173 How can I search for security groups in Active Directory
1175 With groups, the same applies to the "groupType" bit-field:
1176 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1178 filter => '(&(objectclass=group)' .
1179 (groupType:1.2.840.113556.1.4.803:=2147483648))',
1180 # 2147483648 = 0x80000000
1181 attrs => [ '1.1' ]
1182 );
1183 How can I search for all members of a group in AD (including group
1185 nesting)?
1186 AD allows you to find all members of a specified group, the direct
1187 members plus those that are member of the group via group nesting.
1188 The trick to this is the special "LDAP_MATCHING_RULE_IN_CHAIN" matching
1190 rule:
1191 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1193 filter => '(memberOf:1.2.840.113556.1.4.1941:=cn=Testgroup,dc=your,dc=ads,dc=domain)',
1194 attrs => [ '1.1' ]
1195 );
1196 How can I search for all groups one user is a member of in AD (including
1198 group nesting)?
1199 Similarly you can search for all the groups one user is member of,
1200 either directly or via group nesting.
1201 $mesg = $ldap->search( base => 'dc=your,dc=ads,dc=domain',
1203 filter => '(member:1.2.840.113556.1.4.1941:=cn=TestUser,ou=Users,dc=your,dc=ads,dc=domain)',
1204 attrs => [ '1.1' ]
1205 );
1206 How do I search for all members of a large group in AD?
1208 AD normally restricts the number of attribute values returned in one
1209 query. The exact number depends on the AD server version: it was ~1000
1210 in Win2000, 1500 in Win2003 and is 5000 in Win2008 & Win2008R2.
1211 Performing the same standard search again will yield the same values
1213 again.
1214 So, how can you get all members of a really large AD group?
1216 The trick to use here is to use Microsoft's range option when
1218 searching, i.e instead of doing one search for plain "member", perform
1219 multiple searches for e.g. "member;range=1000-*" where the range
1220 starting index increases accordingly:
1221 my $mesg;
1223 my @members;
1224 my $index = 0;
1225 while ($index ne '*') {
1227 $mesg = $ldap->search( base => 'cn=Testgroup,dc=your,dc=ads,dc=domain',
1228 filter => '(objectclass=group)',
1229 scope => 'base',
1230 attrs => [ ($index > 0) ? "member;range=$index-*" : 'member' ]
1231 );
1232 if ($mesg->code == LDAP_SUCCESS) {
1233 my $entry = $mesg->entry(0);
1234 my $attr;
1235 # large group: let's do the range option dance
1237 if (($attr) = grep(/^member;range=/, $entry->attributes)) {
1238 push(@members, $entry->get_value($attr));
1239 if ($attr =~ /^member;range=\d+-(.*)$/) {
1241 $index = $1;
1242 $index++ if ($index ne '*');
1243 }
1244 }
1245 # small group: no need for the range dance
1246 else {
1247 @members = $entry->get_value('member');
1248 last;
1249 }
1250 }
1251 # failure
1252 else {
1253 last;
1254 }
1255 }
1256 if ($mesg->code == LDAP_SUCCESS) {
1258 # success: @members contains the members of the group
1259 }
1260 else {
1261 # failure: deal with the error in $mesg
1262 }
1263 See
1265 <http://msdn.microsoft.com/en-us/library/windows/desktop/aa367017.aspx>
1266 for more details.
1267 How do I create a Microsoft Exchange 5.x user?
1269 This is a solution provided by a perl-ldap user.
1270 This code works with ActiveState Perl running on WinNT 4. Please note
1272 that this requires the Win32::Perms module, and needs valid NT account
1273 info to replace the placeholders.
1274 use Net::LDAP;
1276 use Net::LDAP::Util;
1277 use Win32::Perms;
1278 #Constants taken from ADSI Type Library
1280 $ADS_RIGHT_EXCH_ADD_CHILD = 1;
1281 $ADS_RIGHT_EXCH_DELETE = 0x10000;
1282 $ADS_RIGHT_EXCH_DS_REPLICATION = 64;
1283 $ADS_RIGHT_EXCH_DS_SEARCH = 256;
1284 $ADS_RIGHT_EXCH_MAIL_ADMIN_AS = 32;
1285 $ADS_RIGHT_EXCH_MAIL_RECEIVE_AS = 16;
1286 $ADS_RIGHT_EXCH_MAIL_SEND_AS = 8;
1287 $ADS_RIGHT_EXCH_MODIFY_ADMIN_ATT = 4;
1288 $ADS_RIGHT_EXCH_MODIFY_SEC_ATT = 128;
1289 $ADS_RIGHT_EXCH_MODIFY_USER_ATT = 2;
1290 $EXCH_USER_RIGHTS = $ADS_RIGHT_EXCH_MAIL_RECEIVE_AS |
1292 $ADS_RIGHT_EXCH_MAIL_SEND_AS |
1293 $ADS_RIGHT_EXCH_MODIFY_USER_ATT;
1294 $exch = Net::LDAP->new('server', debug =>0) || die $@;
1296 $exch->bind( 'cn=admin_user,cn=nt_domain,cn=admin', version =>3,
1298 password=>'password');
1299 $myObj = Win32::Perms->new();
1301 $Result = $myObj->Owner('nt_domain\user_name');
1302 $myObj->Group('nt_domain\Everyone');
1303 $myObj->Allow('nt_domain\user_name',
1304 $EXCH_USER_RIGHTS,OBJECT_INHERIT_ACE);
1305 $BinarySD = $myObj->GetSD(SD_RELATIVE);
1306 $TextSD = uc(unpack( "H*", $BinarySD ));
1307 Win32::Perms::ResolveSid('nt_domain\user_name', $sid);
1308 $mysid = uc(unpack("H*",$sid));
1309 $result = $exch->add ( dn =>
1311 'cn=user_name,cn=container,ou=site,o=organisation',
1312 attr => [ 'objectClass' => ['organizationalPerson'],
1313 'cn' => 'directory_name',
1314 'uid' => 'mail_nickname',
1315 'mail' => 'smtp_address',
1316 'assoc-nt-account' => [ $mysid ],
1317 'nt-security-descriptor' => [ $TextSD ],
1318 'mailPreferenceOption' => 0
1319 ]
1320 );
1321 print ldap_error_name($result->code);
1324 How do I reset a user's password ...
1326 ... in most LDAP servers?
1327 Most LDAP servers use the standard userPassword attribute as the
1329 attribute to set when you want to change a user's password.
1330 They usually allow to set the password either using the regular modify
1332 operation on the userPassword attribute or using the extended LDAP
1333 Password Modify operation defined in RFC3062.
1334 The recommended method is the extended Password Modify operation, which
1336 offers a standardized way to set user passwords but unfortunately is
1337 not available on all LDAP servers.
1338 Whether the extended Password Modify operation is available can be
1340 found out by searching the attribute supportedExtension for the value
1341 1.3.6.1.4.1.4203.1.11.1 in the RootDSE object.
1342 If the extended Password Modify operation is not available the
1344 alternative is the regular modification of the userPassword attribute.
1345 But this method has some drawbacks:
1347 · Depending on the type of the server the arguments to the modify
1349 operations may vary. Some want the modify done with replace, some
1350 want it done by explicitly deleting the old password and add of the
1351 new one. This may even depend on whether you change the password
1352 for the bound user or as an administrator for another user.
1353 · With the modify operation some servers expect the client to do the
1355 hashing of the password on the client side. I.e. all clients that
1356 set passwords need to agree on the algorithm and the format of the
1357 hashed password.
1358 · Some LDAP servers do not allow setting the password if the
1360 connection is not sufficiently secured. I.e. require SSL or TLS
1361 support to set the password (which is heavily recommended anyway
1362 ;-)
1363 Here is an example of how to change your own password (for brevity's
1365 sake error checking is left out):
1366 use Net::LDAP;
1368 my $ldap = Net::LDAP->new('ldaps://server.domain') or die "$@";
1370 my $mesg = $ldap->bind('cn=Joe User,dc=perl,dc=ldap,dc=org',
1371 password => 'oldPW');
1372 my $rootdse = $ldap->root_dse();
1374 if ($rootdse->supported_extension('1.3.6.1.4.1.4203.1.11.1') {
1376 require Net::LDAP::Extension::SetPassword;
1378 $mesg = $ldap->set_password(user => 'cn=Joe User,dc=perl,dc=ldap,dc=org',
1380 oldpasswd => 'oldPW',
1381 newpasswd => 'newPW');
1382 }
1383 else {
1384 $mesg = $ldap->modify('cn=Joe User,dc=perl,dc=ldap,dc=org',
1385 changes => [
1386 delete => [ userPassword => $oldPW ]
1387 add => [ userPassword => $newPW ] ]);
1388 }
1389 $ldap->unbind();
1391 ... in MS Active Directory?
1393 With Active Directory a user's password is stored in the unicodePwd
1395 attribute and changed using the regular modify operation.
1396 ADS expects this password to be encoded in Unicode - UTF-16 to be
1398 exact. Before the Unicode conversion is done the password needs to be
1399 surrounded by double quotes which do not belong to the user's password.
1400 For the password modify operation to succeed SSL is required.
1402 When changing the password for the user bound to the directory ADS
1404 expects it to be done by deleting the old password and adding the new
1405 one. When doing it as a user with administrative privileges replacing
1406 the unicodePwd's value with a new one is allowed too.
1407 Perl-ldap contains convenience methods for Active Directory that allow
1409 one to perform this task very easily.
1410 Here's an example that demonstrates setting your own password from
1412 $oldPW to $newPW (again almost no error checking):
1413 use Net::LDAP;
1415 use Net::LDAP::Extra qw(AD);
1416 my $ldap = Net::LDAP->new('ldaps://ads.domain.controller') or die "$@";
1418 my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1420 password => $oldPW);
1421 $mesg = $ldap->change_ADpassword('cn=Joe User,dc=your,dc=ads,dc=domain',
1423 $oldPW, $newPW);
1424 $ldap->unbind();
1426 And the same for perl-ldap versions before 0.49, where everything needs
1428 to be done by hand:
1429 use Net::LDAP;
1431 use Unicode::Map8;
1432 use Unicode::String qw(utf16);
1433 # build the conversion map from your local character set to Unicode
1435 my $charmap = Unicode::Map8->new('latin1') or die;
1436 # surround the PW with double quotes and convert it to UTF-16
1438 # byteswap() was necessary in experiments on i386 Linux, YMMV
1439 my $oldUniPW = $charmap->tou('"'.$oldPW.'"')->byteswap()->utf16();
1440 my $newUniPW = $charmap->tou('"'.$newPW.'"')->byteswap()->utf16();
1441 my $ldap = Net::LDAP->new('ldaps://ads.domain.controller') or die "$@";
1443 my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1445 password => $oldPW);
1446 $mesg = $ldap->modify('cn=Joe User,dc=your,dc=ads,dc=domain',
1448 changes => [
1449 delete => [ unicodePwd => $oldUniPW ]
1450 add => [ unicodePwd => $newUniPW ] ]);
1451 $ldap->unbind();
1453 How can I simulate server failover?
1455 Perl-ldap does not do server failover, however there are several
1456 programming options for getting around this situation.
1457 Here is one possible solution:
1459 $ldaps = Net::LDAPS->new([ $ldapserverone, $ldapservertwo ],
1461 port=>636, timeout=>5) or die "$@";
1462 For perl-ldap versions before 0.27, the same goal can be achieved
1464 using:
1465 unless ( $ldaps =
1467 Net::LDAPS->new($ldapserverone,
1468 port=>636,timeout=>5) )
1469 {
1470 $ldaps = Net::LDAPS->new($ldapservertwo,
1471 port=>636,timeout=>20) ||
1472 return
1473 "Can't connect to $ldapserverone or $ldapservertwo via LDAPS: $@";
1474 }
1475
1477 How do I store X.509 certificates in the directory?
1478 The first problem here is that there are many different formats to hold
1479 certificates in, for example PEM, DER, PKCS#7 and PKCS#12. The
1480 directory only uses the DER format (more correctly, it only uses the
1481 BER format) which is a binary format.
1482 Your first job is to ensure that your certificates are therefore in
1484 DER/BER format. You could use OpenSSL to convert from PEM like this:
1485 openssl x509 -inform PEM -in cert.pem -outform DER -out cert.der
1487 Consult the OpenSSL documentation to find out how to perform other
1489 conversions.
1490 To add a certificate to the directory, just slurp in the DER/BER
1492 certificate into a scalar variable, and add it to the entry's
1493 userCertificate attribute. How you do that will depend on which version
1494 of LDAP you are using.
1495 To slurp in the certificate try something like this:
1497 my $cert;
1499 {
1500 local $/ = undef; # Slurp mode
1501 open CERT, "cert.der" or die;
1502 binmode CERT; # for Windows e.a.
1503 $cert = <CERT>;
1504 close CERT;
1505 }
1506 # The certificate is now in $cert
1507 For LDAPv2, because most directory vendors ignore the string
1509 representation of certificates defined in RFC 1778, you should add this
1510 value to the directory like this:
1511 $res = $ldap->modify("cn=My User, o=My Company,c=XY",
1513 add => [
1514 'userCertificate' => [ $cert ]
1515 ]);
1516 die "Modify failed (" . ldap_error_name($res->code) . ")\n"
1517 if $res->code;
1518 For LDAPv3, you must do this instead:
1520 $res = $ldap->modify("cn=My User, o=My Company, c=XY",
1522 add => [
1523 'userCertificate;binary' => [ $cert ]
1524 ]);
1525 die "Modify failed (" . ldap_error_name($res->code) . ")\n"
1526 if $res->code;
1527 Of course, the entry you are trying to add the certificate to must use
1529 object classes that permit the userCertificate attribute, otherwise the
1530 modify will fail with an object class violation error. The
1531 inetOrgPerson structural object class permits userCertificates, as does
1532 the strongAuthenticationUser auxiliary object class. Others might also.
1533 How do I search objects by the contents of certificates.
1535 The directory needs to support one or more of the certificate*Match
1536 matching rules.
1537 Then using the filter (for certificateExactMatch)
1539 (userCertificate={ serialNumber 1234, issuer "cn=CA,o=TrustCenter" })
1541 allows searching for the objects containing the attribute
1543 userCertificate with a certificate matching these criteria.
1544 Please note that the exact syntax of the values for the serialNumber
1546 and the issuer above may depend on the LDAP server. In any case the
1547 example above works with OpenLDAP 2.4.33.
1548
1550 URLs.
1551 Net::LDAP::Server - LDAP server framework in Perl
1552 http://search.cpan.org/search?module=Net::LDAP::Server
1553 https://github.com/alexrj/Net-LDAP-Server
1554 Net::LDAP::SimpleServer - LDAP server in Perl
1556 http://search.cpan.org/search?module=Net::LDAP::SimpleServer
1557 https://github.com/russoz/Net-LDAP-SimpleServer
1558 LemonLDAP::NG - Web SingleSignOn solution & SAML IdP in Perl
1560 http://lemonldap-ng.org/
1561 Dancer::Plugin::LDAP - LDAP plugin for Dancer micro framework
1563 http://search.cpan.org/search?module=Dancer::Plugin::LDAP
1564 https://github.com/racke/Dancer-Plugin-LDAP
1565 Directory Services Mark Language (DSML)
1567 http://www.oasis-open.org/specs/
1568 eMailman LDAP information http://www.emailman.com/ldap/
1570 Rafael Corvalan's LDAP shell http://sf.net/projects/ldapsh
1572 Jeff Hodges's Kings Mountain LDAP
1574 http://www.kingsmountain.com/ldapRoadmap.shtml (outdated: last update
1575 was in 2004)
1576 willeke.com's LDAP Wiki http://ldapwiki.willeke.com/wiki/LDAP
1578 OpenLDAP Directory Server - open source LDAP server.
1580 http://www.openldap.org/
1581 389 Directory Server - open source LDAP server http://port389.org/
1583 ApacheDS - open source LDAP server in Java http://directory.apache.org/
1585 CriticalPath http://www.cp.net/
1587 ForgeRock's OpenDS - LDAPv3 server with additional REST APIs
1589 http://www.forgerock.com/opendj.html
1590 IBM Tivoli Directory Server
1592 http://www-01.ibm.com/software/tivoli/products/directory-server/
1593 Isode (was MessagingDirect) http://www.isode.com/
1595 Nexor's X.500 and Internet Directories
1597 http://www.nexor.com/info/directory.htm/
1598 Novell's eDirectory http://www.novell.com/
1600 Octet String http://www.octetstring.com/
1602 SUN JAVA JNDI (Java Naming and Directory Interface)
1604 http://java.sun.com/products/jndi/overview.html
1605 Oracle Directory Server Enterprise Edition, formerly Sun One, formerly
1607 iPlanet.
1608 http://www.oracle.com/technetwork/middleware/id-mgmt/index-085178.html
1609 OptimalIDM - Virtual Identity Server - .NET LDAP virtual directory
1611 http://www.optimalidm.com/products/vis/Virtual-Directory-Server-VDS.aspx
1612 Quest One Quick Connect Virtual Directory Server - LDAP virtual
1614 directory
1615 http://www.quest.com/quest-one-quick-connect-virtual-directory-server/
1616 UnboundID's Identity data platform https://www.unboundid.com/
1618 Virtual Directory Blogger https://virtualdirectory.wordpress.com/
1620 eldapo - a directory manager's blog http://eldapo.blogspot.de/
1622 Eine deutsche LDAP Website A German LDAP Website
1624 http://verzeichnisdienst.de/ldap/Perl/index.html
1625 (non-exhaustive) list of LDAP software on Wikipedia
1627 http://en.wikipedia.org/wiki/List_of_LDAP_software
1628 "RFC Sourcebook" on LDAP
1630 http://www.networksorcery.com/enp/protocol/ldap.htm
1631 web2ldap - WWW gateway to LDAP server in Python http://www.web2ldap.de/
1633 Softerra LDAP Browser / Administrator http://www.ldapbrowser.com/
1635 The 2 following URLs deal mainly with Microsoft's Active Directory.
1637 Directory Works http://directoryworks.com/
1639 LDAP Client .Net & ActiveX LDAP Client
1641 http://www.ldapservices.com/Products/Default.aspx
1642 BOOKS
1644 Developing LDAP and ADSI Clients for Microsoft(R) Exchange. By Sven B.
1645 Schreiber. ISBN: 0201657775
1646 Implementing LDAP. By Mark Wilcox. ISBN: 1861002211
1648 LDAP: Programming Directory-Enabled Applications With Lightweight
1650 Directory Access Protocol. By Tim Howes, Mark Smith. ISBN:
1651 1578700000
1652 LDAP Programming; Directory Management and Integration. By Clayton
1654 Donley. ISBN: 1884777910
1655 LDAP Programming with Java. By Rob Weltman, Tony Dahbura. ISBN:
1657 0201657589
1658 LDAP System Administration. By Gerald Carter. ISBN: 1565924916
1660 Managing Enterprise Active Directory Services. By Robbie Allen,
1662 Richard Puckett. ISBN: 0672321254
1663 Solaris and LDAP Naming Services. By Tom Bialaski, Michael Haines.
1665 ISBN: 0-13-030678-9
1666 Understanding and Deploying LDAP Directory Services (2ed). By Tim
1668 Howes, Mark Smith, Gordon Good. ISBN: 0672323168
1669 LDAP Directories Explained. By Brian Arkills. ISBN 0-201-78792-X
1671
1673 Any good FAQ is made up of many authors, everyone that contributes
1674 information to the perl-ldap mail list is a potential author.
1675 An attempt to maintain this FAQ is being done by Chris Ridd
1677 <chris.ridd@isode.com> and Peter Marschall <peter@adpm.de>. It was
1678 previously updated by Clif Harden <charden@pobox.com>.
1679 The original author of this FAQ was Graham Barr <gbarr@pobox.com>
1681 Please report any bugs, or post any suggestions, to the perl-ldap
1683 mailing list <perl-ldap@perl.org>.
1684
1686 Copyright (c) 1999-2004 Graham Barr, (c) 2012 Peter Marschall. All
1687 rights reserved. This document is distributed, and may be
1688 redistributed, under the same terms as Perl itself.
1689perl v5.30.0 2019-07-26 Net::LDAP::FAQ(3)