This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Net/LDAP/Filter, Next: Net/LDAP/LDIF, Prev: Net/LDAP/FAQ, Up: Module List representation of LDAP filters ****************************** NAME ==== Net::LDAP::Filter - representation of LDAP filters SYNOPSIS ======== use Net::LDAP::Filter; $filter = Net::LDAP::Filter->new( $filter_str ); DESCRIPTION =========== CONSTRUCTOR =========== new ( FILTER ) Create a new object and parse FILTER. METHODS ======= parse ( FILTER ) Parse FILTER. The next call to ber will return this filter encoded. asn Return the data structure suitable for passing directly to *Note Convert/ASN1: Convert/ASN1, to encode a filter object. as_string Return the filter in text form. print ( [ FH ] ) Print the text representation of the filter to FH, or the currently selected output handle if FH is not given. FILTER SYNTAX ============= Below is the syntax for a filter given in RFC-2254 http://info.internet.isi.edu/in-notes/rfc/files/rfc2254.txt filter = "(" filtercomp ")" filtercomp = and / or / not / item and = "&" filterlist or = "|" filterlist not = "!" filter filterlist = 1*filter item = simple / present / substring / extensible simple = attr filtertype value filtertype = equal / approx / greater / less equal = "=" approx = "~=" greater = ">=" less = "<=" extensible = attr [":dn"] [":" matchingrule] ":=" value / [":dn"] ":" matchingrule ":=" value present = attr "=*" substring = attr "=" [initial] any [final] initial = value any = "*" *(value "*") final = value attr = AttributeDescription from Section 4.1.5 of RFC-2251 matchingrule = MatchingRuleId from Section 4.1.9 of RFC-2251 value = AttributeValue from Section 4.1.6 of RFC-2251 Special Character encodings --------------------------- * \2a, \* ( \28, \( ) \29, \) \ \5c, \\ NUL \00 SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `Other online documentation|Net::LDAP::RFC' in this node ACKNOWLEDGEMENTS ================ This document is based on a document originally written by Russell Fulton . AUTHOR ====== Graham Barr Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1997-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/LDIF, Next: Net/LDAP/Message, Prev: Net/LDAP/Filter, Up: Module List LDIF reading and writing ************************ NAME ==== Net::LDAP::LDIF - LDIF reading and writing SYNOPSIS ======== use Net::LDAP::LDIF; $ldif = Net::LDAP::LDIF->new( "file.ldif", "r" ); while( $entry = $ldif->read() ) { # Do things with $entry } $ldif->done(); $ldif = Net::LDAP::LDIF->new( $fh, "r" ); @entries = $ldif->read(); DESCRIPTION =========== *Net::LDAP::LDIF* provides a means to convert between `Net::LDAP::Entry|Net::LDAP::Entry' in this node objects and LDAP entries represented in LDIF format files. Reading and writing are supported and may manipulate single entries or lists of entries. As when reading an entire file into memory with perl normally, take into account the possibility of memory use when loading an LDIF file in one go. CONSTRUCTOR =========== new ( [ FILE [, MODE]] ) FILE may be the name of a file or an already open filehandle. If a filename is passed in then it will be opened with the mode specified. MODE defaults to "r" for read. You may specify "w" to for write+truncate or "a" for write+append. METHODS ======= read In a similar fashion to the perl <$fh> operator, read will read one entry or the entire file depending on whether it is called in a scalar or array context. read_cmd write ( ENTRIES ) write_cmd ( ENTRIES ) done This method signals that the LDIF object is no longer needed. If a file was opened automatically when the object was created it will be closed. This method is called automatically via DESTROY when the object goes out of scope. $ldif->done(); AUTHOR ====== Graham Barr . Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1997-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/Message, Next: Net/LDAP/RFC, Prev: Net/LDAP/LDIF, Up: Module List Message response from LDAP server ********************************* NAME ==== Net::LDAP::Message - Message response from LDAP server SYNOPSIS ======== use Net::LDAP; DESCRIPTION =========== *Net::LDAP::Message* is a base class for the objects returned by the `Net::LDAP|Net::LDAP' in this node methods `abandon|Net::LDAP' in this node, `add|Net::LDAP' in this node, `bind|Net::LDAP' in this node, `compare|Net::LDAP' in this node, `delete|Net::LDAP' in this node, `modify|Net::LDAP' in this node, `moddn|Net::LDAP' in this node, `search|Net::LDAP' in this node and `unbind|Net::LDAP' in this node. The sub-class `Net::LDAP::Search|Net::LDAP::Search' in this node returned by `search|Net::LDAP' in this node also defines many methods. If the `Net::LDAP|Net::LDAP' in this node object is in async mode then all these methods, except done, will cause a wait until the request is completed. METHODS ======= code The code value in the result message from the server. Normally for a success zero will be returned. `Constants|Net::LDAP::Constant' in this node for the result codes can be imported from the `Net::LDAP|Net::LDAP' in this node module. control [ OID ] Return a list of controls returned from the server. If OID is given then only controls with type equal to OID will be returned. dn The DN in the result message from the server. done Returns *true* if the request has been completed. error The error message in the result message from the server. If the server did not include an error message, then the result of `ldap_error_desc|Net::LDAP::Util' in this node with the error code from the result message. is_error Returns *true* if the result code is considered to be an error for the operation. mesg_id The message id of the request message sent to the server. referrals Returns a list of referrals from the result message. server_error The error message returned by the server, or undef if the server did not provide a message. sync Wait for the server to complete the request. SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `Net::LDAP::Search|Net::LDAP::Search' in this node, `Net::LDAP::Constant|Net::LDAP::Constant' in this node, `Net::LDAP::Util|Net::LDAP::Util' in this node ACKNOWLEDGEMENTS ================ This document is based on a document originally written by Russell Fulton . AUTHOR ====== Graham Barr Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1997-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/RFC, Next: Net/LDAP/Reference, Prev: Net/LDAP/Message, Up: Module List List of related RFC's ********************* NAME ==== Net::LDAP::RFC - List of related RFC's SYNOPSIS ======== none DESCRIPTION =========== The LDAP protocol is defined in the following RFC's RFC-2251 - Lightweight Directory Access Protocol (v3). http://info.internet.isi.edu/in-notes/rfc/files/rfc2251.txt RFC-2251 - Lightweight Directory Access Protocol (v3). http://info.internet.isi.edu/in-notes/rfc/files/rfc2251.txt RFC-2252 - Attribute Syntax Definitions. http://info.internet.isi.edu/in-notes/rfc/files/rfc2252.txt RFC-2253 - UTF-8 String Representation of Distinguished Names. http://info.internet.isi.edu/in-notes/rfc/files/rfc2253.txt RFC-2254 - The String Representation of LDAP Search Filters. http://info.internet.isi.edu/in-notes/rfc/files/rfc2254.txt RFC-2255 - The LDAP URL Format. http://info.internet.isi.edu/in-notes/rfc/files/rfc2255.txt RFC-2256 - A Summary of the X.500(96) User Schema for use with LDAPv3. http://info.internet.isi.edu/in-notes/rfc/files/rfc2256.txt RFC-2696 - LDAP Control Extension for Simple Paged Results Manipulation http://info.internet.isi.edu/in-notes/rfc/files/rfc2696.txt  File: pm.info, Node: Net/LDAP/Reference, Next: Net/LDAP/Schema, Prev: Net/LDAP/RFC, Up: Module List search reference **************** NAME ==== Net::LDAP::Reference - search reference SYNOPSIS ======== use Net::LDAP; $ldap->search( @search_args, callback => \&process); sub process { my $mesg = shift; my $obj = shift; if (!$obj) { # Search complete } elsif ($obj->isa('Net::LDAP::Reference')) { my $ref; foreach $ref ($obj->references) { # process ref } } else { # Process Net::LDAP::Entry } } DESCRIPTION =========== METHODS ======= references Returns a list of references from the server. SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `Net::LDAP::Search|Net::LDAP::Search' in this node AUTHOR ====== Graham Barr . Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1997-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/Schema, Next: Net/LDAP/Search, Prev: Net/LDAP/Reference, Up: Module List Load and manipulate an LDAP v3 Schema ************************************* NAME ==== Net::LDAP::Schema - Load and manipulate an LDAP v3 Schema SYNOPSIS ======== use Net::LDAP; use Net::LDAP::Schema; # # Read schema from server # $ldap = Net::LDAP->new( $server ); $ldap->bind(); $schema = $ldap->schema(); # # Load from LDIF # $schema = Net::LDAP->new; $schema->parse( "schema.ldif" ) or die $schema->error; DESCRIPTION =========== *Net::LDAP::Schema* provides a means to load an LDAP schema and query it for information regarding supported objectclasses, attributes and syntaxes. METHODS ======= Where a method is stated as taking the 'name or oid' of a schema item (which may be an object class, attribute or syntax) then a case-insensitive name or raw oid (object identifier, in dotted numeric string form, e.g. 2.5.4.0) may be supplied. attributes With no arguments, returns a list of the names all attributes in the schema. @atts = $schema->attributes(); If called with an argument which is the name or oid of a known object class, returns a list of the attributes which may (or must) be present in the OC. @person_atts = $schema->attributes( "person" ); Return value is an array or array reference depending on calling context, or empty list on error. dump Given an argument which is the name of a file, and the file or directory has write permission, will dump the raw schema information to a file. If no argument is given the raw schema information is dumped to standard out. $result = $schema->dump( "./schema.dump" ); or $result = $schema->dump(); If no schema data is returned from directory server, the method will return undefined. Otherwise a value of 1 is always returned. error Returns the last error encountered. is_objectclass, is_attribute, is_syntax, is_matchingrule Given the name or oid of a schema item (object class, attribute, syntax or matchingrule respectively) returns the assoicated OID or undef if the name or oid is not of the appropriate type. # Is foo a known OC? $oid = $schema->is_objectclass( "foo" ); # No? Bale out. die( "Not an objectclass" ) unless $oid; # Yes...so we can do this @must = $schema->must( $oid ); item Given two arguments, first of which is the name or oid of a known object class or attribute and second of which is the name of the item, returns the item's data value. The item's value may be undefined. @item = $schema->item( $oid, "desc" ); Return value is an array or a value depending on calling context. items Given an argument which is the name or oid of a known object class or attribute, returns the items available for this attribute or object class. The returned item name may have an undefined value. @items = $schema->items( $oid ); Return value is an array or array reference depending on calling context. matchingrules Returns a list of the names of all matchingrules in the schema. @mrs = $schema->matchingrules(); Return value is an array or array reference depending on calling context. may Given an argument which is the name or oid of a known object class, returns the name of the attributes which are optional in the class. @may = $schema->may( $oc ); Return value is an array or array reference depending on calling context. must Given an argument which is the name or oid of a known object class, returns the name of the attributes which are mandatory in the class @must = $schema->must( $oc ); Return value is an array or array reference depending on calling context. name2oid Given the name of a schema item (object class, attribute or syntax) returns the assoicated OID or undef if it is not recognised. objectclasses Returns a list of the names of all objectclasses in the schema. @ocs = $schema->objectclasses(); Return value is an array or array reference depending on calling context. parse Takes a single argument which can be any of, A message objected returned from an LDAP search, a Net::LDAP::Entry object or the name of a file containing an LDIF form of the schema. If the argument is a message result from a search, Net::LDAP::Schema will parse the schema from the first entry returned. Returns true on success and undef on error. superclass Given an argument which is the name or oid of a known objectclass, returns the list of names of the immediate superclasses. syntax Given an argument which is the name or oid of a known attribute, returns the name of the attribute's syntax (or the syntax of the attributes superior if the syntax is inherited). $name_syntax = $schema->syntax( "commonName" ); syntaxes Returns a list of the names of all objectclasses in the schema. (The name of a syntax is not well defined. It may be an OID or abbreviated description). @syns = $schema->syntaxes(); Return value is an array or array reference depending on calling context. SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `Other online documentation|Net::LDAP::RFC' in this node AUTHORS ======= Graham Barr John Berthels Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1998-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/Search, Next: Net/LDAP/Util, Prev: Net/LDAP/Schema, Up: Module List Object returned by Net::LDAP search method ****************************************** NAME ==== Net::LDAP::Search - Object returned by Net::LDAP search method SYNOPSIS ======== use Net::LDAP; $mesg = $ldap->search( @search_args ); @entries = $mesg->entries; DESCRIPTION =========== A *Net::LDAP::Search* object is returned from the `search|Net::LDAP' in this node method of a `Net::LDAP|Net::LDAP' in this node object. It is a container object which holds the results of the search. METHODS ======= *Net::LDAP::Search* inherits from `Net::LDAP::Message|Net::LDAP::Message' in this node, and so supports all methods defined in `Net::LDAP::Message|Net::LDAP::Message' in this node. as_struct Returns a reference to a HASH, where the keys are the DN's of the results and the values are HASH references. These second level HASH's hold the attributes such that the keys are the attribute names, in lowercase, and the values are references to and ARRAY holding the values. This method will block until the whole search request has finished. count Returns the number of entries returned by the server. This method will block until the whole search request has finished. entry ( INDEX ) Return the N'th entry, which will be a `Net::LDAP::Entry|Net::LDAP::Entry' in this node object. If INDEX is greater than the total number of entries returned then undef will be returned. This method will block until the search request has returned enough entries. entries Return an array of `Net::LDAP::Entry|Net::LDAP::Entry' in this node objects hat were returned from the server. This method will block until the whole search request has finished. pop_entry Pop an entry from the internal list of `Net::LDAP::Entry|Net::LDAP::Entry' in this node objects for this search. If there are not more entries then undef is returned. This call will block, if the list is empty, until the server returns another entry. references Return a list of references that the server returned. This will be a list of `Net::LDAP::Reference|Net::LDAP::Reference' in this node objects. sorted ( [ ATTR ] ) Return a list of `Net::LDAP::Entry|Net::LDAP::Entry' in this node objects, sorted by ATTR. If ATTR is not given then the entries will be sorted by their DN. shift_entry Shift an entry from the internal list of `Net::LDAP::Entry|Net::LDAP::Entry' in this node objects for this search. If there are not more entries then undef is returned. This call will block, if the list is empty, until the server returns another entry. SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `Net::LDAP::Message|Net::LDAP::Message' in this node, `Net::LDAP::Entry|Net::LDAP::Entry' in this node, `Net::LDAP::Reference|Net::LDAP::Reference' in this node ACKNOWLEDGEMENTS ================ This document is based on a document originally written by Russell Fulton . AUTHOR ====== Graham Barr Please report any bugs, or post any suggestions, to the perl-ldap mailing list . COPYRIGHT ========= Copyright (c) 1997-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAP/Util, Next: Net/LDAPS, Prev: Net/LDAP/Search, Up: Module List Utility functions ***************** NAME ==== Net::LDAP::Util - Utility functions SYNOPSIS ======== use Net::LDAP::Util qw(ldap_error_text ldap_error_name ldap_error_desc ); $mesg = $ldap->search( .... ); die "Error ",ldap_error_name($mesg->code) if $mesg->code; DESCRIPTION =========== *Net::LDAP::Util* is a collection of utility functions for use with the `Net::LDAP|Net::LDAP' in this node modules. FUNCTIONS ========= ldap_error_name ( NUM ) Returns the name corresponding with the error number passed in. If the error is not known the a string in the form `"LDAP error code %d(0x%02X)"' is returned. ldap_error_text ( NUM ) Returns the text from the POD description for the given error. If the error code given is unknown then undef is returned. ldap_error_desc ( NUM ) Returns a short text description of the error. AUTHOR ====== Graham Barr COPYRIGHT ========= Copyright (c) 1999-2000 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAPS, Next: Net/LDAPapi, Prev: Net/LDAP/Util, Up: Module List use LDAP over an SSL connection ******************************* NAME ==== Net::LDAPS - use LDAP over an SSL connection SYNOPSIS ======== use Net::LDAPS; $ldaps = new Net::LDAPS('myhost.example.com', port => '10000', verify => 'require', capath => '/usr/local/cacerts/'); DESCRIPTION =========== Communicate using the LDAP protocol to a directory server using a potentially encrypted (SSL) network connection. This class is a subclass of Net::LDAP so all the normal Net::LDAP methods can be used with a Net::LDAPS object; see the documentation for Net::LDAP to find out how to query a directory server using the LDAP protocol. CONSTRUCTOR =========== new ( HOST [, OPTIONS ] ) Create a new connection. HOST is the hostname to contact. OPTIONS is a number of key/value pairs - additional keys to those understood by Net::LDAP::new are: verify How to verify the server's certificate, either 'none' (the server may provide a cert but don't verify it - this may mean you are be connected to the wrong server), 'optional' (verify if the server offers a cert), or 'require' (the server must provide a cert, and it must be valid.) If you set verify to optional or require, you must also set either cafile or capath. ciphers Specify which subset of cipher suites are permissible for this connection, using the standard OpenSSL string format. The default value for ciphers is 'ALL', which permits all ciphers. clientcert clientkey If you want to use the client to offer a certificate to the server for SSL authentication (which is not the same as for the LDAP Bind operation) then set clientcert to the user's certificate file, and clientkey to the user's private key file. capath cafile When verifying the server's certificate, either set capath to the pathname of the directory containing CA certificates, or set cafile to the filename containing the certificate of the CA who signed the server's certificate. The directory in 'capath' must contain certificates named using the hash value of themselves. To generate these names, use OpenSSL thusly: ln -s cacert.pem `openssl x509 -hash -nout < cacert.pem`.0 (assuming that the certificate of the CA is in cacert.pem.) ADDITIONAL METHODS ================== cipher Returns the cipher mode being used by the connection, in the string format used by OpenSSL. certificate Returns an X509_Certificate object containing the server's certificate. See the IO::Socket::SSL documentation for information about this class. For example, to get the subject name (in a peculiar OpenSSL-specific format, different from RFC 1779 and RFC 2253) from the server's certificate, do this: print "Subject DN: " . $ldaps->certificate->subject_name . "\n"; SEE ALSO ======== `Net::LDAP|Net::LDAP' in this node, `IO::Socket::SSL|IO::Socket::SSL' in this node BUGS ==== Several apparently bogus warnings are emitted when initializing the two underlying modules used by Net::LDAPS, namely IO::Socket::SSL and Net::SSLeay. To avoid these, don't initialize via 'use Net::LDAPS' and instead try initializing Net::LDAPS like this: BEGIN { # Turn off all warnings etc whilst initializing # IO::Socket::SSL and Net::SSLeay. local $^W = 0; no strict; require Net::SSLeay; # The /dev/urandom is a device on Linux that returns # random data. Net::SSLeay::randomize('/dev/urandom'); require Net::LDAPS; } AUTHOR ====== Chris Ridd COPYRIGHT ========= Copyright (c) 2000, Chris Ridd and Graham Barr. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: Net/LDAPapi, Next: Net/NIS, Prev: Net/LDAPS, Up: Module List Perl5 Module Supporting LDAP API ******************************** NAME ==== Net::LDAPapi - Perl5 Module Supporting LDAP API SYNOPSIS ======== use Net::LDAPapi; See individual items and Example Programs for Usage DESCRIPTION =========== This module allows Perl programmers to access and manipulate an LDAP based Directory. Versions beginning with 1.40 support both the original "C API" and new "Perl OO" style interface methods. With version 1.42, I've added named arguments. THE INTIAL CONNECTION ===================== All connections to the LDAP server are started by creating a new "blessed object" in the Net::LDAPapi class. This can be done quite easily by the following type of statement. $ld = new Net::LDAPapi($hostname); Where $hostname is the name of your LDAP server. If you are not using the standard LDAP port (389), you will also need to supply the portnumber. $ld = new Net::LDAPapi($hostname,15555); The new method can also be called with named arguments. $ld = new Net::LDAPapi(-host=>$hostname,-port=>15389); Note that with namd arguments, the order of the arguments is insignificant. BINDING ======= After creating a connection to the LDAP server, you will always need to bind to the server prior to performing any LDAP related functions. This can be done with the 'bind' methods. An anonymous bind can be performed without arguments: $status = $ld->bind_s; A simple bind can be performed by specifying the DN and PASSWORD of the user you are authenticating as: $status = $ld->bind_s($dn,$password); Note that if $password above was "", you would be doing a reference bind, which would return success even if the password in the directory was non-null. Thus if you were using the bind to check a password entered with one in the directory, you should first check to see if $password was NULL. If your LDAP C Library supports Kerberos, you can also do Kerberos binds simply by adding the LDAP_AUTH_KRBV4 option. For example: $status = $ld->bind_s($dn,$password,LDAP_AUTH_KRBV4); For all of the above operations, you could compare $status to LDAP_SUCCESS to see if the operation was successful. Additionally, you could use 'bind' rather than 'bind_s' if you wanted to use the Asynchronous LDAP routines. The asynchronous routines would return a MSGID rather than a status. To find the status of an Asynchronous bind, you would need to first obtain the result with a call to $ld->result. See the entry for result later in the man page, as well as the 'ldapwalk.pl' example for further information on obtaining results from Asynchronous operations. The bind operations can also accept named arguments. $status = $ld->bind_s(-dn=>$dn,-password=>$password,-type=>LDAP_AUTH_SIMPLE); As with all other commands that support named arguments, the order of the arguments makes no difference. GENERATING AN ADD/MODIFY HASH ============================= For the add and modify routines you will need to generate a list of attributes and values. You will do this by creating a HASH table. Each attribute in the hash contains associated values. These values can be one of three things. - SCALAR VALUE (ex. "Clayton Donley") - ARRAY REFERENCE (ex. ["Clayton Donley","Clay Donley"]) - HASH REFERENCE (ex. {"r",["Clayton Donley"]} note: the value inside the HASH REFERENCE must currently be an ARRAY REFERENCE. The key inside the HASH REFERENCE must be one of the following for a modify operation: - "a" for LDAP_MOD_ADD (Add these values to the attribute) - "r" for LDAP_MOD_REPLACE (Replace these values in the attribute) - "d" for LDAP_MOD_DELETE (Delete these values from the attribute) Additionally, in add and modify operations, you may specify "b" if the attributes you are adding are BINARY (ex. "rb" to replace binary). Currently, it is only possible to do one operation per add/modify operation, meaning you can't do something like: {"d",["Clayton"],"a",["Clay"]} <-- WRONG! Using any combination of the above value types, you can do things like: %ldap_modifications = ( "cn", "Clayton Donley", # Replace 'cn' values "givenname", ["Clayton","Clay"], # Replace 'givenname' values "mail", {"a",["donley\@cig.mcel.mot.com"], #Add 'mail' values "jpegphoto", {"rb",[$jpegphotodata]}, # Replace Binary jpegPhoto ); Then remember to call the add or modify operations with a REFERENCE to this HASH. Something like: $ld->modify_s($modify_dn,\%ldap_modifications); GETTING/SETTING LDAP INTERNAL VALUES ==================================== The following methods exist to obtain internal values within a Net::LDAPapi object: o errno - The last error-number returned by the LDAP library for this connection. ex: print "Error Number: " . $ld->errno . "\n"; o errstring - The string equivalent of 'errno'. ex: print "Error: " . $ld->errstring . "\n"; o ld - Reference to the actual internal LDAP structure. Only useful if you needed to obtain this pointer for use in non-OO routines. ex: $ldptr = $ld->ld; o entry - Reference to the current entry. Not typically needed, but method supplied, just in case. ex: $entry = $ld->entry; o msgid - Get msgid from an LDAP Result. ex: $msgid = $ld->msgid; # msgid of current result ex: $msgid = $ld->msgid($result) # msgid of $result o msgtype - Get msgtype from an LDAP Result. ex: $msgtype = $ld->msgtype; # msgtype of current result ex: $msgtype = $ld->msgtype($result) # msgtype of $result These methods are only useful for GETTING internal information, not setting it. No methods are currently available for SETTING these internal values. GETTING AND SETTING LDAP SESSION OPTIONS ======================================== The get_option and set_option methods can be used to get and set LDAP session options. The following LDAP options can be set or gotten with these methods: LDAP_OPT_DEREF - Dereference LDAP_OPT_SIZELIMIT - Maximum Number of Entries to Return LDAP_OPT_TIMELIMIT - Timeout for LDAP Operations LDAP_OPT_REFERRALS - Follow Referrals For both get and set operations, the first argument is the relivant option. In get, the second argument is a reference to a scalar variable that will contain the current value of the option. In set, the second argument is the value at which to set this option. Examples: $ld->set_option(LDAP_OPT_SIZELIMIT,50); $ld->get_option(LDAP_OPT_SIZELIMIT,\$size); When setting LDAP_OPT_REFERRALS, the second argument is either LDAP_OPT_ON or LDAP_OPT_OFF. Other options require a number. Both get_option and set_option return 0 on success and non-zero otherwise. SSL SUPPORT =========== When compiled with the Netscape SDK, this module now supports SSL. I do not have an SSL capable server, but I'm told this works. The functions available are: o ssl - Turn on SSL for this connection. Install I/O routines to make SSL over LDAP possible o ssl_client_init($certdbpath,$certdbhandle) Initialize the secure parts (called only once) Example: $ld = new Net::LDAPapi("host",LDAPS_PORT); $ld->ssl_client_init($certdbpath,$certdbhandle); $ld->ssl; SETTING REBIND PROCESS ====================== As of version 1.42, rebinding now works properly. The set_rebind_proc method is used to set a PERL function to supply DN, PASSWORD, and AUTHTYPE for use when the server rebinds (for referals, etc...). Usage should be something like: $rebind_ref = \&my_rebind_proc; $ld->set_rebind_proc($rebind_ref); You can then create the procedure specified. It should return 3 values. Example: sub my_rebind_proc { return($dn,$pass,LDAP_AUTH_SIMPLE); } SUPPORTED METHODS ================= abandon MSGID This cancels an asynchronous LDAP operation that has not completed. It returns an LDAP STATUS code upon completion. Example: $status = ldap_abandon($ld, $msgid); add DN ATTR Begins an an asynchronous LDAP Add operation. It returns a MSGID or -1 upon completion. Example: %attributes = ( "cn", ["Clayton Donley","Clay Donley"] #Add Multivalue cn "sn", "Donley", #Add sn "telephoneNumber", "+86-10-65551234", #Add telephoneNumber "objectClass", ["person","organizationalPerson"], # Add Multivalue objectClass "jpegphoto", {"b",[$jpegphoto]}, # Add Binary jpegphoto ); $entrydn = "cn=Clayton Donley, o=Motorola, c=US"; $msgid = $ld->add($entrydn, \%attributes); Note that in most cases, you will need to be bound to the LDAP server as an administrator in order to add users. add_s DN ATTR Synchronous version of the 'add' method. Arguments are identical to the 'add' method, but this operation returns an LDAP STATUS, not a MSGID. Example: $ld->add_s($entrydn, \%attributes); See the section on creating the modify structure for more information on populating the ATTRIBUTES field for Add and Modify operations. bind DN PASSWORD TYPE Asynchronous method for binding to the LDAP server. It returns a MSGID. Examples: $msgid = $ld->bind; $msgid = $ld->bind("cn=Clayton Donley, o=Motorola, c=US", "abc123"); bind_s DN PASSWORD TYPE Synchronous method for binding to the LDAP server. It returns an LDAP STATUS. Examples: $status = $ld->bind_s; $status = $ld->bind_s("cn=Clayton Donley, o=Motorola, c=US", "abc123"); compare DN ATTR VALUE Asynchronous method for comparing a value with the value contained within DN. Returns a MSGID. Example: $msgid = $ld->compare("cn=Clayton Donley, o=Motorola, c=US", \ $type,$value); compare_s DN ATTR VALUE Synchronous method for comparing a value with the value contained within DN. Returns an LDAP STATUS. Example: $status = $ld->compare_s("cn=Clayton Donley, o=Motorola, c=US", \ $type, $value); count_entries Calculates and returns the number of entries in an LDAP result chain. Example: $number = $ld->count_entries; delete DN Asynchronous method to delete DN. Returns a MSGID or -1 if error. Example: $msgid = $ld->delete("cn=Clayton Donley, o=Motorola, c=US"); delete_s DN Synchronous method to delete DN. Returns an LDAP STATUS. Example: $status = $ld->delete_s("cn=Clayton Donley, o=Motorola, c=US"); dn2ufn DN Converts a Distinguished Name (DN) to a User Friendly Name (UFN). Returns a string with the UFN. Since this operation doesn't require an LDAP object to work, you could technically access the function directly as 'ldap_dn2ufn' rather that the object oriented form. Example: $ufn = $ld->dn2ufn("cn=Clayton Donley, o=Motorola, c=US"); explode_dn DN NOTYPES Splits the DN into an array comtaining the separate components of the DN. Returns an Array. NOTYPES is a 1 to remove attribute types and 0 to retain attribute types. Can also be accessed directly as 'ldap_explode_dn' if no session is initialized and you don't want the object oriented form. Only available when compiled with Netscape SDK. Example: @components = $ld->explode_dn($dn,0); explode_rdn RDN NOTYPES Same as explode_dn, except that the first argument is a Relative Distinguished Name. NOTYPES is a 1 to remove attribute types and 0 to retain attribute types. Returns an array with each component. Can also be accessed directly as 'ldap_explode_rdn' if no session is initialized and you don't want the object oriented form. Only available with Netscape SDK. Example: @components = $ld->explode_rdn($rdn,0); first_attribute Returns pointer to first attribute name found in the current entry. Note that this only returning attribute names (ex: cn, mail, etc...). Returns a string with the attribute name. Returns an empty string when no attributes are available. Example: $attr = $ld->first_attribute; first_entry Sets internal pointer to the first entry in a chain of results. Returns an empty string when no entries are available. Example: $entry = $ld->first_entry; get_dn Returns a string containing the DN for the specified entry or an empty string if an error occurs. Example: $dn = $ld->get_dn; get_values ATTR Obtain a list of all values associated with a given attribute. Returns an empty list if none are available. Example: @values = $ld->get_values("cn"); This would put all the 'cn' values for $entry into the array @values. get_values_len ATTR Retrieves a set of binary values for the specified attribute. Example: @values = $ld->get_values_len("jpegphoto"); This would put all the 'jpegphoto' values for $entry into the array @values. These could then be written to a file, or further processed. is_ldap_url URL Checks to see if a specified URL is a valid LDAP Url. Returns 0 on false and 1 on true. Example: $isurl = $ld->is_ldap_url("ldap://x500.my.org/o=Org,c=US"); msgfree Frees the current LDAP result. Returns the type of message freed. Example: $type = $ld->msgfree; modify DN MOD Asynchronous method to modify an LDAP entry. DN is the DN to modify and MOD contains a hash-table of attributes and values. If multiple values need to be passed for a specific attribute, a reference to an array must be passed. Returns the MSGID of the modify operation. Example: %mods = ( "telephoneNumber", "", #remove telephoneNumber "sn", "Test", #set SN to TEST "mail", ["me\@abc123.com","me\@second-home.com"], #set multivalue 'mail' "pager", {"a",["1234567"]}, #Add a Pager Value "jpegphoto", {"rb",[$jpegphoto]}, # Replace Binary jpegphoto ); $msgid = $ld->modify($entrydn,\%mods); The above would remove the telephoneNumber attribute from the entry and replace the "sn" attribute with "Test". The value in the "mail" attribute for this entry would be replaced with both addresses specified in @mail. The "jpegphoto" attribute would be replaced with the binary data in $jpegphoto. modify_s DN MOD Synchronous version of modify method. Returns an LDAP STATUS. See the modify method for notes and examples of populating the MOD parameter. Example: $status = $ld->modify_s($entrydn,\%mods); modrdn2 DN NEWRDN DELETE Asynchronous method to change the name of an entry. DELETE is non-zero if you wish to remove the attribute values from the old name. Returns a MSGID. Example: $msgid = $ld->modrdn2("cn=Clayton Donley, o=Motorola, c=US", \ "cn=Clay Donley",0); modrdn2_s DN NEWRDN DELETE Synchronous method to change the name of an entry. DELETE is non-zero if you wish to remove the attribute values from the old name. Returns an LDAP STATUS. Example: $status = $ld->modrdn2_s("cn=Clayton Donley, o=Motorola, c=US", \ "cn=Clay Donley",0); next_attribute Similar to first_attribute, but obtains next attribute. Returns a string comtaining the attribute name. An empty string is returned when no further attributes exist. Example: $attr = $ld->next_attribute; next_entry Moves internal pointer to the next entry in a chain of search results. Example: $entry = $ld->next_entry; perror MSG If an error occurs while performing an LDAP function, this procedure will display it. You can also use the err and errstring methods to manipulate the error number and error string in other ways. Note that this function does NOT terminate your program. You would need to do any cleanup work on your own. Example: $ld->perror("add_s"); result MSGID ALL TIMEOUT Retrieves the result of an operation initiated using an asynchronous LDAP call. Returns the type of result returned or -1 if error. MSGID is the MSGID returned by the Asynchronous LDAP call. Set ALL to 0 to receive entries as they arrive, or non-zero to receive all entries before returning. Set TIMEOUT to the number of seconds to wait for the result, or -1 for no timeout. Example: $type = $ld->result($msgid,0,1); result2error FREEIT Returns the LDAP error code from an LDAP result message. FREEIT will free the memory occupied by the result if set non-zero. This routine also updates message returned by err and errstring methods. Example: $lderrno = $ld->result2error(0); search BASE SCOPE FILTER ATTRS ATTRSONLY Begins an asynchronous LDAP search. Returns a MSGID or -1 if an error occurs. BASE is the base object for the search operation. FILTER is a string containing an LDAP search filter. ATTRS is a reference to an array containing the attributes to return. An empty array would return all attributes. ATTRSONLY set to non-zero will only obtain the attribute types without values. SCOPE is one of the following: LDAP_SCOPE_BASE LDAP_SCOPE_ONELEVEL LDAP_SCOPE_SUBTREE Example: @attrs = ("cn","sn"); # Return specific attributes @attrs = (); # Return all Attributes $msgid = $ld->search("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \ "(sn=Donley),\@attrs,0); search_s BASE SCOPE FILTER ATTRS ATTRSONLY Performs a synchronous LDAP search. Returns an LDAP STATUS. BASE is the base object for the search operation. FILTER is a string containing an LDAP search filter. ATTRS is a reference to an array containing the attributes to return. An empty array would return all attributes. ATTRSONLY set to non-zero will only obtain the attribute types without values. SCOPE is one of the following: LDAP_SCOPE_BASE LDAP_SCOPE_ONELEVEL LDAP_SCOPE_SUBTREE Example: @attrs = ("cn","sn"); # Return specific attributes @attrs = (); # Return all attributes $status = $ld->search_s("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \ "(sn=Donley)",\@attrs,0); search_st BASE SCOPE FILTER ATTRS ATTRSONLY TIMEOUT Performs a synchronous LDAP search with a TIMEOUT. See search_s for a description of parameters. Returns an LDAP STATUS. Results are put into RESULTS. TIMEOUT is a number of seconds to wait before giving up, or -1 for no timeout. Example: $status = $ld->search_st("o=Motorola, c=US",LDAP_SCOPE_SUBTREE, \ "(sn=Donley),[],0,3); unbind Unbind LDAP connection with specified SESSION handler. Example: $ld->unbind; url_parse URL Parses an LDAP URL into separate components. Returns a HASH reference with the following keys, if they exist in the URL: host - LDAP Host port - LDAP Port dn - LDAP Base DN attr - LDAP Attributes to Return (ARRAY Reference) filter - LDAP Search Filter scope - LDAP Search Scope options - Netscape key specifying LDAP over SSL Example: $urlref = $ld->url_parse("ldap://ldap.my.org/o=My,c=US"); url_search URL ATTRSONLY Perform an asynchronous search using an LDAP URL. URL is the LDAP URL to search on. ATTRSONLY determines whether we are returning the values for each attribute (0) or only returning the attribute names (1). Results are retrieved and parsed identically to a call to the search method. Returns a non-negative MSGID upon success. Example: $msgid = $ld->url_search($my_ldap_url,0); url_search_s URL ATTRSONLY Synchronous version of the url_search method. Results are retrieved and parsed identically to a call to the search_s method. Returns LDAP_SUCCESS upon success. Example: $status = $ld->url_search_s($my_ldap_url,0); url_search_st URL ATTRSONLY TIMEOUT Similar to the url_search_s method, except that it allows a timeout to be specified. The timeout is specified as seconds. A timeout of 0 specifies an unlimited timeout. Results are retrieved and parsed identically to a call to the search_st method. Returns LDAP_SUCCESS upon success. Example: $status = $ld->url_search_s($my_ldap_url,0,2); AUTHOR ====== Clayton Donley, donley@wwa.com http://miso.wwa.com/~donley/ SEE ALSO ======== perl(1).  File: pm.info, Node: Net/NIS, Next: Net/NISPlus/Table, Prev: Net/LDAPapi, Up: Module List Interface to Sun's Network Information Service ********************************************** NAME ==== Net::NIS - Interface to Sun's Network Information Service DESCRIPTION =========== The Net::NIS interface comes in two parts. The first part is the raw implementation of the NIS API. The second is the object interface, described in `Net::NIS::Table' in this node. This document describes the NIS API implementation. The NIS package implements all functions described in the `ypclnt(3N)' in this node manual page. The following commands have been implemented: yp_bind($domain) Bind the process to a NIS server for the domain $domain. This function is rarely needed. See `yp_bind(3N)' in this node. yp_unbind($domain) Unbind the process from the specified $domain. This function is also rarely required. See `yp_unbind(3N)' in this node. $domain = yp_get_default_domain() Return the host's local domain. (The same as the `domainname' in this node program). See `yp_get_default_domain(3N)' in this node. ($status, $value) = yp_match($domain, $map, $key) Return the $value for the given $key in the $map for the domain $domain. The $key must be an exact match for an item in the map (*i.e.* yp_match does no partial matching. The $value is only valid if $status is equal to $YP_SUCCESS. ($status, $key, $value) = yp_first($domain, $map) Return the first key-value pair from $map in $domain. As the NIS maps are stored in a DBM table, the order of the returned values is not obvious. ($status, $key, $value) = yp_next($domain, $map, $key) Return the next key-value pair from $map in $domain. The $key must be provided from the previous `yp_first' in this node or `yp_next' in this node. The `yp_first' in this node/`yp_next' in this node method is not recommended, as under some circumstances, entries can be skipped or returned twice. `yp_all' in this node is a better interface to use. ($status, \%values) = yp_all($domain, $map) The `yp_all' in this node call returns an entire map in the %values associative array. ($status, $order) = yp_order($domain, $map) This function returns the order number for $domain. Whatever that is. It mustn't be very important, since it's not implemented on NIS+ servers running in "YP-compatibility mode". I put it in for completeness. ($status, $name) = yp_master($domain, $map) Returns the machine name of the master server for a map. $error = yperr_string($status) Returns a string representation of the error code passed in $status. $status = ypprot_err($code) Translates a NIS name service protocol error code to a ypclnt layer error code. Only used for the C version of `yp_all' in this node, and it is only implemented here for completeness. ERROR CODES =========== The $status variable returned by the above functions can have one of the following values: $Net::NIS::ERR_ACCESS Access violation $Net::NIS::ERR_BADARGS Args to function are bad $Net::NIS::ERR_BADDB yp data base is bad $Net::NIS::ERR_BUSY Database is busy $Net::NIS::ERR_DOMAIN Can't bind to a server which serves this domain $Net::NIS::ERR_KEY No such key in map $Net::NIS::ERR_MAP No such map in server's domain $Net::NIS::ERR_NODOM Local domain name not set $Net::NIS::ERR_PMAP Can't communicate with portmapper $Net::NIS::ERR_NOMORE No more records in map database $Net::NIS::ERR_RESRC Local resource allocation failure $Net::NIS::ERR_RPC RPC failure $Net::NIS::ERR_YPBIND Can't communicate with ypbind $Net::NIS::ERR_YPERR Internal yp server or client interface error $Net::NIS::ERR_YPSERV Can't communicate with ypserv $Net::NIS::ERR_VERS YP version mismatch AUTHOR ====== Copyright (c) 1995 Rik Harris (*rik.harris@fulcrum.com.au*). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The Network Information Service (NIS) was formerly known as Sun Yellow Pages (YP). The functionality of the two remains the same; only the name has changed. The name Yellow Pages is a registered trademark in the United Kingdom of British Telecommunications plc, and may not be used without permission.