[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 =head1 NAME 2 3 Net::LDAP - Lightweight Directory Access Protocol 4 5 =head1 SYNOPSIS 6 7 use Net::LDAP; 8 9 $ldap = Net::LDAP->new( 'ldap.bigfoot.com' ) or die "$@"; 10 11 $mesg = $ldap->bind ; # an anonymous bind 12 13 $mesg = $ldap->search( # perform a search 14 base => "c=US", 15 filter => "(&(sn=Barr) (o=Texas Instruments))" 16 ); 17 18 $mesg->code && die $mesg->error; 19 20 foreach $entry ($mesg->entries) { $entry->dump; } 21 22 $mesg = $ldap->unbind; # take down session 23 24 25 $ldap = Net::LDAP->new( 'ldap.umich.edu' ); 26 27 # bind to a directory with dn and password 28 $mesg = $ldap->bind( 'cn=root, o=University of Michigan, c=us', 29 password => 'secret' 30 ); 31 32 $result = $ldap->add( 'cn=Barbara Jensen, o=University of Michigan, c=US', 33 attr => [ 34 'cn' => ['Barbara Jensen', 'Barbs Jensen'], 35 'sn' => 'Jensen', 36 'mail' => 'b.jensen@umich.edu', 37 'objectclass' => ['top', 'person', 38 'organizationalPerson', 39 'inetOrgPerson' ], 40 ] 41 ); 42 43 $result->code && warn "failed to add entry: ", $result->error ; 44 $mesg = $ldap->unbind; # take down session 45 46 =head1 DESCRIPTION 47 48 B<Net::LDAP> is a collection of modules that implements a LDAP 49 services API for Perl programs. The module may be used to search 50 directories or perform maintenance functions such as adding, deleting 51 or modifying entries. 52 53 This document assumes that the reader has some knowledge of the LDAP 54 protocol. 55 56 =head1 CONSTRUCTOR 57 58 =over 4 59 60 =item new ( HOST, OPTIONS ) 61 62 Creates a new B<Net::LDAP> object and opens a connection to the named host. 63 64 C<HOST> may be a host name or an IP number. TCP port may be specified 65 after the host name followed by a colon (such as localhost:10389). The 66 default TCP port for LDAP is 389. 67 68 You can also specify a URI, such as 'ldaps://127.0.0.1:666' or 69 'ldapi://%2fvar%2flib%2fldap_sock'. Note that '%2f's in the LDAPI 70 socket path will be translated into '/'. This is to support LDAP query 71 options like base, search etc. although the query part of the URI will 72 be ignored in this context. If port was not specified in the URI, the 73 default is either 389 or 636 for 'LDAP' and 'LDAPS' schemes 74 respectively. 75 76 C<HOST> may also be a reference to an array of hosts, host-port pairs 77 or URIs to try. Each will be tried in order until a connection is 78 made. Only when all have failed will the result of C<undef> be 79 returned. 80 81 =over 4 82 83 =item port =E<gt> N 84 85 Port to connect to on the remote server. May be overridden by C<HOST>. 86 87 =item scheme =E<gt> 'ldap' | 'ldaps' | 'ldapi' 88 89 Connection scheme to use when not using an URI as C<HOST>. 90 (Default: ldap) 91 92 =item timeout =E<gt> N 93 94 Timeout passed to L<IO::Socket> when connecting the remote server. 95 (Default: 120) 96 97 =item multihomed =E<gt> N 98 99 Will be passed to L<IO::Socket> as the C<MultiHomed> parameter 100 when connecting to the remote server 101 102 =item localaddr =E<gt> HOST 103 104 Will be passed to L<IO::Socket> as the C<LocalAddr> parameter, which 105 sets the client's IP address (as opposed to the server's IP address.) 106 107 =item debug =E<gt> N 108 109 Set the debug level. See the L<debug|/debug> method for details. 110 111 =item async =E<gt> 1 112 113 Perform all operations asynchronously. 114 115 =item onerror =E<gt> 'die' | 'warn' | undef | sub { ... } 116 117 In synchronous mode, change what happens when an error is detected. 118 119 =over 4 120 121 =item 'die' 122 123 Net::LDAP will croak whenever an error is detected. 124 125 =item 'warn' 126 127 Net::LDAP will warn whenever an error is detected. 128 129 =item undef 130 131 Net::LDAP will warn whenever an error is detected and C<-w> is in 132 effect. The method that was called will return C<undef>. 133 134 =item sub { ... } 135 136 The given sub will be called in a scalar context with a single 137 argument, the result message. The value returned will be the return 138 value for the method that was called. 139 140 =back 141 142 =item version =E<gt> N 143 144 Set the protocol version being used (default is LDAPv3). This is 145 useful if you want to talk to an old server and therefore have to use 146 LDAPv2. 147 148 =item raw =E<gt> REGEX 149 150 Use REGEX to denote the names of attributes that are to be considered 151 binary in search results. 152 153 When running on Perl 5.8 and this option is given Net::LDAP converts all 154 values of attributes not matching this REGEX into Perl UTF-8 strings 155 so that the regular Perl operators (pattern matching, ...) can operate 156 as one expects even on strings with international characters. 157 158 If this option is not given or the version of Perl Net::LDAP is running 159 on is too old strings are encoded the same as in earlier versions of 160 perl-ldap. 161 162 Example: raw =E<gt> qr/(?i:^jpegPhoto|;binary)/ 163 164 =item inet6 =E<gt> N 165 166 Try to connect to the server using IPv6 if C<HOST> resolves to an 167 IPv6 target address. 168 If it resolves to an IPv4 address, the connection is tried using IPv4, 169 the same way as if this option was not given. 170 171 Please note that IPv6 support is considered experimental in 172 IO::Socket::SSL, which is used of SSL/TLS support, and there are a few 173 issues to take care of. See L<IO::Socket::SSL/IPv6> for details. 174 175 =back 176 177 B<Example> 178 179 $ldap = Net::LDAP->new( 'remote.host', async => 1 ); 180 181 LDAPS connections have some extra valid options, see the 182 L<start_tls|/start_tls> method for details. Note the default value for 183 'sslversion' for LDAPS is 'sslv2/3', and the default port for LDAPS 184 is 636. 185 186 For LDAPI connections, HOST is actually the location of a UNIX domain 187 socket to connect to. The default location is '/var/run/ldapi'. 188 189 =back 190 191 =head1 METHODS 192 193 Each of the following methods take as arguments some number of fixed 194 parameters followed by options, these options are passed in a named 195 fashion, for example 196 197 $mesg = $ldap->bind( "cn=me,o=example", password => "mypasswd"); 198 199 The return value from these methods is an object derived from the 200 L<Net::LDAP::Message> class. The methods of this class allow 201 you to examine the status of the request. 202 203 204 =over 4 205 206 =item abandon ( ID, OPTIONS ) 207 208 Abandon a previously issued request. C<ID> may be a number or an 209 object which is a sub-class of L<Net::LDAP::Message>, returned from a 210 previous method call. 211 212 =over 4 213 214 =item control =E<gt> CONTROL 215 216 =item control =E<gt> [ CONTROL, ... ] 217 218 See L</CONTROLS> below 219 220 =item callback =E<gt> CALLBACK 221 222 See L</CALLBACKS> below 223 224 =back 225 226 B<Example> 227 228 $res = $ldap->search( @search_args ); 229 230 $mesg = $ldap->abandon( $res ); # This could be written as $res->abandon 231 232 233 =item add ( DN, OPTIONS ) 234 235 Add a new entry to the directory. C<DN> can be either a 236 L<Net::LDAP::Entry> object or a string. 237 238 =over 4 239 240 =item attrs =E<gt> [ ATTR =E<gt> VALUE, ... ] 241 242 C<VALUE> should be a string if only a single value is wanted, or a 243 reference to an array of strings if multiple values are wanted. 244 245 This argument is not used if C<DN> is a L<Net::LDAP::Entry> object. 246 247 =item control =E<gt> CONTROL 248 249 =item control =E<gt> [ CONTROL, ... ] 250 251 See L</CONTROLS> below 252 253 =item callback =E<gt> CALLBACK 254 255 See L</CALLBACKS> below 256 257 =back 258 259 B<Example> 260 261 # $entry is an object of class Net::LDAP::Entry 262 $mesg = $ldap->add( $entry ); 263 264 $mesg = $ldap->add( $dn, 265 attrs => [ 266 name => 'Graham Barr', 267 attr => 'value1', 268 attr => 'value2', 269 multi => [qw(value1 value2)] 270 ] 271 ); 272 273 =item bind ( DN, OPTIONS ) 274 275 Bind (log in) to the server. C<DN> is the DN to bind with. An 276 anonymous bind may be done by calling bind without any arguments. 277 278 =over 4 279 280 =item control =E<gt> CONTROL 281 282 =item control =E<gt> [ CONTROL, ... ] 283 284 See L</CONTROLS> below 285 286 =item callback =E<gt> CALLBACK 287 288 See L</CALLBACKS> below 289 290 =item noauth | anonymous =E<gt> 1 291 292 Bind without any password. The value passed with this option is ignored. 293 294 =item password =E<gt> PASSWORD 295 296 Bind with the given password. 297 298 =item sasl =E<gt> SASLOBJ 299 300 Bind using a SASL mechanism. The argument given should be a sub-class 301 of L<Authen::SASL>. 302 303 =back 304 305 B<Example> 306 307 $mesg = $ldap->bind; # Anonymous bind 308 309 $mesg = $ldap->bind( $dn, password => $password ); 310 311 # $sasl is an object of class Authen::SASL 312 $mesg = $ldap->bind( $dn, sasl => $sasl, version => 3 ); 313 314 315 =item compare ( DN, OPTIONS ) 316 317 Compare values in an attribute in the entry given by C<DN> on the 318 server. C<DN> may be a string or a L<Net::LDAP::Entry> object. 319 320 =over 4 321 322 =item attr =E<gt> ATTR 323 324 The name of the attribute to compare. 325 326 =item value =E<gt> VALUE 327 328 The value to compare with. 329 330 =item control =E<gt> CONTROL 331 332 =item control =E<gt> [ CONTROL, ... ] 333 334 See L</CONTROLS> below. 335 336 =item callback =E<gt> CALLBACK 337 338 See L</CALLBACKS> below. 339 340 =back 341 342 B<Example> 343 344 $mesg = $ldap->compare( $dn, 345 attr => 'cn', 346 value => 'Graham Barr' 347 ); 348 349 =item delete ( DN, OPTIONS ) 350 351 Delete the entry given by C<DN> from the server. C<DN> may be a string 352 or a L<Net::LDAP::Entry> object. 353 354 =over 4 355 356 =item control =E<gt> CONTROL 357 358 =item control =E<gt> [ CONTROL, ... ] 359 360 See L</CONTROLS> below. 361 362 =item callback =E<gt> CALLBACK 363 364 See L</CALLBACKS> below. 365 366 =back 367 368 B<Example> 369 370 $mesg = $ldap->delete( $dn ); 371 372 =item moddn ( DN, OPTIONS ) 373 374 Rename the entry given by C<DN> on the server. C<DN> may be a string 375 or a L<Net::LDAP::Entry> object. 376 377 =over 4 378 379 =item newrdn =E<gt> RDN 380 381 This value should be a new RDN to assign to C<DN>. 382 383 =item deleteoldrdn =E<gt> 1 384 385 This option should be passwd if the existing RDN is to be deleted. 386 387 =item newsuperior =E<gt> NEWDN 388 389 If given this value should be the DN of the new superior for C<DN>. 390 391 =item control =E<gt> CONTROL 392 393 =item control =E<gt> [ CONTROL, ... ] 394 395 See L</CONTROLS> below. 396 397 =item callback =E<gt> CALLBACK 398 399 See L</CALLBACKS> below. 400 401 =back 402 403 B<Example> 404 405 $mesg = $ldap->moddn( $dn, newrdn => 'cn=Graham Barr' ); 406 407 =item modify ( DN, OPTIONS ) 408 409 Modify the contents of the entry given by C<DN> on the server. C<DN> 410 may be a string or a L<Net::LDAP::Entry> object. 411 412 =over 4 413 414 =item add =E<gt> { ATTR =E<gt> VALUE, ... } 415 416 Add more attributes or values to the entry. C<VALUE> should be a 417 string if only a single value is wanted in the attribute, or a 418 reference to an array of strings if multiple values are wanted. 419 420 $mesg = $ldap->modify( $dn, 421 add => { 422 description => 'List of members', # Add description attribute 423 member => [ 424 'cn=member1,ou=people,dc=example,dc=com', # Add to attribute 425 'cn=member2,ou=people,dc=example,dc=com', 426 ] 427 } 428 ); 429 430 =item delete =E<gt> [ ATTR, ... ] 431 432 Delete complete attributes from the entry. 433 434 $mesg = $ldap->modify( $dn, 435 delete => ['member','description'] # Delete attributes 436 ); 437 438 =item delete =E<gt> { ATTR =E<gt> VALUE, ... } 439 440 Delete individual values from an attribute. C<VALUE> should be a 441 string if only a single value is being deleted from the attribute, or 442 a reference to an array of strings if multiple values are being 443 deleted. 444 445 If C<VALUE> is a reference to an empty array or all existing values 446 of the attribute are being deleted, then the attribute will be 447 deleted from the entry. 448 449 $mesg = $ldap->modify( $dn, 450 delete => { 451 description => 'List of members', 452 member => [ 453 'cn=member1,ou=people,dc=example,dc=com', # Remove members 454 'cn=member2,ou=people,dc=example,dc=com', 455 ], 456 seeAlso => [], # Remove attribute 457 } 458 ); 459 460 =item replace =E<gt> { ATTR =E<gt> VALUE, ... } 461 462 Replace any existing values in each given attribute with 463 C<VALUE>. C<VALUE> should be a string if only a single value is wanted 464 in the attribute, or a reference to an array of strings if multiple 465 values are wanted. A reference to an empty array will remove the 466 entire attribute. If the attribute does not already exist in the 467 entry, it will be created. 468 469 $mesg = $ldap->modify( $dn, 470 replace => { 471 description => 'New List of members', # Change the description 472 member => [ # Replace whole list with these 473 'cn=member1,ou=people,dc=example,dc=com', 474 'cn=member2,ou=people,dc=example,dc=com', 475 ], 476 seeAlso => [], # Remove attribute 477 } 478 ); 479 480 =item increment =E<gt> { ATTR =E<gt> VALUE, ... } 481 482 Atomically increment the existing value in each given attribute by the 483 provided C<VALUE>. The attributes need to have integer syntax, or be 484 otherwise "incrementable". Note this will only work if the server 485 advertizes support for LDAP_FEATURE_MODIFY_INCREMENT. Use 486 L<Net::LDAP::RootDSE/supported_feature> to check this. 487 488 $mesg = $ldap->modify( $dn, 489 increment => { 490 uidNumber => 1 # increment uidNumber by 1 491 } 492 ); 493 494 =item changes =E<gt> [ OP =E<gt> [ ATTR =E<gt> VALUE ], ... ] 495 496 This is an alternative to B<add>, B<delete>, B<replace> and B<increment> 497 where the whole operation can be given in a single argument. C<OP> 498 should be B<add>, B<delete>, B<replace> or B<increment>. C<VALUE> should 499 be either a string or a reference to an array of strings, as before. 500 501 Use this form if you want to control the order in which the operations 502 will be performed. 503 504 $mesg = $ldap->modify( $dn, 505 changes => [ 506 add => [ 507 description => 'A description', 508 member => $newMember, 509 ], 510 delete => [ 511 seeAlso => [], 512 ], 513 add => [ 514 anotherAttribute => $value, 515 ], 516 ] 517 ); 518 519 =item control =E<gt> CONTROL 520 521 =item control =E<gt> [ CONTROL, ... ] 522 523 See L</CONTROLS> below. 524 525 =item callback =E<gt> CALLBACK 526 527 See L</CALLBACKS> below. 528 529 =back 530 531 B<Example> 532 533 $mesg = $ldap->modify( $dn, add => { sn => 'Barr' } ); 534 535 $mesg = $ldap->modify( $dn, delete => [qw(faxNumber)] ); 536 537 $mesg = $ldap->modify( $dn, delete => { 'telephoneNumber' => '911' } ); 538 539 $mesg = $ldap->modify( $dn, replace => { 'mail' => 'gbarr@pobox.com' } ); 540 541 $mesg = $ldap->modify( $dn, 542 changes => [ 543 # add sn=Barr 544 add => [ sn => 'Barr' ], 545 # delete all fax numbers 546 delete => [ faxNumber => []], 547 # delete phone number 911 548 delete => [ telephoneNumber => ['911']], 549 # change email address 550 replace => [ mail => 'gbarr@pobox.com'] 551 ] 552 ); 553 554 =item search ( OPTIONS ) 555 556 Search the directory using a given filter. This can be used to read 557 attributes from a single entry, from entries immediately below a 558 particular entry, or a whole subtree of entries. 559 560 The result is an object of class L<Net::LDAP::Search>. 561 562 =over 4 563 564 =item base =E<gt> DN 565 566 The DN that is the base object entry relative to which the search is 567 to be performed. 568 569 =item scope =E<gt> 'base' | 'one' | 'sub' 570 571 By default the search is performed on the whole tree below 572 the specified base object. This maybe changed by specifying a C<scope> 573 parameter with one of the following values: 574 575 =over 4 576 577 =item base 578 579 Search only the base object. 580 581 =item one 582 583 Search the entries immediately below the base object. 584 585 =item sub 586 587 Search the whole tree below (and including) the base object. This is 588 the default. 589 590 =back 591 592 =item deref =E<gt> 'never' | 'search' | 'find' | 'always' 593 594 By default aliases are dereferenced to locate the base object for the 595 search, but not when searching subordinates of the base object. This 596 may be changed by specifying a C<deref> parameter with one of the 597 following values: 598 599 =over 4 600 601 =item never 602 603 Do not dereference aliases in searching or in locating the base object 604 of the search. 605 606 =item search 607 608 Dereference aliases in subordinates of the base object in searching, 609 but not in locating the base object of the search. 610 611 =item find 612 613 Dereference aliases in locating the base object of the search, but not 614 when searching subordinates of the base object. This is the default. 615 616 =item always 617 618 Dereference aliases both in searching and in locating the base object 619 of the search. 620 621 =back 622 623 =item sizelimit =E<gt> N 624 625 A sizelimit that restricts the maximum number of entries to be returned 626 as a result of the search. A value of 0, and the default, means that 627 no restriction is requested. Servers may enforce a maximum number of 628 entries to return. 629 630 =item timelimit =E<gt> N 631 632 A timelimit that restricts the maximum time (in seconds) allowed for a 633 search. A value of 0 (the default), means that no timelimit will be 634 requested. 635 636 =item typesonly =E<gt> 1 637 638 Only attribute types (no values) should be returned. Normally 639 attribute types and values are returned. 640 641 =item filter =E<gt> FILTER 642 643 A filter that defines the conditions an entry in the directory must meet 644 in order for it to be returned by the search. This may be a string or a 645 L<Net::LDAP::Filter> object. Values inside filters may need to be escaped 646 to avoid security problems; see L<Net::LDAP::Filter> for a definition of 647 the filter format, including the escaping rules. 648 649 =item attrs =E<gt> [ ATTR, ... ] 650 651 A list of attributes to be returned for each entry that matches the 652 search filter. 653 654 If not specified, then the server will return the attributes that are 655 specified as accessible by default given your bind credentials. 656 657 Certain additional attributes such as "createTimestamp" and other 658 operational attributes may also be available for the asking: 659 660 $mesg = $ldap->search( ... , 661 attrs => ['createTimestamp'] 662 ); 663 664 To retrieve the default attributes and additional ones, use '*'. 665 666 $mesg = $ldap->search( ... , 667 attrs => ['*', 'createTimestamp'] 668 ); 669 670 To retrieve no attributes (the server only returns the DNs of matching 671 entries), use '1.1': 672 673 $mesg = $ldap->search( ... , 674 attrs => ['1.1'] 675 ); 676 677 =item control =E<gt> CONTROL 678 679 =item control =E<gt> [ CONTROL, ... ] 680 681 See L</CONTROLS> below. 682 683 =item callback =E<gt> CALLBACK 684 685 See L</CALLBACKS> below. 686 687 =item raw =E<gt> REGEX 688 689 Use REGEX to denote the names of attributes that are to be considered 690 binary in search results. 691 692 When running on Perl 5.8 and this option is given Net::LDAP converts all 693 values of attributes not matching this REGEX into Perl UTF-8 strings 694 so that the regular Perl operators (pattern matching, ...) can operate 695 as one expects even on strings with international characters. 696 697 If this option is not given or the version of Perl Net::LDAP is running on 698 is too old strings are encodeed the same as in earlier versions of perl-ldap. 699 700 The value provided here overwrites the value inherited from the constructor. 701 702 Example: raw =E<gt> qr/(?i:^jpegPhoto|;binary)/ 703 704 =back 705 706 B<Example> 707 708 $mesg = $ldap->search( 709 base => $base_dn, 710 scope => 'sub', 711 filter => '(|(objectclass=rfc822mailgroup)(sn=jones))' 712 ); 713 714 Net::LDAP::LDIF->new( \*STDOUT,"w" )->write( $mesg->entries ); 715 716 =item start_tls ( OPTIONS ) 717 718 Calling this method will convert the existing connection to using 719 Transport Layer Security (TLS), which provides an encrypted 720 connection. This is I<only> possible if the connection uses LDAPv3, 721 and requires that the server advertizes support for 722 LDAP_EXTENSION_START_TLS. Use 723 L<Net::LDAP::RootDSE/supported_extension> to check this. 724 725 =over 4 726 727 =item verify =E<gt> 'none' | 'optional' | 'require' 728 729 How to verify the server's certificate: 730 731 =over 4 732 733 =item none 734 735 The server may provide a certificate but it will not be checked - this 736 may mean you are be connected to the wrong server 737 738 =item optional 739 740 Verify only when the server offers a certificate 741 742 =item require 743 744 The server must provide a certificate, and it must be valid. 745 746 =back 747 748 If you set verify to optional or require, you must also set either 749 cafile or capath. The most secure option is B<require>. 750 751 =item sslversion =E<gt> 'sslv2' | 'sslv3' | 'sslv2/3' | 'tlsv1' 752 753 This defines the version of the SSL/TLS protocol to use. Defaults to 754 B<'tlsv1'>. 755 756 =item ciphers =E<gt> CIPHERS 757 758 Specify which subset of cipher suites are permissible for this 759 connection, using the standard OpenSSL string format. The default 760 value is B<'ALL'>, which permits all ciphers, even those that don't 761 encrypt. 762 763 =item clientcert =E<gt> '/path/to/cert.pem' 764 765 =item clientkey =E<gt> '/path/to/key.pem' 766 767 =item keydecrypt =E<gt> sub { ... } 768 769 If you want to use the client to offer a certificate to the server for 770 SSL authentication (which is not the same as for the LDAP Bind 771 operation) then set clientcert to the user's certificate file, and 772 clientkey to the user's private key file. These files must be in PEM 773 format. 774 775 If the private key is encrypted (highly recommended) then keydecrypt 776 should be a subroutine that returns the decrypting key. For example: 777 778 $ldap = Net::LDAP->new( 'myhost.example.com', version => 3 ); 779 $mesg = $ldap->start_tls( 780 verify => 'require', 781 clientcert => 'mycert.pem', 782 clientkey => 'mykey.pem', 783 keydecrypt => sub { 'secret'; }, 784 capath => '/usr/local/cacerts/' 785 ); 786 787 =item capath =E<gt> '/path/to/servercerts/' 788 789 =item cafile =E<gt> '/path/to/servercert.pem' 790 791 When verifying the server's certificate, either set capath to the 792 pathname of the directory containing CA certificates, or set cafile to 793 the filename containing the certificate of the CA who signed the 794 server's certificate. These certificates must all be in PEM format. 795 796 The directory in 'capath' must contain certificates named using the 797 hash value of the certificates' subject names. To generate these 798 names, use OpenSSL like this in Unix: 799 800 ln -s cacert.pem `openssl x509 -hash -noout < cacert.pem`.0 801 802 (assuming that the certificate of the CA is in cacert.pem.) 803 804 =item checkcrl =E<gt> 1 805 806 If capath has been configured, then it will also be searched for 807 certificate revocation lists (CRLs) when verifying the server's 808 certificate. 809 The CRLs' names must follow the form B<hash>.rB<num> where B<hash> 810 is the hash over the issuer's DN and B<num> is a number starting with 0. 811 812 See L<IO::Socket::SSL/SSL_check_crl> for further information. 813 814 =back 815 816 =item unbind ( ) 817 818 The unbind method does not take any parameters and will unbind you 819 from the server. Some servers may allow you to re-bind or perform 820 other operations after unbinding. If you wish to switch to another set 821 of credentials while continuing to use the same connection, re-binding 822 with another DN and password, without unbind-ing, will generally work. 823 824 B<Example> 825 826 $mesg = $ldap->unbind; 827 828 =back 829 830 The following methods are for convenience, and do not return 831 C<Net::LDAP::Message> objects. 832 833 =over 4 834 835 =item async ( VALUE ) 836 837 If C<VALUE> is given the async mode will be set. The previous value 838 will be returned. The value is I<true> if LDAP operations are being 839 performed asynchronously. 840 841 =item certificate ( ) 842 843 Returns an X509_Certificate object containing the server's 844 certificate. See the IO::Socket::SSL documentation for information 845 about this class. 846 847 For example, to get the subject name (in a peculiar OpenSSL-specific 848 format, different from RFC 1779 and RFC 2253) from the server's 849 certificate, do this: 850 851 print "Subject DN: " . $ldaps->certificate->subject_name . "\n"; 852 853 =item cipher ( ) 854 855 Returns the cipher mode being used by the connection, in the string 856 format used by OpenSSL. 857 858 =item debug ( VALUE ) 859 860 If C<VALUE> is given the debug bit-value will be set. The previous 861 value will be returned. Debug output will be sent to C<STDERR>. The 862 bits of this value are: 863 864 1 Show outgoing packets (using asn_hexdump). 865 2 Show incoming packets (using asn_hexdump). 866 4 Show outgoing packets (using asn_dump). 867 8 Show incoming packets (using asn_dump). 868 869 The default value is 0. 870 871 =item disconnect ( ) 872 873 Disconnect from the server 874 875 =item root_dse ( OPTIONS ) 876 877 The root_dse method retrieves cached information from the server's 878 rootDSE. 879 880 =over 4 881 882 =item attrs =E<gt> [ ATTR, ... ] 883 884 A reference to a list of attributes to be returned. 885 If not specified, then the following attributes will be requested 886 887 subschemaSubentry 888 namingContexts 889 altServer 890 supportedExtension 891 supportedFeatures 892 supportedControl 893 supportedSASLMechanisms 894 supportedLDAPVersion 895 896 =back 897 898 The result is an object of class L<Net::LDAP::RootDSE>. 899 900 B<Example> 901 902 my $root = $ldap->root_dse; 903 # get naming Context 904 $root->get_value( 'namingContext', asref => 1 ); 905 # get supported LDAP versions 906 $root->supported_version; 907 908 As the root DSE may change in certain circumstances - for instance 909 when you change the connection using start_tls - you should always use 910 the root_dse method to return the most up-to-date copy of the root 911 DSE. 912 913 =item schema ( OPTIONS ) 914 915 Read schema information from the server. 916 917 The result is an object of class L<Net::LDAP::Schema>. 918 Read this documentation for further information about methods that 919 can be performed with this object. 920 921 =over 4 922 923 =item dn =E<gt> DN 924 925 If a DN is supplied, it will become the base object entry from 926 which the search for schema information will be conducted. If 927 no DN is supplied the base object entry will be determined from 928 the rootDSE entry. 929 930 =back 931 932 B<Example> 933 934 my $schema = $ldap->schema; 935 # get objectClasses 936 @ocs = $schema->all_objectclasses; 937 # Get the attributes 938 @atts = $schema->all_attributes; 939 940 =item socket ( ) 941 942 Returns the underlying C<IO::Socket> object being used. 943 944 =item host ( ) 945 946 Returns the host to which the connection was established. 947 For LDAPI connections the socket path is returned. 948 949 =item port ( ) 950 951 Returns the the port connected to or C<undef> in case of LDAPI connections. 952 953 =item uri ( ) 954 955 Returns the URI connected to. 956 957 As the value returned is that element of the constructor's HOST 958 argument with which the connection was established this may or 959 may not be a legal URI. 960 961 =item scheme ( ) 962 963 Returns the scheme of the connection. One of I<ldap>, I<ldaps> or I<ldapi>. 964 965 =item sync ( MESG ) 966 967 Wait for a given C<MESG> request to be completed by the server. If no 968 C<MESG> is given, then wait for all outstanding requests to be completed. 969 970 Returns an error code defined in L<Net::LDAP::Constant>. 971 972 =item process ( MESG ) 973 974 Process any messages that the server has sent, but do not block. If C<MESG> 975 is specified then return as soon as C<MESG> has been processed. 976 977 Returns an error code defined in L<Net::LDAP::Constant>. 978 979 =item version ( ) 980 981 Returns the version of the LDAP protocol that is being used. 982 983 =back 984 985 =head1 CONTROLS 986 987 Many of the methods described above accept a control option. 988 This allows the user to pass controls to the server as described 989 in LDAPv3. 990 991 A control is a reference to a HASH and should contain the three 992 elements below. If any of the controls are blessed then the 993 method C<to_asn> will be called which should return a reference 994 to a HASH containing the three elements described below. 995 996 For most purposes L<Net::LDAP::Control> objects are the easiest 997 way to generate controls. 998 999 =over 4 1000 1001 =item type =E<gt> OID 1002 1003 This element must be present and is the name of the type of control 1004 being requested. 1005 1006 =item critical =E<gt> FLAG 1007 1008 critical is optional and should be a boolean value, if it is not specified 1009 then it is assumed to be I<false>. 1010 1011 =item value =E<gt> VALUE 1012 1013 If the control being requested requires a value then this element should 1014 hold the value for the server. 1015 1016 =back 1017 1018 =head1 CALLBACKS 1019 1020 Most of the above commands accept a callback option. This option 1021 should be a reference to a subroutine. This subroutine will be called 1022 for each packet received from the server as a response to the request 1023 sent. 1024 1025 When the subroutine is called the first argument will be the 1026 L<Net::LDAP::Message> object which was returned from the method. 1027 1028 If the request is a search then multiple packets can be received from 1029 the server. Each entry is received as a separate packet. For each of these 1030 the subroutine will be called with a L<Net::LDAP::Entry> object as the second 1031 argument. 1032 1033 During a search the server may also send a list of references. When such 1034 a list is received then the subroutine will be called with a 1035 L<Net::LDAP::Reference> object as the second argument. 1036 1037 =head1 LDAP ERROR CODES 1038 1039 B<Net::LDAP> also exports constants for the error codes that can be received 1040 from the server, see L<Net::LDAP::Constant>. 1041 1042 =head1 SEE ALSO 1043 1044 L<Net::LDAP::Constant>, 1045 L<Net::LDAP::Control>, 1046 L<Net::LDAP::Entry>, 1047 L<Net::LDAP::Filter>, 1048 L<Net::LDAP::Message>, 1049 L<Net::LDAP::Reference>, 1050 L<Net::LDAP::Search>, 1051 L<Net::LDAP::RFC> 1052 1053 The homepage for the perl-ldap modules can be found at 1054 http://ldap.perl.org/. 1055 1056 =head1 ACKNOWLEDGEMENTS 1057 1058 This document is based on a document originally written by Russell Fulton 1059 E<lt>r.fulton@auckland.ac.nzE<gt>. 1060 1061 Chris Ridd E<lt>chris.ridd@isode.comE<gt> for the many hours spent 1062 testing and contribution of the ldap* command line utilities. 1063 1064 =head1 MAILING LIST 1065 1066 A discussion mailing list is hosted by the Perl Foundation at 1067 E<lt>perl-ldap@perl.orgE<gt> No subscription is necessary! 1068 1069 =head1 BUGS 1070 1071 We hope you do not find any, but if you do please report them to 1072 the mailing list. 1073 1074 If you have a patch, please send it as an attachment to the mailing 1075 list. 1076 1077 =head1 AUTHOR 1078 1079 Graham Barr E<lt>gbarr@pobox.comE<gt> 1080 1081 =head1 COPYRIGHT 1082 1083 Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program is 1084 free software; you can redistribute it and/or modify it under the same 1085 terms as Perl itself. 1086 1087 =cut
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |