|Sun Java(TM) System Directory Server 5.2 2005Q1 Plug-In Developer's Guide|
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.
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
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
Immediately before writing a directory entry to or immediately after reading a directory entry from the directory database
For processing an LDAP v3 extended operation
After completing an operation initiated by Directory Server, for which no corresponding client request exists
Before performing an operation initiated by Directory Server, for which no corresponding client request exists
When finding search result candidates based on an extensible match filter (search operations only)
Depends on the functions registered; this is a generic type used to register other types.
Password storage scheme
When storing an encoded userPassword value that cannot be decrypted
After completing an operation requested by a client
Before performing an operation requested by a client
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
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
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. 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.
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
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
Adding client services unavailable in LDAP v3 such as digital signatures in requests and responses
Auditing results of internal operations initiated by another plug-in
Preempting internal operations initiated by another plug-in
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
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 maintain plug-ins developed for a 4.x release of Directory Server, refer to Chapter 2, "Changes to the Plug-In API Since Directory Server 4.x," for information about what has changed since that release.
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.
Refer to the Directory Server Plug-in Developer's Reference for details about particular data structures, functions, and parameter block semantics.