Netscape logo Plug-In ProgrammerĘs Guide
Netscape Directory Server
Previous      Contents      Index      DocHome      Next     

Chapter 13   Using Data Interoperability Plug-Ins


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

You can now use the enhanced pre-operation interfaces (instead of the database backend plug-in interface, support for which was dropped in 5.x and 6.x releases) to implement plug-ins that are designed to provide access to alternative directory data stores. 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 Netscape Directory Server Deployment Guide. To understand the role of a configuration Directory Server in a directory deployment, check Managing Servers with Netscape Console.

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

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:

For general information about installing Directory Server, refer to the accompanying Netscape Directory Server Installation Guide. You can also find the documentation for Directory Server at: http://enterprise.netscape.com/docs/directory/index.html

Installing Two Instances of Directory Server

Follow these instructions to create two instances of Directory Server:

  1. Read the installation-specific documents (Netscape 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
  3. Unpack the binaries.
  4. Run the setup program and install an instance of Directory Server (slapd-<configInstance> in Figure 13-1).
  5. Start Administration Server.
    6. <server_root>/start-admin
     
  6. Start Netscape Console.
    7. <server_root>/startconsole
     
  7. Use Netscape Console to create a new/second instance of Directory Server (slapd-<diopInstance> in Figure 13-1).
    8. In the navigation pane, select the Server Group, right click, and select "Create Instance of Netscape Directory Server," and follow the prompts.
     
  8. Disable the unsupported plug-ins in the second instance (slapd-<diopInstance>), which you will use for enabling the DIOP plug-in.
    1. In Netscape Console, locate and double-click the entry for the second instance of Directory Server.
      2. This opens the Directory Server Console for the second instance.
       
    2. Select the Configuration tab, and expand Plugins.
    3. Disable each of these plug-ins listed in Table 13-1.
      4. To disable a plug-in, select the plug-in and then on the right panel, uncheck the "Enable the Plugin" option. Note that some plug-ins may depend on other plug-ins, and you may see messages that reflect such a dependency.
       
  9. 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:

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

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



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.

Note that 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". 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.

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" explains how you can use the sample plug-in. The next section, "Debugging the Plug-In" explains how you can trobleshoot 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, "Netscape", "6.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 mods done to the server on the null suffix are processed by the plug-in. The plug-in writes the DN of all mods received to a standalone Berkley db, 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 db 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".

Building the Data Interoperability Plug-In

The compiler used on Solaris 8 is Forte 6.2. 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 Control 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 Netscape 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".

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



Previous      Contents      Index      DocHome      Next     

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002 Netscape Communications Corporation. All rights reserved.


Last Updated August 23, 2002