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. 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
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 mydb database.
database mydb
suffix o=test.com
# Directives specific to the anotherdb database.
database anotherdb
suffix o=mycompany.com
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.
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
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 34 and "Configuring the Server" on page 39.
You also need to specify the following directives:
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 the section of the configuration file that registers 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.
database mydbtype
suffix o=MyCompany.com
plugin database /serverroot/plugins/slapd/slapi/examples/mydb.so \ mydb_init
Note that this plugin directive in the example above uses the syntax supported by the Netscape Directory Server 3.x. For the Netscape Directory Server 4.x, the syntax differs slightly:
plugin database on mydbplugin \ /serverroot/plugins/slapd/slapi/examples/mydb.so mydb_init
For more information on the plugin directive, see "Editing the slapd.conf File" on page 40.
Previous
