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.44 with the version you have
369 gunzip perl-ldap-0.44.tar.gz
371 tar xvf perl-ldap-0.44.tar
372 cd perl-ldap-0.44
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.8.3
390 /usr/local/share/perl/5.8.3
391 /usr/lib/perl5
392 /usr/share/perl5
393 /usr/lib/perl/5.8.3
394 /usr/share/perl/5.8.3
395 /usr/local/lib/site_perl
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.44 with the version you have
404 gunzip perl-ldap-0.44.tar.gz
406 tar xvf perl-ldap-0.44.tar
407 cd perl-ldap-0.44/lib
408 cp * /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 Authen::SASL
471 This module is optional. You only need to install Authen::SASL if
472 you want to use the SASL authentication methods.
473 You can obtain the latest release from
475 http://search.cpan.org/search?module=Authen::SASL
476 Digest::MD5
478 This module is optional. It also requires a C compiler when
479 installing. You only need to install Digest::MD5 if you want to
480 use the SASL DIGEST-MD5 authentication mechanism.
481 You can obtain the latest release from
483 http://search.cpan.org/search?module=Digest::MD5
484 As Digest::MD5 is part of the Perl core modules since Perl 5.7.3,
486 you only need a C compiler if you want to install a version that is
487 newer than the version distributed with your Perl installation.
488 Digest::HMAC_MD5
490 This optional module is required only if you want to use the SASL
491 CRAM-MD5 authentication mechanism.
492 You can obtain the latest release from
494 http://search.cpan.org/search?module=Digest::HMAC_MD5
495 GSSAPI
497 This optional module is required only if you want to use the SASL
498 GSSAPI authentication mechanism (e.g. for Kerberos authentication).
499 You can obtain the latest release from
501 http://search.cpan.org/search?module=GSSAPI
502 URI::ldap, URI::ldaps, and URI::ldapi
504 These modules are optional. You only need to install them if you
505 want to parse ldap://, ldaps:// or ldapi:// URIs using
506 ldap_parse_uri in Net::LDAP::Util. or use LWP::Protocol::ldap,
507 LWP::Protocol::ldaps, or LWP::Protocol::ldapi.
508 You can obtain the latest releases from
510 http://search.cpan.org/search?module=URI::ldap
511 http://search.cpan.org/search?module=URI::ldaps
512 http://search.cpan.org/search?module=URI::ldapi
513 LWP::Protocol, LWP::MediaTypes, HTTP::Negotiate, and HTTP::Response
515 These optional modules are needed if you want to use perl-ldap's
516 LWP::Protocol::ldap, LWP::Protocol::ldaps, or LWP::Protocol::ldapi
517 modules.
518 You can obtain the latest releases from
520 http://search.cpan.org/search?module=LWP::Protocol
521 http://search.cpan.org/search?module=LWP::MediaTypes
522 http://search.cpan.org/search?module=HTTP::Negotiate
523 http://search.cpan.org/search?module=HTTP::Response
524 JSON
526 This optional module is required for JSON-formatted output of perl-
527 ldap's LWP::Protocol::ldap, LWP::Protocol::ldaps, or
528 LWP::Protocol::ldapi modules.
529 If you need it, you can obtain the latest releases from
531 http://search.cpan.org/search?module=JSON
532 Time::Local
534 This module is optional, and only required if you want to convert
535 between UNIX time and generalizedTime using the functions provided
536 in Net::LDAP::Util.
537 XML::SAX and XML::SAX::Writer
539 If you want to parse or write DSMLv1 documents with Net::LDAP::DSML
540 to you will need these optional modules.
541 You can obtain the latest releases from
543 http://search.cpan.org/search?module=XML::SAX
544 http://search.cpan.org/search?module=XML::SAX::Writer
545 ResourcePool::Factory::Net::LDAP
547 If you want to use failover the ResourcePool::Factory::Net::LDAP
548 Perl module provides methods to do this.
549 You can obtain the latest release from
551 http://search.cpan.org/search?module=ResourcePool::Factory::Net::LDAP
552
554 How do I connect to my server?
555 The connection to the server is created when you create a new Net::LDAP
556 object, e.g.
557 $ldap = Net::LDAP->new($server);
559 Net::LDAP->new sometimes returns undef, why?
561 The constructor will return undef if there was a problem connecting to
562 the specified server. Any error message will be available in $@
563 What is the proper format of the bind DN?
565 The DN used to bind to a directory is a FULLY QUALIFIED DN. The exact
566 structure of the DN will depend on what data has been stored in the
567 server.
568 The following are valid examples.
570 uid=clif,ou=People,dc=umich,dc=edu
572 cn=directory manager,ou=admins,dc=umich,dc=edu
574 In some servers the following would be a valid fully qualified DN of
576 the directory manager.
577 cn=directory manager
579 How can I tell when the server returns an error, bind() always returns
581 true?
582 Most methods in Net::LDAP return a Net::LDAP::Message object, or a sub-
583 class of that. This object will hold the results from the server,
584 including the result code.
585 So, for example, to determine the result of the bind operation.
587 $mesg = $ldap->bind( $dn, password => $passwd );
589 if ( $mesg->code ) {
591 # Handle error codes here
592 }
593 How can I set the LDAP version of a connection to my ldap server?
595 This is done by adding the version option when connecting or binding to
596 the LDAP server.
597 For example;
599 $ldap = Net::LDAP->new( $server, version => 3 );
601 or
603 $mesg = $ldap->bind( $dn, password => $passwd, version => 3 );
605 Valid version numbers are 2 and 3. As of perl-ldap 0.27 the default
607 LDAP version is 3.
608 I did a search on my directory using the 'search' method. Where did the
610 results go?
611 Your search results are stored in a 'search object'. Consider the
612 following:
613 use Net::LDAP;
615 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
617 $mesg = $ldap->search(
618 base => "o=acme.com",
619 filter => "uid=jsmith",
620 );
621 $mesg is a search object. It is a reference blessed into the
623 Net::LDAP::Search package. By calling methods on this object you can
624 obtain information about the result and also the individual entries.
625 The first thing to check is if the search was successful. This is done
627 with with the method $mesg->code. This method will return the status
628 code that the server returned. A success will yield a zero value, but
629 there are other values, some of which could also be considered a
630 success. See Net::LDAP::Constant
631 use Net::LDAP::Util qw(ldap_error_text);
633 die ldap_error_text($mesg->code)
635 if $mesg->code;
636 There are two ways in which you can access the entries. You can access
638 then with an index or you can treat the container like a stack and
639 shift each entry in turn. For example
640 # as an array
642 # How many entries were returned from the search
644 my $max = $mesg->count;
645 for (my $index = 0 ; $index < $max ; $index++) {
647 my $entry = $mesg->entry($index);
648 # ...
649 }
650 # or as a stack
652 while (my $entry = $mesg->shift_entry) {
654 # ...
655 }
656 In each case $entry is an entry object. It is a reference blessed into
658 the Net::LDAP::Entry package. By calling methods on this object you can
659 obtain information about the entry.
660 For example, to obtain the DN for the entry
662 $dn = $entry->dn;
664 To obtain the attributes that a given entry has
666 @attrs = $entry->attributes;
668 And to get the list of values for a given attribute
670 @values = $entry->get( 'sn' );
672 And to get the first of the values for a given attribute
674 $values = $entry->get( 'cn' );
676 One thing to remember is that attribute names are case insensitive, so
678 'sn', 'Sn', 'sN' and 'SN' are all the same.
679 So, if you want to print all the values for the attribute 'ou' then
681 this is as simple as
682 foreach ($entry->get_value( 'ou' )) {
684 print $_,"\n";
685 }
686 Now if you just want to print all the values for all the attributes you
688 can do
689 foreach my $attr ($entry->attributes) {
691 foreach my $value ($entry->get_value($attr)) {
692 print $attr, ": ", $value, "\n";
693 }
694 }
695 How do I limit the scope of a directory search?
697 You limit the scope of a directory search by setting the scope
698 parameter of search request. Consider the following:
699 use Net::LDAP;
701 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
703 $mesg = $ldap->search(
704 base => "o=acme.com",
705 scope => 'sub',
706 filter => "uid=jsmith",
707 );
708 Values for the scope parameter are as follows.
710 base
712 Search only the base object.
713 one Search the entries immediately below the base object.
715 sub
717 subtree
718 Search the whole tree below (and including) the base object. This
719 is the default.
720 children
722 Search the whole subtree below the base object, excluding the base
723 object itself.
724 Note: children scope requires LDAPv3 subordinate feature extension.
726
728 There are two ways of retrieving the results of a requested LDAP
729 search; inline and by using a callback subroutine.
730 USING THE INLINE APPROACH
732 Using the inline approach involves requesting the data and then waiting
733 for all of the data to be returned before the user starts processing
734 the data.
735 Example:
737 use Net::LDAP;
739 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
741 $mesg = $ldap->search(
742 base => "o=acme.com",
743 scope => 'sub',
744 filter => "sn=smith",
745 );
746 #
747 # At this point the user can get the returned data as an array
748 # or as a stack.
749 # In this example we will use an array
750 # How many entries were returned from the search
752 my $max = $mesg->count;
753 for (my $index = 0 ; $index < $max ; $index++)
755 {
756 my $entry = $mesg->entry($index);
757 my $dn = $entry->dn; # Obtain DN of this entry
758 @attrs = $entry->attributes; # Obtain attributes for this entry.
760 foreach my $var (@attrs)
761 {
762 #get a list of values for a given attribute
763 $attr = $entry->get_value( $var, asref => 1 );
764 if ( defined($attr) )
765 {
766 foreach my $value ( @$attr )
767 {
768 print "$var: $value\n"; # Print each value for the attribute.
769 }
770 }
771 }
772 }
773 As you can see the example is straightforward, but there is one
775 drawback to this approach. You must wait until all entries for the
776 request search to be returned before you can process the data. If
777 there several thousand entries that match the search filter this could
778 take quite a long time period.
779 USING THE CALLBACK SUBROUTINE APPROACH
781 Using the callback approach involves requesting the data be sent to a
782 callback subroutine as each entry arrives at the client.
783 A callback is just a subroutine that is passed two parameters when it
785 is called, the mesg and entry objects.
786 Example:
788 use Net::LDAP;
790 $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
792 $mesg = $ldap->search(
793 base => "o=acme.com",
794 scope => 'sub',
795 filter => "sn=smith",
796 callback => \&callback,
797 );
798 #
799 # At this point the user needs to check the status of the
800 # ldap search.
801 #
802 if ( $mesg->code )
804 {
805 $errstr = $mesg->code;
806 print "Error code: $errstr\n";
807 $errstr = ldap_error_text($errstr);
808 print "$errstr\n";
809 }
810 sub callback
813 {
814 my ( $mesg, $entry) = @_;
815 #
817 # First you must check to see if something was returned.
818 # Last execution of callback subroutine will have no
819 # defined entry and mesg object
820 #
821 if ( !defined($entry) )
822 {
823 print "No records found matching filter $match.\n"
824 if ($mesg->count == 0) ; # if mesg is not defined nothing will print.
825 return;
826 }
827 my $dn = $entry->dn; # Obtain DN of this entry
829 @attrs = $entry->attributes; # Obtain attributes for this entry.
831 foreach my $var (@attrs)
832 {
833 #get a list of values for a given attribute
834 $attr = $entry->get_value( $var, asref => 1 );
835 if ( defined($attr) )
836 {
837 foreach my $value ( @$attr )
838 {
839 print "$var: $value\n"; # Print each value for the attribute.
840 }
841 }
842 }
843 #
844 # For large search requests the following line of code
845 # may be very important, it will reduce the amount of memory
846 # used by the search results.
847 #
848 # If the user is not worried about memory usage then the line
849 # of code can be omitted.
850 #
851 $mesg->pop_entry;
852 } # End of callback subroutine
854 As you can see the example is straightforward and it does not waste
856 time waiting for all of the entries to be returned. However if the
857 pop_entry method is not used the callback approach can allocate a lot
858 of memory to the search request.
859
861 Using an SSL network connection, how do I connect to my server?
862 This class is a subclass of Net::LDAP so all the normal Net::LDAP
863 methods can be used with a Net::LDAPS object; see the documentation for
864 Net::LDAP to find out how to query a directory server using the LDAP
865 protocol.
866 The connection to the server is created when you create a new
868 Net::LDAPS object, e.g.
869 $ldaps = Net::LDAPS->new($server,
871 port => '10000',
872 verify => 'require',
873 capath => '/usr/local/cacerts/',
874 );
875 Starting with version 0.28 perl-ldap also supports URIs in the new
877 method. So, the above can also be expressed as:
878 $ldaps = Net::LDAP->new("ldaps://$server",
880 port => '10000',
881 verify => 'require',
882 capath => '/usr/local/cacerts/',
883 );
884 There are additional options to the new method with LDAPS URIs and the
886 LDAPS new method and several additional methods are included in the
887 LDAPS object class.
888 For further information and code examples read the LDAPS module
890 documentation; perldoc Net::LDAPS
891
893 What are LDAP groups?
894 LDAP groups are object classes that contain an attribute that can store
895 multiple DN values. Two standard object classes are 'groupOfNames'
896 (which has a 'member' attribute) and 'groupOfUniqueNames' (which has a
897 'uniqueMember' attribute.)
898 According to the RFCs a group can be a member of another group, but
900 some LDAP server vendors restrict this flexibility by not allowing
901 nested groups in their servers.
902 Two scripts for working with groups are available in the contrib
904 directory. They are isMember.pl and printMembers.pl.
905 How do you format a filter to search for entries whose 'member' attribute
907 has a particular value?
908 Asking for (member=*) is OK - the directory uses the equality matching
909 rule which is defined for the member attribute.
910 Asking for (member=c*) is not OK - there is no defined substring
912 matching rule for the member attribute. That's because the member
913 values are *not* strings, but distinguished names. There is no
914 substring matching rule for DNs, see RFC 4519 section 2.7.
915 What you have to do is get the results of (member=*) and then select
917 the required results from the returned values. You need to do this
918 using knowledge of the string representation of DNs defined in RFC
919 4514, which is important because the same DN can have different string
920 representations. So you need to perform some canonicalization if you
921 want to be correct.
922
924 How can I access DSML features from perl-ldap?
925 Directory Service Markup Language (DSML) is the XML standard for
926 representing directory service information in XML.
927 Support for DSML is included in perl-ldap starting with version .20.
929 At the moment this module only reads and writes DSML entry entities. It
931 cannot process any schema entities because schema entities are
932 processed differently than elements.
933 Eventually this module will be a full level 2 consumer and producer
935 enabling you to give you full DSML conformance.
936 The specification for DSML is at http://www.oasis-open.org/specs/
938 For further information and code examples read the DSML module
940 documentation; perldoc Net::LDAP::DSML
941
943 How do I access the Control features?
944 Support for LDAP version 3 Control objects is included in perl-ldap
945 starting with version .20.
946 For further information and code examples read the Control module
948 documentation; perldoc Net::LDAP::Control
949 How do I access the Virtual List features?
951 Support for Virtual Lists is included in perl-ldap starting with
952 version .20.
953 For further information and code examples read the Control module
955 documentation; perldoc Net::LDAP::Control
956
958 Are there any other code examples.
959 Yes, there is an Examples pod file. To view the pod do the following
960 command; perldoc Net::LDAP::Examples
961 There is user contributed software in the contrib directory that is
963 supplied with the perl-ldap distribution. This is an excellent source
964 of information on how to use the perl-ldap module.
965 Are there any performance issues with perl-ldap?
967 In the vast majority of use cases (one user has suggested 9 out of 10)
968 there are no performance issues with perl-ldap.
969 Where you may wish to use perl-ldap to perform, for example, a very
971 large number of queries (e.g. 10,000) in succession you may find a
972 noticeable performance difference between perl-ldap and non pure-Perl
973 modules. This is not because of perl-ldap itself but because of the
974 pure-Perl Convert::ASN1 module that it depends on.
975 You should make up your own mind, based upon your own situation
977 (performance requirements, hardware etc.) as to whether you should use
978 perl-ldap or not. The figures quoted in this answer are only
979 indicative, and will differ for different people.
980 Can I contribute Perl scripts that use perl-ldap to the contrib section?
982 Any one can submit a Perl script that uses perl-ldap for inclusion in
983 the contrib section. The perl-ldap maintainers will determiner if the
984 script will be included and will do the initial check in of the script
985 to the Git repository at https://github.com/perl-ldap/perl-ldap.
986 There are a couple of requirements for consideration.
988 You must supply a one line description of your script to be included in
990 the contrib README file.
991 Inside the script will be the pod documentation for the script. No
993 auxiliary documentation will be allowed. For examples of how to do
994 this see the tklkup script currently in the contrib section.
995 Is it possible to get a complete entry, DN and attributes without
997 specifying the attributes name?
998 Yes, just specify you want a list of no attributes back. The RFC says
999 that this tells the server to return all readable attributes back
1000 (there may be access controls to prevent some from being returned.)
1001 So in the search method, just set (for LDAPv2):
1003 attrs => [ ]
1005 If you are using LDAPv3, you can specify an attribute called "*"
1007 instead, which lets you ask for additional (i.g. operational)
1008 attributes in the same search.
1009 attrs => [ "*" ]
1011 To get all operational attributes in a search, some servers allow the
1013 use of the "+" pseudo attribute. So that with these servers
1014 attrs => [ "*", "+" ]
1016 will return the most information from the server.
1018 How do I put a JPEG photo into a entry in the directory?
1020 Follow the following code example, replacing the (...) with whatever is
1021 relevant to your setup.
1022 use Net::LDAP;
1024 use Net::LDAP::Util qw(ldap_error_text);
1025 use CGI;
1026 local $/ = undef;
1028 my $jpeg = <$filename>;
1029 my $ldap = Net::LDAP->new(...);
1031 my $res = $ldap->bind(...);
1032 $res = $ldap->modify(...,
1033 add => [ 'jpegPhoto' => [ $jpeg ] ]);
1034 $res = $ldap->unbind();
1035 How do I add a jpeg photo into a entry in the directory via html-forms?
1037 Follow the following code example, replacing the (...) with whatever is
1038 relevant to your setup.
1039 use Net::LDAP;
1041 use Net::LDAP::Util qw(ldap_error_text);
1042 use CGI;
1043 my $q = new CGI;
1045 print $q->header;
1047 print $q->start_html(-title => 'Change JPEG photo');
1048 if ($q->param('Update')) {
1050 my $filename = $q->param('jpeg');
1051 local $/ = undef;
1052 my $jpeg = <$filename>;
1053 my $ldap = Net::LDAP->new(...);
1055 my $res = $ldap->bind(...);
1056 $res = $ldap->modify(...,
1057 add => [ 'jpegPhoto' => [ $jpeg ] ]);
1058 $res = $ldap->unbind();
1059 } else {
1060 print $q->start_multipart_form();
1061 print $q->filefield(-name => 'jpeg', -size => 50);
1062 print $q->submit('Update');
1063 print $q->end_form();
1064 }
1065 print $q->end_html();
1067 What happens when you delete an attribute that does not exist?
1069 It is an error to delete an attribute that doesn't exist. When you get
1070 the error back the server ignores the entire modify operation you sent
1071 it, so you need to make sure the error doesn't happen.
1072 Another approach, if you are using LDAPv3 (note beginning with version
1074 .27 Net::LDAP uses LDAPv3 by default) is to use a 'replace' with your
1075 attribute name and no values. In LDAPv3, this is defined to always
1076 work even if that attribute doesn't exist in the entry.
1077 i.e.:
1079 my $mesg = $ldap->modify( $entry, replace => { %qv_del_arry } );
1081 But make sure you are using LDAPv3, because that is defined to not work
1083 in LDAPv2. (A nice incompatibility between LDAPv2 and LDAPv3.)
1084 How can I delete a referral from an LDAP tree?
1086 Since this is a proprietary feature, you will have to check your
1087 server's documentation. You might find that you need to use a control.
1088 If there is a control called something like managedsait, that's the one
1089 you should probably use. For proper operation you will need the oid
1090 number for managedsait; 2.16.840.1.113730.3.4.2 and do not specify a
1091 value for type.
1092 The code required will look similar to the following code snippet.
1094 $mesg = $ldap->delete("ref=\"ldap://acme/c=us,o=bricks\",o=clay",
1096 control => {type => "2.16.840.1.113730.3.4.2"} );
1097 How do I add an ACI/ACL entry to a directory server with perl-ldap?
1099 ACIs and ACLs are proprietary features in LDAP. The following code
1100 snippet works with a Netscape directory server. You will need the
1101 specify the correct DN (-DN-) and correct attribute(s) (-nom attr-).
1102 my $aci = '(target="ldap:///-DN-")(targetattr="-nom attr-")(version 3.0;
1104 acl "-nom acl-"; deny(all) userdn = "ldap:///self";)' ;
1105 $ldap->modify($dn_modif, add => {'aci' => $aci });
1107 How do I avoid file type and data type mis-matching when loading data from
1109 a Win32 system?
1110 When loading a binary attribute with data read from a file on a Win32
1111 system, it has been noted that you should set "binmode" on the file
1112 before reading the file contents into the data array.
1113 Another possible solution to this problem is to convert the binary data
1115 into a base64 encoded string and then store the encoded string in the
1116 file. Then when reading the file, decode the base64 encoded string
1117 back to binary and then use perl-ldap to store the data in the
1118 directory.
1119 How do I create an account in Active Directory?
1121 Active Directory accounts need some AD-specific attributes (only the
1122 method we're interested in, no error checking):
1123 $mesg = $ldap->add( 'cn=John Doe,cn=Users,dc=your,dc=ads,dc=domain',
1125 attrs => [
1126 objectClass => [ qw/top user/ ],
1127 cn => 'John Doe',
1128 sn => 'Doe',
1129 givenName => 'John',
1130 displayName => 'John "the one" Doe',
1131 userAccountControl => 514, # disabled regular user
1132 sAMAccountName => 'JohnDoe',
1133 userPrincipalName => 'JohnDoe@your.ads.domain'
1134 ]
1135 );
1136 In order to find out what other attributes can be set, interactively
1138 edit the user in the Active Directory Users and Computers MCC plugin,
1139 perform an LDAP search operation to find out what changed, and update
1140 your "add" routine accordingly.
1141 How can I create a group in Active Directory?
1143 Similar to accounts, groups need some AD-specific attributes too:
1144 $mesg = $ldap->add( 'cn=NewGroup,cn=Users,dc=your,dc=ads,dc=domain',
1146 attrs => [
1147 objectClass => [ qw/top group/ ],
1148 cn => 'NewGroup',
1149 sAMAccountName => 'NewGroup',
1150 groupType => 0x80000002 # global, security enabled group
1151 ]
1152 );
1153 How do I search for disabled accounts in Active Directory
1155 The bit values in "userAccountcontrol" require the
1156 LDAP_MATCHING_RULE_BIT_AND matching rule's OID to be used in an
1157 extensible filter term:
1158 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1160 filter => '(&(objectclass=user)' .
1161 (userAccountControl:1.2.840.113556.1.4.803:=2))',
1162 attrs => [ '1.1' ]
1163 );
1164 How can I search for security groups in Active Directory
1166 With groups, the same applies to the "groupType" bit-field:
1167 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1169 filter => '(&(objectclass=group)' .
1170 (groupType:1.2.840.113556.1.4.803:=2147483648))',
1171 # 2147483648 = 0x80000000
1172 attrs => [ '1.1' ]
1173 );
1174 How can I search for all members of a group in AD (including group
1176 nesting)?
1177 AD allows you to find all members of a specified group, the direct
1178 members plus those that are member of the group via group nesting.
1179 The trick to this is the special "LDAP_MATCHING_RULE_IN_CHAIN" matching
1181 rule:
1182 $mesg = $ldap->search( base => 'cn=Users,dc=your,dc=ads,dc=domain',
1184 filter => '(memberOf:1.2.840.113556.1.4.1941:=cn=Testgroup,dc=your,dc=ads,dc=domain)',
1185 attrs => [ '1.1' ]
1186 );
1187 How can I search for all groups one user is a member of in AD (including
1189 group nesting)?
1190 Similarly you can search for all the groups one user is member of,
1191 either directly or via group nesting.
1192 $mesg = $ldap->search( base => 'dc=your,dc=ads,dc=domain',
1194 filter => '(member:1.2.840.113556.1.4.1941:=cn=TestUser,ou=Users,dc=your,dc=ads,dc=domain)',
1195 attrs => [ '1.1' ]
1196 );
1197 How do I search for all members of a large group in AD?
1199 AD normally restricts the number of attribute values returned in one
1200 query. The exact number depends on the AD server version: it was ~1000
1201 in Win2000, 1500 in Win2003 and is 5000 in Win2008 & Win2008R2.
1202 Performing the same standard search again will yield the same values
1204 again.
1205 So, how can you get all members of a really large AD group?
1207 The trick to use here is to use Microsoft's range option when
1209 searching, i.e instead of doing one search for plain "member", perform
1210 multiple searches for e.g. "member;range=1000-*" where the range
1211 starting index increases accordingly:
1212 my $mesg;
1214 my @members;
1215 my $index = 0;
1216 while ($index ne '*') {
1218 $mesg = $ldap->search( base => 'cn=Testgroup,dc=your,dc=ads,dc=domain',
1219 filter => '(objectclass=group)',
1220 scope => 'base',
1221 attrs => ($index > 0) ? "member;range=$index-*" : 'member'
1222 );
1223 if ($mesg->code == LDAP_SUCCESS) {
1224 my $entry = $mesg->entry(0);
1225 my $attr;
1226 # large group: let's do the range option dance
1228 if (($attr) = grep(/^member;range=/, $entry->attributes)) {
1229 push(@members, $entry->get_value($attr));
1230 if ($attr =~ /^member;range=\d+-(.*)$/) {
1232 $index = $1;
1233 $index++ if ($index ne '*');
1234 }
1235 }
1236 # small group: no need for the range dance
1237 else {
1238 @members = $entry->get_value('member');
1239 last;
1240 }
1241 }
1242 # failure
1243 else {
1244 last;
1245 }
1246 }
1247 if ($mesg->code == LDAP_SUCCESS) {
1249 # success: @members contains the members of the group
1250 }
1251 else {
1252 # failure: deal with the error in $mesg
1253 }
1254 See
1256 <http://msdn.microsoft.com/en-us/library/windows/desktop/aa367017.aspx>
1257 for more details.
1258 How do I create a Microsoft Exchange 5.x user?
1260 This is a solution provided by a perl-ldap user.
1261 This code works with ActiveState Perl running on WinNT 4. Please note
1263 that this requires the Win32::Perms module, and needs valid NT account
1264 info to replace the placeholders.
1265 use Net::LDAP;
1267 use Net::LDAP::Util;
1268 use Win32::Perms;
1269 #Constants taken from ADSI Type Library
1271 $ADS_RIGHT_EXCH_ADD_CHILD = 1;
1272 $ADS_RIGHT_EXCH_DELETE = 0x10000;
1273 $ADS_RIGHT_EXCH_DS_REPLICATION = 64;
1274 $ADS_RIGHT_EXCH_DS_SEARCH = 256;
1275 $ADS_RIGHT_EXCH_MAIL_ADMIN_AS = 32;
1276 $ADS_RIGHT_EXCH_MAIL_RECEIVE_AS = 16;
1277 $ADS_RIGHT_EXCH_MAIL_SEND_AS = 8;
1278 $ADS_RIGHT_EXCH_MODIFY_ADMIN_ATT = 4;
1279 $ADS_RIGHT_EXCH_MODIFY_SEC_ATT = 128;
1280 $ADS_RIGHT_EXCH_MODIFY_USER_ATT = 2;
1281 $EXCH_USER_RIGHTS = $ADS_RIGHT_EXCH_MAIL_RECEIVE_AS |
1283 $ADS_RIGHT_EXCH_MAIL_SEND_AS |
1284 $ADS_RIGHT_EXCH_MODIFY_USER_ATT;
1285 $exch = Net::LDAP->new('server', debug =>0) || die $@;
1287 $exch->bind( 'cn=admin_user,cn=nt_domain,cn=admin', version =>3,
1289 password=>'password');
1290 $myObj = Win32::Perms->new();
1292 $Result = $myObj->Owner('nt_domain\user_name');
1293 $myObj->Group('nt_domain\Everyone');
1294 $myObj->Allow('nt_domain\user_name',
1295 $EXCH_USER_RIGHTS,OBJECT_INHERIT_ACE);
1296 $BinarySD = $myObj->GetSD(SD_RELATIVE);
1297 $TextSD = uc(unpack( "H*", $BinarySD ));
1298 Win32::Perms::ResolveSid('nt_domain\user_name', $sid);
1299 $mysid = uc(unpack("H*",$sid));
1300 $result = $exch->add ( dn =>
1302 'cn=user_name,cn=container,ou=site,o=organization',
1303 attr => [ 'objectClass' => ['organizationalPerson'],
1304 'cn' => 'directory_name',
1305 'uid' => 'mail_nickname',
1306 'mail' => 'smtp_address',
1307 'assoc-nt-account' => [ $mysid ],
1308 'nt-security-descriptor' => [ $TextSD ],
1309 'mailPreferenceOption' => 0
1310 ]
1311 );
1312 print ldap_error_name($result->code);
1315 How do I reset a user's password ...
1317 ... in most LDAP servers?
1318 Most LDAP servers use the standard userPassword attribute as the
1320 attribute to set when you want to change a user's password.
1321 They usually allow to set the password either using the regular modify
1323 operation on the userPassword attribute or using the extended LDAP
1324 Password Modify operation defined in RFC3062.
1325 The recommended method is the extended Password Modify operation, which
1327 offers a standardized way to set user passwords but unfortunately is
1328 not available on all LDAP servers.
1329 Whether the extended Password Modify operation is available can be
1331 found out by searching the attribute supportedExtension for the value
1332 1.3.6.1.4.1.4203.1.11.1 in the RootDSE object.
1333 If the extended Password Modify operation is not available the
1335 alternative is the regular modification of the userPassword attribute.
1336 But this method has some drawbacks:
1338 · Depending on the type of the server the arguments to the modify
1340 operations may vary. Some want the modify done with replace, some
1341 want it done by explicitly deleting the old password and add of the
1342 new one. This may even depend on whether you change the password
1343 for the bound user or as an administrator for another user.
1344 · With the modify operation some servers expect the client to do the
1346 hashing of the password on the client side. I.e. all clients that
1347 set passwords need to agree on the algorithm and the format of the
1348 hashed password.
1349 · Some LDAP servers do not allow setting the password if the
1351 connection is not sufficiently secured. I.e. require SSL or TLS
1352 support to set the password (which is heavily recommended anyway
1353 ;-)
1354 Here is an example of how to change your own password (for brevity's
1356 sake error checking is left out):
1357 use Net::LDAP;
1359 my $ldap = Net::LDAP->new('ldaps://server.domain') or die "$@";
1361 my $mesg = $ldap->bind('cn=Joe User,dc=perl,dc=ldap,dc=org',
1362 password => 'oldPW');
1363 my $rootdse = $ldap->root_dse();
1365 if ($rootdse->supported_extension('1.3.6.1.4.1.4203.1.11.1') {
1367 require Net::LDAP::Extension::SetPassword;
1369 $mesg = $ldap->set_password(user => 'cn=Joe User,dc=perl,dc=ldap,dc=org',
1371 oldpasswd => 'oldPW',
1372 newpasswd => 'newPW');
1373 }
1374 else {
1375 $mesg = $ldap->modify('cn=Joe User,dc=perl,dc=ldap,dc=org',
1376 changes => [
1377 delete => [ userPassword => $oldPW ]
1378 add => [ userPassword => $newPW ] ]);
1379 }
1380 $ldap->unbind();
1382 ... in MS Active Directory?
1384 With Active Directory a user's password is stored in the unicodePwd
1386 attribute and changed using the regular modify operation.
1387 ADS expects this password to be encoded in Unicode - UTF-16 to be
1389 exact. Before the unicode conversion is done the password needs to be
1390 surrounded by double quotes which do not belong to the user's password.
1391 For the password modify operation to succeed SSL is required.
1393 When changing the password for the user bound to the directory ADS
1395 expects it to be done by deleting the old password and adding the new
1396 one. When doing it as a user with administrative privileges replacing
1397 the unicodePwd's value with a new one is allowed too.
1398 Perl-ldap contains convenience methods for Active Directory that allow
1400 one to perform this task very easily.
1401 Here's an example that demonstrates setting your own password from
1403 $oldPW to $newPW (again almost no error checking):
1404 use Net::LDAP;
1406 use Net::LDAP::Extra qw(AD);
1407 my $ldap = Net::LDAP->new('ldaps://ads.domain.controller') or die "$@";
1409 my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1411 password => $oldPW);
1412 $mesg = $ldap->change_ADpassword('cn=Joe User,dc=your,dc=ads,dc=domain',
1414 $oldPW, $newPW);
1415 $ldap->unbind();
1417 And the same for perl-ldap versions before 0.49, where everything needs
1419 to be done by hand:
1420 use Net::LDAP;
1422 use Unicode::Map8;
1423 use Unicode::String qw(utf16);
1424 # build the conversion map from your local character set to Unicode
1426 my $charmap = Unicode::Map8->new('latin1') or die;
1427 # surround the PW with double quotes and convert it to UTF-16
1429 # byteswap() was necessary in experiments on i386 Linux, YMMV
1430 my $oldUniPW = $charmap->tou('"'.$oldPW.'"')->byteswap()->utf16();
1431 my $newUniPW = $charmap->tou('"'.$newPW.'"')->byteswap()->utf16();
1432 my $ldap = Net::LDAP->new('ldaps://ads.domain.controller') or die "$@";
1434 my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1436 password => $oldPW);
1437 $mesg = $ldap->modify('cn=Joe User,dc=your,dc=ads,dc=domain',
1439 changes => [
1440 delete => [ unicodePwd => $oldUniPW ]
1441 add => [ unicodePwd => $newUniPW ] ]);
1442 $ldap->unbind();
1444 How can I simulate server failover?
1446 Perl-ldap does not do server failover, however there are several
1447 programming options for getting around this situation.
1448 Here is one possible solution:
1450 $ldaps = Net::LDAPS->new([ $ldapserverone, $ldapservertwo ],
1452 port=>636, timeout=>5) or die "$@";
1453 For perl-ldap versions before 0.27, the same goal can be achieved
1455 using:
1456 unless ( $ldaps =
1458 Net::LDAPS->new($ldapserverone,
1459 port=>636,timeout=>5) )
1460 {
1461 $ldaps = Net::LDAPS->new($ldapservertwo,
1462 port=>636,timeout=>20) ||
1463 return
1464 "Can't connect to $ldapserverone or $ldapservertwo via LDAPS: $@";
1465 }
1466
1468 How do I store X.509 certificates in the directory?
1469 The first problem here is that there are many different formats to hold
1470 certificates in, for example PEM, DER, PKCS#7 and PKCS#12. The
1471 directory only uses the DER format (more correctly, it only uses the
1472 BER format) which is a binary format.
1473 Your first job is to ensure that your certificates are therefore in
1475 DER/BER format. You could use OpenSSL to convert from PEM like this:
1476 openssl x509 -inform PEM -in cert.pem -outform DER -out cert.der
1478 Consult the OpenSSL documentation to find out how to perform other
1480 conversions.
1481 To add a certificate to the directory, just slurp in the DER/BER
1483 certificate into a scalar variable, and add it to the entry's
1484 userCertificate attribute. How you do that will depend on which version
1485 of LDAP you are using.
1486 To slurp in the certificate try something like this:
1488 my $cert;
1490 {
1491 local $/ = undef; # Slurp mode
1492 open CERT, "cert.der" or die;
1493 binmode CERT; # for Windows e.a.
1494 $cert = <CERT>;
1495 close CERT;
1496 }
1497 # The certificate is now in $cert
1498 For LDAPv2, because most directory vendors ignore the string
1500 representation of certificates defined in RFC 1778, you should add this
1501 value to the directory like this:
1502 $res = $ldap->modify("cn=My User, o=My Company,c=XY",
1504 add => [
1505 'userCertificate' => [ $cert ]
1506 ]);
1507 die "Modify failed (" . ldap_error_name($res->code) . ")\n"
1508 if $res->code;
1509 For LDAPv3, you must do this instead:
1511 $res = $ldap->modify("cn=My User, o=My Company, c=XY",
1513 add => [
1514 'userCertificate;binary' => [ $cert ]
1515 ]);
1516 die "Modify failed (" . ldap_error_name($res->code) . ")\n"
1517 if $res->code;
1518 Of course, the entry you are trying to add the certificate to must use
1520 object classes that permit the userCertificate attribute, otherwise the
1521 modify will fail with an object class violation error. The
1522 inetOrgPerson structural object class permits userCertificates, as does
1523 the strongAuthenticationUser auxiliary object class. Others might also.
1524 How do I search objects by the contents of certificates.
1526 The directory needs to support one or more of the certificate*Match
1527 matching rules.
1528 Then using the filter (for certificateExactMatch)
1530 (userCertificate={ serialNumber 1234, issuer "cn=CA,o=TrustCenter" })
1532 allows searching for the objects containing the attribute
1534 userCertificate with a certificate matching these criteria.
1535 Please note that the exact syntax of the values for the serialNumber
1537 and the issuer above may depend on the LDAP server. In any case the
1538 example above works with OpenLDAP 2.4.33.
1539
1541 URLs.
1542 Net::LDAP::Server - LDAP server framework in Perl
1543 http://search.cpan.org/search?module=Net::LDAP::Server
1544 https://github.com/alexrj/Net-LDAP-Server
1545 Net::LDAP::SimpleServer - LDAP server in Perl
1547 http://search.cpan.org/search?module=Net::LDAP::SimpleServer
1548 https://github.com/russoz/Net-LDAP-SimpleServer
1549 LemonLDAP::NG - Web SingleSignOn solution & SAML IdP in Perl
1551 http://lemonldap-ng.org/
1552 Dancer::Plugin::LDAP - LDAP plugin for Dancer micro framework
1554 http://search.cpan.org/search?module=Dancer::Plugin::LDAP
1555 https://github.com/racke/Dancer-Plugin-LDAP
1556 Directory Services Mark Language (DSML)
1558 http://www.oasis-open.org/specs/
1559 eMailman LDAP information http://www.emailman.com/ldap/
1561 Rafael Corvalan's LDAP shell http://sf.net/projects/ldapsh
1563 Jeff Hodges's Kings Mountain LDAP
1565 http://www.kingsmountain.com/ldapRoadmap.shtml (outdated: last update
1566 was in 2004)
1567 willeke.com's LDAP Wiki http://ldapwiki.willeke.com/wiki/LDAP
1569 OpenLDAP Directory Server - open source LDAP server.
1571 http://www.openldap.org/
1572 389 Directory Server - open source LDAP server http://port389.org/
1574 ApacheDS - open source LDAP server in Java http://directory.apache.org/
1576 CriticalPath http://www.cp.net/
1578 ForgeRock's OpenDS - LDAPv3 server with additional REST APIs
1580 http://www.forgerock.com/opendj.html
1581 IBM Tivoli Directory Server
1583 http://www-01.ibm.com/software/tivoli/products/directory-server/
1584 Isode (was MessagingDirect) http://www.isode.com/
1586 Nexor's X.500 and Internet Directories
1588 http://www.nexor.com/info/directory.htm/
1589 Novell's eDirectory http://www.novell.com/
1591 Octet String http://www.octetstring.com/
1593 SUN JAVA JNDI (Java Naming and Directory Interface)
1595 http://java.sun.com/products/jndi/overview.html
1596 Oracle Directory Server Enterprise Edition, formerly Sun One, formerly
1598 iPlanet.
1599 http://www.oracle.com/technetwork/middleware/id-mgmt/index-085178.html
1600 OptimalIDM - Virtual Identity Server - .NET LDAP virtual directory
1602 http://www.optimalidm.com/products/vis/Virtual-Directory-Server-VDS.aspx
1603 Quest One Quick Connect Virtual Directory Server - LDAP virtual
1605 directory
1606 http://www.quest.com/quest-one-quick-connect-virtual-directory-server/
1607 UnboundID's Identity data platform https://www.unboundid.com/
1609 Virtual Directory Blogger https://virtualdirectory.wordpress.com/
1611 eldapo - a directory manager's blog http://eldapo.blogspot.de/
1613 Eine deutsche LDAP Website A german LDAP Website
1615 http://verzeichnisdienst.de/ldap/Perl/index.html
1616 (non-exhaustive) list of LDAP software on Wikipedia
1618 http://en.wikipedia.org/wiki/List_of_LDAP_software
1619 "RFC Sourcebook" on LDAP
1621 http://www.networksorcery.com/enp/protocol/ldap.htm
1622 web2ldap - WWW gateway to LDAP server in Python http://www.web2ldap.de/
1624 Softerra LDAP Browser / Administrator http://www.ldapbrowser.com/
1626 The 2 following URLs deal mainly with Microsoft's Active Directory.
1628 Directory Works http://directoryworks.com/
1630 LDAP Client .Net & ActiveX LDAP Client
1632 http://www.ldapservices.com/Products/Default.aspx
1633 BOOKS
1635 Developing LDAP and ADSI Clients for Microsoft(R) Exchange. By Sven B.
1636 Schreiber. ISBN: 0201657775
1637 Implementing LDAP. By Mark Wilcox. ISBN: 1861002211
1639 LDAP: Programming Directory-Enabled Applications With Lightweight
1641 Directory Access Protocol. By Tim Howes, Mark Smith. ISBN:
1642 1578700000
1643 LDAP Programming; Directory Management and Integration. By Clayton
1645 Donley. ISBN: 1884777910
1646 LDAP Programming with Java. By Rob Weltman, Tony Dahbura. ISBN:
1648 0201657589
1649 LDAP System Administration. By Gerald Carter. ISBN: 1565924916
1651 Managing Enterprise Active Directory Services. By Robbie Allen,
1653 Richard Puckett. ISBN: 0672321254
1654 Solaris and LDAP Naming Services. By Tom Bialaski, Michael Haines.
1656 ISBN: 0-13-030678-9
1657 Understanding and Deploying LDAP Directory Services (2ed). By Tim
1659 Howes, Mark Smith, Gordon Good. ISBN: 0672323168
1660 LDAP Directories Explained. By Brian Arkills. ISBN 0-201-78792-X
1662
1664 Any good FAQ is made up of many authors, everyone that contributes
1665 information to the perl-ldap mail list is a potential author.
1666 An attempt to maintain this FAQ is being done by Chris Ridd
1668 <chris.ridd@isode.com> and Peter Marschall <peter@adpm.de>. It was
1669 previously updated by Clif Harden <charden@pobox.com>.
1670 The original author of this FAQ was Graham Barr <gbarr@pobox.com>
1672 Please report any bugs, or post any suggestions, to the perl-ldap
1674 mailing list <perl-ldap@perl.org>.
1675
1677 Copyright (c) 1999-2004 Graham Barr, (c) 2012 Peter Marschall. All
1678 rights reserved. This document is distributed, and may be
1679 redistributed, under the same terms as Perl itself.
1680perl v5.16.3 2018-10-30 Net::LDAP::FAQ(3)