Sun Java System Directory Server Enterprise Edition 6.2 Developer's Guide

Specify Plug-In Configuration Settings

Plug-in configuration settings specify information that Directory Server requires. The server uses the information to load a plug-in at startup, to identify the plug-in, and to pass parameters to the plug-in at load time.

You access configuration settings through the dsconf(1M) command, using the subcommands create-plugin, set-plugin-prop, and enable-plugin.

The dsconf create-plugin command forces you to set required plug-in configuration settings. The settings include the name, plug-in initialization function, path to the library that contains the plug-in, and plug-in type.

The dsconf set-plugin-prop command allows you to set optional configuration settings.

The dsconf enable-plugin command allows you to turn the plug-in on or off. When you change this setting, you must restart the server.

The following table identifies the configuration settings and indicates whether the settings are required, set with dsconf create-plugin, or optional, set with dsconf set-plugin-prop.

Table 4–1 Plug-In Configuration Settings

Setting 

Description 

Required or Optional 

Plug-in name 

Common name for the plug-in, corresponding to the name registered by the plug-in 

Required 

Initialization function (-F)

Name of the initialization function that is called during Directory Server startup as the name appears in the plug-in code 

Required 

Library path (-H)

Full path to the library that contains the plug-in, not including 64-bit directory for 64-bit plug-in libraries 

Refer to Searching Plug-In Libraries for details.

Required 

Plug-in type (-Y)

Plug-in type that defines the types of functions the plug-in implements 

Refer to Understanding Plug-In Types and Dependencies for details.

Required 

argument

A parameter passed to the plug-in at Directory Server startup such as suffix=dc=example,dc=com

Refer to Retrieving Arguments Passed to Plug-Ins

Optional 

depends-on-named

One or more plug-in dependencies on plug-in names (RDN) such as State Change Plugin or Multimaster Replication Plugin

Refer to Understanding Plug-In Types and Dependencies for details.

Optional 

depends-on-type

One or more plug-in dependencies on plug-in types such as preoperation or database

Refer to Understanding Plug-In Types and Dependencies for details.

Optional 

desc

One-line description as specified in the spd_description field of the plug-in Slapi_PluginDesc structure

Optional 

feature

Identifier as specified in the spd_id field of the plug-in Slapi_PluginDesc structure

Optional 

vendor

Vendor name as specified in the spd_vendor field of the plug-in Slapi_PluginDesc structure

Optional 

version

Version number as specified in the spd_version field of the plug-in Slapi_PluginDesc structure

Optional 

Understanding Plug-In Types and Dependencies

The plug-in type tells Directory Server which type of plug-in functions can be registered by a plug-in. A plug-in type corresponds to the principal type of operation that the plug-in performs. Refer to How Plug-Ins Interact With the Server and Example Uses for explanations of plug-in types. Part II, Directory Server Plug-In API Reference describes plug-in types and lists type property settings that correspond to the type identifiers specified in slapi-plugin.h.

Determining the plug-in type is clear-cut when you know what the plug-in must do. For example, if you write a plug-in to handle authentication of a request before Directory Server processes the bind for that request, the type is preoperation. In other words, the plug-in does something to the request prior to the bind operation. Such a plug-in therefore registers at least a pre-bind plug-in function to process the request prior to the bind. If, on the other hand, you write a plug-in to encode passwords, and also compare incoming passwords with encoded passwords, the type is pwdstoragescheme. Such a plug-in registers at least password encoding, and also compares functions. In both cases, plug-in type follows plug-in function.

Plug-in dependencies tell Directory Server that a plug-in requires one or more other plug-ins in order to function properly. Directory Server resolves dependencies as the server loads the plug-ins. Therefore, Directory Server fails to register a plug-in if a plug-in that the plug-in depends on cannot be registered.

Specify plug-in dependencies by name, using depends-on-named, or by type, using depends-on-type. Here, plug-in name refers to the plug-in relative distinguished name (RDN) from the configuration entry. Plug-in type is a type identifier from the list of types in Chapter 18, Parameter Block Reference. Both depends-on-named and nsslapddepends-on-type can take multiple values.

A plug-in configuration entry can specify either kind or both kinds of dependencies. Use the configuration entry to identify dependencies on specific plug-ins by name. Identify dependencies on a type of plug-in by type. If a dependency identifies a plug-in by name, Directory Server only registers the plug-in after the server registers the named plug-in. If a dependency identifies a plug-in by type, Directory Server only registers the plug-in after the server registers all plug-ins of the specified type.

Do not confuse plug-in registration dependencies with a mechanism to specify the order in which Directory Server calls plug-ins.

Ordering Plug-In Calls

Directory Server allows you to define the order in which plug-ins are called. This mechanism is independent of the mechanism that defines plug-in load dependencies.

This mechanism uses a set of attributes on the entry with DN cn=plugins,cn=monitor. Plug-in call ordering is defined for each type of plug-in on attributes whose values are comma-separated lists of plug-in names. Each attribute type name starts with plugin-list- and identifies a point in the server request processing where plug-ins can be called. In the comma-separated list of plug-ins, the first plug-in in the list is called first, the second is called second, and so forth.

For example, six postoperation plug-ins are called after a modify operation. The plugin-list-postoperation-modify attribute on cn=plugins,cn=monitor shows the order in which these six plug-ins are called by the server.

plugin-list-postoperation-modify:
 Class of Service,
 Legacy replication postoperation plugin,
 Multimaster replication postoperation plugin,
 Retrocl postoperation plugin,
 Roles Plugin,
 State Change Plugin

You can also retrieve these attributes by performing a search on the entry with DN cn=plugins,cn=monitor.

To change the order in which plug-ins are called, you must not modify the value of the attribute type starting with plugin-list-. Instead, you must modify the value of a corresponding attribute type starting with plugin-order-, and having the same ending as the plugin-list- attribute.

The full list of plug-in call ordering attribute types is as follows:

For example, if you want to change the order in which postoperation plug-ins are called after a modify, first read plugin-list-postoperation-modify. Next set plugin-order-postoperation-modify, copying plug-in names from the value of plugin-list-postoperation-modify. Then restart Directory Server. Plug-in names are not case—sensitive, but white spaces are taken into account. Unrecognized names are ignored.

With a single asterisk, *, as an item in the comma-separated list, you let Directory Server define the call order for plug-ins you do not identify explicitly.

If you have two postoperation modify plug-ins, the first, Call Me First, and the second, Call Me Last, you could set plugin-list-postoperation-modify as follows:

plugin-order-postoperation-modify: Call Me First,*,Call Me Last

The plug-in name that you specify must be identical to the name argument that is passed to the slapi_register_plugin function. There must also be no white space between the comma delimiter and the adjacent plug-in names, and no white space at the end of the names list.

Plug-ins can remain that you do not explicitly identify by name or implicitly identify using *. Directory Server calls such plug-ins before calling the plug-ins that you listed.

Retrieving Arguments Passed to Plug-Ins

Your plug-in can retrieve parameters specified in the configuration settings property argument, which is multivalued. Directory Server makes the argument available to the plug-in through the parameter block passed to the plug-in initialization function.

If you include parameters in the configuration settings, the following apply:

The following example uses slapi_pblock_get() to retrieve the arguments from install-path/examples/testextendedop.c.


Example 4–4 Plug–In Using Arguments (testextendedop.c)

#include "slapi-plugin.h"

Slapi_PluginDesc expdesc = {
    "test-extendedop",                 /* plug-in identifier       */
    "Sun Microsystems, Inc.",          /* vendor name              */
    "6.0",                             /* plug-in revision number  */
    "Sample extended operation plug-in"/* plug-in description      */
};

/* Register the plug-in with the server.                           */
#ifdef _WIN32
__declspec(dllexport)
#endif
int
testexop_init(Slapi_PBlock * pb)
{
    char ** argv;                      /* Args from configuration  */
    int     argc;                      /* entry for plug-in.       */
    char ** oid_list;                  /* OIDs supported           */
    int     rc = 0;                    /* 0 means success          */
    int     i;

    /* Get the arguments from the configuration entry.             */
    rc |= slapi_pblock_get(pb, SLAPI_PLUGIN_ARGV, &argv);
    rc |= slapi_pblock_get(pb, SLAPI_PLUGIN_ARGC, &argc);
    if (rc != 0) {
        slapi_log_info_ex(
            SLAPI_LOG_INFO_AREA_PLUGIN,
            SLAPI_LOG_INFO_LEVEL_DEFAULT,
            SLAPI_LOG_NO_MSGID,
            SLAPI_LOG_NO_CONNID,
            SLAPI_LOG_NO_OPID,
            "testexop_init in test-extendedop plug-in",
            "Could not get plug-in arguments.\n"
        );
        return (rc);
    }

    /* Extended operation plug-ins may handle a range of OIDs. */
    oid_list = (char **)slapi_ch_malloc((argc + 1) * sizeof(char *));
    for (i = 0; i < argc; ++i) {
        oid_list[i] = slapi_ch_strdup(argv[i]);
        slapi_log_info_ex(
            SLAPI_LOG_INFO_AREA_PLUGIN,
            SLAPI_LOG_INFO_LEVEL_DEFAULT,
            SLAPI_LOG_NO_MSGID,
            SLAPI_LOG_NO_CONNID,
            SLAPI_LOG_NO_OPID,
            "testexop_init in test-extendedop plug-in",
            "Registering plug-in for extended operation %s.\n",
            oid_list[i]
        );
    }
    oid_list[argc] = NULL;
    
    rc |= slapi_pblock_set(            /* Plug-in API version      */
        pb,
        SLAPI_PLUGIN_VERSION,
        SLAPI_PLUGIN_CURRENT_VERSION
    );
    rc |= slapi_pblock_set(            /* Plug-in description      */
        pb,
        SLAPI_PLUGIN_DESCRIPTION,
        (void *) &expdesc
    );
    rc |= slapi_pblock_set(            /* Extended op. handler     */
        pb,
        SLAPI_PLUGIN_EXT_OP_FN,
        (void *) test_extendedop
    );
    rc |= slapi_pblock_set(            /* List of OIDs handled     */
        pb,
        SLAPI_PLUGIN_EXT_OP_OIDLIST,
        oid_list
    );
    return (rc);
}

You can specify multiple arguments by using multiple properties in the command line. The dsconf command causes the server to provide the arguments to the plug-in in the order you specify on the command line. When you change the list of arguments by using the dsconf command, the new arguments replace the existing arguments. The arguments are not appended to the list.

Searching Plug-In Libraries

Directory Server searches for plug-in libraries with the library path that you specify with the -H option to the dsconf create-plugin command.

Directory Server fails to start when the server cannot find a plug-in library specified in the configuration entry.