This chapter helps you to decide whether to implement a server plug-in. It also explains what to do next if you choose to implement a plug-in.
This chapter covers the following topics:
Many Sun Java System Directory Server native product features rely on server plug-ins. Plug-ins are libraries of functions that are registered with the server to perform key parts of specific directory service operations.
The Directory Server plug-in API provides an interface to add server capabilities that are not in the current releases of the product. If you must add server capabilities because a required feature has not yet been implemented, the plug-in API might render that enhancement possible. If you can instead use standard features of the product, avoid creating a plug-in.
Be aware that creating your own plug-in links your software solution to a specific product release. The plug-in API can evolve from release to release to accommodate new features. As you choose to upgrade to take advantage of new features, you might need to update your Directory Server plug-ins.
You can use the header files with class libraries solely to create and distribute programs to interface with the Software’s APIs. You can also use libraries to create, then distribute program “plug-ins” to interface with the Software’s plug-in APIs. You cannot 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 request that you reproduce the problem after turning your custom plug-ins off.
Sun Services can help you make the right deployment decisions. Sun Services can also help you to deploy the right solution for your specific situation, whether or not the solution includes custom plug-ins.
All client requests to Directory Server instances undergo particular processing sequences. The exact sequence depends on the operation that the client has requested. Yet 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, the Directory Server front end decodes the request. The core server handles the decoded request, calling the necessary back end functions to find or store entries, for example. The primary function of the Directory Server back end is to retrieve and store entries. Unless abandoned, however, a client request results in a response originating in the back end. The front end formats the response and sends it to the client.
The following figure illustrates how client request data moves through Directory Server.
As a rule, plug-ins register functions to be called by Directory Server at specific steps of processing the client request. A plug-in has a specific type, such as preoperation or postoperation. A preoperation plug-in registers functions that handle incoming requests before the requests are processed in the server. For example, a preoperation plug-in can register a pre-bind function that is called before the core server begins processing the client bind. The pre-bind function might redefine how the client authenticates to Directory Server, enabling authentication against an external database. A postoperation plug-in registers functions that are called after a request is processed. For example, a postoperation plug-in might register a post-modification function that is called to log the information about the modification request. Example Uses 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 that are triggered for internal Directory Server operations. Internal operations are initiated not by client requests, but by Directory Server or by another plug-in called by Directory Server. Exercise caution when manipulating internal operation data.
The following table 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 type: ldbmentryfetchstore |
Extended operation |
For processing an LDAP v3 extended operation type: extendedop |
Internal postoperation |
After completing an operation initiated by Directory Server, for which no corresponding client request exists type: internalpostoperation |
Internal preoperation |
Before performing an operation initiated by Directory Server, for which no corresponding client request exists type: internalpreoperation |
Matching rule |
When finding search result candidates based on an extensible match filter for search operations only type: matchingrule |
Object |
Depends on the functions that are registered. (This type is generic and is used to register other types) type: object |
Password check |
When performing a strong check on a userPassword value to add or modify type: passwordcheck |
Password storage scheme |
When storing an encoded userPassword value that cannot be decrypted type: pwdstoragescheme |
Postoperation |
After completing an operation requested by a client type: postoperation |
Preoperation |
Before performing an operation requested by a client type: preoperation |
The following figure illustrates where in the processing sequence Directory Server calls some of the plug-in types described in Table 1–1.
Notice that postoperation return codes do not affect Directory Server processing.
The plug-in type and plug-in configuration information are typically specified statically in a configuration entry.
You can include multiple plug-ins in a single shared library, but you must specify individual, server-specific configuration entries for each plug-in that is registered statically. This means that if you want preoperation and postoperation functions, you typically write two plug-ins. Then you register each plug-in with Directory Server. Both plug-ins can be contained in the same shared library. Both plug-ins can communicate private data across the same operation or connection, as well, using the interface provided. You can also write one plug-in that initializes other plug-ins, if that configuration 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.
The following figure shows multiple plug-ins that reside in the same library.
Each plug-in includes a registration routine that is called by Directory Server at startup. The registration routine explicitly registers each plug-in function with Directory Server.
Plug-in libraries are linked with Directory Server. Plug-ins execute in the same memory address space as Directory Server. Plug-ins 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. Due to this danger, 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. Multiple threads can call your entry point simultaneously. These threads can be rescheduled at any time.
To select the right plug-in type for the job is an art, rather than a science. The following table 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 as the entry is written to disk |
Extended operation |
Adding client services that are not available in LDAP v3 such as digital signatures in requests and responses |
Internal postoperation |
Auditing results of internal operations initiated by another plug-in |
Internal preoperation |
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 check |
Forcing new passwords to conform to corporate policy for password syntax |
Password storage scheme |
Using a custom algorithm for password encryption instead of one of the algorithms supported by the standard product |
Postoperation |
Associating alerts and alarms sent after particular operations Auditing changes to specific entries Performing cleanup after an operation |
Preoperation |
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 the request |
The list of example uses is by no means exhaustive, but is instead intended to help you brainstorm solutions.
Most of the rest of this guide is devoted to examples that demonstrate 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.
You might not have installed Sun Java System Directory Server software. You might not have installed development software for the C language for use during plug-in development. Install the software now. Without development tools and a functioning Directory Server, you cannot use the examples discussed here.
If you have not yet written a plug-in for the current release, refer to Chapter 4, Getting Started With Directory Server Plug-Ins. The chapter helps you to build a simple plug-in, and to register the plug-in with Directory Server.
If you maintain plug-ins developed for a previous release of Directory Server, refer to Chapter 2, Changes to the Plug-In API Since Directory Server 5.2 and Chapter 3, Changes to the Plug-In API From Directory Server 4 to Directory Server 5.2 for information about what has changed.
Examples for several plug-in types are provided with the product in install-path/examples Subsequent chapters demonstrate the use of the sample plug-ins.
See Part II, Directory Server Plug-In API Reference for details about particular data structures, functions, and parameter block semantics.