Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java(TM) System Directory Server 5 2004Q2 Plug-In Developer's Guide 

Chapter 1
Before You Start

If you are not yet familiar with Sun Java System Directory Server software, take the time to read Directory Server Technical Overview.

Next, read this short chapter. It helps you decide whether to implement a server plug-in, and what to do next if you choose to implement one.

When to Implement a Server Plug-In

Many Sun Java System Directory Server native product features rely on server plug-ins, libraries of functions registered with the server to perform key parts of specific directory service operations. In publishing the Sun Java System Directory Server plug-in API, the Directory Server team offers you an interface to extend server capabilities for needs not met in the currently available releases of the product.

Enhancing Server Capabilities

If you must enhance server capabilities because some required feature — such as custom authentication, encryption, validation, pattern matching, or notification — has not yet been implemented in the product, the plug-in API may render that enhancement possible. If you can instead use standard features of the product, avoid creating a plug-in.

Maintaining Plug-Ins

Know that creating your own plug-in links your software solution to a specific product release. The plug-in API may evolve from release to release to accommodate new features. As you choose to upgrade and take advantage of new features, you may need to update your Directory Server plug-ins to account for the changes.

You may use the header files and class libraries solely to create and distribute programs to interface with the Software’s APIs. You may also use libraries to create and distribute program “plug-ins” to interface with the Software’s plug-in APIs. You may not modify the header files or libraries. You acknowledge that Sun makes no direct or implied guarantees that the plug-in APIs will be backward-compatible in future releases of the Software. In addition, you acknowledge that Sun is under no obligation to support or to provide upgrades or error corrections to any derivative plug-ins.

When providing technical support, Sun technical support personnel will request that you reproduce the problem after disactivating your custom plug-ins.

Sun Professional Services

For information about what Sun Professional Services has to offer, refer to

Sun Professional Services can help you make the right deployment decisions, and can help you deploy the right solution for your specific situation, whether or not the solution includes custom plug-ins.

How Plug-Ins Interact With the Server

All client requests to Directory Server instances undergo particular processing sequences. The exact sequence depends on the operation requested, but overall the sequences are similar. The way plug-ins handle requests is independent of how the client encodes the request. In other words, client request data appears essentially the same to plug-ins regardless of the client access protocol used to communicate with Directory Server.

In general, client request processing proceeds as follows. First, Directory Server frontend decodes the request. The core server handles the decoded request, calling the necessary backend functions to find or store entries for example. The primary function of the Directory Server backend is to retrieve and store entries. Unless abandoned, however, a client request results in a response originating in the backend. The frontend formats the response and sends it to the client.

Figure 1-1 illustrates how client request data moves through Directory Server.

Figure 1-1  Client Request Processing

Client request processing flow

As a rule, plug-ins register functions to be called by Directory Server at specific points in the client request processing sequence. A plug-in has a specific type, such as preoperation or postoperation. A preoperation plug-in registers functions handling incoming requests before they are processed in the server. For example, a preoperation plug-in may register a pre-bind function called before the core server begins processing the client bind. The pre-bind function might redefine the way the client authenticates to Directory Server, enabling authentication against an external database. A postoperation plug-in registers functions called after a request is processed. For example, a postoperation plug-in may register a post-modification function called to log the information about the modification request. Table 1-2 provides examples for other plug-in types.

The two internal operation plug-in types form an exception to the rule that functions are called to perform client request processing. Internal operation plug-ins implement functions triggered for internal Directory Server operations. Internal operations are initiated not by client requests, but instead by Directory Server itself or by another plug-in called by Directory Server. Exercise great caution when manipulating internal operation data!

Table 1-1 summarizes when Directory Server calls documented plug-in function types.

Table 1-1  Server Plug-In Types 

Plug-In Type

When Called

Entry store/fetch

Immediately before writing a directory entry to or immediately after reading a directory entry from the directory database

nsslapd-pluginType: ldbmentryfetchstore

Extended operation

Before processing an LDAP v3 extended operation

nsslapd-pluginType: extendedop

Internal post-operation

After completing an operation initiated by Directory Server, for which no corresponding client request exists

nsslapd-pluginType: internalpostoperation

Internal pre-operation

Before performing an operation initiated by Directory Server, for which no corresponding client request exists

nsslapd-pluginType: internalpreoperation

Matching rule

When finding search result candidates based on an extensible match filter (search operations only)

nsslapd-pluginType: matchingrule


Depends on the functions registered; this is a generic type used to register other types.

nsslapd-pluginType: object

Password storage scheme

When storing an encoded userPassword value that cannot be decrypted

nsslapd-pluginType: pwdstoragescheme


After completing an operation requested by a client

nsslapd-pluginType: postoperation


Before performing an operation requested by a client

nsslapd-pluginType: preoperation

Reversible password storage scheme

When storing an encoded userPassword value that must be decrypted during processing

nsslapd-pluginType: reverpwdstoragescheme

Figure 1-2 illustrates where in the processing sequence Directory Server calls several of the plug-in types described in Table 1-1.

Figure 1-2  Plug-In Entry Points

Plug-in entry points

Notice that post-operation return codes do not affect Directory Server processing.

Plug-in type and other configuration information is typically specified statically in a configuration entry.

You may include multiple plug-ins in a single shared library, but you must specify individual, server-specific configuration entries for each plug-in registered statically. This means that if you want both pre- and post-operation functions, you typically write two plug-ins and register each with Directory Server. Both plug-ins may be contained in the same shared library. Both plug-ins may communicate private data across the same operation or connection, as well, using the interface provided. It is also possible to write one plug-in that initializes other plug-ins if that is required for your deployment.

The sample plug-ins delivered with the product follow the principle of building all plug-ins into one library, then registering plug-ins individually.

Figure 1-3 shows multiple plug-ins residing in the same library.

Figure 1-3  Multiple Plug-Ins in a Shared Library

Multiple plug-ins in same library

Each plug-in includes a registration routine, called by Directory Server at startup. The registration routine explicitly registers each plug-in function with Directory Server.


Plug-ins libraries are linked with Directory Server. Plug-ins execute in the same memory address space as Directory Server itself. They have direct access to data structures used by Directory Server. As a result, plug-ins can corrupt memory used by Directory Server. Such memory corruption can result in database corruption. This is why you never use an untested plug-in on a production Directory Server.

Furthermore, Directory Server runs as a multi-threaded process. Directory Server plug-in code should be reentrant.

Example Uses

Selecting the right plug-in type for the job is an art, rather than a science. Table 1-2 suggests example uses for documented plug-in types.

Table 1-2  Plug-In Example Uses, By Type 

Plug-In Type

Example Uses

Entry store/fetch

Encoding and decoding entire plug-in entries

Auditing or logging each entry written to or read from the directory as it is written to disk

Extended operation

Adding client services unavailable in LDAP v3 such as digital signatures in requests and responses

Internal post-operation

Auditing results of internal operations initiated by another plug-in

Internal pre-operation

Preempting internal operations initiated by another plug-in

Matching rule

Offering enhanced sounds-like matching for directory searches


Developing a plug-in that registers a group of other plug-ins with Directory Server

Password storage scheme, Reversible password storage scheme

Using a custom algorithm for password encryption instead of one of the algorithms supported by the standard product


Associating alerts and alarms sent after particular operations

Auditing changes to specific entries

Performing cleanup after an operation


Handling custom authentication methods external to the directory

Forcing syntax checking for attribute values before adding or modifying an entry

Adding attributes to or deleting attributes from a request

Preprocessing client request content to translate requests from legacy applications

Approving or rejecting the content of a client modification request before processing it

The list of example uses is by no means exhaustive, but is instead intended to help you brainstorm solutions.

Where to Go From Here

We devote most of the rest of this guide to examples demonstrating the specific plug-in types.


Never develop plug-ins on a production server, but instead on a test server used specifically for plug-in development.

Prepare Your Development Environment

If you have not yet installed Sun Java System Directory Server software and have not installed C language development tools for use during plug-in development, install them now. Without development tools and a functioning Directory Server, you cannot use the examples discussed here.

Learn About Plug-In Development

If you have not yet written a plug-in for the current release, refer to Chapter 3, "Getting Started With Directory Server Plug-Ins," for a demonstration of how to build a simple plug-in and register it with Directory Server.

Upgrade Existing Plug-Ins

If you already have plug-ins developed for a previous release and need to upgrade them for use with the current release, refer to Chapter 2, "What’s New."

Try a Sample Plug-In

Examples for several plug-in types are provided with the product under ServerRoot/plugins/slapd/slapi/examples/. Subsequent chapters demonstrate the use of the sample plug-ins.

Find Details

Refer to the Directory Server Plug-In Developer’s Reference for details about particular data structures, functions, and parameter block semantics.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.