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 attr => [
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 timeout => N
88 Timeout passed to IO::Socket when connecting the remote server.
89 (Default: 120)
90 multihomed => N
92 Will be passed to IO::Socket as the "MultiHomed" parameter when
93 connecting to the remote server
94 localaddr => HOST
96 Will be passed to IO::Socket as the "LocalAddr" parameter,
97 which sets the client's IP address (as opposed to the server's
98 IP address.)
99 debug => N
101 Set the debug level. See the debug method for details.
102 async => 1
104 Perform all operations asynchronously.
105 onerror => 'die' | 'warn' | undef | sub { ... }
107 In synchronous mode, change what happens when an error is
108 detected.
109 'die'
111 Net::LDAP will croak whenever an error is detected.
112 'warn'
114 Net::LDAP will warn whenever an error is detected.
115 undef
117 Net::LDAP will warn whenever an error is detected and "-w"
118 is in effect. The method that was called will return
119 "undef".
120 sub { ... }
122 The given sub will be called in a scalar context with a
123 single argument, the result message. The value returned
124 will be the return value for the method that was called.
125 version => N
127 Set the protocol version being used (default is LDAPv3). This
128 is useful if you want to talk to an old server and therefore
129 have to use LDAPv2.
130 raw => REGEX
132 Use REGEX to denote the names of attributes that are to be
133 considered binary in search results.
134 When running on Perl 5.8 and this option is given Net::LDAP
136 converts all values of attributes not matching this REGEX into
137 Perl UTF-8 strings so that the regular Perl operators (pattern
138 matching, ...) can operate as one expects even on strings with
139 international characters.
140 If this option is not given or the version of Perl Net::LDAP is
142 running on is too old strings are encoded the same as in
143 earlier versions of perl-ldap.
144 Example: raw => qr/(?i:^jpegPhoto|;binary)/
146 inet6 => N
148 Try to connect to the server using IPv6 if "HOST" resolves to
149 an IPv6 target address. If it resolves to an IPv4 address, the
150 connection is tried using IPv4, the same way as if this option
151 was not given.
152 Please note that IPv6 support is considered experimental in
154 IO::Socket::SSL, which is used of SSL/TLS support, and there
155 are a few issues to take care of. See "IPv6" in IO::Socket::SSL
156 for details.
157 Example
159 $ldap = Net::LDAP->new( 'remote.host', async => 1 );
161 LDAPS connections have some extra valid options, see the start_tls
163 method for details. Note the default value for 'sslversion' for
164 LDAPS is 'sslv2/3', and the default port for LDAPS is 636.
165 For LDAPI connections, HOST is actually the location of a UNIX
167 domain socket to connect to. The default location is
168 '/var/run/ldapi'.
169
171 Each of the following methods take as arguments some number of fixed
172 parameters followed by options, these options are passed in a named
173 fashion, for example
174 $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd");
176 The return value from these methods is an object derived from the
178 Net::LDAP::Message class. The methods of this class allow you to
179 examine the status of the request.
180 abandon ( ID, OPTIONS )
182 Abandon a previously issued request. "ID" may be a number or an
183 object which is a sub-class of Net::LDAP::Message, returned from a
184 previous method call.
185 control => CONTROL
187 control => [ CONTROL, ... ]
188 See "CONTROLS" below
189 callback => CALLBACK
191 See "CALLBACKS" below
192 Example
194 $res = $ldap->search( @search_args );
196 $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon
198 add ( DN, OPTIONS )
200 Add a new entry to the directory. "DN" can be either a
201 Net::LDAP::Entry object or a string.
202 attrs => [ ATTR => VALUE, ... ]
204 "VALUE" should be a string if only a single value is wanted, or
205 a reference to an array of strings if multiple values are
206 wanted.
207 This argument is not used if "DN" is a Net::LDAP::Entry object.
209 control => CONTROL
211 control => [ CONTROL, ... ]
212 See "CONTROLS" below
213 callback => CALLBACK
215 See "CALLBACKS" below
216 Example
218 # $entry is an object of class Net::LDAP::Entry
220 $mesg = $ldap->add( $entry );
221 $mesg = $ldap->add( $dn,
223 attrs => [
224 name => 'Graham Barr',
225 attr => 'value1',
226 attr => 'value2',
227 multi => [qw(value1 value2)]
228 ]
229 );
230 bind ( DN, OPTIONS )
232 Bind (log in) to the server. "DN" is the DN to bind with. An
233 anonymous bind may be done by calling bind without any arguments.
234 control => CONTROL
236 control => [ CONTROL, ... ]
237 See "CONTROLS" below
238 callback => CALLBACK
240 See "CALLBACKS" below
241 noauth | anonymous => 1
243 Bind without any password. The value passed with this option is
244 ignored.
245 password => PASSWORD
247 Bind with the given password.
248 sasl => SASLOBJ
250 Bind using a SASL mechanism. The argument given should be a
251 sub-class of Authen::SASL or an Authen::SASL client connection
252 by calling "client_new" on an Authen::SASL object.
253 If passed an Authen::SASL object then "client_new" will be
255 called to create a client connection object. The hostname
256 passed by "Net::LDAP" to "client_new" is the result of calling
257 "peerhost" on the socket. If this is not correct for your
258 environment, consider calling "client_new" and passing the
259 client connection object.
260 Example
262 $mesg = $ldap->bind; # Anonymous bind
264 $mesg = $ldap->bind( $dn, password => $password );
266 # $sasl is an object of class Authen::SASL
268 $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 );
269 compare ( DN, OPTIONS )
271 Compare values in an attribute in the entry given by "DN" on the
272 server. "DN" may be a string or a Net::LDAP::Entry object.
273 attr => ATTR
275 The name of the attribute to compare.
276 value => VALUE
278 The value to compare with.
279 control => CONTROL
281 control => [ CONTROL, ... ]
282 See "CONTROLS" below.
283 callback => CALLBACK
285 See "CALLBACKS" below.
286 Example
288 $mesg = $ldap->compare( $dn,
290 attr => 'cn',
291 value => 'Graham Barr'
292 );
293 delete ( DN, OPTIONS )
295 Delete the entry given by "DN" from the server. "DN" may be a
296 string or a Net::LDAP::Entry object.
297 control => CONTROL
299 control => [ CONTROL, ... ]
300 See "CONTROLS" below.
301 callback => CALLBACK
303 See "CALLBACKS" below.
304 Example
306 $mesg = $ldap->delete( $dn );
308 moddn ( DN, OPTIONS )
310 Rename the entry given by "DN" on the server. "DN" may be a string
311 or a Net::LDAP::Entry object.
312 newrdn => RDN
314 This value should be a new RDN to assign to "DN".
315 deleteoldrdn => 1
317 This option should be passed if the existing RDN is to be
318 deleted.
319 newsuperior => NEWDN
321 If given this value should be the DN of the new superior for
322 "DN".
323 control => CONTROL
325 control => [ CONTROL, ... ]
326 See "CONTROLS" below.
327 callback => CALLBACK
329 See "CALLBACKS" below.
330 Example
332 $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' );
334 modify ( DN, OPTIONS )
336 Modify the contents of the entry given by "DN" on the server. "DN"
337 may be a string or a Net::LDAP::Entry object.
338 add => { ATTR => VALUE, ... }
340 Add more attributes or values to the entry. "VALUE" should be a
341 string if only a single value is wanted in the attribute, or a
342 reference to an array of strings if multiple values are wanted.
343 $mesg = $ldap->modify( $dn,
345 add => {
346 description => 'List of members', # Add description attribute
347 member => [
348 'cn=member1,ou=people,dc=example,dc=com', # Add to attribute
349 'cn=member2,ou=people,dc=example,dc=com',
350 ]
351 }
352 );
353 delete => [ ATTR, ... ]
355 Delete complete attributes from the entry.
356 $mesg = $ldap->modify( $dn,
358 delete => ['member','description'] # Delete attributes
359 );
360 delete => { ATTR => VALUE, ... }
362 Delete individual values from an attribute. "VALUE" should be a
363 string if only a single value is being deleted from the
364 attribute, or a reference to an array of strings if multiple
365 values are being deleted.
366 If "VALUE" is a reference to an empty array or all existing
368 values of the attribute are being deleted, then the attribute
369 will be deleted from the entry.
370 $mesg = $ldap->modify( $dn,
372 delete => {
373 description => 'List of members',
374 member => [
375 'cn=member1,ou=people,dc=example,dc=com', # Remove members
376 'cn=member2,ou=people,dc=example,dc=com',
377 ],
378 seeAlso => [], # Remove attribute
379 }
380 );
381 replace => { ATTR => VALUE, ... }
383 Replace any existing values in each given attribute with
384 "VALUE". "VALUE" should be a string if only a single value is
385 wanted in the attribute, or a reference to an array of strings
386 if multiple values are wanted. A reference to an empty array
387 will remove the entire attribute. If the attribute does not
388 already exist in the entry, it will be created.
389 $mesg = $ldap->modify( $dn,
391 replace => {
392 description => 'New List of members', # Change the description
393 member => [ # Replace whole list with these
394 'cn=member1,ou=people,dc=example,dc=com',
395 'cn=member2,ou=people,dc=example,dc=com',
396 ],
397 seeAlso => [], # Remove attribute
398 }
399 );
400 increment => { ATTR => VALUE, ... }
402 Atomically increment the existing value in each given attribute
403 by the provided "VALUE". The attributes need to have integer
404 syntax, or be otherwise "incrementable". Note this will only
405 work if the server advertises support for
406 LDAP_FEATURE_MODIFY_INCREMENT. Use "supported_feature" in
407 Net::LDAP::RootDSE to check this.
408 $mesg = $ldap->modify( $dn,
410 increment => {
411 uidNumber => 1 # increment uidNumber by 1
412 }
413 );
414 changes => [ OP => [ ATTR => VALUE ], ... ]
416 This is an alternative to add, delete, replace and increment
417 where the whole operation can be given in a single argument.
418 "OP" should be add, delete, replace or increment. "VALUE"
419 should be either a string or a reference to an array of
420 strings, as before.
421 Use this form if you want to control the order in which the
423 operations will be performed.
424 $mesg = $ldap->modify( $dn,
426 changes => [
427 add => [
428 description => 'A description',
429 member => $newMember,
430 ],
431 delete => [
432 seeAlso => [],
433 ],
434 add => [
435 anotherAttribute => $value,
436 ],
437 ]
438 );
439 control => CONTROL
441 control => [ CONTROL, ... ]
442 See "CONTROLS" below.
443 callback => CALLBACK
445 See "CALLBACKS" below.
446 Example
448 $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } );
450 $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] );
452 $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } );
454 $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } );
456 $mesg = $ldap->modify( $dn,
458 changes => [
459 # add sn=Barr
460 add => [ sn => 'Barr' ],
461 # delete all fax numbers
462 delete => [ faxNumber => []],
463 # delete phone number 911
464 delete => [ telephoneNumber => ['911']],
465 # change email address
466 replace => [ mail => 'gbarr@pobox.com']
467 ]
468 );
469 search ( OPTIONS )
471 Search the directory using a given filter. This can be used to
472 read attributes from a single entry, from entries immediately below
473 a particular entry, or a whole subtree of entries.
474 The result is an object of class Net::LDAP::Search.
476 base => DN
478 The DN that is the base object entry relative to which the
479 search is to be performed.
480 scope => 'base' | 'one' | 'sub'
482 By default the search is performed on the whole tree below the
483 specified base object. This maybe changed by specifying a
484 "scope" parameter with one of the following values:
485 base
487 Search only the base object.
488 one Search the entries immediately below the base object.
490 sub Search the whole tree below (and including) the base
492 object. This is the default.
493 deref => 'never' | 'search' | 'find' | 'always'
495 By default aliases are dereferenced to locate the base object
496 for the search, but not when searching subordinates of the base
497 object. This may be changed by specifying a "deref" parameter
498 with one of the following values:
499 never
501 Do not dereference aliases in searching or in locating the
502 base object of the search.
503 search
505 Dereference aliases in subordinates of the base object in
506 searching, but not in locating the base object of the
507 search.
508 find
510 Dereference aliases in locating the base object of the
511 search, but not when searching subordinates of the base
512 object. This is the default.
513 always
515 Dereference aliases both in searching and in locating the
516 base object of the search.
517 sizelimit => N
519 A sizelimit that restricts the maximum number of entries to be
520 returned as a result of the search. A value of 0, and the
521 default, means that no restriction is requested. Servers may
522 enforce a maximum number of entries to return.
523 timelimit => N
525 A timelimit that restricts the maximum time (in seconds)
526 allowed for a search. A value of 0 (the default), means that no
527 timelimit will be requested.
528 typesonly => 1
530 Only attribute types (no values) should be returned. Normally
531 attribute types and values are returned.
532 filter => FILTER
534 A filter that defines the conditions an entry in the directory
535 must meet in order for it to be returned by the search. This
536 may be a string or a Net::LDAP::Filter object. Values inside
537 filters may need to be escaped to avoid security problems; see
538 Net::LDAP::Filter for a definition of the filter format,
539 including the escaping rules.
540 attrs => [ ATTR, ... ]
542 A list of attributes to be returned for each entry that matches
543 the search filter.
544 If not specified, then the server will return the attributes
546 that are specified as accessible by default given your bind
547 credentials.
548 Certain additional attributes such as "createTimestamp" and
550 other operational attributes may also be available for the
551 asking:
552 $mesg = $ldap->search( ... ,
554 attrs => ['createTimestamp']
555 );
556 To retrieve the default attributes and additional ones, use
558 '*'.
559 $mesg = $ldap->search( ... ,
561 attrs => ['*', 'createTimestamp']
562 );
563 To retrieve no attributes (the server only returns the DNs of
565 matching entries), use '1.1':
566 $mesg = $ldap->search( ... ,
568 attrs => ['1.1']
569 );
570 control => CONTROL
572 control => [ CONTROL, ... ]
573 See "CONTROLS" below.
574 callback => CALLBACK
576 See "CALLBACKS" below.
577 raw => REGEX
579 Use REGEX to denote the names of attributes that are to be
580 considered binary in search results.
581 When running on Perl 5.8 and this option is given Net::LDAP
583 converts all values of attributes not matching this REGEX into
584 Perl UTF-8 strings so that the regular Perl operators (pattern
585 matching, ...) can operate as one expects even on strings with
586 international characters.
587 If this option is not given or the version of Perl Net::LDAP is
589 running on is too old strings are encoded the same as in
590 earlier versions of perl-ldap.
591 The value provided here overwrites the value inherited from the
593 constructor.
594 Example: raw => qr/(?i:^jpegPhoto|;binary)/
596 Example
598 $mesg = $ldap->search(
600 base => $base_dn,
601 scope => 'sub',
602 filter => '(|(objectclass=rfc822mailgroup)(sn=jones))'
603 );
604 Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries );
606 start_tls ( OPTIONS )
608 Calling this method will convert the existing connection to using
609 Transport Layer Security (TLS), which provides an encrypted
610 connection. This is only possible if the connection uses LDAPv3,
611 and requires that the server advertises support for
612 LDAP_EXTENSION_START_TLS. Use "supported_extension" in
613 Net::LDAP::RootDSE to check this.
614 verify => 'none' | 'optional' | 'require'
616 How to verify the server's certificate:
617 none
619 The server may provide a certificate but it will not be
620 checked - this may mean you are be connected to the wrong
621 server
622 optional
624 Verify only when the server offers a certificate
625 require
627 The server must provide a certificate, and it must be
628 valid.
629 If you set verify to optional or require, you must also set
631 either cafile or capath. The most secure option is require.
632 sslversion => 'sslv2' | 'sslv3' | 'sslv2/3' | 'tlsv1'
634 This defines the version of the SSL/TLS protocol to use.
635 Defaults to 'tlsv1'.
636 ciphers => CIPHERS
638 Specify which subset of cipher suites are permissible for this
639 connection, using the standard OpenSSL string format. The
640 default behavior is to keep the decision on the underlying
641 cryptographic library.
642 clientcert => '/path/to/cert.pem'
644 clientkey => '/path/to/key.pem'
645 keydecrypt => sub { ... }
646 If you want to use the client to offer a certificate to the
647 server for SSL authentication (which is not the same as for the
648 LDAP Bind operation) then set clientcert to the user's
649 certificate file, and clientkey to the user's private key file.
650 These files must be in PEM format.
651 If the private key is encrypted (highly recommended) then
653 keydecrypt should be a subroutine that returns the decrypting
654 key. For example:
655 $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 );
657 $mesg = $ldap->start_tls(
658 verify => 'require',
659 clientcert => 'mycert.pem',
660 clientkey => 'mykey.pem',
661 keydecrypt => sub { 'secret'; },
662 capath => '/usr/local/cacerts/'
663 );
664 capath => '/path/to/servercerts/'
666 cafile => '/path/to/servercert.pem'
667 When verifying the server's certificate, either set capath to
668 the pathname of the directory containing CA certificates, or
669 set cafile to the filename containing the certificate of the CA
670 who signed the server's certificate. These certificates must
671 all be in PEM format.
672 The directory in 'capath' must contain certificates named using
674 the hash value of the certificates' subject names. To generate
675 these names, use OpenSSL like this in Unix:
676 ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
678 (assuming that the certificate of the CA is in cacert.pem.)
680 checkcrl => 1
682 If capath has been configured, then it will also be searched
683 for certificate revocation lists (CRLs) when verifying the
684 server's certificate. The CRLs' names must follow the form
685 hash.rnum where hash is the hash over the issuer's DN and num
686 is a number starting with 0.
687 See "SSL_check_crl" in IO::Socket::SSL for further information.
689 unbind ( )
691 The unbind method does not take any parameters and will unbind you
692 from the server. Some servers may allow you to re-bind or perform
693 other operations after unbinding. If you wish to switch to another
694 set of credentials while continuing to use the same connection, re-
695 binding with another DN and password, without unbind-ing, will
696 generally work.
697 Example
699 $mesg = $ldap->unbind;
701 The following methods are for convenience, and do not return
703 "Net::LDAP::Message" objects.
704 async ( VALUE )
706 If "VALUE" is given the async mode will be set. The previous value
707 will be returned. The value is true if LDAP operations are being
708 performed asynchronously.
709 certificate ( )
711 Returns an X509_Certificate object containing the server's
712 certificate. See the IO::Socket::SSL documentation for information
713 about this class.
714 For example, to get the subject name (in a peculiar OpenSSL-
716 specific format, different from RFC 1779 and RFC 2253) from the
717 server's certificate, do this:
718 print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
720 cipher ( )
722 Returns the cipher mode being used by the connection, in the string
723 format used by OpenSSL.
724 debug ( VALUE )
726 If "VALUE" is given the debug bit-value will be set. The previous
727 value will be returned. Debug output will be sent to "STDERR". The
728 bits of this value are:
729 1 Show outgoing packets (using asn_hexdump).
731 2 Show incoming packets (using asn_hexdump).
732 4 Show outgoing packets (using asn_dump).
733 8 Show incoming packets (using asn_dump).
734 The default value is 0.
736 disconnect ( )
738 Disconnect from the server
739 root_dse ( OPTIONS )
741 The root_dse method retrieves cached information from the server's
742 rootDSE.
743 attrs => [ ATTR, ... ]
745 A reference to a list of attributes to be returned. If not
746 specified, then the following attributes will be requested
747 subschemaSubentry
749 namingContexts
750 altServer
751 supportedExtension
752 supportedFeatures
753 supportedControl
754 supportedSASLMechanisms
755 supportedLDAPVersion
756 The result is an object of class Net::LDAP::RootDSE.
758 Example
760 my $root = $ldap->root_dse;
762 # get naming Context
763 $root->get_value( 'namingContext', asref => 1 );
764 # get supported LDAP versions
765 $root->supported_version;
766 As the root DSE may change in certain circumstances - for instance
768 when you change the connection using start_tls - you should always
769 use the root_dse method to return the most up-to-date copy of the
770 root DSE.
771 schema ( OPTIONS )
773 Read schema information from the server.
774 The result is an object of class Net::LDAP::Schema. Read this
776 documentation for further information about methods that can be
777 performed with this object.
778 dn => DN
780 If a DN is supplied, it will become the base object entry from
781 which the search for schema information will be conducted. If
782 no DN is supplied the base object entry will be determined from
783 the rootDSE entry.
784 Example
786 my $schema = $ldap->schema;
788 # get objectClasses
789 @ocs = $schema->all_objectclasses;
790 # Get the attributes
791 @atts = $schema->all_attributes;
792 socket ( )
794 Returns the underlying "IO::Socket" object being used.
795 host ( )
797 Returns the host to which the connection was established. For
798 LDAPI connections the socket path is returned.
799 port ( )
801 Returns the the port connected to or "undef" in case of LDAPI
802 connections.
803 uri ( )
805 Returns the URI connected to.
806 As the value returned is that element of the constructor's HOST
808 argument with which the connection was established this may or may
809 not be a legal URI.
810 scheme ( )
812 Returns the scheme of the connection. One of ldap, ldaps or ldapi.
813 sync ( MESG )
815 Wait for a given "MESG" request to be completed by the server. If
816 no "MESG" is given, then wait for all outstanding requests to be
817 completed.
818 Returns an error code defined in Net::LDAP::Constant.
820 process ( MESG )
822 Process any messages that the server has sent, but do not block. If
823 "MESG" is specified then return as soon as "MESG" has been
824 processed.
825 Returns an error code defined in Net::LDAP::Constant.
827 version ( )
829 Returns the version of the LDAP protocol that is being used.
830
832 Many of the methods described above accept a control option. This
833 allows the user to pass controls to the server as described in LDAPv3.
834 A control is a reference to a HASH and should contain the three
836 elements below. If any of the controls are blessed then the method
837 "to_asn" will be called which should return a reference to a HASH
838 containing the three elements described below.
839 For most purposes Net::LDAP::Control objects are the easiest way to
841 generate controls.
842 type => OID
844 This element must be present and is the name of the type of control
845 being requested.
846 critical => FLAG
848 critical is optional and should be a boolean value, if it is not
849 specified then it is assumed to be false.
850 value => VALUE
852 If the control being requested requires a value then this element
853 should hold the value for the server.
854
856 Most of the above commands accept a callback option. This option should
857 be a reference to a subroutine. This subroutine will be called for each
858 packet received from the server as a response to the request sent.
859 When the subroutine is called the first argument will be the
861 Net::LDAP::Message object which was returned from the method.
862 If the request is a search then multiple packets can be received from
864 the server. Each entry is received as a separate packet. For each of
865 these the subroutine will be called with a Net::LDAP::Entry object as
866 the second argument.
867 During a search the server may also send a list of references. When
869 such a list is received then the subroutine will be called with a
870 Net::LDAP::Reference object as the second argument.
871
873 Net::LDAP also exports constants for the error codes that can be
874 received from the server, see Net::LDAP::Constant.
875
877 Net::LDAP::Constant, Net::LDAP::Control, Net::LDAP::Entry,
878 Net::LDAP::Filter, Net::LDAP::Message, Net::LDAP::Reference,
879 Net::LDAP::Search, Net::LDAP::RFC
880 The homepage for the perl-ldap modules can be found at
882 http://ldap.perl.org/.
883
885 This document is based on a document originally written by Russell
886 Fulton <r.fulton@auckland.ac.nz>.
887 Chris Ridd <chris.ridd@isode.com> for the many hours spent testing and
889 contribution of the ldap* command line utilities.
890
892 A discussion mailing list is hosted by the Perl Foundation at
893 <perl-ldap@perl.org> No subscription is necessary!
894
896 We hope you do not find any, but if you do please report them to the
897 mailing list.
898 If you have a patch, please send it as an attachment to the mailing
900 list.
901
903 Graham Barr <gbarr@pobox.com>
904
906 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
907 is free software; you can redistribute it and/or modify it under the
908 same terms as Perl itself.
909perl v5.10.1 2017-03-21 Net::LDAP(3)