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

DESCRIPTION

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

CONSTRUCTOR

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

METHODS

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

CONTROLS

903       Many of the methods described above accept a control option.  This
904       allows the user to pass controls to the server as described in LDAPv3.
905
906       A control is a reference to a HASH and should contain the three
907       elements below. If any of the controls are blessed then the method
908       "to_asn" will be called which should return a reference to a HASH
909       containing the three elements described below.
910
911       For most purposes Net::LDAP::Control objects are the easiest way to
912       generate controls.
913
914       type => OID
915           This element must be present and is the name of the type of control
916           being requested.
917
918       critical => FLAG
919           critical is optional and should be a Boolean value, if it is not
920           specified then it is assumed to be false.
921
922       value => VALUE
923           If the control being requested requires a value then this element
924           should hold the value for the server.
925

CALLBACKS

927       Most of the above commands accept a callback option. This option should
928       be a reference to a subroutine. This subroutine will be called for each
929       packet received from the server as a response to the request sent.
930
931       When the subroutine is called the first argument will be the
932       Net::LDAP::Message object which was returned from the method.
933
934       If the request is a search then multiple packets can be received from
935       the server. Each entry is received as a separate packet. For each of
936       these the subroutine will be called with a Net::LDAP::Entry object as
937       the second argument.
938
939       During a search the server may also send a list of references. When
940       such a list is received then the subroutine will be called with a
941       Net::LDAP::Reference object as the second argument.
942

LDAP ERROR CODES

944       Net::LDAP also exports constants for the error codes that can be
945       received from the server, see Net::LDAP::Constant.
946

SEE ALSO

948       Net::LDAP::Constant, Net::LDAP::Control, Net::LDAP::Entry,
949       Net::LDAP::Filter, Net::LDAP::Message, Net::LDAP::Reference,
950       Net::LDAP::Search, Net::LDAP::RFC
951
952       The homepage for the perl-ldap modules can be found at
953       http://ldap.perl.org/.
954

ACKNOWLEDGEMENTS

956       This document is based on a document originally written by Russell
957       Fulton <r.fulton@auckland.ac.nz>.
958
959       Chris Ridd <chris.ridd@isode.com> for the many hours spent testing and
960       contribution of the ldap* command line utilities.
961

MAILING LIST

963       A discussion mailing list is hosted by the Perl Foundation at
964       <perl-ldap@perl.org> No subscription is necessary!
965

BUGS

967       We hope you do not find any, but if you do please report them to the
968       mailing list.
969
970       If you have a patch, please send it as an attachment to the mailing
971       list.
972

AUTHOR

974       Graham Barr <gbarr@pobox.com>
975
977       Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
978       is free software; you can redistribute it and/or modify it under the
979       same terms as Perl itself.
980
981
982
983perl v5.36.0                      2022-07-22                      Net::LDAP(3)
Impressum