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 address. TCP port may be
63 specified after the host name followed by a colon (such as
64 localhost:10389). The default TCP port for LDAP is 389.
65 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 this option is given, Net::LDAP converts all values of
143 attributes not matching this REGEX into Perl UTF-8 strings so
144 that the regular Perl operators (pattern matching, ...) can
145 operate as one expects even on strings with international
146 characters.
147 If this option is not given, attribute values are treated as
149 byte strings.
150 Example: raw => qr/(?i:^jpegPhoto|;binary)/
152 inet4 => N
154 inet6 => N
155 Try to connect to the server using the specified IP protocol
156 only, i.e. either IPv4 or IPv6. If the protocol selected is
157 not supported, connecting will fail.
158 The default is to use any of the two protocols.
160 Example
162 $ldap = Net::LDAP->new( 'remote.host', async => 1 );
164 LDAPS connections have some extra valid options, see the start_tls
166 method for details. Note the default port for LDAPS is 636, and the
167 default value for 'sslversion' is the value used as default by
168 IO::Socket::SSL.
169 For LDAPI connections, HOST is actually the location of a UNIX
171 domain socket to connect to. The default location is
172 '/var/run/ldapi'.
173
175 Each of the following methods take as arguments some number of fixed
176 parameters followed by options, these options are passed in a named
177 fashion, for example
178 $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd");
180 The return value from these methods is an object derived from the
182 Net::LDAP::Message class. The methods of this class allow you to
183 examine the status of the request.
184 abandon ( ID, OPTIONS )
186 Abandon a previously issued request. "ID" may be a number or an
187 object which is a sub-class of Net::LDAP::Message, returned from a
188 previous method call.
189 control => CONTROL
191 control => [ CONTROL, ... ]
192 See "CONTROLS" below
193 callback => CALLBACK
195 See "CALLBACKS" below
196 Example
198 $res = $ldap->search( @search_args );
200 $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon
202 add ( DN, OPTIONS )
204 Add a new entry to the directory. "DN" can be either a
205 Net::LDAP::Entry object or a string.
206 attrs => [ ATTR => VALUE, ... ]
208 "VALUE" should be a string if only a single value is wanted, or
209 a reference to an array of strings if multiple values are
210 wanted.
211 This argument is not used if "DN" is a Net::LDAP::Entry object.
213 control => CONTROL
215 control => [ CONTROL, ... ]
216 See "CONTROLS" below
217 callback => CALLBACK
219 See "CALLBACKS" below
220 Example
222 # $entry is an object of class Net::LDAP::Entry
224 $mesg = $ldap->add( $entry );
225 $mesg = $ldap->add( $dn,
227 attrs => [
228 name => 'Graham Barr',
229 attr => 'value1',
230 attr => 'value2',
231 multi => [qw(value1 value2)]
232 ]
233 );
234 bind ( DN, OPTIONS )
236 Bind (log in) to the server. "DN" is the DN to bind with. An
237 anonymous bind may be done by calling bind without any arguments.
238 control => CONTROL
240 control => [ CONTROL, ... ]
241 See "CONTROLS" below
242 callback => CALLBACK
244 See "CALLBACKS" below
245 noauth | anonymous => 1
247 Bind without any password. The value passed with this option is
248 ignored.
249 password => PASSWORD
251 Bind with the given password.
252 sasl => SASLOBJ
254 Bind using a SASL mechanism. The argument given should be a
255 sub-class of Authen::SASL or an Authen::SASL client connection
256 by calling "client_new" on an Authen::SASL object.
257 If passed an Authen::SASL object then "client_new" will be
259 called to create a client connection object. The hostname
260 passed by "Net::LDAP" to "client_new" can be set using the
261 "sasl_host" option below. If this is not correct for your
262 environment, consider calling "client_new" yourself and passing
263 the client connection object as "SASLOBJ".
264 sasl_host => SASLHOST
266 When binding using SASL, allow the hostname used in the SASL
267 communication to differ from the hostname connected to.
268 If "SASLHOST" evaluates to TRUE, then it is used as the SASL
270 hostname.
271 If it evaluates to FALSE, then the value is determined by
273 calling "peerhost" on the socket. In older versions of
274 Net::LDAP this was the standard behaviour, but it turned out to
275 cause more trouble than it fixed.
276 When the option is not given, the SASL host name used defaults
278 to the host name / IP address taken from the "HOST" parameter
279 when connecting.
280 Example
282 $mesg = $ldap->bind; # Anonymous bind
284 $mesg = $ldap->bind( $dn, password => $password );
286 # $sasl is an object of class Authen::SASL
288 $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 );
289 compare ( DN, OPTIONS )
291 Compare values in an attribute in the entry given by "DN" on the
292 server. "DN" may be a string or a Net::LDAP::Entry object.
293 attr => ATTR
295 The name of the attribute to compare.
296 value => VALUE
298 The value to compare with.
299 control => CONTROL
301 control => [ CONTROL, ... ]
302 See "CONTROLS" below.
303 callback => CALLBACK
305 See "CALLBACKS" below.
306 Example
308 $mesg = $ldap->compare( $dn,
310 attr => 'cn',
311 value => 'Graham Barr'
312 );
313 delete ( DN, OPTIONS )
315 Delete the entry given by "DN" from the server. "DN" may be a
316 string or a Net::LDAP::Entry object.
317 control => CONTROL
319 control => [ CONTROL, ... ]
320 See "CONTROLS" below.
321 callback => CALLBACK
323 See "CALLBACKS" below.
324 Example
326 $mesg = $ldap->delete( $dn );
328 moddn ( DN, OPTIONS )
330 Rename the entry given by "DN" on the server. "DN" may be a string
331 or a Net::LDAP::Entry object.
332 newrdn => RDN
334 This value should be a new RDN to assign to "DN".
335 deleteoldrdn => 1
337 This option should be passed if the existing RDN is to be
338 deleted.
339 newsuperior => NEWDN
341 If given this value should be the DN of the new superior for
342 "DN".
343 control => CONTROL
345 control => [ CONTROL, ... ]
346 See "CONTROLS" below.
347 callback => CALLBACK
349 See "CALLBACKS" below.
350 Example
352 $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' );
354 modify ( DN, OPTIONS )
356 Modify the contents of the entry given by "DN" on the server. "DN"
357 may be a string or a Net::LDAP::Entry object.
358 add => { ATTR => VALUE, ... }
360 Add more attributes or values to the entry. "VALUE" should be a
361 string if only a single value is wanted in the attribute, or a
362 reference to an array of strings if multiple values are wanted.
363 $mesg = $ldap->modify( $dn,
365 add => {
366 description => 'List of members', # Add description attribute
367 member => [
368 'cn=member1,ou=people,dc=example,dc=com', # Add to attribute
369 'cn=member2,ou=people,dc=example,dc=com',
370 ]
371 }
372 );
373 delete => [ ATTR, ... ]
375 Delete complete attributes from the entry.
376 $mesg = $ldap->modify( $dn,
378 delete => ['member','description'] # Delete attributes
379 );
380 delete => { ATTR => VALUE, ... }
382 Delete individual values from an attribute. "VALUE" should be a
383 string if only a single value is being deleted from the
384 attribute, or a reference to an array of strings if multiple
385 values are being deleted.
386 If "VALUE" is a reference to an empty array or all existing
388 values of the attribute are being deleted, then the attribute
389 will be deleted from the entry.
390 $mesg = $ldap->modify( $dn,
392 delete => {
393 description => 'List of members',
394 member => [
395 'cn=member1,ou=people,dc=example,dc=com', # Remove members
396 'cn=member2,ou=people,dc=example,dc=com',
397 ],
398 seeAlso => [], # Remove attribute
399 }
400 );
401 replace => { ATTR => VALUE, ... }
403 Replace any existing values in each given attribute with
404 "VALUE". "VALUE" should be a string if only a single value is
405 wanted in the attribute, or a reference to an array of strings
406 if multiple values are wanted. A reference to an empty array
407 will remove the entire attribute. If the attribute does not
408 already exist in the entry, it will be created.
409 $mesg = $ldap->modify( $dn,
411 replace => {
412 description => 'New List of members', # Change the description
413 member => [ # Replace whole list with these
414 'cn=member1,ou=people,dc=example,dc=com',
415 'cn=member2,ou=people,dc=example,dc=com',
416 ],
417 seeAlso => [], # Remove attribute
418 }
419 );
420 increment => { ATTR => VALUE, ... }
422 Atomically increment the existing value in each given attribute
423 by the provided "VALUE". The attributes need to have integer
424 syntax, or be otherwise "incrementable". Note this will only
425 work if the server advertises support for
426 LDAP_FEATURE_MODIFY_INCREMENT. Use "supported_feature" in
427 Net::LDAP::RootDSE to check this.
428 $mesg = $ldap->modify( $dn,
430 increment => {
431 uidNumber => 1 # increment uidNumber by 1
432 }
433 );
434 changes => [ OP => [ ATTR => VALUE ], ... ]
436 This is an alternative to add, delete, replace and increment
437 where the whole operation can be given in a single argument.
438 "OP" should be add, delete, replace or increment. "VALUE"
439 should be either a string or a reference to an array of
440 strings, as before.
441 Use this form if you want to control the order in which the
443 operations will be performed.
444 $mesg = $ldap->modify( $dn,
446 changes => [
447 add => [
448 description => 'A description',
449 member => $newMember,
450 ],
451 delete => [
452 seeAlso => [],
453 ],
454 add => [
455 anotherAttribute => $value,
456 ],
457 ]
458 );
459 control => CONTROL
461 control => [ CONTROL, ... ]
462 See "CONTROLS" below.
463 callback => CALLBACK
465 See "CALLBACKS" below.
466 Example
468 $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } );
470 $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] );
472 $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } );
474 $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } );
476 $mesg = $ldap->modify( $dn,
478 changes => [
479 # add sn=Barr
480 add => [ sn => 'Barr' ],
481 # delete all fax numbers
482 delete => [ faxNumber => []],
483 # delete phone number 911
484 delete => [ telephoneNumber => ['911']],
485 # change email address
486 replace => [ mail => 'gbarr@pobox.com']
487 ]
488 );
489 search ( OPTIONS )
491 Search the directory using a given filter. This can be used to
492 read attributes from a single entry, from entries immediately below
493 a particular entry, or a whole subtree of entries.
494 The result is an object of class Net::LDAP::Search.
496 base => DN
498 The DN that is the base object entry relative to which the
499 search is to be performed.
500 scope => 'base' | 'one' | 'sub' | 'subtree' | 'children'
502 By default the search is performed on the whole tree below the
503 specified base object. This maybe changed by specifying a
504 "scope" parameter with one of the following values:
505 base
507 Search only the base object.
508 one Search the entries immediately below the base object.
510 sub
512 subtree
513 Search the whole tree below (and including) the base
514 object. This is the default.
515 children
517 Search the whole subtree below the base object, excluding
518 the base object itself.
519 Note: children scope requires LDAPv3 subordinate feature
521 extension.
522 deref => 'never' | 'search' | 'find' | 'always'
524 By default aliases are dereferenced to locate the base object
525 for the search, but not when searching subordinates of the base
526 object. This may be changed by specifying a "deref" parameter
527 with one of the following values:
528 never
530 Do not dereference aliases in searching or in locating the
531 base object of the search.
532 search
534 Dereference aliases in subordinates of the base object in
535 searching, but not in locating the base object of the
536 search.
537 find
539 Dereference aliases in locating the base object of the
540 search, but not when searching subordinates of the base
541 object. This is the default.
542 always
544 Dereference aliases both in searching and in locating the
545 base object of the search.
546 sizelimit => N
548 A sizelimit that restricts the maximum number of entries to be
549 returned as a result of the search. A value of 0, and the
550 default, means that no restriction is requested. Servers may
551 enforce a maximum number of entries to return.
552 timelimit => N
554 A timelimit that restricts the maximum time (in seconds)
555 allowed for a search. A value of 0 (the default), means that no
556 timelimit will be requested.
557 typesonly => 1
559 Only attribute types (no values) should be returned. Normally
560 attribute types and values are returned.
561 filter => FILTER
563 A filter that defines the conditions an entry in the directory
564 must meet in order for it to be returned by the search. This
565 may be a string or a Net::LDAP::Filter object. Values inside
566 filters may need to be escaped to avoid security problems; see
567 Net::LDAP::Filter for a definition of the filter format,
568 including the escaping rules.
569 attrs => [ ATTR, ... ]
571 A list of attributes to be returned for each entry that matches
572 the search filter.
573 If not specified, then the server will return the attributes
575 that are specified as accessible by default given your bind
576 credentials.
577 Certain additional attributes such as "createTimestamp" and
579 other operational attributes may also be available for the
580 asking:
581 $mesg = $ldap->search( ... ,
583 attrs => ['createTimestamp']
584 );
585 To retrieve the default attributes and additional ones, use
587 '*'.
588 $mesg = $ldap->search( ... ,
590 attrs => ['*', 'createTimestamp']
591 );
592 To retrieve no attributes (the server only returns the DNs of
594 matching entries), use '1.1':
595 $mesg = $ldap->search( ... ,
597 attrs => ['1.1']
598 );
599 control => CONTROL
601 control => [ CONTROL, ... ]
602 See "CONTROLS" below.
603 callback => CALLBACK
605 See "CALLBACKS" below.
606 raw => REGEX
608 Use REGEX to denote the names of attributes that are to be
609 considered binary in search results.
610 When this option is given, Net::LDAP converts all values of
612 attributes not matching this REGEX into Perl UTF-8 strings so
613 that the regular Perl operators (pattern matching, ...) can
614 operate as one expects even on strings with international
615 characters.
616 If this option is not given, attribute values are treated as
618 byte strings.
619 The value provided here overwrites the value inherited from the
621 constructor.
622 Example: raw => qr/(?i:^jpegPhoto|;binary)/
624 Example
626 $mesg = $ldap->search(
628 base => $base_dn,
629 scope => 'sub',
630 filter => '(|(objectclass=rfc822mailgroup)(sn=jones))'
631 );
632 Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries );
634 start_tls ( OPTIONS )
636 Calling this method will convert the existing connection to using
637 Transport Layer Security (TLS), which provides an encrypted
638 connection. This is only possible if the connection uses LDAPv3,
639 and requires that the server advertises support for
640 LDAP_EXTENSION_START_TLS. Use "supported_extension" in
641 Net::LDAP::RootDSE to check this.
642 verify => 'none' | 'optional' | 'require'
644 How to verify the server's certificate:
645 none
647 The server may provide a certificate but it will not be
648 checked - this may mean you are be connected to the wrong
649 server
650 optional
652 Verify only when the server offers a certificate
653 require
655 The server must provide a certificate, and it must be
656 valid.
657 If you set verify to optional or require, you must also set
659 either cafile or capath. The most secure option is require.
660 sslversion => 'sslv2' | 'sslv3' | 'sslv23' | 'tlsv1' | 'tlsv1_1' |
662 'tlsv1_2'
663 This defines the version of the SSL/TLS protocol to use.
664 Default is to use the value that IO::Socket::SSL uses as
665 default.
666 See "SSL_version" in IO::Socket::SSL for more details.
668 ciphers => CIPHERS
670 Specify which subset of cipher suites are permissible for this
671 connection, using the standard OpenSSL string format. The
672 default behavior is to keep the decision on the underlying
673 cryptographic library.
674 clientcert => '/path/to/cert.pem'
676 clientkey => '/path/to/key.pem'
677 keydecrypt => sub { ... }
678 If you want to use the client to offer a certificate to the
679 server for SSL authentication (which is not the same as for the
680 LDAP Bind operation) then set clientcert to the user's
681 certificate file, and clientkey to the user's private key file.
682 These files must be in PEM format.
683 If the private key is encrypted (highly recommended) then
685 keydecrypt should be a subroutine that returns the decrypting
686 key. For example:
687 $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 );
689 $mesg = $ldap->start_tls(
690 verify => 'require',
691 clientcert => 'mycert.pem',
692 clientkey => 'mykey.pem',
693 keydecrypt => sub { 'secret'; },
694 capath => '/usr/local/cacerts/'
695 );
696 capath => '/path/to/servercerts/'
698 cafile => '/path/to/servercert.pem'
699 When verifying the server's certificate, either set capath to
700 the pathname of the directory containing CA certificates, or
701 set cafile to the filename containing the certificate of the CA
702 who signed the server's certificate. These certificates must
703 all be in PEM format.
704 The directory in 'capath' must contain certificates named using
706 the hash value of the certificates' subject names. To generate
707 these names, use OpenSSL like this in Unix:
708 ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0
710 (assuming that the certificate of the CA is in cacert.pem.)
712 checkcrl => 1
714 If capath has been configured, then it will also be searched
715 for certificate revocation lists (CRLs) when verifying the
716 server's certificate. The CRLs' names must follow the form
717 hash.rnum where hash is the hash over the issuer's DN and num
718 is a number starting with 0.
719 See "SSL_check_crl" in IO::Socket::SSL for further information.
721 unbind ( )
723 The unbind method does not take any parameters and will unbind you
724 from the server. Some servers may allow you to re-bind or perform
725 other operations after unbinding. If you wish to switch to another
726 set of credentials while continuing to use the same connection, re-
727 binding with another DN and password, without unbind-ing, will
728 generally work.
729 Example
731 $mesg = $ldap->unbind;
733 done ( )
735 Convenience alias for "unbind()", named after the clean-up method
736 of Net::LDAP::LDIF.
737 The following methods are for convenience, and do not return
739 "Net::LDAP::Message" objects.
740 async ( VALUE )
742 If "VALUE" is given the async mode will be set. The previous value
743 will be returned. The value is true if LDAP operations are being
744 performed asynchronously.
745 certificate ( )
747 Returns an X509_Certificate object containing the server's
748 certificate. See the IO::Socket::SSL documentation for information
749 about this class.
750 For example, to get the subject name (in a peculiar OpenSSL-
752 specific format, different from RFC 1779 and RFC 4514) from the
753 server's certificate, do this:
754 print "Subject DN: " . $ldaps->certificate->subject_name . "\n";
756 cipher ( )
758 Returns the cipher mode being used by the connection, in the string
759 format used by OpenSSL.
760 debug ( VALUE )
762 If "VALUE" is given the debug bit-value will be set. The previous
763 value will be returned. Debug output will be sent to "STDERR". The
764 bits of this value are:
765 1 Show outgoing packets (using asn_hexdump).
767 2 Show incoming packets (using asn_hexdump).
768 4 Show outgoing packets (using asn_dump).
769 8 Show incoming packets (using asn_dump).
770 The default value is 0.
772 disconnect ( )
774 Disconnect from the server
775 root_dse ( OPTIONS )
777 The root_dse method retrieves cached information from the server's
778 rootDSE.
779 attrs => [ ATTR, ... ]
781 A reference to a list of attributes to be returned. If not
782 specified, then the following attributes will be requested
783 subschemaSubentry
785 namingContexts
786 altServer
787 supportedExtension
788 supportedFeatures
789 supportedControl
790 supportedSASLMechanisms
791 supportedLDAPVersion
792 The result is an object of class Net::LDAP::RootDSE.
794 Example
796 my $root = $ldap->root_dse;
798 # get naming Context
799 $root->get_value( 'namingContexts', asref => 1 );
800 # get supported LDAP versions
801 $root->supported_version;
802 As the root DSE may change in certain circumstances - for instance
804 when you change the connection using start_tls - you should always
805 use the root_dse method to return the most up-to-date copy of the
806 root DSE.
807 schema ( OPTIONS )
809 Read schema information from the server.
810 The result is an object of class Net::LDAP::Schema. Read this
812 documentation for further information about methods that can be
813 performed with this object.
814 dn => DN
816 If a DN is supplied, it will become the base object entry from
817 which the search for schema information will be conducted. If
818 no DN is supplied the base object entry will be determined from
819 the rootDSE entry.
820 Example
822 my $schema = $ldap->schema;
824 # get objectClasses
825 @ocs = $schema->all_objectclasses;
826 # Get the attributes
827 @atts = $schema->all_attributes;
828 sasl ( )
830 Returns the "Authen::SASL" object associated with the LDAP object,
831 or "undef" if there isn't.
832 socket ( OPTIONS )
834 Returns the underlying socket object being used.
835 The exact object type returned depends on whether SASL layers are
837 established. Without SASL layers the result is always an
838 "IO::Socket" object; with SASL layers the outcome depends on the
839 options given:
840 sasl_layer => FLAG
842 This option is only relevant if SASL layers are established.
843 If it it missing or if is set to a TRUE value, then the SASL
845 layer handle is returned. Depending on the SASL library used,
846 the object returned is not necessarily an "IO::Socket" object.
847 If it exists, but is set to a value evaluating to FALSE, then
849 the base "IO::Socket" object underneath the SASL layer is
850 returned.
851 host ( )
853 Returns the host to which the connection was established. For
854 LDAPI connections the socket path is returned.
855 port ( )
857 Returns the port connected to or "undef" in case of LDAPI
858 connections.
859 uri ( )
861 Returns the URI connected to.
862 As the value returned is that element of the constructor's HOST
864 argument with which the connection was established this may or may
865 not be a legal URI.
866 scheme ( )
868 Returns the scheme of the connection. One of ldap, ldaps or ldapi.
869 sync ( MESG )
871 Wait for a given "MESG" request to be completed by the server. If
872 no "MESG" is given, then wait for all outstanding requests to be
873 completed.
874 Returns an error code defined in Net::LDAP::Constant.
876 process ( MESG )
878 Process any messages that the server has sent, but do not block. If
879 "MESG" is specified then return as soon as "MESG" has been
880 processed.
881 Returns an error code defined in Net::LDAP::Constant.
883 version ( )
885 Returns the version of the LDAP protocol that is being used.
886
888 Many of the methods described above accept a control option. This
889 allows the user to pass controls to the server as described in LDAPv3.
890 A control is a reference to a HASH and should contain the three
892 elements below. If any of the controls are blessed then the method
893 "to_asn" will be called which should return a reference to a HASH
894 containing the three elements described below.
895 For most purposes Net::LDAP::Control objects are the easiest way to
897 generate controls.
898 type => OID
900 This element must be present and is the name of the type of control
901 being requested.
902 critical => FLAG
904 critical is optional and should be a Boolean value, if it is not
905 specified then it is assumed to be false.
906 value => VALUE
908 If the control being requested requires a value then this element
909 should hold the value for the server.
910
912 Most of the above commands accept a callback option. This option should
913 be a reference to a subroutine. This subroutine will be called for each
914 packet received from the server as a response to the request sent.
915 When the subroutine is called the first argument will be the
917 Net::LDAP::Message object which was returned from the method.
918 If the request is a search then multiple packets can be received from
920 the server. Each entry is received as a separate packet. For each of
921 these the subroutine will be called with a Net::LDAP::Entry object as
922 the second argument.
923 During a search the server may also send a list of references. When
925 such a list is received then the subroutine will be called with a
926 Net::LDAP::Reference object as the second argument.
927
929 Net::LDAP also exports constants for the error codes that can be
930 received from the server, see Net::LDAP::Constant.
931
933 Net::LDAP::Constant, Net::LDAP::Control, Net::LDAP::Entry,
934 Net::LDAP::Filter, Net::LDAP::Message, Net::LDAP::Reference,
935 Net::LDAP::Search, Net::LDAP::RFC
936 The homepage for the perl-ldap modules can be found at
938 http://ldap.perl.org/.
939
941 This document is based on a document originally written by Russell
942 Fulton <r.fulton@auckland.ac.nz>.
943 Chris Ridd <chris.ridd@isode.com> for the many hours spent testing and
945 contribution of the ldap* command line utilities.
946
948 A discussion mailing list is hosted by the Perl Foundation at
949 <perl-ldap@perl.org> No subscription is necessary!
950
952 We hope you do not find any, but if you do please report them to the
953 mailing list.
954 If you have a patch, please send it as an attachment to the mailing
956 list.
957
959 Graham Barr <gbarr@pobox.com>
960
962 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
963 is free software; you can redistribute it and/or modify it under the
964 same terms as Perl itself.
965perl v5.28.0 2015-04-06 Net::LDAP(3)