From: Chris R. <chr...@us...> - 2003-05-06 15:54:23
|
Update of /cvsroot/perl-ldap/ldap/lib/Net/LDAP In directory sc8-pr-cvs1:/tmp/cvs-serv9918 Modified Files: FAQ.pod Log Message: Major updates to terminology section, misc fixes, and updated books Index: FAQ.pod =================================================================== RCS file: /cvsroot/perl-ldap/ldap/lib/Net/LDAP/FAQ.pod,v retrieving revision 1.27 retrieving revision 1.28 diff -u -d -r1.27 -r1.28 --- FAQ.pod 14 Mar 2003 10:04:55 -0000 1.27 +++ FAQ.pod 6 May 2003 15:54:19 -0000 1.28 @@ -48,13 +48,14 @@ =head2 Is there a mailing list ? -Yes there is at per...@li... +Yes there is at per...@pe... -You can subscribe to this list at - http://lists.sourceforge.net/mailman/listinfo/perl-ldap-dev +You can subscribe to this list by mailing per...@pe... =head2 Is the mailing list archived ? +Yes, at http://archive.develooper.com/per...@pe.../ + Archives of messages since we switched to using sourceforge can be found at @@ -145,8 +146,8 @@ =head2 What is a directory. -A directory is a special purpose database that usually contains -typed information such as text strings, binary data, or X.509 +A directory is a special purpose hierarchical database that usually +contains typed information such as text strings, binary data, or X.509 certificates. =head2 What is LDAP. @@ -167,14 +168,13 @@ =head2 What is a LDAP Directory. -In the strictest terms of the definition there is no such -thing as a LDAP directory. To be practical about this -situation every day directory professionals refer to their -directory as " a LDAP directory" because it is easy to -say and it does convey the type of protocol used to -communicate with their directory. Using this definition -a LDAP directory is a directory whose server software -conforms to the Lightweight Directory Access Protocol when +In the strictest terms of the definition there is no such thing as a +LDAP directory. To be practical about this situation every day +directory professionals refer to their directory as " a LDAP +directory" because it is easy to say and it does convey the type of +protocol used to communicate with their directory. Using this +definition a LDAP directory is a directory whose server software +conforms to the Lightweight Directory Access Protocol when communicating with a client. =head2 What is an Entry. @@ -183,19 +183,80 @@ is called an Entry. Entries are composed of attributes that contain the information to be recorded about an object. -Another non-traditional definition of a directory object -is called a record. Some directory professionals prefer -to use this definition because of the confusion that sometimes -results when using the term Entry. +(An entry in LDAP is somewhat analogous to a record in a table in an +SQL database, but don't get too hung up about this analogy!) -=head2 What is a Distinguished Name. +Entries are held in an upside-down tree structure. Entries can +therefore contain subordinate entries, and entries B<must> have one +direct superior entry. -Every entry in a directory, whether it is X.500 or LDAP, has -a Distinguished Name, or DN. It is a unique Entry identifier -through out the complete directory. No two Entries can have the -same DN within the same directory. +Entries with subordinate entries are called 'non-leaf' entries. -Example of a DN: +Entries without subordinate entries are called 'leaf' entries. + +An entry's direct superior entry is called the entry's 'parent'. + +'Non-leaf' entries are also said to have 'child' entries. + +=head2 What is an attribute. + +The entry(s) in a directory are composed of attributes that contain +information about the object. Each attribute has a type +and can contain one or more values. + +For example: + + cn=Road Runner + +is an attribute with a type named "cn", and one value. + +Each attribute is described by a 'syntax' which defines what kind of +information can be stored in the attributes values. Trying to store a +value that doesn't conform to the attribute's syntax will result in an +error. + +For example: + + jpegPhoto=unknown + +is not permitted by the directory, because jpegPhotos may only contain +JPEG-formatted images. + +Attributes may also be searched. The algorithms used to perform +different kinds of searches are described by the attribute's 'matching +rules'. Some matching rules are case-sensitive and some are +case-insensitive, for example. Sometimes matching rules aren't +defined for a particular attribute: there's no way to search for +jpegPhotos that contain a substring! + +You can examine all of a server's attribute definitions by reading the +schema from the server. + +=head2 What is an object class. + +An object class is the name associated with a group of attributes that +B<must> be present in an entry, and the group of attributes that +B<may> also be present in an entry. + +Object classes may be derived (subclassed) from other object classes. +For example the widely used 'inetOrgPerson' object class is derived +from 'organizationalPerson', which is itself derived from 'person' +which is itself derived from 'top'. + +Every entry has an attribute called 'objectClass' that lists all the +names of object classes (and their superclasses) being used with the +entry. + +You can examine all of a server's objectclass definitions by reading +the schema from the server. + +=head2 What is a Distinguished Name (DN). + +Every entry in a directory has a Distinguished Name, or DN. It is a +unique Entry identifier throughout the complete directory. No two +Entries can have the same DN within the same directory. + +Examples of DNs: cn=Road Runner, ou=bird, dc=cartoon, dc=com ou=bird, dc=cartoon, dc=com @@ -204,12 +265,15 @@ =head2 What is a Relative Distinguished Name. -Every Entry in a directory, whether it is X.500 or LDAP, has -a Distinguished Name which is made up of a sequence of Relative -Distinguished Names, or RDNs. The sequences of RDNs are separated -by commas (,) or semi-colons (;). There can be more than one -identical RDN in a directory, but they must be in different -bases, or branches, of the directory. +Every DN is made up of a sequence of Relative Distinguished Names, or +RDNs. The sequences of RDNs are separated by commas (,). In LDAPv2 +semi-colons (;) were also allowed. There can be more than one +identical RDN in a directory, but they must have different parent +entries. + +Technically, an RDN contains attribute-value assertions, or AVAs. When +an AVA is written down, the attribute name is separated from the +attribute value with an equals (=) sign. Example of a DN: @@ -221,21 +285,33 @@ RDN => dc=cartoon RDN => dc=com -The RDNs are delimited by a comma. +RDNs can contain multiple attributes, though this is somewhat +ususual. They are called multi-AVA RDNs, and each AVA is separated in +the RDN from the others with a plus sign (+). -=head2 What is a Naming RDN. +Example of a DN with a multi-AVA RDN: -Example of a DN: + cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com - cn=Road Runner,ou=bird,dc=cartoon,dc=com +=head2 Where is an entry's name held? - Naming RDN of the proceeding DN: +Entries do B<not> contain their DN. When you retrieve an entry from +a search, the server will tell you the DN of each entry. - cn=Road Runner +On the other hand, entries B<do> contain their RDN. Recall that the RDN +is formed from one or more attribute-value assertions (AVAs); each entry +must contain all the attributes and values in the RDN. -Most of the time when directory professionals refer -to the RDN of an entry, this is the RDN that they -are referring to. +For example the entry: + + cn=Road Runner+l=Arizona,ou=bird,dc=cartoon,dc=com + +B<must> contain a 'cn' attribute containing at least the value +"Road Runner", B<and> an 'l' attribute containing at least the value +"Arizona". + +The attributes used in the RDN may contain additional values, but the +entry still only has one DN. =head2 What is a search base. @@ -256,19 +332,7 @@ Setting the search base to the lowest possible branch of the directory will speed up searches considerably. -=head2 What is an attribute. - -The entry(s) in a directory are composed of attributes that contain -information about the object. Each attribute has a type -and can contain one or more values. The attribute type is -associated with a syntax that defines what kind of information -can be stored in the attributes values and controls how -directory operations on the attribute behave. What attributes -are required and allowed in a entry is controlled by content -rules that are defined on a per-server basis or by a special -attribute in each entry called an objectClass. - -=head2 What is the difference between a LDAP server and a relational database +=head2 What is the difference between a LDAP server and a relational database. The most basic difference is that a directory server is a specialized database designed to provide fast searches. While a relational @@ -278,7 +342,7 @@ Directories also typically are hierarchical in nature (RDBMS is typically flat, but you can implement a hierarchy using tables and queries), -network-able, distributed and replicated. +networkable, distributed and replicated. LDAP provides an open-standard to a directory service. @@ -286,7 +350,7 @@ provide an LDAP client now) and authorization services (authentication and access control). -You could use a RDBMS for these types of queries but there's not a +You could use a RDBMS for these types of queries but there's no set standard, in particular over TCP/IP to connect to databases over the network. There's language specific protocols (like Perl's DBI and Java's JDBC) that hide this problem behind an API abstraction, but that's not a @@ -326,11 +390,11 @@ same steps that you would for most other distributions found on CPAN, that is - # replace 0.13 with the version you have + # replace 0.27 with the version you have - gunzip perl-ldap-0.13.tar.gz - tar xvf perl-ldap-0.13.tar - cd perl-ldap-0.13 + gunzip perl-ldap-0.27.tar.gz + tar xvf perl-ldap-0.27.tar + cd perl-ldap-0.27 perl Makefile.PL make @@ -472,19 +536,20 @@ =head2 What is the proper format of the bind DN. -The DN used to bind to a LDAP or X.550 directory is a FULLY QUALIFIED DN. -The exact syntax of the DN will vary between LDAP or X.500 implementations. +The DN used to bind to a directory is a FULLY QUALIFIED DN. The exact +structure of the DN will depend on what data has been stored in the +server. The following are valid examples. -uid=clif,ou=People,dc=umich,dc=edu + uid=clif,ou=People,dc=umich,dc=edu -cn=directory manager,ou=admins,dc=umich,dc=edu + cn=directory manager,ou=admins,dc=umich,dc=edu -In many LDAP and X.500 directory implementations the following -would be a valid fully qualified DN of the directory manager. +In some servers the following would be a valid fully qualified DN of +the directory manager. -cn=directory manager + cn=directory manager =head2 How can I tell when the server returns an error, bind() always returns true ? @@ -501,9 +566,9 @@ # Handle error codes here } -=head2 How can I set the ldap version of a connection to my ldap server? +=head2 How can I set the LDAP version of a connection to my ldap server? -This is done by adding the version option when binding to the ldap +This is done by adding the version option when binding to the LDAP server. For example; @@ -515,7 +580,7 @@ =head2 I did a search on my directory using the 'search' method. Where did the results go ? -Your search results are stored in a 'search object' container. +Your search results are stored in a 'search object'. Consider the following: use Net::LDAP; @@ -526,10 +591,10 @@ filter => "uid=jsmith", ); -$mesg is a search object container. It is a reference blessed into the -L<Net::LDAP::Search> package. By calling methods on -this object you can obtain information about the result and also the -individual entries. +$mesg is a search object. It is a reference blessed into the +L<Net::LDAP::Search> package. By calling methods on this object you +can obtain information about the result and also the individual +entries. The first thing to check is if the search was successful. This is done with with the method $mesg->code. This method will return the status code @@ -562,9 +627,9 @@ # ... } -In each case $entry is an entry object container. It is a reference blessed -into the L<Net::LDAP::Entry> package. By calling methods on this object -you can obtain information about the entry. +In each case $entry is an entry object. It is a reference blessed into +the L<Net::LDAP::Entry> package. By calling methods on this object you +can obtain information about the entry. For example, to obtain the DN for the entry @@ -764,7 +829,7 @@ =head1 USING NET::LDAPS -=head2 Using a potentially encrypted (SSL) network connection, how do I connect to my server? +=head2 Using an SSL network connection, how do I connect to my server? This class is a subclass of Net::LDAP so all the normal Net::LDAP methods can be used with a Net::LDAPS object; @@ -790,11 +855,12 @@ =head2 What are LDAP groups. -LDAP groups are a collection of distinguished names (DN) that are -listed in an attribute called member. One I<important note> to -remember is that a group can be a collection of groups. This -does I<NOT> imply that the subgroups will be flattened into one -big group. +LDAP groups are object classes that contain an attribute that can +store multiple DN values. Two standard object classes are +'groupOfNames' (which has a 'member' attribute) and +'groupOfUniqueNames' (which has a 'uniqueMember' attribute.) + +A group can be a member of another group. Two scripts for working with groups are available in the contrib directory. They are isMember.pl and printMembers.pl. @@ -893,7 +959,7 @@ must register with sourceforge before your scripts will be put into the contrib CVS system. -=head2 Is possible to get a complete entry, dn and attributes +=head2 Is possible to get a complete entry, DN and attributes without specifying the attributes name? Yes, just specify you want a list of no attributes back. The RFC says @@ -910,7 +976,7 @@ attrs => [ "*" ] -=head2 How do I put a jpeg photo into a entry in the directory. +=head2 How do I put a JPEG photo into a entry in the directory. Follow the following code example, replacing the (...) with whatever is relevant to your setup. @@ -977,7 +1043,7 @@ my $mesg = $ldap->modify( $entry, replace => { %qv_del_arry } ); -But make sure you are using LDAPv3, because that is defined to *not* work +But make sure you are using LDAPv3, because that is defined to B<not> work in LDAPv2. (A nice incompatibility between LDAPv2 and LDAPv3.) =head2 How can I delete a referral from an LDAP tree. @@ -1100,7 +1166,7 @@ The first problem here is that there are many different formats to hold certificates in, for example PEM, DER, PKCS#7 and PKCS#12. The directory -*only* uses the DER format (more correctly, it only uses the BER format) +B<only> uses the DER format (more correctly, it only uses the BER format) which is a binary format. Your first job is to ensure that your certificates are therefore in DER/BER @@ -1118,34 +1184,35 @@ To slurp in the certificate try something like this: - my $cert; - { - local $/ = undef; # Slurp mode - open CERT, "cert.der" or die; - $cert = <CERT>; - close CERT; - } - # The certificate is now in $cert + my $cert; + { + local $/ = undef; # Slurp mode + open CERT, "cert.der" or die; + binmode CERT; + $cert = <CERT>; + close CERT; + } + # The certificate is now in $cert For LDAPv2, because most directory vendors ignore the string representation of certificates defined in RFC 1778, you should add this value to the directory like this: - $res = $ldap->modify("cn=My User, o=My Company,c=XY", - add => [ - 'userCertificate' => [ $cert ] - ]); - die "Modify failed (" . ldap_error_name($res->code) . ")\n" - if $res->code; + $res = $ldap->modify("cn=My User, o=My Company,c=XY", + add => [ + 'userCertificate' => [ $cert ] + ]); + die "Modify failed (" . ldap_error_name($res->code) . ")\n" + if $res->code; For LDAPv3, you must do this instead: - $res = $ldap->modify("cn=My User, o=My Company, c=XY", - add => [ - 'userCertificate;binary' => [ $cert ] - ]); - die "Modify failed (" . ldap_error_name($res->code) . ")\n" - if $res->code; + $res = $ldap->modify("cn=My User, o=My Company, c=XY", + add => [ + 'userCertificate;binary' => [ $cert ] + ]); + die "Modify failed (" . ldap_error_name($res->code) . ")\n" + if $res->code; Of course, the entry you are trying to add the certificate to must use object classes that permit the userCertificate attribute, otherwise the @@ -1244,9 +1311,12 @@ Solaris and LDAP Naming Services. By Tom Bialaski, Michael Haines. ISBN: 0-13-030678-9 -Understanding and Deploying Ldap Directory Services. -By Tim Howes, Mark Smith, Gordon Good, Timothy A. Howe -ISBN: 1578700701 +Understanding and Deploying LDAP Directory Services (2ed). +By Tim Howes, Mark Smith, Gordon Good +ISBN: 0672323168 + +LDAP Directories Explained. +By Brian Arkills. ISBN 0-201-78792-X =head1 AUTHORS |