Sun Directory Server Enterprise Edition 7.0 Developer's Guide

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 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.

Figure 1–1 Client Request Processing

Diagram shows how Directory Server receives, processes,
and responds to a client application request.

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.

Figure 1–2 Plug-In Entry Points

Diagram identifies points in client request processing
where plug-ins may be called.

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.

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

Diagram shows multiple plug-ins of different types may
be linked in a single shared 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.


Caution – Caution –

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.