|
 |
 |
 |
|
|
|
|
|||||||||||||||||||||||||
|
|
PerLDAP: Frequently Asked Questions$Revision: 1.47 $Contact: Leif Hedstrom <leif@netscape.com> Discussion: netscape.public.mozilla.directory
These are the most Frequently Asked Questions about the PerLDAP source and distributions from mozilla.org. A few of these questions will most likely be merged into the official POD documentation, in a later release. The questions are divided into these sections:
Recent changes to this document1999-03-09:
1. General information about PerLDAP
2. Using and building PerLDAP from the source
3. Binary distributions and released versions
4. Working with the source, CVS and bug reports
5. LDAP related questions
6. Platform, Perl and version specific problems
7. Known bugs and problems
8. Missing features and modules
1. General information about PerLDAP
PerLDAP, Perl-LDAP, is made up of two main components to write LDAP clients: An interface to the C SDK API, and a set of Object Oriented Perl classes. The API interface is almost 100% compatible with Netscape's C SDK, but it's harder to use than the OO layer. The Object oriented interface is ment to be an easier way to write most common LDAP clients. For more information, see the Mozilla Directory project home page.
I've also prepared a PerLDAP presentation in
PowerPoint, which is available in
HTML as well.
The source is available via both CVS and FTP. You can use Mozilla's CVS server to easily keep up to date with latest releases and development. For more information about relevant CVS modules to check out, see question 4.5. If you don't have access to CVS, or want to quickly get the latest CVS release, you can FTP a source distribution. After unpacking such a distribution, you can again use CVS to get updates etc. A few unsupported binary distributions are available from Netscape's DevEdge Online, Directory Developer Central. You can download both C SDK distributions, and PerLDAP binaries. Currently only v1.0 PerLDAP has been released, for Solaris and Windows/NT. Binaries for v1.2.1 will be created for a few selected platforms. ActiveState also supports PerLDAP for their ActivePerl builds, check out their Web site.Please use the News Discussion group as much as possible. You can also use Bugzilla, see question 4.7 for details. As a last resort, you can send a mail directly to me (Leif). Here's the list of all currently open PerLDAP bugs and RFEs. Ldapp and Ldapc are the old Perl/LDAP modules developed at Netscape. They are no longer supported, and we strongly recommend you upgrade to use PerLDAP. If you used the OO layer of Ldapp, migrating to PerLDAP should be easy. In most cases it's just a matter of changing the "use" statements, e.g. from use Ldapp; to use Mozilla::LDAP::Conn; Yes! But only if the C SDK you have installed supports SSL, PerLDAP itself does not have any SSL code or encryption code. As such, PerLDAP source can be distributed without any export restrictions. Absolutely, how about: 2. Using and building PerLDAP from the source
CVS is your friend! You can use Mozilla's CVS server to easily keep up to date with latest releases and development. The CVS module for PerLDAP is named PerLDAP. The tip of the tree is the latest stable release, and all development is being done on branches. You can also use FTP to get a packaged source distribution. At a minimum you'll need The latest official release is v1.2.1, released 03/21/99. The tip of the CVS tree is always the latest official release, development is done on branches. We strongly encourage everyone to upgrade from v1.0 to v1.2.1 as soon as possible, it fixes a number of bugs and has many improvements. The beta releases and development branches are only available via CVS. The current beta/development branch is devel-branch-1_3, and the branch for future v2.x is devel-branch-1_9. PerLDAP v1.2.1 has been merged onto the main trunk, and is also tagged as v1.2.1. I'll make snapshots of the development branches available every now and then, or upon request. These can easiest be downloaded from my private FTP site. This is a known problem in PerLDAP v1.0, and is caused by a library naming mismatch. You must also link with both libldap.so and liblber.so when using Mozilla SDK source. The best solution is to use PerLDAP v1.2.1, it fixes these and other problems. Alternatively you can rename the SDK libraries to match the names used in the DevEdge distributions. The following patch to Makefile.PL might also do it (this is not the real solution as used in v1.2.1, but does work with v1.0): You are using PerLDAP v1.0, and didn't apply the patch above, did you? You should have seen a warning like: Well, unfortunately that error can not be ignored, it's vital that you link in the LDAP SDK libraries. Go back to Q-2.5, or get PerLDAP v1.2.1 or later. Absolutely! If you intend to build PerLDAP, you will need a Netscape C-SDK distribution, period. Mozilla distributes the source to this SDK, which will build and run on a number of platforms. Unfortunately this source does not have any encryption support, so you can use SSL. Netscape's DevEdge Online provides precompiled (binary) distributions of the C SDK. You can get if from the Directory Developer Central. 3. Binary distributions and released versions
Currently only two binary distributions are prepared by us, for Solaris and Windows/NT. They are both available from Netscape DevEdge Online, Directory Developer Central. Note that this are created using the old v1.0 version of PerLDAP, new binaries are in progress. ActiveState has also prepared a binary distribution suitable for their ActivePerl release. It's available from their Web site. From DevEdge, it's PerLDAP v1.0, I'm not sure about ActiveState or other sites. Please let me know if you have binary distributions available for certain platforms and packages. This is most likely because your Perl interpreter is built with statically linking the Perl core library. Our binary distributions on Solaris was built with a Perl using libperl.so. If you have this problem, either reconfigure and rebuild Perl, or rebuild PerLDAP. The binary distributions will only work with the Perl version used during the build. Currently that means Perl v5.004. The next binary distributions will hopefully be complete perl distributions, which should make this much easier to maintain. At Netscape's DevEdge site. See Q-2.7 above.
4. Working with the source, CVS and bug reports
CVS is a source code version control system, used to manage large software projects with many developers. It's built on top of RCS, and is available for free for most Unix and Windows platforms. Source for the latest CVS version (currently v1.10.3) can be FTP'd from the Cyclic FTP repository for instance. The source includes documentation, which I've also made available on my Web site. I've also made a few, unsupported, binary distributions available, for: Note that you might have to <shift>-click on the links above to get the download dialog. Alternatively, you can use HTTP to get these files. Again, these are not Mozilla "blessed" builds, I'm just providing them for your convenience. You can use anonymous CVS to the mozilla CVS server, logging in with the username anonymous, password anonymous. For instance, to login and check out the tip of the PerLDAP module, you'll do Remember that you usually only have to login the first time you use CVS, the authentication credentials are stored in your ~/.cvspass file. The "-z3" option tells CVS to use compression, make sure your version of CVS has support for this (some versions apparently chokes badly with this option). The following releases are available, please use the main trunk when possible (to get the latest, stable code): Just as above, but also specify a specific branch to check out. For instance, to update your source to the v1.3 branch, you can do something like We will continuously tag the development branch with snapshots, e.g. devel-release-1_3_1, devel-release-1_3_2 and so on. Hopefully we'll also get these snapshots packaged up automatically and added to the Mozilla FTP server. For now I'm making them available on the PerLDAP site. Of course: It's recommended that you use the main trunk (release-1_2) in production use, and devel-branch-1_3 for PerLDAP development. The PerLDAP module is named PerLDAP. You can also check out the entire "directory" source, with something like The above gives you everything, if you're only intersted in say the C SDK source, you can limit the checkout to the module DirectorySDKSourceC. A list of all available modules is in the modules files in the CVSROOT directory. Post it to the News group. Post it to the News group. If you have access to Bugzilla, file a bug against me. Here's the list of all currently open PerLDAP bugs and RFEs. See previous question, Q-4.7. 5. LDAP related questions
You do a base search with the DN as the baseDN, and a filter of (objectclass=*). For example: Right now there's no code ready for this, but we are working on a DS-4 management module using PerLDAP. This control can be used to manage Smart Referrals for instance. For more information, see the DevEdge documentation. PerLDAP has support for controls, but the OO layers do not use (or support) them at this point. Yep, the API.pm package does. The OO layers (Conn.pm, Entry.pm etc.) do not use an LDAP v3 features, yet. We'll be working on this in the next few months, hopefully adding cool features like LDAP controls, VLV indexes and so on. RTFM, perhaps from one of the links above. By default a PerLDAP search operation will retrieve all attributes that an entry has, assuming you have read permission to the entry (and/or the attributes). You can limit the number of attributes by specifying an array of attribute types, for instance The 0 parameter in the example is a flag, which if set to 1, ("True") tells the search function to only retrieve the attribute types, not the actual values. In most cases you want to set this flag to 0 ("False"). Remember that just because you explicitly asked for an attribute, doesn't necessarily mean you'll get it (either because the entry doesn't have such a user attribute value, or perhaps because you don't have access to it). Some attributes, typically operational attributes, are not returned by default, and you might have to explicitly ask for them. An example of such an attribute is the modifiersName attribute. If you want to get all user attributes, and an operational attribute, you can do The attribute "*" matches all attributes. If you don't want to retrive any attributes at all, specify the attribute "1.1" (there is no such OID, so no attributes can be returned). This is useful if you need the DN only, and no attribute values. This is not generally recommended when using the OO modules (e.g. Conn.pm) . But there are two methods to retrieve the internala handles from the Mozilla::LDAP::Conn object: The first method returns the LDAP connection handle, and the second returns the handle to the last result message. Use these with care, and remember that this might cause your code to break in future version of PerLDAP. Also, the getRes() method is only available as of PerLDAP v1.2, for PerLDAP v1.0 you could instead use an even uglier solution: Using the information from the previous question, the answer is of course: Again, this is not really recommended, and this might change in future releases. One possibility is to add this feature as a native method, but I need to investigate this further, since v2.0 of PerLDAP might use asynchronous LDAP calls (for much better scalability). Another common task is to decide if a search returns exactly one entry, no more, no less. That can easily be done with the existing modules, for instance There are several options, the easiest are then please change it to be one of The outline to create a new object is, as of PerLDAP v1.2, something like: Easy, first bind as the anonymous user, find the DN for the person you wish to authenticate, get the DN, and rebind using the DN and password. This example, which requires PerLDAP v1.2 or later, shows how to do flexible user authentication: 6. Platform and Perl version specific problems
Any Perl version from v5.004 or later. The binaries prepared will only work with the Perl version used during the build, see README and INSTALL information for more details on the distribution. Perl v5.005_02. I know PerLDAP v1.2.1 and later should work on at least these platform and version combinations:
If you are using PerLDAP on another platform, please let us know. I've succesfully compiled Perl and PerLDAP using nmake and Visual C++. Your mileage might vary, if you have build details we want to hear about it. One common problem seems to be where to put the C SDK libldap DLL. I've found that copying the DLL to the perl "bin" directory, where the perl.exe resides, works well. Another good alternative is to add the C-SDK library folder to your PATH environment variable. As of Perl v5.005, it seems that you should put the libldap DLL in the "site" directory, and not the the "bin" directory. For instance, if you installed ActiveState build 509 in C:\perl, put the LDAP DLL in C:\perl\site. All released C SDK versions are supported in PerLDAP v1.2 and later. In v1.0 we only verified SDK v1.2 and SDK v3.0. As of v1.2, the Mozilla C SDK source should also work out of the box with PerLDAP. PerLDAP has full support for SSL, but only if your C SDK has support for it. The Mozilla C SDK source on mozilla.org does not have SSL support, but the DevEdge binary distributions do.The -taso/-xtaso compile options are used for 32 bit compatibility. Specificially What does this mean? Well, apparently there can be a mismatch in how you compiled Perl for instance, causing the dynamic loader to misbehave. If someone can give more information exactly how to compile PerLDAP for OSF, I'd be happy to put that in here (post something to the News group). I don't know, I saw something about some special linker options, someone who knows Irix please let me know. With Perl v5.005, I had to remove the link option -nodefaultlib from the LINK_FLAGS definition in the Makefile (when building Perl itself). I don't know why this was added in v5.005, but at least this solved the problem for me. There are several alternatives to solve this problem, like Easy, give an option like "LIB=/u/leif/lib" to the Makefile.PL script during the installation and configuration, like 7. Known bugs and problems
There's been reports on this, and a patch was made by the nice people at ActiveState. That patch has been merged into PerLDAP v1.2 and later. I've verified that PerLDAP v1.2 and ActivePerl build 509 compiles, unfortunately my regression tests sometimes fails with a Runtime exception error (any one care to debug this in ActivePerl?). No, and yes. We are working on it, for now expect it to use a lot of memory, I'll update this FAQ question if/when I know more. I have a few ideas I'm working on. Adding this code to Entry.pm might help you, I'm working with this for the v1.2.1 release: I know, my regression test also fails with ActivePerl (build 509) some times, with an "Error: Runtime exception". This doesn't happen on all tests, or not even on the same test twice. I can not explain it at this time, other PerLDAP scripts seems to work with ActivePerl, but not the t/conn.pl regression test script. My regression test does a number of different LDAP operations in the same script, and using the same LDAP connection. It does also delete and create new Conn objects frequently. If someone can debug this problem, and let me know if there's anything I can do to fix it, please let me know. Yeah, I know, I suck... This has been fixed in PerLDAP v1.2.1. 8. Missing features and modules
The API.pm has full support for controls, but apparently a bug in the v1.0 PerLDAP source prevents using LDAP v3 extensions. This is fixed in PerLDAP v1.2 and later. There's no OO layers for controls yet, but it's on our ToDo list. More information about using LDAP v3 controls are available on the DevEdge documentation site. Yes, if you write code using the API directly. An OO module will be added in v1.5. Yes, if you use API directly. We will have a VLV OO module for v1.5 or v2.0. I suck. Version v1.2 has some minor improvements, and in v1.3 we have a completely new LDIF.pm module, written by Netscape LDAP guru John Kristian <kristian@netscape.com> Not any specific code, yet. Hopefully a new schema package, and a Netscape Console module will be developed by Netscape's Allen Tom <atom@netscape.com> Tons of new code. I'm just about ready with v1.2.1, and I'm eager start working on some new cool features for v1.4/v2.0. Some ideas include Problems with this page? Last modified: Mon Mar 22 23:10:21 1999 |
|
||||||||||||||||||||||||||||
|
 |
 |
|
|
|
|
|||||||||||||||||||||||||
| Copyright © 1998-1999 The Mozilla Organization. | |||||||||||||||||||||||||||||||
