Chapter 1 Before You Start

This chapter helps you decide whether to implement a server plug-in, and what to do next if you choose to implement one.If you are not yet familiar with Directory Server, read the Directory Server Technical Overview.

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

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.

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 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	For 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
Object	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
Post-operation	After completing an operation requested by a client nsslapd-pluginType: postoperation
Pre-operation	Before performing an operation requested by a client nsslapd-pluginType: preoperation

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

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.

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.



Tip	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. Code you write for a plug-in must be reentrant, as multiple threads may call your entry point simultaneously, and these threads be rescheduled at any time.

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
Object	Developing a plug-in that registers a group of other plug-ins with Directory Server
Password storage scheme	Using a custom algorithm for password encryption instead of one of the algorithms supported by the standard product
Post-operation	Associating alerts and alarms sent after particular operations Auditing changes to specific entries Performing cleanup after an operation
Pre-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.

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

Upgrade Existing Plug-Ins

Try a Sample Plug-In


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

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.

Previous Contents Index Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Plug-In Developer's Guide