1Net::LDAP(3) User Contributed Perl Documentation Net::LDAP(3)
2
6 Net::LDAP - Lightweight Directory Access Protocol
7
9 use Net::LDAP;
10 $ldap = Net::LDAP->new( 'ldap.bigfoot.com' ) or die "$@";
12 $mesg = $ldap->bind ; # an anonymous bind
14 $mesg = $ldap->search( # perform a search
16 base => "c=US",
17 filter => "(&(sn=Barr)(o=Texas Instruments))"
18 );
19 $mesg->code && die $mesg->error;
21 foreach $entry ($mesg->entries) { $entry->dump; }
23 $mesg = $ldap->unbind; # take down session
25 $ldap = Net::LDAP->new( 'ldap.umich.edu' );
28 # 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 $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 $result->code && warn "failed to add entry: ", $result->error ;
46 $mesg = $ldap->unbind; # take down session
47
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 This document assumes that the reader has some knowledge of the LDAP
55 protocol.
56
58 new ( HOST, OPTIONS )
59 Creates a new Net::LDAP object and opens a connection to the named
60 host.
61 "HOST" may be a host name or an IP number. 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 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 "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 port => N
80 Port to connect to on the remote server. May be overridden by
81 "HOST".
82 scheme => 'ldap' | 'ldaps' | 'ldapi'
84 Connection scheme to use when not using an URI as "HOST".
85 (Default: ldap)
86 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 Failures in changing the socket's SO_KEEPALIVE option are
92 ignored.
93 timeout => N
95 Timeout passed to IO::Socket when connecting the remote server.
96 (Default: 120)
97 multihomed => N
99 Will be passed to IO::Socket as the "MultiHomed" parameter when
100 connecting to the remote server
101 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 debug => N
108 Set the debug level. See the debug method for details.
109 async => 1
111 Perform all operations asynchronously.
112 onerror => 'die' | 'warn' | undef | sub { ... }
114 In synchronous mode, change what happens when an error is
115 detected.
116 'die'
118 Net::LDAP will croak whenever an error is detected.
119 'warn'
121 Net::LDAP will warn whenever an error is detected.
122 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 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 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 raw => REGEX
139 Use REGEX to denote the names of attributes that are to be
140 considered binary in search results.
141 When running on Perl 5.8 and this option is given Net::LDAP
143 converts all values of attributes not matching this REGEX into
144 Perl UTF-8 strings so that the regular Perl operators (pattern
145 matching, ...) can operate as one expects even on strings with
146 international characters.
147 If this option is not given or the version of Perl Net::LDAP is
149 running on is too old strings are encoded the same as in
150 earlier versions of perl-ldap.
151 Example: raw => qr/(?i:^jpegPhoto|;binary)/
153 inet4 => N
155 inet6 => N
156 Try to connect to the server using the specified IP protocol
157 only, i.e. either IPv4 or IPv6. If the protocol selected is
158 not supported, connecting will fail.
159 The default is to use any of the two protocols.
161 Example
163 $ldap = Net::LDAP->new( 'remote.host', async => 1 );
165 LDAPS connections have some extra valid options, see the start_tls
167 method for details. Note the default port for LDAPS is 636, and the
168 default value for 'sslversion' is the value used as default by
169 IO::Socket::SSL.
170 For LDAPI connections, HOST is actually the location of a UNIX
172 domain socket to connect to. The default location is
173 '/var/run/ldapi'.
174
176 Each of the following methods take as arguments some number of fixed
177 parameters followed by options, these options are passed in a named
178 fashion, for example
179 $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd");
181 The return value from these methods is an object derived from the
183 Net::LDAP::Message class. The methods of this class allow you to
184 examine the status of the request.
185 abandon ( ID, OPTIONS )
187 Abandon a previously issued request. "ID" may be a number or an
188 object which is a sub-class of Net::LDAP::Message, returned from a
189 previous method call.
190 control => CONTROL
192 control => [ CONTROL, ... ]
193 See "CONTROLS" below
194 callback => CALLBACK
196 See "CALLBACKS" below
197 Example
199 $res = $ldap->search( @search_args );
201 $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon
203 add ( DN, OPTIONS )
205 Add a new entry to the directory. "DN" can be either a
206 Net::LDAP::Entry object or a string.
207 attrs => [ ATTR => VALUE, ... ]
209 "VALUE" should be a string if only a single value is wanted, or
210 a reference to an array of strings if multiple values are
211 wanted.
212 This argument is not used if "DN" is a Net::LDAP::Entry object.
214 control => CONTROL
216 control => [ CONTROL, ... ]
217 See "CONTROLS" below
218 callback => CALLBACK
220 See "CALLBACKS" below
221 Example
223 # $entry is an object of class Net::LDAP::Entry
225 $mesg = $ldap->add( $entry );
226 $mesg = $ldap->add( $dn,
228 attrs => [
229 name => 'Graham Barr',
230 attr => 'value1',
231 attr => 'value2',
232 multi => [qw(value1 value2)]
233 ]
234 );
235 bind ( DN, OPTIONS )
237 Bind (log in) to the server. "DN" is the DN to bind with. An
238 anonymous bind may be done by calling bind without any arguments.
239 control => CONTROL
241 control => [ CONTROL, ... ]
242 See "CONTROLS" below
243 callback => CALLBACK
245 See "CALLBACKS" below
246 noauth | anonymous => 1
248 Bind without any password. The value passed with this option is
249 ignored.
250 password => PASSWORD
252 Bind with the given password.
253 sasl => SASLOBJ
255 Bind using a SASL mechanism. The argument given should be a
256 sub-class of Authen::SASL or an Authen::SASL client connection
257 by calling "client_new" on an Authen::SASL object.
258 If passed an Authen::SASL object then "client_new" will be
260 called to create a client connection object. The hostname
261 passed by "Net::LDAP" to "client_new" is the result of calling
262 "peerhost" on the socket. If this is not correct for your
263 environment, consider calling "client_new" and passing the
264 client connection object.
265 Example
267 $mesg = $ldap->bind; # Anonymous bind
269 $mesg = $ldap->bind( $dn, password => $password );
271 # $sasl is an object of class Authen::SASL
273 $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 );
274 compare ( DN, OPTIONS )
276 Compare values in an attribute in the entry given by "DN" on the
277 server. "DN" may be a string or a Net::LDAP::Entry object.
278 attr => ATTR
280 The name of the attribute to compare.
281 value => VALUE
283 The value to compare with.
284 control => CONTROL
286 control => [ CONTROL, ... ]
287 See "CONTROLS" below.
288 callback => CALLBACK
290 See "CALLBACKS" below.
291 Example
293 $mesg = $ldap->compare( $dn,
295 attr => 'cn',
296 value => 'Graham Barr'
297 );
298 delete ( DN, OPTIONS )
300 Delete the entry given by "DN" from the server. "DN" may be a
301 string or a Net::LDAP::Entry object.
302 control => CONTROL
304 control => [ CONTROL, ... ]
305 See "CONTROLS" below.
306 callback => CALLBACK
308 See "CALLBACKS" below.
309 Example
311 $mesg = $ldap->delete( $dn );
313 moddn ( DN, OPTIONS )
315 Rename the entry given by "DN" on the server. "DN" may be a string
316 or a Net::LDAP::Entry object.
317 newrdn => RDN
319 This value should be a new RDN to assign to "DN".
320 deleteoldrdn => 1
322 This option should be passed if the existing RDN is to be
323 deleted.
324 newsuperior => NEWDN
326 If given this value should be the DN of the new superior for
327 "DN".
328 control => CONTROL
330 control => [ CONTROL, ... ]
331 See "CONTROLS" below.
332 callback => CALLBACK
334 See "CALLBACKS" below.
335 Example
337 $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' );
339 modify ( DN, OPTIONS )
341 Modify the contents of the entry given by "DN" on the server. "DN"
342 may be a string or a Net::LDAP::Entry object.
343 add => { ATTR => VALUE, ... }
345 Add more attributes or values to the entry. "VALUE" should be a
346 string if only a single value is wanted in the attribute, or a
347 reference to an array of strings if multiple values are wanted.
348 $mesg = $ldap->modify( $dn,
350 add => {
351 description => 'List of members', # Add description attribute
352 member => [
353 'cn=member1,ou=people,dc=example,dc=com', # Add to attribute
354 'cn=member2,ou=people,dc=example,dc=com',
355 ]
356 }
357 );
358 delete => [ ATTR, ... ]
360 Delete complete attributes from the entry.
361 $mesg = $ldap->modify( $dn,
363 delete => ['member','description'] # Delete attributes
364 );
365 delete => { ATTR => VALUE, ... }
367 Delete individual values from an attribute. "VALUE" should be a
368 string if only a single value is being deleted from the
369 attribute, or a reference to an array of strings if multiple
370 values are being deleted.
371 If "VALUE" is a reference to an empty array or all existing
373 values of the attribute are being deleted, then the attribute
374 will be deleted from the entry.
375 $mesg = $ldap->modify( $dn,
377 delete => {
378 description => 'List of members',
379 member => [
380 'cn=member1,ou=people,dc=example,dc=com', # Remove members
381 'cn=member2,ou=people,dc=example,dc=com',
382 ],
383 seeAlso => [], # Remove attribute
384 }
385 );
386 replace => { ATTR => VALUE, ... }
388 Replace any existing values in each given attribute with
389 "VALUE". "VALUE" should be a string if only a single value is
390 wanted in the attribute, or a reference to an array of strings
391 if multiple values are wanted. A reference to an empty array
392 will remove the entire attribute. If the attribute does not
393 already exist in the entry, it will be created.
394 $mesg = $ldap->modify( $dn,
396 replace => {
397 description => 'New List of members', # Change the description
398 member => [ # Replace whole list with these
399 'cn=member1,ou=people,dc=example,dc=com',
400 'cn=member2,ou=people,dc=example,dc=com',
401 ],
402 seeAlso => [], # Remove attribute
403 }
404 );
405 increment => { ATTR => VALUE, ... }
407 Atomically increment the existing value in each given attribute
408 by the provided "VALUE". The attributes need to have integer
409 syntax, or be otherwise "incrementable". Note this will only
410 work if the server advertises support for
411 LDAP_FEATURE_MODIFY_INCREMENT. Use "supported_feature" in
412 Net::LDAP::RootDSE to check this.
413 $mesg = $ldap->modify( $dn,
415 increment => {
416 uidNumber => 1 # increment uidNumber by 1
417 }
418 );
419 changes => [ OP => [ ATTR => VALUE ], ... ]
421 This is an alternative to add, delete, replace and increment
422 where the whole operation can be given in a single argument.
423 "OP" should be add, delete, replace or increment. "VALUE"
424 should be either a string or a reference to an array of
425 strings, as before.
426 Use this form if you want to control the order in which the
428 operations will be performed.
429 $mesg = $ldap->modify( $dn,
431 changes => [
432 add => [
433 description => 'A description',
434 member => $newMember,
435 ],
436 delete => [
437 seeAlso => [],
438 ],
439 add => [
440 anotherAttribute => $value,
441 ],
442 ]
443 );
444 control => CONTROL
446 control => [ CONTROL, ... ]
447 See "CONTROLS" below.
448 callback => CALLBACK
450 See "CALLBACKS" below.
451 Example
453 $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } );
455 $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] );
457 $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } );
459 $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } );
461 $mesg = $ldap->modify( $dn,
463 changes => [
464 # add sn=Barr
465 add => [ sn => 'Barr' ],
466 # delete all fax numbers
467 delete => [ faxNumber => []],
468 # delete phone number 911
469 delete => [ telephoneNumber => ['911']],
470 # change email address
471 replace => [ mail => 'gbarr@pobox.com']
472 ]
473 );
474 search ( OPTIONS )
476 Search the directory using a given filter. This can be used to
477 read attributes from a single entry, from entries immediately below
478 a particular entry, or a whole subtree of entries.
479 The result is an object of class Net::LDAP::Search.
481 base => DN
483 The DN that is the base object entry relative to which the
484 search is to be performed.
485 scope => 'base' | 'one' | 'sub' | 'subtree' | 'children'
487 By default the search is performed on the whole tree below the
488 specified base object. This maybe changed by specifying a
489 "scope" parameter with one of the following values:
490 base
492 Search only the base object.
493 one Search the entries immediately below the base object.
495 sub
497 subtree
498 Search the whole tree below (and including) the base
499 object. This is the default.
500 children
502 Search the whole subtree below the base object, excluding
503 the base object itself.
504 Note: children scope requires LDAPv3 subordinate feature
506 extension.
507 deref => 'never' | 'search' | 'find' | 'always'
509 By default aliases are dereferenced to locate the base object
510 for the search, but not when searching subordinates of the base
511 object. This may be changed by specifying a "deref" parameter
512 with one of the following values:
513 never
515 Do not dereference aliases in searching or in locating the
516 base object of the search.
517 search
519 Dereference aliases in subordinates of the base object in
520 searching, but not in locating the base object of the
521 search.
522 find
524 Dereference aliases in locating the base object of the
525 search, but not when searching subordinates of the base
526 object. This is the default.
527 always
529 Dereference aliases both in searching and in locating the
530 base object of the search.
531 sizelimit => N
533 A sizelimit that restricts the maximum number of entries to be
534 returned as a result of the search. A value of 0, and the
535 default, means that no restriction is requested. Servers may
536 enforce a maximum number of entries to return.
537 timelimit => N
539 A timelimit that restricts the maximum time (in seconds)
540 allowed for a search. A value of 0 (the default), means that no
541 timelimit will be requested.
542 typesonly => 1
544 Only attribute types (no values) should be returned. Normally
545 attribute types and values are returned.
546 filter => FILTER
548 A filter that defines the conditions an entry in the directory
549 must meet in order for it to be returned by the search. This
550 may be a string or a Net::LDAP::Filter object. Values inside
551 filters may need to be escaped to avoid security problems; see
552 Net::LDAP::Filter for a definition of the filter format,
553 including the escaping rules.
554 attrs => [ ATTR, ... ]
556 A list of attributes to be returned for each entry that matches
557 the search filter.
558 If not specified, then the server will return the attributes
560 that are specified as accessible by default given your bind
561 credentials.
562 Certain additional attributes such as "createTimestamp" and
564 other operational attributes may also be available for the
565 asking:
566 $mesg = $ldap->search( ... ,
568 attrs => ['createTimestamp']
569 );
570 To retrieve the default attributes and additional ones, use
572 '*'.
573 $mesg = $ldap->search( ... ,
575 attrs => ['*', 'createTimestamp']
576 );
577 To retrieve no attributes (the server only returns the DNs of
579 matching entries), use '1.1':
580 $mesg = $ldap->search( ... ,
582 attrs => ['1.1']
583 );
584 control => CONTROL
586 control => [ CONTROL, ... ]
587 See "CONTROLS" below.
588 callback => CALLBACK
590 See "CALLBACKS" below.
591 raw => REGEX
593 Use REGEX to denote the names of attributes that are to be
594 considered binary in search results.
595 When running on Perl 5.8 and this option is given Net::LDAP
597 converts all values of attributes not matching this REGEX into
598 Perl UTF-8 strings so that the regular Perl operators (pattern
599 matching, ...) can operate as one expects even on strings with
600 international characters.
601 If this option is not given or the version of Perl Net::LDAP is
603 running on is too old strings are encoded the same as in
604 earlier versions of perl-ldap.
605 The value provided here overwrites the value inherited from the
607 constructor.
608 Example: raw => qr/(?i:^jpegPhoto|;binary)/
610 Example
612 $mesg = $ldap->search(
614 base => $base_dn,
615 scope => 'sub',
616 filter => '(|(objectclass=rfc822mailgroup)(sn=jones))'
617 );
618 Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries );
620 start_tls ( OPTIONS )
622 Calling this method will convert the existing connection to using
623 Transport Layer Security (TLS), which provides an encrypted
624 connection. This is only possible if the connection uses LDAPv3,
625 and requires that the server advertises support for
626 LDAP_EXTENSION_START_TLS. Use "supported_extension" in
627 Net::LDAP::RootDSE to check this.
628 verify => 'none' | 'optional' | 'require'
630 How to verify the server's certificate:
631 none
633 The server may provide a certificate but it will not be
634 checked - this may mean you are be connected to the wrong
635 server
636 optional
638 Verify only when the server offers a certificate
639 require
641 The server must provide a certificate, and it must be
642 valid.
643 If you set verify to optional or require, you must also set
645 either cafile or capath. The most secure option is require.
646 sslversion => 'sslv2' | 'sslv3' | 'sslv23' | 'tlsv1' | 'tlsv1_1' |
648 'tlsv1_2'
649 This defines the version of the SSL/TLS protocol to use.
650 Default is to use the value that IO::Socket::SSL uses as
651 default.
652 See "SSL_version" in IO::Socket::SSL for more details.
654 ciphers => CIPHERS
656 Specify which subset of cipher suites are permissible for this
657 connection, using the standard OpenSSL string format. The
658 default behavior is to keep the decision on the underlying
659 cryptographic library.
660 clientcert => '/path/to/cert.pem'
662 clientkey => '/path/to/key.pem'
663 keydecrypt => sub { ... }
664 If you want to use the client to offer a certificate to the
665 server for SSL authentication (which is not the same as for the
666 LDAP Bind operation) then set clientcert to the user's
667 certificate file, and clientkey to the user's private key file.
668 These files must be in PEM format.
669 If the private key is encrypted (highly recommended) then
671 keydecrypt should be a subroutine that returns the decrypting
672 key. For example:
673 $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 );
675 $mesg = $ldap->start_tls(
676 verify => 'require',
677 clientcert => 'mycert.pem',
678 clientkey => 'mykey.pem',
679 keydecrypt => sub { 'secret'; },
680 capath => '/usr/local/cacerts/'
681 );
682 capath => '/path/to/servercerts/'
684 cafile => '/path/to/servercert.pem'
685 When verifying the server's certificate, either set capath to
686 the pathname of the directory containing CA certificates, or
687 set cafile to the filename containing the certificate of the CA
688 who signed the server's certificate. These certificates must
689 all be in PEM format.
690 The directory in 'capath' must contain certificates named using
692 the hash value of the certificates' subject names. To generate
693 these names, use OpenSSL like this in Unix:
694 ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
696 (assuming that the certificate of the CA is in cacert.pem.)
698 checkcrl => 1
700 If capath has been configured, then it will also be searched
701 for certificate revocation lists (CRLs) when verifying the
702 server's certificate. The CRLs' names must follow the form
703 hash.rnum where hash is the hash over the issuer's DN and num
704 is a number starting with 0.
705 See "SSL_check_crl" in IO::Socket::SSL for further information.
707 unbind ( )
709 The unbind method does not take any parameters and will unbind you
710 from the server. Some servers may allow you to re-bind or perform
711 other operations after unbinding. If you wish to switch to another
712 set of credentials while continuing to use the same connection, re-
713 binding with another DN and password, without unbind-ing, will
714 generally work.
715 Example
717 $mesg = $ldap->unbind;
719 done ( )
721 Convenience alias for "unbind()", named after the clean-up method
722 of Net::LDAP::LDIF.
723 The following methods are for convenience, and do not return
725 "Net::LDAP::Message" objects.
726 async ( VALUE )
728 If "VALUE" is given the async mode will be set. The previous value
729 will be returned. The value is true if LDAP operations are being
730 performed asynchronously.
731 certificate ( )
733 Returns an X509_Certificate object containing the server's
734 certificate. See the IO::Socket::SSL documentation for information
735 about this class.
736 For example, to get the subject name (in a peculiar OpenSSL-
738 specific format, different from RFC 1779 and RFC 4514) from the
739 server's certificate, do this:
740 print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
742 cipher ( )
744 Returns the cipher mode being used by the connection, in the string
745 format used by OpenSSL.
746 debug ( VALUE )
748 If "VALUE" is given the debug bit-value will be set. The previous
749 value will be returned. Debug output will be sent to "STDERR". The
750 bits of this value are:
751 1 Show outgoing packets (using asn_hexdump).
753 2 Show incoming packets (using asn_hexdump).
754 4 Show outgoing packets (using asn_dump).
755 8 Show incoming packets (using asn_dump).
756 The default value is 0.
758 disconnect ( )
760 Disconnect from the server
761 root_dse ( OPTIONS )
763 The root_dse method retrieves cached information from the server's
764 rootDSE.
765 attrs => [ ATTR, ... ]
767 A reference to a list of attributes to be returned. If not
768 specified, then the following attributes will be requested
769 subschemaSubentry
771 namingContexts
772 altServer
773 supportedExtension
774 supportedFeatures
775 supportedControl
776 supportedSASLMechanisms
777 supportedLDAPVersion
778 The result is an object of class Net::LDAP::RootDSE.
780 Example
782 my $root = $ldap->root_dse;
784 # get naming Context
785 $root->get_value( 'namingContexts', asref => 1 );
786 # get supported LDAP versions
787 $root->supported_version;
788 As the root DSE may change in certain circumstances - for instance
790 when you change the connection using start_tls - you should always
791 use the root_dse method to return the most up-to-date copy of the
792 root DSE.
793 schema ( OPTIONS )
795 Read schema information from the server.
796 The result is an object of class Net::LDAP::Schema. Read this
798 documentation for further information about methods that can be
799 performed with this object.
800 dn => DN
802 If a DN is supplied, it will become the base object entry from
803 which the search for schema information will be conducted. If
804 no DN is supplied the base object entry will be determined from
805 the rootDSE entry.
806 Example
808 my $schema = $ldap->schema;
810 # get objectClasses
811 @ocs = $schema->all_objectclasses;
812 # Get the attributes
813 @atts = $schema->all_attributes;
814 socket ( )
816 Returns the underlying "IO::Socket" object being used.
817 host ( )
819 Returns the host to which the connection was established. For
820 LDAPI connections the socket path is returned.
821 port ( )
823 Returns the the port connected to or "undef" in case of LDAPI
824 connections.
825 uri ( )
827 Returns the URI connected to.
828 As the value returned is that element of the constructor's HOST
830 argument with which the connection was established this may or may
831 not be a legal URI.
832 scheme ( )
834 Returns the scheme of the connection. One of ldap, ldaps or ldapi.
835 sync ( MESG )
837 Wait for a given "MESG" request to be completed by the server. If
838 no "MESG" is given, then wait for all outstanding requests to be
839 completed.
840 Returns an error code defined in Net::LDAP::Constant.
842 process ( MESG )
844 Process any messages that the server has sent, but do not block. If
845 "MESG" is specified then return as soon as "MESG" has been
846 processed.
847 Returns an error code defined in Net::LDAP::Constant.
849 version ( )
851 Returns the version of the LDAP protocol that is being used.
852
854 Many of the methods described above accept a control option. This
855 allows the user to pass controls to the server as described in LDAPv3.
856 A control is a reference to a HASH and should contain the three
858 elements below. If any of the controls are blessed then the method
859 "to_asn" will be called which should return a reference to a HASH
860 containing the three elements described below.
861 For most purposes Net::LDAP::Control objects are the easiest way to
863 generate controls.
864 type => OID
866 This element must be present and is the name of the type of control
867 being requested.
868 critical => FLAG
870 critical is optional and should be a boolean value, if it is not
871 specified then it is assumed to be false.
872 value => VALUE
874 If the control being requested requires a value then this element
875 should hold the value for the server.
876
878 Most of the above commands accept a callback option. This option should
879 be a reference to a subroutine. This subroutine will be called for each
880 packet received from the server as a response to the request sent.
881 When the subroutine is called the first argument will be the
883 Net::LDAP::Message object which was returned from the method.
884 If the request is a search then multiple packets can be received from
886 the server. Each entry is received as a separate packet. For each of
887 these the subroutine will be called with a Net::LDAP::Entry object as
888 the second argument.
889 During a search the server may also send a list of references. When
891 such a list is received then the subroutine will be called with a
892 Net::LDAP::Reference object as the second argument.
893
895 Net::LDAP also exports constants for the error codes that can be
896 received from the server, see Net::LDAP::Constant.
897
899 Net::LDAP::Constant, Net::LDAP::Control, Net::LDAP::Entry,
900 Net::LDAP::Filter, Net::LDAP::Message, Net::LDAP::Reference,
901 Net::LDAP::Search, Net::LDAP::RFC
902 The homepage for the perl-ldap modules can be found at
904 http://ldap.perl.org/.
905
907 This document is based on a document originally written by Russell
908 Fulton <r.fulton@auckland.ac.nz>.
909 Chris Ridd <chris.ridd@isode.com> for the many hours spent testing and
911 contribution of the ldap* command line utilities.
912
914 A discussion mailing list is hosted by the Perl Foundation at
915 <perl-ldap@perl.org> No subscription is necessary!
916
918 We hope you do not find any, but if you do please report them to the
919 mailing list.
920 If you have a patch, please send it as an attachment to the mailing
922 list.
923
925 Graham Barr <gbarr@pobox.com>
926
928 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
929 is free software; you can redistribute it and/or modify it under the
930 same terms as Perl itself.
931perl v5.16.3 2018-10-30 Net::LDAP(3)