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 document

• Added some links to CVS binaries.
• Added Q-5.6, about LDAP attributes.

1. General information about PerLDAP

1. What is PerLDAP?
2. Where can I get source code for PerLDAP?
3. Where can I get binary distributions?
4. Where do I send bug reports, or ask for help?
5. What about Ldapp? How can I migrate to PerLDAP?
6. Does PerLDAP support SSL?
7. Do you have some links to relevant LDAP sites?

2. Using and building PerLDAP from the source

1. How do I get the source code?
2. What do I need to build PerLDAP?
3. What's the latest PerLDAP version?
4. Where are the beta/development releases?
5. Why doesn't PerLDAP v1.0 build with Mozilla SDK?

3. Binary distributions and released versions

1. Where can I find a binary distribution for platform <XXX>?
2. What's the latest released binary version?
3. Why is the "Perl_tmps_floor" symbol missing??
4. I can't get the v1.0 binary distribution to work with Perl v<Y.Z>.

4. Working with the source, CVS and bug reports

1. What the heck is CVS? How do I use it? Where can I get it?
2. How do I check out the latest, stable released code?
3. How do I check out a beta/development branch?
4. Is there a list of all development branches?
5. What CVS modules are available and relevant to PerLDAP?
6. Where do I send patches or new code I'd like to contribute?
7. How do I report a bug I just found?
8. Where can I read about known, open bugs?

5. LDAP related questions

1. How do I "browse" an LDAP entry when I know it's DN?
2. How can I manage my Netscape DS-4 server information with PerLDAP?
3. What is the "manage DSA IT" control? Can I use it with PerLDAP?
4. Does PerLDAP support all LDAP v3 features?
5. How do I search for something? What is an LDAP filter?
6. How do I specify/limit what attributes are retrieved in a search?

6. Platform and Perl version specific problems

1. What Perl versions are supported?
2. Which Perl version is recommended?
3. Which Unix and Windows platforms are supported?
4. How do I get PerLDAP to work on my Windows/NT machine?
5. What C SDKs are supported? What about SSL?
6. What is the build options for DecUnix/OSF? What is "-taso"?
7. What link options are used/needed for Irix?

7. Known bugs and problems

1. I can't get PerLDAP to work with ActiveState.
2. Is it just me, or is PerLDAP very memory intensive?

8. Missing features and modules

1. What about LDAP controls?
2. How can I use and support the LDAP v3 password management control?
3. Does PerLDAP support VLV indexes?
4. The LDIF module seems horky, what gives?
5. Are there any PerLDAP code to manage LDAP schemas?
6. What are the plans for the next PerLDAP version?

1. General information about PerLDAP

1. What is 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.

2. Where can I get source code for PerLDAP?

   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.

3. Where can I get binary distributions?

   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.

   ActiveState also supports PerLDAP, check out their Web site.

4. Where do I send bug reports, or ask for help?

   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).

5. What about Ldapp? How can I migrate to PerLDAP?

   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;

6. Does PerLDAP support SSL?

   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.

7. Do you have some links to relevant LDAP sites?

   Absolutely, how about:

   • The official Mozilla Directory source code home page.
   • Netscape DevEdge Directory Developer Central.
   • My private LDAP central pages.
   • The PerLDAP home page, not much there yet, but I'm working on it...

2. Using and building PerLDAP from the source

1. How do I get the source code?

   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.

2. What do I need to build PerLDAP?

   At a minimum you'll need

   • An ANSI compatible C compiler (e.g. gcc or Visual C++).
   • A make tool, like GNU make, or nmake.
   • Perl version 5.004 or later, including ActiveState's latest Perl distribution (but not ActiveState v5.003 or earlier).
   • A C SDK, either a binary distribution from Netscape's DevEdge, or the Mozilla source.

3. What's the latest PerLDAP version?

   The latest official release is v1.0. The tip of the CVS tree is always the latest official release, development is done on branches. Work is in progress to finish v1.1, which is available as a beta release already. v1.1 has very few new features, it's primarily a bug fix release.

4. Where are the beta/development releases?

   The beta releases and development branches are only available via CVS. The current beta/development branch is devel-branch-1_1, the next branch (not yet available) will be devel-branch-1_5. When v1.1 is release, the development branch will be merged into the tip of the tree.

   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.

5. Why doesn't PerLDAP v1.0 build with Mozilla SDK?

   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 the latest development branch (v1.1 or later) of PerLDAP, which fixes this problem. 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.1, but does work with v1.0):

   
   Index: Makefile.PL
   ===================================================================
   RCS file: /cvsroot/mozilla/directory/perldap/Makefile.PL,v
   retrieving revision 1.13
   diff -c -r1.13 Makefile.PL
   *** Makefile.PL 1998/08/14 21:45:39     1.13
   --- Makefile.PL 1998/09/08 08:54:53
   ***************
   *** 128,134 ****
           ) : (
           'INC'           =>      "",
           )),
   !       'LIBS'          =>      ["-L$lib_ldap -l$ldap_lib"],
           'MYEXTLIB'      =>      $myextlib,
           'DEFINE'        =>      "$v3_def $ssl_def",
     );
   --- 128,134 ----
           ) : (
           'INC'           =>      "",
           )),
   !       'LIBS'          =>      ["-L$lib_ldap -lldap -llber"],
           'MYEXTLIB'      =>      $myextlib,
           'DEFINE'        =>      "$v3_def $ssl_def",
     );
     

3. Binary distributions and released versions

1. Where can I find a binary distribution for platform <XXX>?

   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.

   ActiveState has also prepared a binary distribution suitable for their ActivePerl release. It's available from their Web site.

2. What's the latest released binary version?

   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.

3. Why is the "Perl_tmps_floor" symbol missing?

   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.

4. I can't get the v1.0 binary distribution to work with Perl v<Y.Z>.

   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.

4. Working with the source, CVS and bug reports

1. What the heck is CVS? How do I use it? Where can I get it?

   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:

   • Linux (install with "rpm -i cvs-1.10.3-1.i586.rpm").
   • Solaris (gunzip the file, and install with "pkgadd -d GNUcvs-1.10.3.pkg").
   • Windows/NT (use your favorite "unzip" application to extract the cvs.exe binary).

   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.

2. How do I check out the latest, stable released code?

   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

   
   % cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot login
   (Logging in to anonymous@cvs-mirror.mozilla.org)
   CVS password:  [you type anonymous]
   %
   % cvs -z3 -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co PerLDAP
   
   cvs server: Updating mozilla/directory/perldap
   U mozilla/directory/perldap/API.pm
   U mozilla/directory/perldap/API.xs
   U mozilla/directory/perldap/ChangeLog
   .
     

   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).

3. How do I check out a beta/development branch?

   Just as above, but also specify a specific branch to check out. For instance, to update your source to the v1.1 branch, you can do something like

   
   % cd mozilla/directory/perldap
   % cvs -z3 update -r devel-branch-1_1
   cvs server: Updating .
   P API.pm
   P API.xs
   .
     

4. Is there a list of all development branches?

   No, currently there's only one branch, devel-branch-1_1, the next development branch will be devel-branch-1_5.

5. What CVS modules are available and relevant to PerLDAP?

   The PerLDAP module is named PerLDAP. You can also check out the entire "directory" source, with something like

   
   % cvs -d :pserver:anonymous@cvs-mirror.mozilla.org:/cvsroot co mozilla/directory
     

   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.

6. Where do I send patches or new code I'd like to contribute?

   Post it to the News group.

7. How do I report a bug I just found?

   Post it to the News group. If you have access to Bugzilla, file a bug against me.

8. Where can I read about known, open bugs?

   See previous question.

5. LDAP related questions

1. How do I "browse" an LDAP entry when I know it's DN?

   You do a base search with the DN as the baseDN, and a filter of (objectclass=*). For example:

   
   use Getopt::Std;
   use Mozilla::LDAP::Conn;
   use Mozilla::LDAP::Utils;
   #
   # Include other code to parse arguments etc here...
   #
   $DN = "uid=leif, ou=People, dc=netscape, dc=com";
   $conn = new Mozilla::LDAP::Conn(\%ld);
   die "Could't connect to LDAP server $ld{host}" unless $conn;
   
   $entry = $conn->search($DN, "base", "(objectclass=*)");
   if ($entry) {
     # We found one entry
   } else {
     # We did not find an entry, the DN is invalid.
   }
     

2. How can I manage my Netscape DS-4 server information with PerLDAP?

   Right now there's no code ready for this, but we are working on a DS-4 management module using PerLDAP.

3. What is the "manage DSA IT" control? Can I use it with 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.

4. Does PerLDAP support all LDAP v3 features?

   Yep, the API.pm does. The OO layers (Conn.pm, Entry.pm etc.) do not use an LDAP v3 features, yet.

5. How do I search for something? What is an LDAP filter?

   RTFM, perhaps from one of the links above.

6. How do I specify/limit what attributes are retrieved in a search?

   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

   
   @attr = ("cn", "uid", "mail");
   $entry = $conn->search($base, "sub", $filter, 0, @attr);
     

   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

   
   @attr = ("*", "modifiersName");
   $entry = $conn->search($base, "sub", $filter, 0, @attr);
     

   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.

   
   @attr = ("1.1");
   $entry = $conn->search($base, "sub", $filter, 0, @attr);
     

6. Platform and Perl version specific problems

1. What Perl versions are supported?

   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.

2. Which Perl version is recommended?

   Perl v5.005_02.

3. Which Unix and Windows platforms are supported?

   I know PerLDAP should work on at least these platforms:

   • SunOS 5.5 - 5.6 (aka Solaris 2.5/2.6)
   • Linux, using glibc2.
   • Windows/NT v4.0 with SP3 and SP4.

   If you are using PerLDAP on another platform, please let us know.

4. How do I get PerLDAP to work on my Windows/NT machine?

   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.

5. What C SDKs are supported? What about SSL?

   All released C SDK versions are supported in PerLDAP v1.1 and later. In v1.0 we only verified SDK v1.1 and SDK v3.0. As of v1.1, 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.

6. What is the build options for DecUnix/OSF? What is "-taso"?

   The -taso/-xtaso compile options are used for 32 bit compatibility. Specificially

   • -taso ensures that the code is 32 bit compatible, specfically, the linker forces loading of a library or module into the lower 31 bits of virtual memory. It is useful in porting from 32-bit architectures.
   • -xtaso extends the 32 bit -taso style builds to optionally use 32-bit pointers. This requires using #pragma pointer_size in the code and linking with -taso and -xtaso objects.

   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).

7. What link options are used/needed for Irix?

   I don't know, I saw something about some special linker options, someone who knows Irix please let me know.

7. Known bugs and problems

1. I can't get PerLDAP to work with ActiveState.

   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.1 and later, if someone could verify that it works that'd be great.

2. Is it just me, or is PerLDAP very memory intensive?

   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.

8. Missing features and modules

1. What about LDAP controls?

   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.1 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.

2. How can I use and support the LDAP v3 password management control?

   Yes, if you write code using the API directly. An OO module will be added in v1.5.

3. Does PerLDAP support VLV indexes?

   Yes, if you use API directly. We will have a VLV OO module for v1.5 or v2.0.

4. The LDIF module seems horky, what gives?

   I suck. Version v1.1 has some minor improvements, but LDIF.pm is still very much work in progress.

5. Are there any PerLDAP code to manage LDAP schemas?

   Not any specific code, and apparently there's issues using the regular PerLDAP modules. I don't have any details on this, but I have an open bug on this issue.

6. What are the plans for the next PerLDAP version?

   Tons of new code. I hope to have PerLDAP v1.1 finished any day now, and start working on some new cool features for v1.5.