Chapter 1   Introduction to the iPlanet
Directory Server Resource Kit


The iPlanet™ Directory Server Resource Kit (iPlanet DSRK) provides tools and APIs for deploying, accessing, tuning, and maintaining your iPlanet Directory Server. These utilities will help you implement and maintain more robust solutions based on LDAP, the Lightweight Directory Access Protocol.

The LDAP SDKs (Software Development Kits) for C and Java™ programming languages make it simple to write client applications for your directory. These APIs expose all of the functions for connecting to an LDAP directory and accessing or modifying its entries. Use them to design and integrate directory functionality into your applications at the programmatic level.

The command-line tools will help you test the performance of your Directory Server installation, debug logs and database files, and administer the contents of your directory. These tools are themselves based on the LDAP SDKs, and they were created to help iPlanet development teams to test and validate the iPlanet Directory Server.

This chapter contains the following sections:

• What's New

• iPlanet LDAP SDK for C

• iPlanet Java LDAP SDK

• Tools Reference

What's New

---

This section briefly describes the new tools in the iPlanet Directory Server Resource Kit, v5.1, and any new features of existing tools since the previous release.

New ldapcompare Tool

The new ldapcompare tool described in Chapter 6 simplifies the task of verifying attribute values in a directory. It takes either a textual or binary attribute value and determines whether or not it is equal to the contents of one or more entries. By using this tool in scripts, you can simplify common LDAP applications such as validation or authorization based on existing attribute values.

New ldclt Tool

The new ldclt (LDAP client) tool described in Chapter 9 is a powerful application for performing a variety of performance tests on a directory. The multi-threaded tool performs searches, additions, modifications, deletions or entry renaming while measuring the average response time of the directory server.

This highly configurable tool provides many options for tailoring the data and randomizing the values used to test the directory. This flexibility allows you to closely simulate the actual usage of your LDAP directory under many conditions. And the many command-line options make this tool easy to use in scripts for automatic testing.

New create_instance.pl Tool

The new create_instance.pl tool described in Chapter 15 is a command-line tool that allows you to create new instances of Directory Server 4.x in an existing installation. This tool is not compatible with Directory Server 5.x.

New replcheck.pl Tool

The new replcheck.pl (replication check) tool described in Chapter 22 compares the replication status of two or more iPlanet Directory Server. This Perl script can be used to monitor replicas automatically and report which pairs of replicas are not in sync.

New Gateway Sample Application

This web-based phone book application described in Chapter 29 is the new version of the gateway application previously available with iPlanet Directory Server. Entirely rewritten and now based on JavaServer Pages™ (JSP™) technology, this complete implementation shows one way to access a directory server through a web browser.

The new gateway uses XML-like tags and servlets written in the Java™ programming language to encapsulate the logic that accesses the directory and generates the web page in response. The application is easy to install and the LDAP Tag Library reference in Chapter 30 provides an extensible foundation for your web-based directory applications.

idsktune for Windows

The idsktune tool now runs on Windows platforms and reports on operating system compatibility and the required service pack level.

New Password Security

The tools based on the iPlanet LDAP SDK for C (ldapsearch, ldapmodify, ldapdelete, ldapcompare, and ldapcmp) now include options to avoid exposing the bind password on the command line. When performing simple authentication with a bind DN, you may specify the new -j filename option to read the password from a file or the -w - option to enter the password interactively.

New searchrate Functionality

The searchrate command described in Chapter 11 now supports multiple input files and multiple randomized strings in search filters. This functionality allows you to create more complex and thus more realistic scenarios for performance measurements.

New modrate Options

The modrate command described in Chapter 12 has two new options to manage referrals:

-O hopLimit (Capital letter O) specifies the maximum number of referral hops to follow while finding an entry to modify.

-R specifies that referrals should not be followed. By default, referrals are followed automatically.

New authrate Option

The authrate command described in Chapter 13 has a new option:

-i inputFile allows you to use %s placeholders for substituting random strings from the input file into the bind DN or password strings on the command line. This allows you to create realistic authentication scenarios.

Renamed infadd Options

The following options have changed in the infadd tool described in Chapter 14. They have been renamed for consistency with the other performance evaluation tools:

-D bindDN       replaces      -u bindDN
-B baseDN       replaces      -s suffix
-y      replaces      -d      (for TCP_NODELAY)
-m addOps       replaces      -l addOps
-j seconds       replaces      -i millisecs

New logconv.pl Options

The logconv.pl script described in Chapter 21 has two new options:

-N will resolve IP addresses into hostnames for easier reading of the output.

-E errorCode will count of the number of errors of the given numeric code and display a table with the details of each occurrence.

viewcore Renamed to viewldbg

The viewcore tool has been renamed to viewldbg (view LDAP debugging), but its functionality remains unchanged (see Chapter 25).

Quick Installation

---

Follow the simple instructions in the "Installation Guide" chapter to install or update to the iPlanet Directory Server Resource Kit Version 5.1. Thanks to a simplified installer, the whole process should take less than five minutes.

The installation contains all the libraries for using the LDAP SDKs and all the executables for running the tools. No configuration is necessary, and you can start using the software right away. Only the sample phone book application requires you to install further components, but these are provided in the product.

To help you get started, the iPlanet LDAP SDK for C contains example code, and the toolkit includes many sample Perl scripts that use the tools to perform specific maintenance operations.

iPlanet LDAP SDK for C

---

The iPlanet DSRK bundles version 5.08 of the iPlanet LDAP SDK for C. Use this library to write client applications in C or C++ that take full advantage of the performance of the iPlanet Directory Server. The API includes extensions that also give access to the latest features of iPlanet Directory Server 5.1.

Built around the core functions of the LDAP v2 and v3 standards, the API can be used to interact with any conforming LDAP server as well. This API conforms to IETF standard "LDAP Application Programming Interface," defined by RFC 1823 and now revised by draft-ietf-ldapext-ldap-c-api-05.

The API is defined by the header files that declare all of the functions, data types and code values that are available in the binaries. The complete API is documented separately in the iPlanet LDAP SDK for C Programming Guide, available from the same source as this document. The SDK also includes sample code that demonstrates how to call most of the functions.

The iPlanet LDAP SDK for C is a binary release of the open source LDAP SDK for C source code available through www.mozilla.org. Updated releases are also available at:

http://www.iplanet.com/downloads/developer/

iPlanet Java LDAP SDK

---

The iPlanet DSRK bundles version 4.15 of the iPlanet LDAP SDK for the Java™ programming language. Equivalent in functionality to the SDK for C, Java client applications use this API to interact with LDAP directories. Whereas the Java Naming and Directory Interface™ (JNDI) provides a protocol-independent abstraction of directory services, this API exposes the LDAP-specific operations for direct access to an LDAP directory server.

Use the classes and methods of the API to develop LDAP-enabled applets or applications for the J2EE™ platform or any of the Java platforms.

The iPlanet LDAP SDK for Java conforms to the IETF standard "Java LDAP Application Program Interface," defined by draft-ietf-ldapext-ldap-java- api-15. The SDK consists of binary jar files containing all packages, classes and methods of the API. The source code is also available as open source through www.mozilla.org, and updated releases are available at:

http://www.iplanet.com/downloads/developer/

The Java API is documented separately in the iPlanet LDAP SDK for Java Programming Guide, also available from the same source as this document. However, the programming guide does not include all of the latest updates to the API. Please refer to the corresponding Javadoc™ pages for the latest reference information.

Tools Reference

---

The third component of the iPlanet Directory Server Resource Kit is the set of tools and scripts that make a directory accessible through a command-line shell. The wide range of tools can be used for simple directory access, for performance testing, and for the maintenance of directory servers. Finally, the commands that run these tools can be used to write scripts to automate all of these tasks.

This guide explains how to use each of the tools by giving their command-line reference information, usage scenarios and examples. Each tool is covered in a separate chapter and chapters for like tools are grouped within a part of the book.

Directory Access Commands

The directory access commands provide the fundamental tools for accessing a directory. Use these commands to retrieve entries, view their attributes, and make modifications. These tools are based directly upon the iPlanet LDAP SDK for C and make the functionality of this API available through their various options.

Table 1-1    Directory Access Commands

Command	Purpose
ldapsearch	Perform simple and complex searches to retrieve data.
ldapmodify	Modify the attribute values of one or more entries, or add new entries.
ldapdelete	Delete one or more entries given by their DN (distinguished name).
ldapcompare	Compare attribute values with those given on the command line.
ldapcmp	Compare DNs and attribute values in entire subtrees of two directories.

Performance Evaluation Tools

The performance evaluation tools help you run tests to measure your server's average response time to client requests. These tools perform repeated LDAP authentication, search, add, and delete operations to simulate actual usage. Use these tools before and after reconfiguring your directory to optimize performance and run them regularly to monitor server response as your directory size and usage evolve.

Table 1-2    Performance Evaluation Tools

Command	Purpose
idsktune	Optimize your OS and network settings for iPlanet Directory Server.
ldclt	A powerful and flexible LDAP client tool for testing directory servers.
rsearch	Measure the performance of search, compare, and delete operations.
searchrate	Measure search performance under high server loads.
modrate	Measure the performance of modification operations.
authrate	Measure the performance of connecting and performing authentication.
infadd	Measure the performance of add operations for creating new entries.

LDIF Deployment Tools

LDIF (LDAP Data Interchange Format) is the standard format for importing and exporting directory contents. The LDIF deployment tools process large LDIF files, either generating, modifying, or comparing the LDAP entries and attribute values they contain. Use these tools to deploy a testing environment and generate large test databases, to make global directory updates off line, and to synchronize multiple unconnected databases.

Table 1-3    LDIF Deployment Tools

Command	Purpose
create_ instance.pl	Use existing configuration files and interactive user input to generate an .inf file and create a new server instance (Directory Server 4.x only).
dbgen.pl	Generate random data for tests with the performance evaluation tools.
ldifgen	Generate random data for tests with legacy tools.
ldifxform	Edit an LDIF file for global updates and extracts data for reports.
mmldif	Simulate a multi-master merge using LDIF files.
ldiffer.pl	Synchronizes differences between two directories.

Maintenance and Debugging Tools

The maintenance and debugging tools help directory administrators to interpret the log files and other trouble-shooting files. Use these tools to determine the causes of errors when they occur, as well as to perform preventive maintenance by monitoring directory usage and server statistics.

Table 1-4    Maintenance and Debugging Tools

Command	Purpose
logconv.pl	Interpret access logs and compile usages statistics.
replcheck.pl	Verify whether two or more replicating servers are synchronized.
migrateSchemaTo5.pl	Automate the process of updating your schema for iPlanet Directory Server 5.1 from 4.x .
searchplay	Replay search operations found in the directory access log.
viewldbg	Debug a core file (Solaris platforms only).
dbscan	Create text output of iPlanet Directory Server database files.
Security Tools	Manage and debug security mechanisms used in client applications.
Unsupported Utilities	This chapter gives a brief description for each of the Perl scripts provided in the installDir /unsupported/perl directory.

Gateway Application

The HTML gateway has been redesigned as the JSP™ Directory Gateway (jdgw) and consists of an LDAP tag library that is used in JavaServer™ Pages. Using this technology, you can design a web client that can present directory contents in any browser. The JavaServer Pages use the LDAP tag library to access a directory and generate the response in HTML. The sample application is a phone book called LookMeUp that searches for person names in a corporate directory of employees.

iPlanet LDAP Administrative Shell

The iPlanet LDAP Administrative Shell (ilash) provides a complete shell environment for performing LDAP operations and managing a directory server. The ilash tool is based on the Tcl language and is an interpreter of Tcl scripts. Its built-in commands navigate through a directory as in a file system. Use the ilash tool to simplify directory access and to create powerful scripts for directory maintenance.