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
How Database Plug-Ins Work
Writing Database Plug-In Functions
Registering Database Plug-In Functions
Adding a Back-End to the Server
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).
# 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 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.
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
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.
dynamicconf /server_root/slapd-id/config/slapd.ldbm.conf
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:
# My database
plugin database on "my database 1" "/disk1/ds40/plugins/slapd/slapi/ examples/test.so" test_init
... dynamicconf /server_root/slapd-id/config/slapd.ldbm.conf include "/server_root/slapd-id/config/mydb.conf"
include "/server_root/slapd-id/config/mydb.conf"
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
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:
SLAPI_FAIL_GENERAL Your function should return this value if an error occurs and the requested operation cannot be completed.
Your function should return this value if an error occurs and the requested operation cannot be completed.
SLAPI_FAIL_DISKFULL Your function should return this value if no disk space is available. If your function returns this value, the server prints a "DISK FULL" message to the error log and attempts to shut itself down.
Your function should return this value if no disk space is available. If your function returns this value, the server prints a "DISK FULL" message to the error log and attempts to shut itself down.
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
SLAPI_PLUGIN_DB_CONFIG_FN
SLAPI_PLUGIN_DB_BIND_FN
SLAPI_PLUGIN_DB_UNBIND_FN
SLAPI_PLUGIN_DB_SEARCH_FN
SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_FN
SLAPI_PLUGIN_DB_NEXT_SEARCH_ENTRY_EXT_FN
SLAPI_PLUGIN_DB_ENTRY_RELEASE_FN
SLAPI_PLUGIN_DB_COMPARE_FN
SLAPI_PLUGIN_DB_ADD_FN
SLAPI_PLUGIN_DB_MODIFY_FN
SLAPI_PLUGIN_DB_MODRDN_FN
SLAPI_PLUGIN_DB_DELETE_FN
SLAPI_PLUGIN_DB_ABANDON_FN
SLAPI_PLUGIN_CLOSE_FN
SLAPI_PLUGIN_DB_FLUSH_FN
SLAPI_PLUGIN_START_FN
SLAPI_PLUGIN_DB_SEQ_FN
SLAPI_PLUGIN_DB_LDIF2DB_FN
SLAPI_PLUGIN_DB_DB2LDIF_FN
SLAPI_PLUGIN_DB_ARCHIVE2DB_FN
SLAPI_PLUGIN_DB_DB2ARCHIVE_FN
SLAPI_PLUGIN_DB_SIZE_FN
SLAPI_PLUGIN_DB_TEST_FN
SLAPI_PLUGIN_DB_DB2INDEX_FN
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.
Use the database directive to specify a database type.
Use the suffix directive to indicate the suffix of the directory tree that is handled by your back-end.
Use the plugin database directive to specify the library containing your plug-in functions and the name of the initialization function that registers your database plug-in.
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 /serverroot/plugins/slapd/slapi/examples/mydb.so \ mydb_init
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.
plugin database on mydbplugin \ /serverroot/plugins/slapd/slapi/examples/mydb.so mydb_init