Chapter 1   Before You Start

If you are not yet familiar with Sun ONE Directory Server software, take the time to read Sun ONE Directory Server Getting Started Guide.

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 ONE 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 ONE 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, as described in the license.

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

http://www.sun.com/service/sunps/sunone/

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 read entries from and write entries to the database. Unless abandoned, 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 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
Object	Depends on the functions registered 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
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

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.

---

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.

---

Example Uses

---

Selecting 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 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, Reversible 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.

---

Tip	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 ONE 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 Sun ONE Directory Server Plug-In API Reference for details about particular data structures, functions, and parameter block semantics.