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

NAME

6       Net::LDAP - Lightweight Directory Access Protocol
7

SYNOPSIS

9        use Net::LDAP;
10
11        $ldap = Net::LDAP->new( 'ldap.bigfoot.com' ) or die "$@";
12
13        $mesg = $ldap->bind ;    # an anonymous bind
14
15        $mesg = $ldap->search( # perform a search
16                               base   => "c=US",
17                               filter => "(&(sn=Barr)(o=Texas Instruments))"
18                             );
19
20        $mesg->code && die $mesg->error;
21
22        foreach $entry ($mesg->entries) { $entry->dump; }
23
24        $mesg = $ldap->unbind;   # take down session
25
26
27        $ldap = Net::LDAP->new( 'ldap.umich.edu' );
28
29        # bind to a directory with dn and password
30        $mesg = $ldap->bind( 'cn=root, o=University of Michigan, c=us',
31                             password => 'secret'
32                           );
33
34        $result = $ldap->add( 'cn=Barbara Jensen, o=University of Michigan, c=US',
35                              attrs => [
36                                'cn'   => ['Barbara Jensen', 'Barbs Jensen'],
37                                'sn'   => 'Jensen',
38                                'mail' => 'b.jensen@umich.edu',
39                                'objectclass' => ['top', 'person',
40                                                  'organizationalPerson',
41                                                  'inetOrgPerson' ],
42                              ]
43                            );
44
45        $result->code && warn "failed to add entry: ", $result->error ;
46        $mesg = $ldap->unbind;  # take down session
47

DESCRIPTION

49       Net::LDAP is a collection of modules that implements a LDAP services
50       API for Perl programs. The module may be used to search directories or
51       perform maintenance functions such as adding, deleting or modifying
52       entries.
53
54       This document assumes that the reader has some knowledge of the LDAP
55       protocol.
56

CONSTRUCTOR

58       new ( HOST, OPTIONS )
59           Creates a new Net::LDAP object and opens a connection to the named
60           host.
61
62           "HOST" may be a host name or an IP address. TCP port may be
63           specified after the host name followed by a colon (such as
64           localhost:10389). The default TCP port for LDAP is 389.
65
66           You can also specify a URI, such as 'ldaps://127.0.0.1:666' or
67           'ldapi://%2fvar%2flib%2fldap_sock'. Note that '%2f's in the LDAPI
68           socket path will be translated into '/'. This is to support LDAP
69           query options like base, search etc. although the query part of the
70           URI will be ignored in this context. If port was not specified in
71           the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
72           schemes respectively.
73
74           "HOST" may also be a reference to an array of hosts, host-port
75           pairs or URIs to try. Each will be tried in order until a
76           connection is made. Only when all have failed will the result of
77           "undef" be returned.
78
79           port => N
80               Port to connect to on the remote server. May be overridden by
81               "HOST".
82
83           scheme => 'ldap' | 'ldaps' | 'ldapi'
84               Connection scheme to use when not using an URI as "HOST".
85               (Default: ldap)
86
87           keepalive => 1
88               If given, set the socket's SO_KEEPALIVE option depending on the
89               Boolean value of the option.  (Default: use system default)
90
91               Failures in changing the socket's SO_KEEPALIVE option are
92               ignored.
93
94           timeout => N
95               Timeout passed to IO::Socket when connecting the remote server.
96               (Default: 120)
97
98           multihomed => N
99               Will be passed to IO::Socket as the "MultiHomed" parameter when
100               connecting to the remote server
101
102           localaddr => HOST
103               Will be passed to IO::Socket as the "LocalAddr" parameter,
104               which sets the client's IP address (as opposed to the server's
105               IP address.)
106
107           debug => N
108               Set the debug level. See the debug method for details.
109
110           async => 1
111               Perform all operations asynchronously.
112
113           onerror => 'die' | 'warn' | undef | sub { ... }
114               In synchronous mode, change what happens when an error is
115               detected.
116
117               'die'
118                   Net::LDAP will croak whenever an error is detected.
119
120               'warn'
121                   Net::LDAP will warn whenever an error is detected.
122
123               undef
124                   Net::LDAP will warn whenever an error is detected and "-w"
125                   is in effect. The method that was called will return
126                   "undef".
127
128               sub { ... }
129                   The given sub will be called in a scalar context with a
130                   single argument, the result message. The value returned
131                   will be the return value for the method that was called.
132
133           version => N
134               Set the protocol version being used (default is LDAPv3). This
135               is useful if you want to talk to an old server and therefore
136               have to use LDAPv2.
137
138           raw => REGEX
139               Use REGEX to denote the names of attributes that are to be
140               considered binary in search results.
141
142               When this option is given, Net::LDAP converts all values of
143               attributes not matching this REGEX into Perl UTF-8 strings so
144               that the regular Perl operators (pattern matching, ...) can
145               operate as one expects even on strings with international
146               characters.
147
148               If this option is not given, attribute values are treated as
149               byte strings.
150
151               Example: raw => qr/(?i:^jpegPhoto|;binary)/
152
153           inet4 => N
154           inet6 => N
155               Try to connect to the server using the specified IP protocol
156               only, i.e. either IPv4 or IPv6.  If the protocol selected is
157               not supported, connecting will fail.
158
159               The default is to use any of the two protocols.
160
161           Example
162
163             $ldap = Net::LDAP->new( 'remote.host', async => 1 );
164
165           LDAPS connections have some extra valid options, see the start_tls
166           method for details. Note the default port for LDAPS is 636, and the
167           default value for 'sslversion' is the value used as default by
168           IO::Socket::SSL.
169
170           For LDAPI connections, HOST is actually the location of a UNIX
171           domain socket to connect to. The default location is
172           '/var/run/ldapi'.
173

METHODS

175       Each of the following methods take as arguments some number of fixed
176       parameters followed by options, these options are passed in a named
177       fashion, for example
178
179         $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd");
180
181       The return value from these methods is an object derived from the
182       Net::LDAP::Message class. The methods of this class allow you to
183       examine the status of the request.
184
185       abandon ( ID, OPTIONS )
186           Abandon a previously issued request. "ID" may be a number or an
187           object which is a sub-class of Net::LDAP::Message, returned from a
188           previous method call.
189
190           control => CONTROL
191           control => [ CONTROL, ... ]
192               See "CONTROLS" below
193
194           callback => CALLBACK
195               See "CALLBACKS" below
196
197           Example
198
199             $res = $ldap->search( @search_args );
200
201             $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon
202
203       add ( DN, OPTIONS )
204           Add a new entry to the directory. "DN" can be either a
205           Net::LDAP::Entry object or a string.
206
207           attrs => [ ATTR => VALUE, ... ]
208               "VALUE" should be a string if only a single value is wanted, or
209               a reference to an array of strings if multiple values are
210               wanted.
211
212               This argument is not used if "DN" is a Net::LDAP::Entry object.
213
214           control => CONTROL
215           control => [ CONTROL, ... ]
216               See "CONTROLS" below
217
218           callback => CALLBACK
219               See "CALLBACKS" below
220
221           Example
222
223             # $entry is an object of class Net::LDAP::Entry
224             $mesg = $ldap->add( $entry );
225
226             $mesg = $ldap->add( $dn,
227                                 attrs => [
228                                   name  => 'Graham Barr',
229                                   attr  => 'value1',
230                                   attr  => 'value2',
231                                   multi => [qw(value1 value2)]
232                                 ]
233                               );
234
235       bind ( DN, OPTIONS )
236           Bind (log in) to the server. "DN" is the DN to bind with. An
237           anonymous bind may be done by calling bind without any arguments.
238
239           control => CONTROL
240           control => [ CONTROL, ... ]
241               See "CONTROLS" below
242
243           callback => CALLBACK
244               See "CALLBACKS" below
245
246           noauth | anonymous => 1
247               Bind without any password. The value passed with this option is
248               ignored.
249
250           password => PASSWORD
251               Bind with the given password.
252
253           sasl => SASLOBJ
254               Bind using a SASL mechanism. The argument given should be a
255               sub-class of Authen::SASL or an Authen::SASL client connection
256               by calling "client_new" on an Authen::SASL object.
257
258               If passed an Authen::SASL object then "client_new" will be
259               called to create a client connection object.  The hostname
260               passed by "Net::LDAP" to "client_new" can be set using the
261               "sasl_host" option below.  If this is not correct for your
262               environment, consider calling "client_new" yourself and passing
263               the client connection object as "SASLOBJ".
264
265           sasl_host => SASLHOST
266               When binding using SASL, allow the hostname used in the SASL
267               communication to differ from the hostname connected to.
268
269               If "SASLHOST" evaluates to TRUE, then it is used as the SASL
270               hostname.
271
272               If it evaluates to FALSE, then the value is determined by
273               calling "peerhost" on the socket.  In older versions of
274               Net::LDAP this was the standard behaviour, but it turned out to
275               cause more trouble than it fixed.
276
277               When the option is not given, the SASL host name used defaults
278               to the host name / IP address taken from the "HOST" parameter
279               when connecting.
280
281           Example
282
283             $mesg = $ldap->bind; # Anonymous bind
284
285             $mesg = $ldap->bind( $dn, password => $password );
286
287             # $sasl is an object of class Authen::SASL
288             $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 );
289
290       compare ( DN, OPTIONS )
291           Compare values in an attribute in the entry given by "DN" on the
292           server. "DN" may be a string or a Net::LDAP::Entry object.
293
294           attr => ATTR
295               The name of the attribute to compare.
296
297           value => VALUE
298               The value to compare with.
299
300           control => CONTROL
301           control => [ CONTROL, ... ]
302               See "CONTROLS" below.
303
304           callback => CALLBACK
305               See "CALLBACKS" below.
306
307           Example
308
309             $mesg = $ldap->compare( $dn,
310                                     attr  => 'cn',
311                                     value => 'Graham Barr'
312                                   );
313
314       delete ( DN, OPTIONS )
315           Delete the entry given by "DN" from the server. "DN" may be a
316           string or a Net::LDAP::Entry object.
317
318           control => CONTROL
319           control => [ CONTROL, ... ]
320               See "CONTROLS" below.
321
322           callback => CALLBACK
323               See "CALLBACKS" below.
324
325           Example
326
327            $mesg = $ldap->delete( $dn );
328
329       moddn ( DN, OPTIONS )
330           Rename the entry given by "DN" on the server. "DN" may be a string
331           or a Net::LDAP::Entry object.
332
333           newrdn => RDN
334               This value should be a new RDN to assign to "DN".
335
336           deleteoldrdn => 1
337               This option should be passed if the existing RDN is to be
338               deleted.
339
340           newsuperior => NEWDN
341               If given this value should be the DN of the new superior for
342               "DN".
343
344           control => CONTROL
345           control => [ CONTROL, ... ]
346               See "CONTROLS" below.
347
348           callback => CALLBACK
349               See "CALLBACKS" below.
350
351           Example
352
353            $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' );
354
355       modify ( DN, OPTIONS )
356           Modify the contents of the entry given by "DN" on the server. "DN"
357           may be a string or a Net::LDAP::Entry object.
358
359           add => { ATTR => VALUE, ... }
360               Add more attributes or values to the entry. "VALUE" should be a
361               string if only a single value is wanted in the attribute, or a
362               reference to an array of strings if multiple values are wanted.
363
364                 $mesg = $ldap->modify( $dn,
365                   add => {
366                     description => 'List of members',    # Add description attribute
367                     member      => [
368                       'cn=member1,ou=people,dc=example,dc=com',    # Add to attribute
369                       'cn=member2,ou=people,dc=example,dc=com',
370                     ]
371                   }
372                 );
373
374           delete => [ ATTR, ... ]
375               Delete complete attributes from the entry.
376
377                 $mesg = $ldap->modify( $dn,
378                   delete => ['member','description'] # Delete attributes
379                 );
380
381           delete => { ATTR => VALUE, ... }
382               Delete individual values from an attribute. "VALUE" should be a
383               string if only a single value is being deleted from the
384               attribute, or a reference to an array of strings if multiple
385               values are being deleted.
386
387               If "VALUE" is a reference to an empty array or all existing
388               values of the attribute are being deleted, then the attribute
389               will be deleted from the entry.
390
391                 $mesg = $ldap->modify( $dn,
392                   delete => {
393                     description => 'List of members',
394                     member      => [
395                       'cn=member1,ou=people,dc=example,dc=com',    # Remove members
396                       'cn=member2,ou=people,dc=example,dc=com',
397                     ],
398                     seeAlso => [],   # Remove attribute
399                   }
400                 );
401
402           replace => { ATTR => VALUE, ... }
403               Replace any existing values in each given attribute with
404               "VALUE". "VALUE" should be a string if only a single value is
405               wanted in the attribute, or a reference to an array of strings
406               if multiple values are wanted. A reference to an empty array
407               will remove the entire attribute. If the attribute does not
408               already exist in the entry, it will be created.
409
410                 $mesg = $ldap->modify( $dn,
411                   replace => {
412                     description => 'New List of members', # Change the description
413                     member      => [ # Replace whole list with these
414                       'cn=member1,ou=people,dc=example,dc=com',
415                       'cn=member2,ou=people,dc=example,dc=com',
416                     ],
417                     seeAlso => [],   # Remove attribute
418                   }
419                 );
420
421           increment => { ATTR => VALUE, ... }
422               Atomically increment the existing value in each given attribute
423               by the provided "VALUE". The attributes need to have integer
424               syntax, or be otherwise "incrementable". Note this will only
425               work if the server advertises support for
426               LDAP_FEATURE_MODIFY_INCREMENT. Use "supported_feature" in
427               Net::LDAP::RootDSE to check this.
428
429                 $mesg = $ldap->modify( $dn,
430                   increment => {
431                     uidNumber => 1 # increment uidNumber by 1
432                   }
433                 );
434
435           changes => [ OP => [ ATTR => VALUE ], ... ]
436               This is an alternative to add, delete, replace and increment
437               where the whole operation can be given in a single argument.
438               "OP" should be add, delete, replace or increment. "VALUE"
439               should be either a string or a reference to an array of
440               strings, as before.
441
442               Use this form if you want to control the order in which the
443               operations will be performed.
444
445                 $mesg = $ldap->modify( $dn,
446                   changes => [
447                     add => [
448                       description => 'A description',
449                       member      => $newMember,
450                     ],
451                     delete => [
452                       seeAlso => [],
453                     ],
454                     add => [
455                       anotherAttribute => $value,
456                     ],
457                   ]
458                 );
459
460           control => CONTROL
461           control => [ CONTROL, ... ]
462               See "CONTROLS" below.
463
464           callback => CALLBACK
465               See "CALLBACKS" below.
466
467           Example
468
469            $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } );
470
471            $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] );
472
473            $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } );
474
475            $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } );
476
477            $mesg = $ldap->modify( $dn,
478                                   changes => [
479                                       # add sn=Barr
480                                     add     => [ sn => 'Barr' ],
481                                       # delete all fax numbers
482                                     delete  => [ faxNumber => []],
483                                       # delete phone number 911
484                                     delete  => [ telephoneNumber => ['911']],
485                                       # change email address
486                                     replace => [ mail => 'gbarr@pobox.com']
487                                   ]
488                                 );
489
490       search ( OPTIONS )
491           Search the directory using a given filter.  This can be used to
492           read attributes from a single entry, from entries immediately below
493           a particular entry, or a whole subtree of entries.
494
495           The result is an object of class Net::LDAP::Search.
496
497           base => DN
498               The DN that is the base object entry relative to which the
499               search is to be performed.
500
501           scope => 'base' | 'one' | 'sub' | 'subtree' | 'children'
502               By default the search is performed on the whole tree below the
503               specified base object. This maybe changed by specifying a
504               "scope" parameter with one of the following values:
505
506               base
507                   Search only the base object.
508
509               one Search the entries immediately below the base object.
510
511               sub
512               subtree
513                   Search the whole tree below (and including) the base
514                   object. This is the default.
515
516               children
517                   Search the whole subtree below the base object, excluding
518                   the base object itself.
519
520                   Note: children scope requires LDAPv3 subordinate feature
521                   extension.
522
523           deref => 'never' | 'search' | 'find' | 'always'
524               By default aliases are dereferenced to locate the base object
525               for the search, but not when searching subordinates of the base
526               object. This may be changed by specifying a "deref" parameter
527               with one of the following values:
528
529               never
530                   Do not dereference aliases in searching or in locating the
531                   base object of the search.
532
533               search
534                   Dereference aliases in subordinates of the base object in
535                   searching, but not in locating the base object of the
536                   search.
537
538               find
539                   Dereference aliases in locating the base object of the
540                   search, but not when searching subordinates of the base
541                   object. This is the default.
542
543               always
544                   Dereference aliases both in searching and in locating the
545                   base object of the search.
546
547           sizelimit => N
548               A sizelimit that restricts the maximum number of entries to be
549               returned as a result of the search. A value of 0, and the
550               default, means that no restriction is requested.  Servers may
551               enforce a maximum number of entries to return.
552
553           timelimit => N
554               A timelimit that restricts the maximum time (in seconds)
555               allowed for a search. A value of 0 (the default), means that no
556               timelimit will be requested.
557
558           typesonly => 1
559               Only attribute types (no values) should be returned. Normally
560               attribute types and values are returned.
561
562           filter => FILTER
563               A filter that defines the conditions an entry in the directory
564               must meet in order for it to be returned by the search. This
565               may be a string or a Net::LDAP::Filter object. Values inside
566               filters may need to be escaped to avoid security problems; see
567               Net::LDAP::Filter for a definition of the filter format,
568               including the escaping rules.
569
570           attrs => [ ATTR, ... ]
571               A list of attributes to be returned for each entry that matches
572               the search filter.
573
574               If not specified, then the server will return the attributes
575               that are specified as accessible by default given your bind
576               credentials.
577
578               Certain additional attributes such as "createTimestamp" and
579               other operational attributes may also be available for the
580               asking:
581
582                 $mesg = $ldap->search( ... ,
583                                        attrs => ['createTimestamp']
584                                      );
585
586               To retrieve the default attributes and additional ones, use
587               '*'.
588
589                 $mesg = $ldap->search( ... ,
590                                        attrs => ['*', 'createTimestamp']
591                                      );
592
593               To retrieve no attributes (the server only returns the DNs of
594               matching entries), use '1.1':
595
596                 $mesg = $ldap->search( ... ,
597                                        attrs => ['1.1']
598                                      );
599
600           control => CONTROL
601           control => [ CONTROL, ... ]
602               See "CONTROLS" below.
603
604           callback => CALLBACK
605               See "CALLBACKS" below.
606
607           raw => REGEX
608               Use REGEX to denote the names of attributes that are to be
609               considered binary in search results.
610
611               When this option is given, Net::LDAP converts all values of
612               attributes not matching this REGEX into Perl UTF-8 strings so
613               that the regular Perl operators (pattern matching, ...) can
614               operate as one expects even on strings with international
615               characters.
616
617               If this option is not given, attribute values are treated as
618               byte strings.
619
620               The value provided here overwrites the value inherited from the
621               constructor.
622
623               Example: raw => qr/(?i:^jpegPhoto|;binary)/
624
625           Example
626
627            $mesg = $ldap->search(
628                                   base   => $base_dn,
629                                   scope  => 'sub',
630                                   filter => '(|(objectclass=rfc822mailgroup)(sn=jones))'
631                                 );
632
633            Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries );
634
635       start_tls ( OPTIONS )
636           Calling this method will convert the existing connection to using
637           Transport Layer Security (TLS), which provides an encrypted
638           connection. This is only possible if the connection uses LDAPv3,
639           and requires that the server advertises support for
640           LDAP_EXTENSION_START_TLS. Use "supported_extension" in
641           Net::LDAP::RootDSE to check this.
642
643           verify => 'none' | 'optional' | 'require'
644               How to verify the server's certificate:
645
646               none
647                   The server may provide a certificate but it will not be
648                   checked - this may mean you are be connected to the wrong
649                   server
650
651               optional
652                   Verify only when the server offers a certificate
653
654               require
655                   The server must provide a certificate, and it must be
656                   valid.
657
658               If you set verify to optional or require, you must also set
659               either cafile or capath. The most secure option is require.
660
661           sslversion => 'sslv2' | 'sslv3' | 'sslv23' | 'tlsv1' | 'tlsv1_1' |
662           'tlsv1_2'
663               This defines the version of the SSL/TLS protocol to use.
664               Default is to use the value that IO::Socket::SSL uses as
665               default.
666
667               See "SSL_version" in IO::Socket::SSL for more details.
668
669           ciphers => CIPHERS
670               Specify which subset of cipher suites are permissible for this
671               connection, using the standard OpenSSL string format. The
672               default behavior is to keep the decision on the underlying
673               cryptographic library.
674
675           clientcert => '/path/to/cert.pem'
676           clientkey => '/path/to/key.pem'
677           keydecrypt => sub { ... }
678               If you want to use the client to offer a certificate to the
679               server for SSL authentication (which is not the same as for the
680               LDAP Bind operation) then set clientcert to the user's
681               certificate file, and clientkey to the user's private key file.
682               These files must be in PEM format.
683
684               If the private key is encrypted (highly recommended) then
685               keydecrypt should be a subroutine that returns the decrypting
686               key. For example:
687
688                $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 );
689                $mesg = $ldap->start_tls(
690                                          verify => 'require',
691                                          clientcert => 'mycert.pem',
692                                          clientkey => 'mykey.pem',
693                                          keydecrypt => sub { 'secret'; },
694                                          capath => '/usr/local/cacerts/'
695                                        );
696
697           capath => '/path/to/servercerts/'
698           cafile => '/path/to/servercert.pem'
699               When verifying the server's certificate, either set capath to
700               the pathname of the directory containing CA certificates, or
701               set cafile to the filename containing the certificate of the CA
702               who signed the server's certificate. These certificates must
703               all be in PEM format.
704
705               The directory in 'capath' must contain certificates named using
706               the hash value of the certificates' subject names. To generate
707               these names, use OpenSSL like this in Unix:
708
709                   ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
710
711               (assuming that the certificate of the CA is in cacert.pem.)
712
713           checkcrl => 1
714               If capath has been configured, then it will also be searched
715               for certificate revocation lists (CRLs) when verifying the
716               server's certificate.  The CRLs' names must follow the form
717               hash.rnum where hash is the hash over the issuer's DN and num
718               is a number starting with 0.
719
720               See "SSL_check_crl" in IO::Socket::SSL for further information.
721
722       unbind ( )
723           The unbind method does not take any parameters and will unbind you
724           from the server. Some servers may allow you to re-bind or perform
725           other operations after unbinding. If you wish to switch to another
726           set of credentials while continuing to use the same connection, re-
727           binding with another DN and password, without unbind-ing, will
728           generally work.
729
730           Example
731
732            $mesg = $ldap->unbind;
733
734       done ( )
735           Convenience alias for "unbind()", named after the clean-up method
736           of Net::LDAP::LDIF.
737
738       The following methods are for convenience, and do not return
739       "Net::LDAP::Message" objects.
740
741       async ( VALUE )
742           If "VALUE" is given the async mode will be set. The previous value
743           will be returned. The value is true if LDAP operations are being
744           performed asynchronously.
745
746       certificate ( )
747           Returns an X509_Certificate object containing the server's
748           certificate. See the IO::Socket::SSL documentation for information
749           about this class.
750
751           For example, to get the subject name (in a peculiar OpenSSL-
752           specific format, different from RFC 1779 and RFC 4514) from the
753           server's certificate, do this:
754
755               print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
756
757       cipher ( )
758           Returns the cipher mode being used by the connection, in the string
759           format used by OpenSSL.
760
761       debug ( VALUE )
762           If "VALUE" is given the debug bit-value will be set. The previous
763           value will be returned. Debug output will be sent to "STDERR". The
764           bits of this value are:
765
766            1   Show outgoing packets (using asn_hexdump).
767            2   Show incoming packets (using asn_hexdump).
768            4   Show outgoing packets (using asn_dump).
769            8   Show incoming packets (using asn_dump).
770
771           The default value is 0.
772
773       disconnect ( )
774           Disconnect from the server
775
776       root_dse ( OPTIONS )
777           The root_dse method retrieves cached information from the server's
778           rootDSE.
779
780           attrs => [ ATTR, ... ]
781               A reference to a list of attributes to be returned.  If not
782               specified, then the following attributes will be requested
783
784                 subschemaSubentry
785                 namingContexts
786                 altServer
787                 supportedExtension
788                 supportedFeatures
789                 supportedControl
790                 supportedSASLMechanisms
791                 supportedLDAPVersion
792
793           The result is an object of class Net::LDAP::RootDSE.
794
795           Example
796
797            my $root = $ldap->root_dse;
798            # get naming Context
799            $root->get_value( 'namingContexts', asref => 1 );
800            # get supported LDAP versions
801            $root->supported_version;
802
803           As the root DSE may change in certain circumstances - for instance
804           when you change the connection using start_tls - you should always
805           use the root_dse method to return the most up-to-date copy of the
806           root DSE.
807
808       schema ( OPTIONS )
809           Read schema information from the server.
810
811           The result is an object of class Net::LDAP::Schema.  Read this
812           documentation for further information about methods that can be
813           performed with this object.
814
815           dn => DN
816               If a DN is supplied, it will become the base object entry from
817               which the search for schema information will be conducted.  If
818               no DN is supplied the base object entry will be determined from
819               the rootDSE entry.
820
821           Example
822
823            my $schema = $ldap->schema;
824            # get objectClasses
825            @ocs = $schema->all_objectclasses;
826            # Get the attributes
827            @atts = $schema->all_attributes;
828
829       sasl ( )
830           Returns the "Authen::SASL" object associated with the LDAP object,
831           or "undef" if there isn't.
832
833       socket ( OPTIONS )
834           Returns the underlying socket object being used.
835
836           The exact object type returned depends on whether SASL layers are
837           established.  Without SASL layers the result is always an
838           "IO::Socket" object; with SASL layers the outcome depends on the
839           options given:
840
841           sasl_layer => FLAG
842               This option is only relevant if SASL layers are established.
843
844               If it it missing or if is set to a TRUE value, then the SASL
845               layer handle is returned. Depending on the SASL library used,
846               the object returned is not necessarily an "IO::Socket" object.
847
848               If it exists, but is set to a value evaluating to FALSE, then
849               the base "IO::Socket" object underneath the SASL layer is
850               returned.
851
852       host ( )
853           Returns the host to which the connection was established.  For
854           LDAPI connections the socket path is returned.
855
856       port ( )
857           Returns the port connected to or "undef" in case of LDAPI
858           connections.
859
860       uri ( )
861           Returns the URI connected to.
862
863           As the value returned is that element of the constructor's HOST
864           argument with which the connection was established this may or may
865           not be a legal URI.
866
867       scheme ( )
868           Returns the scheme of the connection. One of ldap, ldaps or ldapi.
869
870       sync ( MESG )
871           Wait for a given "MESG" request to be completed by the server. If
872           no "MESG" is given, then wait for all outstanding requests to be
873           completed.
874
875           Returns an error code defined in Net::LDAP::Constant.
876
877       process ( MESG )
878           Process any messages that the server has sent, but do not block. If
879           "MESG" is specified then return as soon as "MESG" has been
880           processed.
881
882           Returns an error code defined in Net::LDAP::Constant.
883
884       version ( )
885           Returns the version of the LDAP protocol that is being used.
886

CONTROLS

888       Many of the methods described above accept a control option.  This
889       allows the user to pass controls to the server as described in LDAPv3.
890
891       A control is a reference to a HASH and should contain the three
892       elements below. If any of the controls are blessed then the method
893       "to_asn" will be called which should return a reference to a HASH
894       containing the three elements described below.
895
896       For most purposes Net::LDAP::Control objects are the easiest way to
897       generate controls.
898
899       type => OID
900           This element must be present and is the name of the type of control
901           being requested.
902
903       critical => FLAG
904           critical is optional and should be a Boolean value, if it is not
905           specified then it is assumed to be false.
906
907       value => VALUE
908           If the control being requested requires a value then this element
909           should hold the value for the server.
910

CALLBACKS

912       Most of the above commands accept a callback option. This option should
913       be a reference to a subroutine. This subroutine will be called for each
914       packet received from the server as a response to the request sent.
915
916       When the subroutine is called the first argument will be the
917       Net::LDAP::Message object which was returned from the method.
918
919       If the request is a search then multiple packets can be received from
920       the server. Each entry is received as a separate packet. For each of
921       these the subroutine will be called with a Net::LDAP::Entry object as
922       the second argument.
923
924       During a search the server may also send a list of references. When
925       such a list is received then the subroutine will be called with a
926       Net::LDAP::Reference object as the second argument.
927

LDAP ERROR CODES

929       Net::LDAP also exports constants for the error codes that can be
930       received from the server, see Net::LDAP::Constant.
931

SEE ALSO

933       Net::LDAP::Constant, Net::LDAP::Control, Net::LDAP::Entry,
934       Net::LDAP::Filter, Net::LDAP::Message, Net::LDAP::Reference,
935       Net::LDAP::Search, Net::LDAP::RFC
936
937       The homepage for the perl-ldap modules can be found at
938       http://ldap.perl.org/.
939

ACKNOWLEDGEMENTS

941       This document is based on a document originally written by Russell
942       Fulton <r.fulton@auckland.ac.nz>.
943
944       Chris Ridd <chris.ridd@isode.com> for the many hours spent testing and
945       contribution of the ldap* command line utilities.
946

MAILING LIST

948       A discussion mailing list is hosted by the Perl Foundation at
949       <perl-ldap@perl.org> No subscription is necessary!
950

BUGS

952       We hope you do not find any, but if you do please report them to the
953       mailing list.
954
955       If you have a patch, please send it as an attachment to the mailing
956       list.
957

AUTHOR

959       Graham Barr <gbarr@pobox.com>
960
962       Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
963       is free software; you can redistribute it and/or modify it under the
964       same terms as Perl itself.
965
966
967
968perl v5.28.1                      2015-04-06                      Net::LDAP(3)
Impressum