1Net::LDAP::FAQ(3)     User Contributed Perl Documentation    Net::LDAP::FAQ(3)
2
3
4

NAME

6       Net::LDAP::FAQ - Frequently Asked Questions about Net::LDAP
7

SYNOPSIS

9        perldoc Net::LDAP::FAQ
10

DESCRIPTION

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
15       The latest version of this FAQ can be found at
16
17        http://ldap.perl.org/FAQ.html
18

GENERAL

20   What is perl-ldap?
21       perl-ldap is the distribution name. The perl-ldap distribution contains
22       the Net::LDAP modules.
23
24   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
30   Where can I get it?
31       Perl-ldap is available from CPAN.  You can find the released versions
32       at:
33
34        http://search.cpan.org/dist/perl-ldap/
35
36   Is there a web page for perl-ldap?
37       Yes there is at http://ldap.perl.org/
38
39   Is there a mailing list?
40       Yes there is at perl-ldap@perl.org
41
42       You can subscribe to this list by mailing perl-ldap-subscribe@perl.org
43
44   Is the mailing list archived?
45       Yes, at http://nntp.perl.org/group/perl.ldap
46
47       Archives with messages before we switched to using perl.org can be
48       found at
49
50        http://marc.theaimsgroup.com/?l=perl-ldap-dev
51
52       There is also an archive of the perl-ldap mailing list at
53
54        http://www.xray.mpe.mpg.de/mailing-lists/perl-ldap/
55
56       which also has messages from before the move.
57
58   Is there any online documentation?
59       Yes. perl-ldap has online documentation at
60
61        http://ldap.perl.org/
62
63       which will have the latest documentation available.
64
65   Is there a public repository?
66       Yes, there is a public Git repository at
67
68        https://github.com/perl-ldap/perl-ldap
69
70   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
74       There are several ways this can be done - see below.
75
76       CPAN
77           You can download it from CPAN by following the "Download" link on:
78
79            http://search.cpan.org/dist/perl-ldap/
80
81           Example;
82
83            http://search.cpan.org/CPAN/authors/id/M/MA/MARSCHAP/perl-ldap-0.54.tar.gz
84
85       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
90            https://github.com/perl-ldap/perl-ldap
91
92           and simply click on the "Fork" button near the top-right corner.
93
94       Git - clone repository
95           You can download latest development version of perl-ldap from
96           GitHub by cloning the repository using the command:
97
98            git clone https://github.com/perl-ldap/perl-ldap.git
99
100           This command will create a directory named 'perl-ldap' in your
101           current directory containing a local clone of the repository.
102
103           Keeping your local repository in sync with perl-ldap's GitHub
104           repository is easy:
105
106             cd perl-ldap
107             git pull
108
109       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
116   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

LDAP AND DIRECTORY TERMINOLOGY.

123       In order to help the user understand the perl-ldap module better some
124       key LDAP terminology is defined here.
125
126   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
131   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
137       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
145   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
154   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
159       (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
162       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
166       Entries with subordinate entries are called 'non-leaf' entries.
167
168       Entries without subordinate entries are called 'leaf' entries.
169
170       An entry's direct superior entry is called the entry's 'parent'.
171
172       'Non-leaf' entries are also said to have 'child' entries.
173
174   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
179       For example:
180
181         cn=Road Runner
182
183       is an attribute with a type named "cn", and one value.
184
185       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
190       For example:
191
192         jpegPhoto=unknown
193
194       is not permitted by the directory, because jpegPhotos may only contain
195       JPEG-formatted images.
196
197       Most syntaxes used in LDAP however describe text strings rather than
198       binary objects (like JPEGs or certificates.)
199
200       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
206       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
210       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
217       You can examine all of a server's attribute definitions by reading the
218       schema from the server.
219
220   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
225       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
230       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
234       You can examine all of a server's objectclass definitions by reading
235       the schema from the server.
236
237   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
242       Examples of DNs:
243
244        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
249   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
256       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
260       Example of a DN:
261
262        cn=Road Runner,ou=bird,dc=cartoon,dc=com
263
264        RDNs of the proceeding DN:
265        RDN => cn=Road Runner
266        RDN => ou=bird
267        RDN => dc=cartoon
268        RDN => dc=com
269
270       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
274       Example of a DN with a multi-AVA RDN:
275
276        cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com
277
278   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
282       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
286       For example the entry:
287
288        cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com
289
290       must contain a 'cn' attribute containing at least the value "Road
291       Runner", and an 'l' attribute containing at least the value "Arizona".
292
293       The attributes used in the RDN may contain additional values, but the
294       entry still only has one DN.
295
296   What is a search base?
297       A search base is a Distinguished Name that is the starting point of
298       search queries.
299
300       Example of a DN:
301
302        cn=Road Runner,ou=bird,dc=cartoon,dc=com
303
304       Possible search base(s) for the proceeding DN:
305
306        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
311       Setting the search base to the lowest possible branch of the directory
312       will speed up searches considerably.
313
314   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
321       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
325       LDAP provides an open-standard to a directory service.
326
327       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
331       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
337       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
347       More information on this topic can be found on the following URLs;
348
349        http://www.openldap.org/faq/data/cache/378.html
350
351        http://www.isode.com/whitepapers/ic-6055.html
352
353   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
357       A continuation reference is returned when part of the operation must be
358       resent to another server.
359
360       See RFC 4511 section 4.5.3 for more details.
361

perl-ldap INSTALLATION

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
368          # replace 0.62 with the version you have
369
370          gunzip perl-ldap-0.62.tar.gz
371          tar xvf perl-ldap-0.62.tar
372          cd perl-ldap-0.62
373
374          perl Makefile.PL
375          make
376          make test
377          make install
378
379   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
383         perl -V
384
385       This will output information about the version of Perl you have
386       installed. Near the bottom you will find something like
387
388         @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
397       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
403          # replace 0.62 with the version you have
404
405          gunzip perl-ldap-0.62.tar.gz
406          tar xvf perl-ldap-0.62.tar
407          cd perl-ldap-0.62/lib
408
409          cp -r * /usr/local/lib/site_perl
410
411   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
415       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
420       2.  If the user has nmake installed, the user can do a normal Perl
421           module install using nmake instead of make.
422
423       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
427            perl install-nomake
428
429           The install-nomake script can be used on any system that does not
430           have make installed.
431
432   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
436       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
440       Alternatively, you may use your favorite web search engine to find the
441       package that you need.
442
443       Convert::ASN1
444           This module converts between Perl data structures and ASN.1, and is
445           required for perl-ldap to work.
446
447           You can obtain the latest release from
448             http://search.cpan.org/search?module=Convert::ASN1
449
450       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
455           You can obtain the latest release of IO::Socket::SSL from
456             http://search.cpan.org/search?module=IO::Socket::SSL
457
458           You can obtain the latest release of OpenSSL from
459             http://www.openssl.org/
460
461       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
467           You can obtain the latest releases from
468             http://search.cpan.org/search?module=IO::Socket::INET6
469
470       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
476           You can obtain the latest releases from
477             http://search.cpan.org/search?module=IO::Socket::IP
478
479       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
483           You can obtain the latest release from
484             http://search.cpan.org/search?module=Authen::SASL
485
486       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
491           You can obtain the latest release from
492             http://search.cpan.org/search?module=Digest::MD5
493
494           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
498       Digest::HMAC_MD5
499           This optional module is required only if you want to use the SASL
500           CRAM-MD5 authentication mechanism.
501
502           You can obtain the latest release from
503             http://search.cpan.org/search?module=Digest::HMAC_MD5
504
505       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
509           You can obtain the latest release from
510             http://search.cpan.org/search?module=GSSAPI
511
512       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
518           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
523       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
528           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
534       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
539           If you need it, you can obtain the latest releases from
540            http://search.cpan.org/search?module=JSON
541
542       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
547       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
551           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
555       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
559           You can obtain the latest release from
560             http://search.cpan.org/search?module=ResourcePool::Factory::Net::LDAP
561

USING NET::LDAP

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
567         $ldap = Net::LDAP->new($server);
568
569   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
573   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
578       The following are valid examples.
579
580         uid=clif,ou=People,dc=umich,dc=edu
581
582         cn=directory manager,ou=admins,dc=umich,dc=edu
583
584       In some servers the following would be a valid fully qualified DN of
585       the directory manager.
586
587         cn=directory manager
588
589   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
595       So, for example, to determine the result of the bind operation.
596
597         $mesg = $ldap->bind( $dn, password => $passwd );
598
599         if ( $mesg->code ) {
600           # Handle error codes here
601         }
602
603   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
607       For example;
608
609         $ldap = Net::LDAP->new( $server, version => 3 );
610
611       or
612
613         $mesg = $ldap->bind( $dn, password => $passwd, version => 3 );
614
615       Valid version numbers are 2 and 3.  As of perl-ldap 0.27 the default
616       LDAP version is 3.
617
618   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
623        use Net::LDAP;
624
625        $ldap = Net::LDAP->new('ldap.acme.com') or die "$@";
626        $mesg = $ldap->search(
627                              base   => "o=acme.com",
628                              filter => "uid=jsmith",
629                             );
630
631       $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
635       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
641         use Net::LDAP::Util qw(ldap_error_text);
642
643         die ldap_error_text($mesg->code)
644           if $mesg->code;
645
646       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
650         # as an array
651
652         # How many entries were returned from the search
653         my $max = $mesg->count;
654
655         for (my $index = 0 ; $index < $max ; $index++) {
656           my $entry = $mesg->entry($index);
657           # ...
658         }
659
660         # or as a stack
661
662         while (my $entry = $mesg->shift_entry) {
663           # ...
664         }
665
666       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
670       For example, to obtain the DN for the entry
671
672         $dn = $entry->dn;
673
674       To obtain the attributes that a given entry has
675
676         @attrs = $entry->attributes;
677
678       And to get the list of values for a given attribute
679
680         @values = $entry->get( 'sn' );
681
682       And to get the first of the values for a given attribute
683
684         $values = $entry->get( 'cn' );
685
686       One thing to remember is that attribute names are case insensitive, so
687       'sn', 'Sn', 'sN' and 'SN' are all the same.
688
689       So, if you want to print all the values for the attribute 'ou' then
690       this is as simple as
691
692         foreach ($entry->get_value( 'ou' )) {
693             print $_,"\n";
694           }
695
696       Now if you just want to print all the values for all the attributes you
697       can do
698
699         foreach my $attr ($entry->attributes) {
700           foreach my $value ($entry->get_value($attr)) {
701             print $attr, ": ", $value, "\n";
702           }
703         }
704
705   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
709        use Net::LDAP;
710
711        $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
718       Values for the scope parameter are as follows.
719
720       base
721           Search only the base object.
722
723       one Search the entries immediately below the base object.
724
725       sub
726       subtree
727           Search the whole tree below (and including) the base object.  This
728           is the default.
729
730       children
731           Search the whole subtree below the base object, excluding the base
732           object itself.
733
734           Note: children scope requires LDAPv3 subordinate feature extension.
735

GETTING SEARCH RESULTS

737       There are two ways of retrieving the results of a requested LDAP
738       search; inline and by using a callback subroutine.
739
740   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
745       Example:
746
747        use Net::LDAP;
748
749        $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
760        # How many entries were returned from the search
761        my $max = $mesg->count;
762
763        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
768          @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
783       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
789   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
793       A callback is just a subroutine that is passed two parameters when it
794       is called, the mesg and entry objects.
795
796       Example:
797
798        use Net::LDAP;
799
800        $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
812        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
820
821        sub callback
822        {
823        my ( $mesg, $entry) = @_;
824
825          #
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
837          my $dn = $entry->dn; # Obtain DN of this entry
838
839          @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
862        }  # End of callback subroutine
863
864       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

USING NET::LDAPS

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
876       The connection to the server is created when you create a new
877       Net::LDAPS object, e.g.
878
879         $ldaps = Net::LDAPS->new($server,
880                                  port => '10000',
881                                  verify => 'require',
882                                  capath => '/usr/local/cacerts/',
883                                  );
884
885       Starting with version 0.28 perl-ldap also supports URIs in the new
886       method.  So, the above can also be expressed as:
887
888         $ldaps = Net::LDAP->new("ldaps://$server",
889                                  port => '10000',
890                                  verify => 'require',
891                                  capath => '/usr/local/cacerts/',
892                                  );
893
894       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
898       For further information and code examples read the LDAPS module
899       documentation;  perldoc Net::LDAPS
900

USING LDAP GROUPS.

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
908       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
912       Two scripts for working with groups are available in the contrib
913       directory.  They are isMember.pl and printMembers.pl.
914
915   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
920       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
925       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

USING DSML.

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
937       Support for DSML is included in perl-ldap starting with version .20.
938
939       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
943       Eventually this module will be a full level 2 consumer and producer
944       enabling you to give you full DSML conformance.
945
946       The specification for DSML is at http://www.oasis-open.org/specs/
947
948       For further information and code examples read the DSML module
949       documentation;  perldoc Net::LDAP::DSML
950

USING CONTROLS AND VIRTUAL LISTS.

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
956       For further information and code examples read the Control module
957       documentation;  perldoc Net::LDAP::Control
958
959   How do I access the Virtual List features?
960       Support for Virtual Lists is included in perl-ldap starting with
961       version .20.
962
963       For further information and code examples read the Control module
964       documentation;  perldoc Net::LDAP::Control
965

GENERAL QUESTIONS.

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
971       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
975   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
979       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
985       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
990   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
996       There are a couple of requirements for consideration.
997
998       You must supply a one line description of your script to be included in
999       the contrib README file.
1000
1001       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
1005   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
1011       So in the search method, just set (for LDAPv2):
1012
1013                       attrs => [ ]
1014
1015       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
1019                       attrs => [ "*" ]
1020
1021       To get all operational attributes in a search, some servers allow the
1022       use of the "+" pseudo attribute. So that with these servers
1023
1024                       attrs => [ "*", "+" ]
1025
1026       will return the most information from the server.
1027
1028   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
1032         use Net::LDAP;
1033         use Net::LDAP::Util qw(ldap_error_text);
1034         use CGI;
1035
1036         local $/ = undef;
1037         my $jpeg = <$filename>;
1038
1039         my $ldap = Net::LDAP->new(...);
1040         my $res = $ldap->bind(...);
1041            $res = $ldap->modify(...,
1042                          add => [ 'jpegPhoto' => [ $jpeg ] ]);
1043            $res = $ldap->unbind();
1044
1045   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
1049         use Net::LDAP;
1050         use Net::LDAP::Util qw(ldap_error_text);
1051         use CGI;
1052
1053         my $q = new CGI;
1054
1055         print $q->header;
1056         print $q->start_html(-title => 'Change JPEG photo');
1057
1058         if ($q->param('Update')) {
1059                 my $filename = $q->param('jpeg');
1060                 local $/ = undef;
1061                 my $jpeg = <$filename>;
1062
1063                 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
1075         print $q->end_html();
1076
1077   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
1082       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
1087       I.e.:
1088
1089         my $mesg = $ldap->modify( $entry, replace => { %qv_del_arry } );
1090
1091       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
1094   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
1102       The code required will look similar to the following code snippet.
1103
1104         $mesg =  $ldap->delete("ref=\"ldap://acme/c=us,o=bricks\",o=clay",
1105                         control => {type => "2.16.840.1.113730.3.4.2"} );
1106
1107   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
1112         my $aci = '(target="ldap:///-DN-")(targetattr="-ATTRNAMEs-")(version 3.0;
1113                     acl "-ACLNAME-"; deny(all) userdn = "ldap:///self";)' ;
1114
1115         $ldap->modify($dn_modif, add => {'aci' => $aci });
1116
1117   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
1123       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
1129   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
1133         $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
1146       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
1151   How can I create a group in Active Directory?
1152       Similar to accounts, groups need some AD-specific attributes too:
1153
1154         $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
1163   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
1168         $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
1174   How can I search for security groups in Active Directory
1175       With groups, the same applies to the "groupType" bit-field:
1176
1177         $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
1184   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
1189       The trick to this is the special "LDAP_MATCHING_RULE_IN_CHAIN" matching
1190       rule:
1191
1192         $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
1197   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
1202         $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
1207   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
1212       Performing the same standard search again will yield the same values
1213       again.
1214
1215       So, how can you get all members of a really large AD group?
1216
1217       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
1222         my $mesg;
1223         my @members;
1224         my $index = 0;
1225
1226         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
1236             # 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
1240               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
1257         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
1264       See
1265       <http://msdn.microsoft.com/en-us/library/windows/desktop/aa367017.aspx>
1266       for more details.
1267
1268   How do I create a Microsoft Exchange 5.x user?
1269       This is a solution provided by a perl-ldap user.
1270
1271       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
1275         use Net::LDAP;
1276         use Net::LDAP::Util;
1277         use Win32::Perms;
1278
1279         #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
1291         $EXCH_USER_RIGHTS = $ADS_RIGHT_EXCH_MAIL_RECEIVE_AS |
1292         $ADS_RIGHT_EXCH_MAIL_SEND_AS |
1293         $ADS_RIGHT_EXCH_MODIFY_USER_ATT;
1294
1295         $exch = Net::LDAP->new('server', debug =>0) || die $@;
1296
1297         $exch->bind( 'cn=admin_user,cn=nt_domain,cn=admin', version =>3,
1298         password=>'password');
1299
1300         $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
1310         $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
1322
1323         print ldap_error_name($result->code);
1324
1325   How do I reset a user's password ...
1326       ... in most LDAP servers?
1327
1328       Most LDAP servers use the standard userPassword attribute as the
1329       attribute to set when you want to change a user's password.
1330
1331       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
1335       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
1339       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
1343       If the extended Password Modify operation is not available the
1344       alternative is the regular modification of the userPassword attribute.
1345
1346       But this method has some drawbacks:
1347
1348       ·   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
1354       ·   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
1359       ·   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
1364       Here is an example of how to change your own password (for brevity's
1365       sake error checking is left out):
1366
1367         use Net::LDAP;
1368
1369         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
1373         my $rootdse = $ldap->root_dse();
1374
1375         if ($rootdse->supported_extension('1.3.6.1.4.1.4203.1.11.1') {
1376
1377             require Net::LDAP::Extension::SetPassword;
1378
1379             $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
1390         $ldap->unbind();
1391
1392       ... in MS Active Directory?
1393
1394       With Active Directory a user's password is stored in the unicodePwd
1395       attribute and changed using the regular modify operation.
1396
1397       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
1401       For the password modify operation to succeed SSL is required.
1402
1403       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
1408       Perl-ldap contains convenience methods for Active Directory that allow
1409       one to perform this task very easily.
1410
1411       Here's an example that demonstrates setting your own password from
1412       $oldPW to $newPW (again almost no error checking):
1413
1414         use Net::LDAP;
1415         use Net::LDAP::Extra qw(AD);
1416
1417         my $ldap = Net::LDAP->new('ldaps://ads.domain.controller')  or  die "$@";
1418
1419         my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1420                                password => $oldPW);
1421
1422         $mesg = $ldap->change_ADpassword('cn=Joe User,dc=your,dc=ads,dc=domain',
1423                                          $oldPW, $newPW);
1424
1425         $ldap->unbind();
1426
1427       And the same for perl-ldap versions before 0.49, where everything needs
1428       to be done by hand:
1429
1430         use Net::LDAP;
1431         use Unicode::Map8;
1432         use Unicode::String qw(utf16);
1433
1434         # build the conversion map from your local character set to Unicode
1435         my $charmap = Unicode::Map8->new('latin1')  or  die;
1436
1437         # 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
1442         my $ldap = Net::LDAP->new('ldaps://ads.domain.controller')  or  die "$@";
1443
1444         my $mesg = $ldap->bind('cn=Joe User,dc=your,dc=ads,dc=domain',
1445                                password => $oldPW);
1446
1447         $mesg = $ldap->modify('cn=Joe User,dc=your,dc=ads,dc=domain',
1448                               changes => [
1449                                   delete => [ unicodePwd => $oldUniPW ]
1450                                   add    => [ unicodePwd => $newUniPW ] ]);
1451
1452         $ldap->unbind();
1453
1454   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
1458       Here is one possible solution:
1459
1460         $ldaps = Net::LDAPS->new([ $ldapserverone, $ldapservertwo ],
1461                                  port=>636, timeout=>5)  or  die "$@";
1462
1463       For perl-ldap versions before 0.27, the same goal can be achieved
1464       using:
1465
1466         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

Using X.509 certificates.

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
1483       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
1486         openssl x509 -inform PEM -in cert.pem -outform DER -out cert.der
1487
1488       Consult the OpenSSL documentation to find out how to perform other
1489       conversions.
1490
1491       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
1496       To slurp in the certificate try something like this:
1497
1498         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
1508       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
1512         $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
1519       For LDAPv3, you must do this instead:
1520
1521         $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
1528       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
1534   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
1538       Then using the filter (for certificateExactMatch)
1539
1540         (userCertificate={ serialNumber 1234, issuer "cn=CA,o=TrustCenter" })
1541
1542       allows searching for the objects containing the attribute
1543       userCertificate with a certificate matching these criteria.
1544
1545       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

ADDITIONAL DIRECTORY AND LDAP RESOURCES.

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
1555       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
1559       LemonLDAP::NG - Web SingleSignOn solution & SAML IdP in Perl
1560       http://lemonldap-ng.org/
1561
1562       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
1566       Directory Services Mark Language (DSML)
1567       http://www.oasis-open.org/specs/
1568
1569       eMailman LDAP information http://www.emailman.com/ldap/
1570
1571       Rafael Corvalan's LDAP shell http://sf.net/projects/ldapsh
1572
1573       Jeff Hodges's Kings Mountain LDAP
1574       http://www.kingsmountain.com/ldapRoadmap.shtml (outdated: last update
1575       was in 2004)
1576
1577       willeke.com's LDAP Wiki http://ldapwiki.willeke.com/wiki/LDAP
1578
1579       OpenLDAP Directory Server - open source LDAP server.
1580       http://www.openldap.org/
1581
1582       389 Directory Server - open source LDAP server http://port389.org/
1583
1584       ApacheDS - open source LDAP server in Java http://directory.apache.org/
1585
1586       CriticalPath http://www.cp.net/
1587
1588       ForgeRock's OpenDS - LDAPv3 server with additional REST APIs
1589       http://www.forgerock.com/opendj.html
1590
1591       IBM Tivoli Directory Server
1592       http://www-01.ibm.com/software/tivoli/products/directory-server/
1593
1594       Isode (was MessagingDirect) http://www.isode.com/
1595
1596       Nexor's X.500 and Internet Directories
1597       http://www.nexor.com/info/directory.htm/
1598
1599       Novell's eDirectory http://www.novell.com/
1600
1601       Octet String http://www.octetstring.com/
1602
1603       SUN JAVA JNDI (Java Naming and Directory Interface)
1604       http://java.sun.com/products/jndi/overview.html
1605
1606       Oracle Directory Server Enterprise Edition, formerly Sun One, formerly
1607       iPlanet.
1608       http://www.oracle.com/technetwork/middleware/id-mgmt/index-085178.html
1609
1610       OptimalIDM - Virtual Identity Server - .NET LDAP virtual directory
1611       http://www.optimalidm.com/products/vis/Virtual-Directory-Server-VDS.aspx
1612
1613       Quest One Quick Connect Virtual Directory Server - LDAP virtual
1614       directory
1615       http://www.quest.com/quest-one-quick-connect-virtual-directory-server/
1616
1617       UnboundID's Identity data platform https://www.unboundid.com/
1618
1619       Virtual Directory Blogger https://virtualdirectory.wordpress.com/
1620
1621       eldapo - a directory manager's blog http://eldapo.blogspot.de/
1622
1623       Eine deutsche LDAP Website A German LDAP Website
1624       http://verzeichnisdienst.de/ldap/Perl/index.html
1625
1626       (non-exhaustive) list of LDAP software on Wikipedia
1627       http://en.wikipedia.org/wiki/List_of_LDAP_software
1628
1629       "RFC Sourcebook" on LDAP
1630       http://www.networksorcery.com/enp/protocol/ldap.htm
1631
1632       web2ldap - WWW gateway to LDAP server in Python http://www.web2ldap.de/
1633
1634       Softerra LDAP Browser / Administrator http://www.ldapbrowser.com/
1635
1636       The 2 following URLs deal mainly with Microsoft's Active Directory.
1637
1638       Directory Works http://directoryworks.com/
1639
1640       LDAP Client .Net & ActiveX LDAP Client
1641       http://www.ldapservices.com/Products/Default.aspx
1642
1643   BOOKS
1644       Developing LDAP and ADSI Clients for Microsoft(R) Exchange.  By Sven B.
1645       Schreiber.  ISBN:  0201657775
1646
1647       Implementing LDAP.  By Mark Wilcox.  ISBN:  1861002211
1648
1649       LDAP: Programming Directory-Enabled Applications With Lightweight
1650       Directory Access Protocol.  By Tim Howes, Mark Smith.  ISBN:
1651       1578700000
1652
1653       LDAP Programming; Directory Management and Integration.  By Clayton
1654       Donley.  ISBN:  1884777910
1655
1656       LDAP Programming with Java.  By Rob Weltman, Tony Dahbura.  ISBN:
1657       0201657589
1658
1659       LDAP System Administration.  By Gerald Carter.  ISBN:  1565924916
1660
1661       Managing Enterprise Active Directory Services.  By Robbie Allen,
1662       Richard Puckett.  ISBN:  0672321254
1663
1664       Solaris and LDAP Naming Services.  By Tom Bialaski, Michael Haines.
1665       ISBN:  0-13-030678-9
1666
1667       Understanding and Deploying LDAP Directory Services (2ed).  By Tim
1668       Howes, Mark Smith, Gordon Good.  ISBN:  0672323168
1669
1670       LDAP Directories Explained.  By Brian Arkills. ISBN 0-201-78792-X
1671

AUTHORS

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
1676       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
1680       The original author of this FAQ was Graham Barr <gbarr@pobox.com>
1681
1682       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.
1689
1690
1691
1692perl v5.30.1                      2020-01-30                 Net::LDAP::FAQ(3)
Impressum