Complete Contents
Getting Started
Chapter 1 Understanding Server Plug-Ins
Chapter 2 Writing and Compiling Plug-Ins
Chapter 3 Calling the Front-End API Functions
Chapter 4 Quick Start
Chapter 5 Writing Database Plug-Ins
Chapter 6 Writing Pre/Post-Operation Plug-Ins
Chapter 7 Defining Functions for LDAP Operations
Chapter 8 Defining Functions for Database Operations
Chapter 9 Defining Functions for Authentication
Chapter 10 Writing Entry Store/Fetch Plug-Ins
Chapter 11 Writing Extended Operation Plug-Ins
Chapter 12 Writing Matching Rule Plug-Ins
Chapter 13 Data Type and Structure Reference
Chapter 14 Function Reference
Chapter 15 Parameter Reference
Glossary
Previous Next Contents Bookshelf


Chapter 5 Writing Database Plug-Ins

This chapter explains the architecture of the directory server and how the back-ends work with databases. The chapter also describes how you can add your own back-end to the server database.


How Directory Server Back-Ends Work
Directory entries are stored in a back-end database by the directory server. ldbm, the standard database provided with the directory server is a general purpose LDAP database designed to be used with directories in a variety of sizes and configurations.

In some cases, you may have special needs for your directory that require a database with different characteristics. In these cases, you can write a database plug-in to integrate your own database with the back-end of the directory server.

The directory server is designed to allow you to specify different databases.

Server Configuration in Netscape Directory Server 3.x

The slapd.conf server configuration file is organized in the following way:

# Directives general to all databases.
...
localhost ldap.airius.com
port 389
...
# Directives specific to the ldbm database. 
database ldbm
#######################################################################
# ldbm database definitions
#######################################################################
suffix  o=Airius.com
suffix  "o=Airius.com, c=US"
suffix  o=netscape.com
suffix  dc=rtfm,dc=mcom,dc=com
suffix  cn=schema
plugin database "/server_root/lib/libback-ldbm.so" ldbm_back_init...
The first section of the slapd.conf file contains directives that are general to all databases (for example, the directives specifying the hostname and port number of the directory server).

The database directive identifies the beginning of a section specific to that database. The suffix directive specifies the suffix handled by that database. (For example, according to the section of the slapd.conf file shown above, entries that end with "o=Airius.com" are stored in the ldbm database.

When the directory server reads in the slapd.conf file and encounters a database directive, it creates a back-end in memory and adds it to a list of existing back-ends. The server also reads any suffix directives and plugin directives after the database directive and associates these with the back-end.

If the directory server encounters another database directive, the server creates another back-end in memory, and any subsequent directives are associated with this back-end.

The database directive marks the beginning and end of a section containing directives specific to a database. For example:

...
# Directives specific to the ldbm database. 
database ldbm
suffix  o=Airius.com
suffix  "o=Airius.com, c=US"
suffix  o=netscape.com
suffix  dc=rtfm,dc=mcom,dc=com
suffix  cn=schema
plugin database "/server_root/lib/libback-ldbm.so" ldbm_back_init
...
# Directives specific to the mydb database. 
database mydb
suffix  o=test.com
plugin database "/server_root/plugins/slapd/slapi/examples/mydb.so" 
my_db_init
...
# Directives specific to the anotherdb database. 
database anotherdb
suffix  o=mycompany.com
plugin database "/server_root/plugins/slapd/slapi/examples/
myotherdb.so" my_other_db_init
...
Note. The directory server always needs to access the ldbm database, even if you plan to store your data in a different back-end database.

Server Configuration in Netscape Directory Server 4.0

In Netscape Directory Server 4.0, the slapd.conf file is not divided into database sections. Instead, the database-specific directives for the default ldbm database are stored in the slapd.ldbm.conf file.

The dynamicconf directive identifies the location of the default ldbm database configuration file.

dynamicconf /server_root/slapd-id/config/slapd.ldbm.conf
To configure the server to use a different database plug-in, create your own configuration file and add an include directive to identify the file.

Your configuration file should contain at least the database directive, one or more suffix directives, and the plugin database directive that identifies your plug-in.

For example:

# My database
database mydb
suffix o=test.com
plugin database on "my database 1" "/disk1/ds40/plugins/slapd/slapi/
examples/test.so" test_init
If you specify this information in a file named mydb.conf, you should add an include directive to the end of the slapd.conf file to include your database configuration file:

...
dynamicconf /server_root/slapd-id/config/slapd.ldbm.conf
include "/server_root/slapd-id/config/mydb.conf"

How Database Plug-Ins Work
A database plug-in registers the back-end functions that allow the directory server to interact with the database. When processing an LDAP operation that deals with the directory data (such as a search or a modification of an entry), the front-end of the directory server calls the registered back-end functions to access the database.

For example, when processing an LDAP search operation, the front-end of the directory server calls the search function that is registered for that back-end. Or when processing an LDAP add operation, the directory server front-end calls the add function registered for the back-end.

As is the case with other plug-ins, the front-end places data relevant to the operation in a parameter block. When the front-end calls the back-end function, it passes the parameter block to the function.

Figure 5.1 illustrates how the directory server front-end calls back-end functions to access the database and process LDAP operations.

Figure 5.1 How the server calls database plug-in functions


Writing Database Plug-In Functions
Database plug-in functions pass in a parameter block as an argument and return an integer. The server passes information to the plug-in function through parameters in the parameter block. You can call the slapi_pblock_get() function to get the values in the parameter block.

If your function successfully completes the requested operation, your function should return 0.

In the Netscape Directory Server 3.x, you should return -1 if an error occurs. In the Netscape Directory Server 4.x, the following return codes have been defined for database plug-in functions:


Registering Database Plug-In Functions
As is the case with other server plug-in functions (see Chapter  2, "Writing and Compiling Plug-Ins"), you register database plug-in functions by writing an initialization function that specifies the functions in a parameter block.

Each function has an ID in the parameter block. You can call the slapi_pblock_set() function to specify the name of your function that corresponds to the back-end function.

Table 5.1 lists the directory server back-end functions and the purpose of each function.

Table 5.1 Functions comprising the directory server database back-end

ID in Parameter Block
Description
SLAPI_PLUGIN_DB_CONFIG_FN
Specifies the function called when the directory server reads in and parses the slapd.conf configuration file.
If the directory server front-end does not recognize a directive, it passes the directive to this back-end function.
For information on writing this type of function, see "Reading Configuration Files" on page  104.
SLAPI_PLUGIN_DB_BIND_FN
Specifies the function called when the directory server processes an LDAP bind operation.
For information on writing this type of function, see "Processing an LDAP Bind Operation" on page  105.
SLAPI_PLUGIN_DB_UNBIND_FN
Specifies the function called when the directory server processes an LDAP unbind operation.
For information on writing this type of function, see "Processing an LDAP Unbind Operation" on page  107.
SLAPI_PLUGIN_DB_SEARCH_FN
Specifies the function called when the directory server processes an LDAP search operation.
For information on writing this type of function, see "Processing an LDAP Search Operation" on page  107.
SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN
Specifies the function called when the directory server iterates through the next search result in the result set.
For information on writing this type of function, see "Iterating through Candidates" on page  110.
SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_EXT_FN
(Netscape Directory Server 4.0) Reserved for future use.

SLAPI_PLUGIN_DB_ENTRY_RELEASE_FN
(Netscape Directory Server 4.0) Reserved for future use.

SLAPI_PLUGIN_DB_COMPARE_FN
Specifies the function called when the directory server processes an LDAP compare operation.
For information on writing this type of function, see "Processing an LDAP Compare Operation" on page  111.
SLAPI_PLUGIN_DB_ADD_FN
Specifies the function called when the directory server processes an LDAP add operation.
For information on writing this type of function, see "Processing an LDAP Add Operation" on page  112.
SLAPI_PLUGIN_DB_MODIFY_FN
Specifies the function called when the directory server processes an LDAP modify operation.
For information on writing this type of function, see "Processing an LDAP Modify Operation" on page  113.
SLAPI_PLUGIN_DB_MODRDN_FN
Specifies the function called when the directory server processes an LDAP modify RDN operation.
For information on writing this type of function, see "Processing an LDAP Modify RDN Operation" on page  115.
SLAPI_PLUGIN_DB_DELETE_FN
Specifies the function called when the directory server processes an LDAP delete operation.
For information on writing this type of function, see "Processing an LDAP Delete Operation" on page  117.
SLAPI_PLUGIN_DB_ABANDON_FN
Specifies the function called when the directory server processes an LDAP abandon operation.
For information on writing this type of function, see "Processing an LDAP Abandon Operation" on page  118.
SLAPI_PLUGIN_CLOSE_FN
Specifies the function called when the directory server is shutting down (this function allows the back-end database to be shut down correctly before the server shuts down).
SLAPI_PLUGIN_DB_FLUSH_FN
Specifies the function called when the directory server flushes any open caches or unwritten information to disk.
SLAPI_PLUGIN_START_FN
Specifies the function called for each back-end on server startup after the slapd.conf configuration file is read in.
SLAPI_PLUGIN_DB_SEQ_FN
Specifies the function called when the front-end needs to iterate through database entries sequentially.
SLAPI_PLUGIN_DB_LDIF2DB_FN
Specifies the function called when the front-end needs to convert an LDIF file to database format.
For information on writing this type of function, see "Importing an LDIF File into the Database" on page  120.
SLAPI_PLUGIN_DB_DB2LDIF_FN
Specifies the function called when the front-end needs to convert a database to LDIF file format.
For information on writing this type of function, see "Exporting the Database to an LDIF File" on page  122.
SLAPI_PLUGIN_DB_ARCHIVE2DB_FN
Specifies the function called when the front-end needs to restore a database from its archive.
For information on writing this type of function, see "Restoring the Database from an Archive" on page  123.
SLAPI_PLUGIN_DB_DB2ARCHIVE_FN
Specifies the function called when the front-end needs to archive a database.
For information on writing this type of function, see "Saving the Database as an Archive" on page  123.
SLAPI_PLUGIN_DB_SIZE_FN
Specifies the function called to get the size of the database and set as SLAPI_DBSIZE in the parameter block.
For information on writing this type of function, see "Reporting the Size of the Database" on page  124.
SLAPI_PLUGIN_DB_TEST_FN
Specifies the function called to test the back-end database.
For information on writing this type of function, see "Testing the Database" on page  124.
SLAPI_PLUGIN_DB_DB2INDEX_FN
Specifies the function called to generate indexes for the existing database.
For information on writing this type of function, see "Generating Indexes for the Database" on page  124.

If you do not define a database plug-in function for a back-end function, the directory server will return an LDAP_UNWILLING_TO_PERFORM error ("Function not implemented") when that back-end function needs to be called.

For example, suppose you have not defined a database function for the back-end add function. When the directory server receives a request for an LDAP add operation, the server returns an LDAP_UNWILLING_TO_PERFORM error to the client.

This provides an easy way to provide custom back-end functions that only cover part of the interface. (For example, you could provide a read-only interface that allows users to search for and compare entries but not to add, modify, or delete entries.)

See Chapter  7, "Defining Functions for LDAP Operations" and Chapter  8, "Defining Functions for Database Operations" for more information on writing functions to handle each LDAP operation and each database operation.

To register your database plug-in functions, you need to write an initialization function and then configure the server to load your plug-in.

For details, follow the procedures outlined in "Writing an Initialization Function" on page  41 and "Configuring the Server" on page  46.


Adding a Back-End to the Server
In the server configuration file (slapd.conf in Netscape Directory Server 3.x, your own included configuration file in Netscape Directory Server 4.0), specify the following directives:

In addition, you can specify other plugin directives to register plug-ins that apply to this back-end.

Other directives that appear within the ldbm database section are specific to the ldbm back-end. (For example, adding a dbcachesize directive to the section for your back-end will not set the database cache size (unless you have registered a configuration function that handles that directive).

Note. Do not remove the database section for the default ldbm database. The directory server needs to have access to this database, even though you plan to store your directory data in another database.

The following is an example of a set of directives that register the back-end mydbtype. The back-end serves requests for entries that end with the suffix "o=MyCompany.com". On startup, the server will call the mydb_init() function in the mydb.so shared object to register the database plug-in functions.

In Netscape Directory Server 3.x, the following directives can be added to the end of the slapd.conf file:

database mydbtype
suffix o=MyCompany.com
plugin database /serverroot/plugins/slapd/slapi/examples/mydb.so \
mydb_init
In the Netscape Directory Server 4.0, the following directives can be added to your own configuration file, which should be identified at the end of the slapd.conf file by an include directive:

database mydbtype
suffix o=MyCompany.com
plugin database on mydbplugin \
/serverroot/plugins/slapd/slapi/examples/mydb.so mydb_init
For more information on the plugin directive, see "Editing the Server Configuration Files" on page  47.

 

© Copyright 1998 Netscape Communications Corporation