|Plug-in Programmerís Guide
Red Hat Directory Server
An Overview of Directory Server Plug-ins
This chapter introduces you to Red Hat Directory Server (Directory Server) plug-ins and discusses the different types of plug-ins that you can write. The chapter covers the following topics:
- What Are Directory Server Plug-ins? (page 29 )
- How Directory Server Plug-ins Work (page 30)
- Types of Directory Server Plug-ins (page 34)
If you have already written a plug-in for Directory Server, refer to "Using Directory Server Plug-in APIs," on page 21, for information on migrating your plug-in to the latest version of the Directory Server.
What Are Directory Server Plug-ins?
If you want to extend the capabilities of the Directory Server, you can write your own Directory Server plug-in. A server plug-in is a shared object or library that contains custom functions that you write.
By writing your own plug-in functions, you can extend the functionality of the Directory Server. For example, here are some of the things you can do with Directory Server plug-ins:
- You can design an action that the Directory Server performs before the server processes an LDAP action. For example, you can write a custom function to validate data before the server performs an LDAP operation on the data.
- You can design an action that the Directory Server performs after the server successfully completes an LDAP operation. For example, you can send mail to a client after an LDAP operation is successfully completed.
- You can define extended operations, as defined in the the LDAP v3 protocol.
- You can provide alternate matching rules when comparing certain attribute values.
How Directory Server Plug-ins Work
When properly configured, the Directory Server will load your plug-in on startup. Once loaded, the Directory Server will resolve calls made to your plug-in functions as it processes the LDAP requests contained in your applications.
Internally, the Directory Server has hooks that allow you to register your own functions to be called when specific events occur. For example, the Directory Server has hooks to call a registered plug-in in the following situations:
- Before preforming an LDAP operation (for example, before an entry is added to the directory).
- When adding, modifying, removing, renaming, or searching for entries in the database.
- After performing an LDAP operation (for example, after an entry is added to the directory).
- Before writing an entry to the database.
- After reading an entry from the database.
- When processing an extended operation.
- When indexing an attribute.
- When filtering search result candidates based on an attribute.
When you register your plug-in functions, you specify the function type and the plug-in type. Together, these specifications indicate when the function is called. For more information on this topic, refer to the section "Types of Directory Server Plug-ins," on page 34.
Calling Directory Server Plug-in Functions
At specific LDAP events, the Directory Server calls all plug-in functions that are registered for that event. For example, before performing an LDAP add operation (an add event), the server calls all plug-in functions registered as pre-operation add functions. When the add operation is completed, the server will call all registered post-operation add functions.
In most plug-in function calls, the server passes a parameter block to the function. The parameter block contains data relevant to the operation. In most Directory Server plug-in functions you write, you access and modify the data in the parameter block.
For example, when the Directory Server receives an LDAP add request, the server does the following:
- Parses the request, and retrieves the new DN and the entry to be added.
- Places pointers to the DN and the entry in the parameter block.
- Calls any registered pre-operation add functions, passing the parameter block to these functions.
- Calls the registered database add function (which is responsible for adding the entry to the directory database), and passes to it the parameter block.
- Calls any registered post-operation add functions, passing the parameter block to these functions.
If you are writing a function that is invoked before an LDAP operation is performed, you can prevent the operation from being performed. For example, you can write a function that validates data before a new entry is added to the directory. If the data are not valid, you can prevent the LDAP add operation from occurring and return an error message to the LDAP client.
In some situations, you can also set the data that are used by the server to perform an operation. For example, in a pre-operation add function, you can change an entry before it is added to the directory.
The Directory Server Architecture
Internally, the Directory Server consists of two major subsections, the front-end and the backend.
The front-end receives LDAP requests from clients and processes those requests. When processing requests, the front-end calls functions in the backend to read and write data. The front-end then sends the results back to the client.
The backend reads and writes data to the database containing the directory entries. The backend abstracts the database from the front-end. The data stored in a backend is identified by the suffixes that the backend supports. For example, a backend that supports the dc=example,dc=com suffix contains directory entries that end with that suffix.
Figure 1-1 illustrates the Directory Server architecture.
Figure 1-1 Directory Server Architecture
Types of Directory Server Plug-ins
You can write the following types of plug-ins for the Directory Server:
- Pre-operation/data validation. The server calls a pre-operation/data validation plug-in function before performing an LDAP operation.
- The main purpose of this type of plug-in is to validate data before the data is added to the directory or before it is used in an operation.
- Post-operation/data notification. The server calls a post-operation/data notification plug-in function after performing an LDAP operation.
- The main purpose of this type of plug-in is to invoke a function after a particular operation is executed. For example, you can write a plug-in that sends email to users if their entries are modified.
- Entry storage and entry fetch. The server calls an entry storage plug-in function right before writing data to the database backend. The server calls entry fetch plug-in functions after retrieving an entry from the database backend.
- For example, you can create an entry storage plug-in that encrypts an entry before it is saved to the database and an entry fetch plug-in that decrypts an entry after it is read from the database.
- Extended operation. The server calls an extended operation plug-in function when the client requests an operation by OID. Extended operations are defined in LDAP v3 and are described in more detail in Chapter 10, "Writing Extended Operation Plug-ins."
- Syntax. The server calls a syntax plug-in function when getting a list of possible candidates for a search. The server also calls these functions when adding or deleting values from certain attribute indexes.
- Syntax plug-in functions can define the comparison operations used in searches. For example, you could use a syntax plug-in function to define how the "equals" comparison works for case-insensitive strings.
- Matching rule. The server calls matching rule plug-in functions when the client sends a search request with an extensible matching search filter. You can also write matching rule plug-in functions that the server calls when indexing attributes for the backend database.
Figure 1-2 illustrates how some of these different plug-in types fit into the Directory Server architecture.
Figure 1-2 Architecture of the Directory Server and Server Plug-ins