Plug-in Programmer’s Guide
Red Hat Directory Server                                                            
Previous
 Contents
 Index
 Next

Chapter 13

Using Data Interoperability Plug-ins

This chapter explains how to use the Data Interoperability (DIOP) feature of Red Hat Directory Server (Directory Server). The DIOP feature refers to Directory Server's ability to work with a proprietary database, instead of the default database created during installation.

You can now use the enhanced pre-operation interfaces to implement plug-ins that are designed to provide access to alternative directory data stores, instead of the database backend plug-in interface, which is not support in current releases. You do this by developing a custom pre-operation plug-in to provide an alternate functionality for the LDAP operations, such as search, modify, add, and so on. These operations are generally targeted at the root suffix or the null DN (meaning dn:), and your plug-in will have to be designed to intercept these operations and divert them to be serviced by an alternate data source or alternate access methods.

This chapter covers deployment considerations, configuration changes required to use the DIOP feature, a list of supported and unsupported features, and other useful information.

This chapter contains the following sections:

Installing Directory Server

This section explains how to install Directory Server in order to test and use the DIOP feature.

Understanding Deployment Configuration

To verify whether the DIOP feature works in Directory Server, your deployment must comprise two instances of Directory Server:

For detailed information on directory deployments, check the Red Hat Directory Server Deployment Guide. To understand the role of a configuration Directory Server in a directory deployment, check Managing Servers with Red Hat Console.

Because the DIOP plug-in is a pre-operation plug-in, enabling the plug-in will impose certain limitations on the default behavior of Directory Server.

Table 13-1 Plug-in Status in DIOP-Enabled Directory Server  
Default Directory Server Plug-ins
(Names as they appear in the Directory Server Console)
Unsupported Plug-ins (Indicated by X)
7-bit check
X
ACL
-
ACL preoperation
-
Binary Syntax
-
Boolean Syntax
-
Case Exact String Syntax
-
Case Ignore String Syntax
-
chaining database
X
Class of Service
X
Country String Syntax
-
Distinguished Name Syntax
-
Generalized Time Syntax
-
HTTP Client
-
Integer Syntax
-
Internationalization Plugin
-
JPEG Syntax
-
ldbm database
-
Legacy Replication
X
Multimaster Replication
X
Octet String Syntax
-
OID Syntax
-
Pass-through Authentication
X
Postal Address Syntax
-
Referential Integrity Postoperation
X
Retro Changelog
X
Roles
X
Space Insensitive Syntax
-
State Change
X
Telephone Syntax
-
UID Uniqueness
X
URI Syntax
-
Views
X
CLEAR
-
CRYPT
-
DES
-
NS-MTA-MD5
-
SHA
-
SSHA
-

Figure 13-1 illustrates Directory Server deployment required for testing the DIOP feature.

Figure 13-1 A Typical Directory Server Deployment



In the above figure, slapd-configInstance is the configuration Directory Server and slapd-diopInstance is the Directory Server instance with the DIOP plug-in turned on.

To summarize the installation requirements for testing the DIOP feature:

/opt/redhat-ds/servers/slapd-configInstance
/opt/redhat-ds/servers/slapd-diopInstance
where /opt/redhat-ds/servers is the default installation directory. In the sections that follow, the installation directory is identified as server_root.

For general information about installing Directory Server, refer to the accompanying Red Hat Directory Server Installation Guide. You can also find the documentation for Directory Server at http://www.redhat.com/docs/manuals/dir-server/

Installing Two Instances of Directory Server

Follow these instructions to create two instances of Directory Server:

  1. Read the installation-specific documents (Red Hat Directory Server Installation Guide and Release Notes), and verify that your system meets the requirements specified in the documentation. Ensure that all patches are installed.
  2. Unset the environment variable:
unsetenv LD_LIBRARY_PATH
  1. Unpack the binaries.
  2. Run the setup program, and install an instance of Directory Server (slapd-configInstance in Figure 13-1).
  3. Start Administration Server.
server_root /start-admin
  1. Start Red Hat Console.
server_root /startconsole
  1. Use Red Hat Console to create a new/second instance of Directory Server (slapd-diopInstance in Figure 13-1).
In the navigation pane, select the Server Group, right click, select "Create Instance of Red Hat Directory Server," and follow the prompts.
  1. Disable the unsupported plug-ins in the second instance (slapd-diopInstance), which you will use for enabling the DIOP plug-in.
    1. In Red Hat Console, locate and double-click the entry for the second instance of Directory Server.
This opens the Directory Server Console for the second instance.
    1. Select the Configuration tab, and expand Plugins.
    2. Disable each of these plug-ins listed in Table 13-1, on page 164.
To disable a plug-in, select the plug-in, and then, on the right panel, uncheck the "Enable the Plugin" option. Some plug-ins may depend on other plug-ins, and you may see messages that reflect such a dependency.
  1. Use the second instance to enable the DIOP feature, which is explained in the next section.

Enabling the DIOP Feature in Directory Server

For a Directory Server instance to support the DIOP feature, its default configuration needs to be modified - the server needs to be configured to use the null DN or the root suffix in the server. This can be done by adding the following entry to the dse.ldif file of the server instance in which you want to enable the DIOP feature: 

dn: cn="",cn=mapping tree,cn=config

 objectClass: top

 objectClass: extensibleObject

 objectClass: nsMappingTree

 cn: ""

 nsslapd-state: container

You can modify the dse.ldif in either of the following ways:

server_root /slapd-diopInstance /stop-server
The file is located in the server_root /slapd-diopInstance /config/dse.ldif directory.
server_root /slapd-diopInstance /start-server
You can also add the above entry by running the ldapmodify command on the slapd-diopInstance server with the an LDIF input file containing the above entry. For example, your command might look like this:
./ldapmodify -h host  -p port  -w password  -D "cn=directory manager" -vcaf ldif_file_containing_the_entry

Once you add the above entry to the server configuration, the DIOP functionality is enabled in the server.

Note

An example plug-in is shipped with the server to show how a DIOP pre-operation plug-in can be used to work with the DIOP-enabled server. For details about the sample plug-in, see "Sample DIOP Plug-in," on page 172.

To use the sample plug-in or your own custom plug-in in the server, see "Using the DIOP Feature," on page 170.


Using the DIOP Feature

This section explains how you can verify whether the DIOP feature works in Directory Server. After you have successfully installed and configured two instances of Directory Servers, as explained in the preceding sections, follow the instructions in this section.

To help you understand the DIOP feature, a sample plug-in in provided. Details of this plug-in is covered in "Sample DIOP Plug-in," on page 172. It is recommended that you review the sample plug-in first and use that as an example to develop your own plug-in.

To verify the DIOP feature, you may use the sample plug-in or reconfigure Directory Server to use your own plug-in. You can also remove the plug-in altogether from the server.

cd server_root /plugins/slapd/slapi/examples
gmake
dn: cn=datainterop,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
cn: datainterop
nsslapd-pluginPath: server_root //plugins/slapd/slapi/examples/libtest-plugin.so
nsslapd-pluginInitfunc: nullsuffix_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginId: nullsuffix-preop
nsslapd-pluginVersion: 7.1
nsslapd-pluginVendor: Red Hat, Inc.
nsslapd-pluginDescription: sample pre-operation null suffix plugin

You can also use the ldapmodify command to make these changes.

Sample DIOP Plug-in

To help you understand the DIOP feature, a sample DIOP plug-in is included with Directory Server. This section provides an overview of the sample plug-in and explains how you can use the plug-in to verify whether the DIOP feature works in Directory Server. The preceding section, "Using the DIOP Feature," on page 170, explains how you can use the sample plug-in. The next section, "Debugging the Plug-in," on page 174, explains how you can troubleshoot the plug-in.

The sample plug-in is located in the server_root /plugins/slapd/slapi/examples directory. The shared library for the plug-in is named libtest-plugin.so and is implemented by 

testdatainterop.c[.h]

testdbinterop.c

db.h

located in the same directory.

Note the following:

In the following table, the various required elements of the pre-operation plug-in are identified by the function calls used in the testdatainterop.c (to illustrate the use and simplify understanding).

Table 13-2 Elements of Pre-Operation Plug-in  
Description of the Plug-in
#define PLUGIN_NAME "nullsuffix-preop"
static Slapi_PluginDesc plugindesc = { PLUGIN_NAME, "Red Hat", "7.1", "sample pre-operation null suffix plugin"
}
Initialization of the Plug-in by the Server
nullsuffix_init( Slapi_PBlock *pb )
In this function, all the callbacks are set up and will be called by the server for each LDAP operation.
Flag used for LDAP operation            Callback
SLAPI_PLUGIN_PRE_SEARCH_FN         nullsuffix_search
SLAPI_PLUGIN_PRE_ADD_FN            nullsuffix_add
SLAPI_PLUGIN_PRE_MODIFY_FN         nullsuffix_modify
SLAPI_PLUGIN_PRE_DELETE_FN         nullsuffix_delete
SLAPI_PLUGIN_PRE_BIND_FN           nullsuffix_bind
SLAPI_PLUGIN_PRE_MODRDN_FN         nullsuffix_modrdn
Reserved Naming Contexts
(cn=schema, cn=config, cn=monitor)
slapi_op_reserved(pb) is called to determine whether the operation should be handled internally by Directory Server; for example, whether the base on which the operation is applied is a reserved naming context. If slapi_op_reserved() returns a non-zero value, the plug-in does not attempt to handle that operation. It is done by the following code snippet:
if( slapi_op_reserved(pb) ){
 return PLUGIN_OPERATION_IGNORED;
  }
See testdatainterop.c for details.
The slapi_op_reserved() function, which can be used for reserving some of the naming contexts in the Directory Server (cn=schema, cn=config, cn=monitor), is called first in the database plug-in and then the call for turning off access control.
Sparse Tree Support
Any modifications done to the server on the null suffix are processed by the plug-in. The plug-in writes the DN of all modifications received to a standalone BerkleyDB, and trying a simple test using LDIF entries without the required object classes or parent entries will still get processed by the server, populating the database created by the plug-in.
See nullsuffix_modify and testdbinterop.c for details.
The plug-in has not been coded for the retrieval of those entries but has been coded to demonstrate sparse tree support only.
Access Control
Switching off access control for the operation is done by:
slapi_operation_set_flag(op, SLAPI_OP_FLAG_NO_ACCESS_CHECK );
See testdatainterop.c for details.
Null Suffix Support
The plug-in cannot control the support for null-suffix in the server. The support for null-suffix is done through configuration modification of the server as shown in "Installing Directory Server," on page 164.
Building the Data Interoperability Plug-in
The compiler used on Solaris is Forte. For example:
cd server_root /plugins/slapd/slapi/examples
gmake
<libtest-plugin.so is generated>

Debugging the Plug-in

If you need to debug the plug-in installed on a Solaris machine, you can use dbx:

  1. cd server_root /bin/slapd/server
  2. setenv NETSITE_ROOT server_root
  3. dbx ns-slapd
  4. run -d 65536 -D server_root /slapd-diopInstance
  5. Once the server starts up and error logs show that the server has started, press Ctrl+C.
  6. stop in user-defined-function-in-the-plugin

Similar steps can be done on other platforms, using the platform-specific debuggers and commands.

Plug-in API Reference

This section contains reference information on APIs that enable the following:

Preserving the Default Behavior of the Server

Directory Server implements internal backends for supporting subtrees cn=config, cn=schema, and cn=monitor, which are the reserved naming contexts for the server. For more information about these, check the Red Hat Directory Server Configuration, Command, and File Reference.

It may be required in some cases to let the default behavior of the server be preserved and not be intercepted by the custom pre-operation plug-ins. To implement a custom DIOP plug-in without affecting the default behavior of the Directory Server, a new function named slapi_op_reserved() is being made available. For details about this function, see "Functions Related to Data Interoperability," on page 559.

Bypassing Access Control Checks

It may be desirable to disable access control checking for operations that are handled by the custom DIOP plug-in. To enable the plug-ins to bypass access control, a new flag, SLAPI_OP_FLAG_NO_ACCESS_CHECK, has been defined. You allow a custom plug-in to bypass access control by setting the flag on the operation-data structure, which is available to the plug-in through the parameter (pblock) setting; see Chapter 16, "Parameter Block Reference."

The following functions have been defined for this purpose: 

slapi_operation_set_flag()
 
slapi_operation_clear_flag()
 
slapi_is_flag_set()

For details about these functions, see "Functions Related to Data Interoperability," on page 559.




Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated May 26, 2005